The object APIs enable you to create and manage records and activities within HubSpot. The object APIs have the same basic functionality for all supported objects, which allows you to substitute the objectTypeId
of an object in the endpoints. For example, to create contacts, you'd make a POST
request to crm/v3/objects/0-1
and to create courses, the request would be to crm/v3/objects/0-410
.
In this article, learn the basics of how to use the object APIs. For certain objects, you can refer to object-specific guides with examples and other details about unique functionality: Companies, Contacts, Deals, Tickets, Calls, Communications, Custom objects, Emails, Feedback submissions, Invoices, Leads, Marketing events, Meetings, Notes, Orders, Payments, Postal mail, Products, Quotes, Subscriptions, Tasks, Users.
Please note: new objects (e.g., appointments, courses, listings, services) must be activated in the HubSpot account before you can manage their records via API. Learn how to check if they're activated via the object library API and how to activate them in HubSpot.
You can retrieve records individually or in batches.
- To retrieve an individual record, make a
GET
request to/crm/v3/objects/{objectTypeId}/{recordId}
. - To request a list of all records for an object, make a
GET
request to/crm/v3/objects/{objectTypeId}
. - To retrieve a batch of specific records by record ID or a custom unique identifier property, make a
POST
request tocrm/v3/objects/{objectTypeId}/batch/read
and include theid
values of the records in the request body. The batch endpoint cannot retrieve associations. Learn how to batch read associations with the associations API.
For these endpoints, you can include the following query parameters in the request URL:
Parameter | Description |
---|---|
properties | A comma separated list of the properties to be returned in the response. If the requested record doesn't have a value for a property, it will not appear in the response. |
propertiesWithHistory | A comma separated list of the current and historical properties to be returned in the response. If the requested record doesn't have a value for a property, it will not appear in the response. |
associations | A comma separated list of objects to retrieve associated IDs for. Any specified associations that don't exist will not be returned in the response. Learn more about the associations API.Note: this parameter is not supported in the batch read endpoint. |
idProperty | Indicates the unique identifier property used to identify records. You only need to use this parameter if retrieving by a custom unique identifier property. |
For example, to retrieve a meeting with the meeting's text body and starting time, you'd make a GET
request to /crm/v3/objects/0-47/{meetingId}?properties=hs_meeting_body,hs_timestamp
and your response would look similar to the following:
///Example response
// GET crm/v3/objects/0-47/65059681027?properties=hs_meeting_body,hs_timestamp
{
"id": "65059681027",
"properties": {
"hs_createdate": "2024-11-20T20:12:09.236Z",
"hs_lastmodifieddate": "2024-11-20T20:12:10.610Z",
"hs_meeting_body": "<div style=\"\" dir=\"auto\" data-top-level=\"true\"><p style=\"margin:0;\">New meeting</p></div>",
"hs_object_id": "65059681027",
"hs_timestamp": "2024-11-20T20:12:03.054Z"
},
"createdAt": "2024-11-20T20:12:09.236Z",
"updatedAt": "2024-11-20T20:12:10.610Z",
"archived": false
}
To retrieve a batch of deals, your request could look like either of the following:
xxxxxxxxxx
///Example request body
// GET crm/v3/objects/0-3/batch/read
{
"properties": ["dealname", "dealstage", "pipeline"],
"inputs": [
{
"id": "7891023"
},
{
"id": "987654"
}
]
}
xxxxxxxxxx
///Example request body
// GET crm/v3/objects/0-3/batch/read?idProperty=uniqueordernumber
{
"properties": ["dealname", "dealstage", "pipeline"],
"idProperty": "uniqueordernumber",
"inputs": [
{
"id": "0001111"
},
{
"id": "0001112"
}
]
}
- To create a record for an object, make a
POST
request tocrm/v3/objects/{objectTypeId}
. - To create multiple records, make a
POST
request to/crm/v3/objects/{objectTypeId}/batch/create
.
In your request, include data for each record in a properties
object. You can also add an associations
object to associate your new record with existing records (e.g., companies, deals), or activities (e.g., meetings, notes).
If you want to create and update records at the same time, learn how to upsert records below.
Record details are stored in properties. To view all available properties for an object, you can retrieve a list of your account's properties by making a GET
request to /crm/v3/properties/{objectTypeId}
. Learn more about the properties API and how to format property values.
The table below includes the objects for which records can be created via API and the properties required for creation.
Type ID | Object | Required properties to create |
---|---|---|
0-2 | Companies | At least one of domain (recommended) or name |
0-1 | Contacts | At least one of of email (recommended), firstname , or lastname |
0-3 | Deals | dealname , dealstage and pipeline |
0-5 | Tickets | subject (the ticket's name), hs_pipeline_stage (the ticket's status), and hs_pipeline |
0-421 | Appointments | hs_appointment_start |
0-48 | Calls | hs_timestamp |
0-18 | Communications | hs_timestamp and hs_communication_channel_type |
0-410 | Courses | hs_course_name |
2-XXX | Custom objects | The required properties specified in your object's schema. |
0-49 | Emails | hs_timestamp and hs_email_direction |
0-136 | Leads | hs_associated_contact_email , hs_associated_contact_lastname , hs_lead_name , hs_associated_company_domain , hs_associated_contact_firstname , and hs_associated_company_name |
0-8 | Line items | Recommended properties |
0-420 | Listings | hs_name |
0-54 | Marketing events | hs_event_description and hs_event_name |
0-47 | Meetings | hs_timestamp |
0-46 | Notes | hs_timestamp |
0-123 | Orders | hs_order_name |
0-116 | Postal mail | hs_timestamp |
0-7 | Products | hs_sku , hs_folder , price , name , and description |
0-14 | Quotes | hs_title and hs_expiration_date |
0-162 | Services | hs_name , hs_pipeline , and hs_pipeline_stage |
0-69 | Subscriptions | hs_name |
0-27 | Tasks | hs_timestamp |
0-115 | Users | hs_internal_user_id and hs_email |
For example, to create a new ticket without associations, your request may look similar to the following:
xxxxxxxxxx
///Example request body
// POST /crm/v3/objects/0-1
{
"properties": {
"hs_pipeline": "0",
"hs_pipeline_stage": "1",
"hs_ticket_priority": "HIGH",
"subject": "troubleshoot report"
}
}
For example, to create multiple contacts without associations, your request may look similar to the following:
xxxxxxxxxx
///Example request body
// POST crm/v3/objects/0-1/batch/create
{
"inputs": [
{
"properties": {
"email": "testone@test.com",
"firstname": "Test",
"lastname": "PersonOne",
"favorite_food": "Pizza"
}
},
{
"properties": {
"email": "testtwo@test.com",
"firstname": "Test",
"lastname": "PersonTwo",
"favorite_food": "Ice cream"
}
}
]
}
When creating a new record, you can also associate it with existing records or activities by including an associations
object. In the associations
object, you should include the following:
Parameter | Description |
---|---|
to | The record or activity you want to associate with the record, specified by its unique id value. |
types | The type of the association between the record and the record/activity. Include the associationCategory and associationTypeId . Default association type IDs are listed here, or you can retrieve the value for custom association types (i.e. labels) via the associations API. |
For example, to create a new contact and associate with an existing company and email, your request would look like the following:
xxxxxxxxxx
///Example request body
// POST /crm/v3/objects/0-1
{
"properties": {
"email": "example@hubspot.com",
"firstname": "Jane",
"lastname": "Doe",
"phone": "(555) 555-5555",
"company": "HubSpot",
"website": "hubspot.com",
"lifecyclestage": "marketingqualifiedlead"
},
"associations": [
{
"to": {
"id": 123456
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 279
}
]
},
{
"to": {
"id": 556677
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 197
}
]
}
]
}
For example, to create multiple deals and associate them with existing companies and meetings, your request would look similar to the following:
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.
xxxxxxxxxx
///Example request body
// POST /crm/v3/objects/0-3/batch/create
{
"inputs": [
{
"associations": [
{
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 5
}
],
"to": {
"id": "23125848331"
}
},
{
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 211
}
],
"to": {
"id": "65059681027"
}
}
],
"properties": {
"dealname": "New deal 1",
"dealstage": "qualifiedtobuy",
"pipeline": "default"
}
},
{
"associations": [
{
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 5
}
],
"to": {
"id": "23125848331"
}
},
{
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 211
}
],
"to": {
"id": "65059681027"
}
}
],
"properties": {
"dealname": "New deal 2",
"dealstage": "qualifiedtobuy",
"pipeline": "default"
}
}
]
}
You can update records individually or in batches. For existing records, the Record ID is a default unique value that you can use to update the record via API, but you can also identify records using the idProperty
parameter with a custom unique identifier property. If you want to create and update records at the same time, learn how to upsert records.
- To update an individual record, make a
PATCH
request to/crm/v3/objects/{objectTypeId}/{recordId}
, and include the data you want to update. - To update multiple records, make a
POST
request to/crm/v3/objects/{objectTypeId}/batch/update
. In the request body, include an array with the identifiers for the records and the properties you want to update.
For example, to update a contact, your request would look similar to the following:
xxxxxxxxxx
// Example request body with record ID
// PATCH /crm/v3/objects/0-1/123456789
{
"properties": {
"favorite_food": "burger",
"jobtitle": "Manager",
"lifecyclestage": "Customer"
}
}
You can also batch create and update records at the same time using the upsert endpoint. For this endpoint, you can use a custom unique identifier property or email
for contacts. Following the request, if the records already exist, they'll be updated and if the records don't exist, they'll be created.
To upsert records, make a POST
request to /crm/v3/objects/{objectTypeId}/batch/upsert
. In your request body, include the idProperty
parameter to identify the unique identifier property you're using. Include that property's value as the id
and add the other properties you want to set or update.
For example, to upsert contacts to set the phone number property, using email as the identifier, your request would look similar to the following:
xxxxxxxxxx
// Example request body with email
// POST /crm/v3/objects/0-1/batch/upsert
{
"inputs": [
{
"properties": {
"phone": "5555555555"
},
"id": "luke@lukesdiner.com",
"idProperty": "email"
},
{
"properties": {
"phone": "7777777777"
},
"id": "lorelai@thedragonfly.com",
"idProperty": "email"
},
{
"properties": {
"phone": "1111111111"
},
"id": "michel@thedragonfly.com",
"idProperty": "email"
}
]
}
Once records are created, you can update their associations using the associations API.
- To associate a record with other records or an activity, make a
PUT
request to/crm/v3/objects/{objectTypeId}/{fromRecordId}/associations/{toObjectTypeId}/{toRecordId}/{associationTypeId}
. - To remove an association between a record and a record or activity, make a
DELETE
request to the following URL:/crm/v3/objects/{objectTypeId}/{fromRecordId}/associations/{toObjectTypeId}/{toRecordId}/{associationTypeId}
.
To retrieve the associationTypeId
value, refer to this list of default values, or make a GET
request to /crm/v4/associations/{fromObjectTypeId}/{toObjectTypeId}/labels
.
You can pin an activity on a record by including the hs_pinned_engagement_id
field in your create, update, or upsert request. In the field, include the id
of the activity to pin, which can be retrieved by making a GET
request to /crm/v3/objects/{objectTypeId}/{recordId}
for calls, communications, emails, meetings, notes, postal mail, or tasks. You can pin one activity per record, and the activity must already be associated with the record prior to pinning.
For example, to set or update an existing deal's pinned activity, your request could look like:
xxxxxxxxxx
///Example request body
// PATCH /crm/v3/objects/0-3/{recordId}
{
"properties": {
"hs_pinned_engagement_id": 123456789
}
}
To create a new deal, associate it with an activity, and pin that activity, you request would look like:
xxxxxxxxxx
// Example request body
// POST /crm/v3/objects/0-3
{
"properties": {
"dealname": "New Deal",
"pipeline": "default",
"dealstage": "appointmentscheduled",
"hs_pinned_engagement_id": 123456789
},
"associations": [
{
"to": {
"id": 123456789
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 205
}
]
}
]
}
You can delete records individually or in batches, which will add the record to the recycling bin in HubSpot. You can restore the record within HubSpot for up to 90 days after deletion.
- To delete an individual record by its record ID, make a
DELETE
request to/crm/v3/objects/{objectTypeId}/{recordId}
. - To delete multiple records, make a
POST
request to/crm/v3/objects/{objectTypeId}/batch/archive
and include the record ID values as theid
inputs in your request body.
For example, to delete multiple appointments, your request would look like:
xxxxxxxxxx
// Example request body
// POST /crm/v3/objects/0-421/batch/archive
{
"inputs": [
{
"id": "123456"
},
{
"id": "7891011"
},
{
"id": "12123434"
}
]
}