Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

In HubSpot, listings store information about a particular property or unit to be bought, sold, or rented. The listings endpoints allow you to create and manage listing records in your HubSpot account, as well as sync listing data between HubSpot and other systems. The listing object must be activated in the HubSpot account to manage listing records. Learn more about objects, records, properties, and associations APIs in the Understanding the CRM guide.

​
Create listings

To create new listings:
  • To create one listing, make a POST request to /crm/objects/2026-03/listings.
  • To create multiple listings, make a POST request to /crm/objects/2026-03/listings/batch/create.
In your request, include your listing data in a properties object. You can also add an associations object to associate your new listing with existing records (e.g., contacts, companies), or activities (e.g., meetings, notes).
For batch create actions, you can enable multi-status errors which tell you which records were successfully created and which were not. Learn more about setting up multi-status error handling.

​
Create listings with property values

When creating a listing, include listing properties to store the listing’s details. For example, to create a new listing, your request may look similar to the following: 
{
  "properties": {
    "hs_name": "123 Main Street",
    "hs_price": "450000",
    "hs_listing_type": "house"
  }
}
To view all available listing properties in your account, make a GET request to /crm/properties/2026-03/listings. Learn more about the properties API.

​
Create listings with associations

When creating a new listing, you can also associate the listing with existing records or activities by including an associations array. For example, to associate a new listing with an existing contact, your request would look like the following: 
{
  "properties": {
    "hs_name": "123 Main Street",
    "hs_price": "450000",
    "hs_listing_type": "house"
  },
  "associations": [
    {
      "to": {
        "id": "123456"
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 882
        }
      ]
    }
  ]
}
ParameterDescription
toThe record or activity you want to associate with the listing, specified by its unique id value.
typesThe type of the association between the listing and the record/activity. Include the associationCategory and associationTypeId. Default association type IDs are listed on the associations API guide, or you can retrieve the value for custom association types via the associations API.

​
Retrieve listings

You can retrieve listings individually or in batches. Include the following query parameters in your request URLs to retrieve certain data.
ParameterDescription
propertiesA comma-separated list of the properties to be returned in the response. If a requested property isn’t defined, it won’t be included in the response. If a requested property is defined but a listing doesn’t have a value, it will be returned as null.
propertiesWithHistoryA comma-separated list of the current and historical properties to be returned in the response.
associationsSupported when retrieving an individual listing or all listings, a comma-separated list of objects to retrieve associated IDs for. Learn more about the associations API.

​
Retrieve an individual listing

To retrieve an individual listing by its record ID, make a GET request to /crm/objects/2026-03/listings/{listingId}.

​
Retrieve all listings

To request a list of all listings, make a GET request to /crm/objects/2026-03/listings. You can retrieve up to 100 listings in one request.
  • To retrieve a specific amount under 100, add a value to the limit parameter. For example, ?limit=50.
  • To paginate through results, include the after parameter with the after value returned from the previous request.

​
Retrieve a batch of listings

To retrieve listings in batches, make a POST request to /crm/objects/2026-03/listings/batch/read. Include the id values of the listings you want to retrieve.
Please note: the batch endpoint cannot retrieve associations. To view associations for a specific batch of listings, retrieve the listings’ id values first, then include them in a request to the batch read associations API endpoint. Learn how to retrieve associations with the associations API.
For example, to retrieve a batch of listings by their record ID values: 
{
  "properties": ["hs_name", "hs_price", "hs_listing_type"],
  "inputs": [
    {
      "id": "1234567"
    },
    {
      "id": "987456"
    }
  ]
}

​
Update listings

You can update listings individually or in batches.

​
Update an individual listing

To update an individual listing by its record ID, make a PATCH request to /crm/objects/2026-03/listings/{listingId}, and include the data you want to update. For example: 
{
  "properties": {
    "hs_listing_type": "townhouse"
  }
}

​
Update a batch of listings

To update multiple listings, make a POST request to /crm/objects/2026-03/listings/batch/update. In your request body, include each listing’s record ID as the id and include the properties you want to update. For example: 
{
  "inputs": [
    {
      "id": "123456789",
      "properties": {
        "hs_price": "50000"
      }
    },
    {
      "id": "56789123",
      "properties": {
        "hs_price": "80000"
      }
    }
  ]
}

​
Upsert listings

You can batch create and update listings at the same time using the upsert endpoint. Following the request, if the listings already exist, they’ll be updated; if they don’t exist, they’ll be created. To upsert listings, make a POST request to /crm/objects/2026-03/listings/batch/upsert.

​
Associate existing listings with records or activities

To associate a listing with other CRM records or an activity, make a PUT request to /crm/objects/2026-03/listings/{listingId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}.
To retrieve the associationTypeId value, refer to the list of default values, or make a GET request to /crm/associations/2026-03/{fromObjectType}/{toObjectType}/labels.
Learn more about the associations API.

​
Delete listings

You can delete listings individually or in batches, which will add the listing to the recycling bin in HubSpot. You can later restore the record within HubSpot.
  • To delete an individual listing, make a DELETE request to /crm/objects/2026-03/listings/{listingId}.
  • To delete listings in batches, make a POST request to /crm/objects/2026-03/listings/batch/archive.
Last modified on May 7, 2026