Contacts
In HubSpot, contacts store information about the individual people that interact with your business. The contacts endpoints allow you to create and manage contact records in your HubSpot account, as well as sync contact data between HubSpot and other systems.
Learn more about objects, records, properties, and associations APIs in the Understanding the CRM guide. For more general information about objects and records in HubSpot, learn how to manage your CRM database.
To create new contacts, make a POST
request to /crm/v3/objects/contacts
.
In your request, include your contact data in a properties object. You can also add an associations object to associate your new contact with existing records (e.g., companies, deals), or activities (e.g., meetings, notes).
Contact details are stored in contact properties. There are default HubSpot contact properties, but you can also create custom contact properties.
When creating a new contact, you should include at least one of the following properties in your request: email
, firstname
, or lastname
. It is recommended to always include email
, because email address is the primary unique identifier to avoid duplicate contacts in HubSpot.
To view all available properties, you can retrieve a list of your account's contact properties by making a GET
request to /crm/v3/properties/contacts
. Learn more about the the properties API.
lifecyclestage
in your request, values must refer to the lifecycle stage's internal name. The internal names of default stages are text values, and do not change even if you edit the stage's label(e.g., subscriber
or marketingqualifiedlead
). The internal names of custom stagesare numeric values. You can find a stage's internal ID in your lifecycle stage settings,or by retrieving the lifecycle stage property via API.
For example, to create a new contact, your request may look similar to the following:
When creating a new contact, you can also associate the contact with existing records or activities by including an associations object. For example, to associate a new contact with an existing company and email, your request would look like the following:
In the associations object, you should include the following:
Parameter | Description |
---|---|
to
| The record or activity you want to associate with the contact, specified by its unique |
types
| The type of the association between the contact and the record/activity. Include the |
You can retrieve contacts individually or in batches.
- To retrieve an individual contact, make a
GET
request to/crm/v3/objects/contacts/{contactId} or
/crm/v3/objects/contacts/{email}?idProperty=email
. - To request a list of all contacts, make a
GET
request to/crm/v3/objects/contacts
.
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 contact 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 contact 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. |
- To retrieve a batch of specific contacts by record ID, email address, or a custom unique identifier property, make a
POST
request tocrm/v3/objects/contacts/batch/read
. The batch endpoint cannot retrieve associations. Learn how to batch read associations with the associations API.
idProperty
parameter to retrieve contacts by email
or a custom unique identifier property. By default, the id
values in the request refer to the record ID (hs_object_id
), so the idProperty
parameter is not required when retrieving by record ID. If you're using email
or a custom unique value property to retrieve contacts, you must include the idProperty
parameter.For example, to retrieve a batch of contacts based on their record ID values, your request could look like the following (current values only, or current and historical values):
To retrieve contacts based on email address or a custom unique identifier property (e.g., a customer ID number unique for your business), your request would look like:
You can update contacts individually or in batches.
To update individual contacts, you can use record ID (id
) or the contact's email address (email
).
- To update an individual contact by its record ID, make a
PATCH
request to/crm/v3/objects/contacts/{contactId}
, and include the data you want to update. - To update an individual contact by its email, make a
PATCH
request to
/crm/v3/objects/contacts/{email}?idProperty=email
, and include the data you want to update.
For example:
To update contacts in batches, you can use the contacts' record ID values (id
). To update multiple contacts, make a POST
request to /crm/v3/objects/contacts/batch/update
. In your request body, include each contact's record ID as the id
and include the properties you want to update.
For example:
You can also batch create and update contacts at the same time using the upsert endpoint. For this endpoint, you can use email
or a custom unique identifier property. Following the request, if the contacts already exist, they'll be updated and if the contacts don't exist, they'll be created.
To upsert contacts, make a POST
request to /crm/v3/objects/contacts/batch/upsert
. In your request body, include the idProperty
parameter to identify whether you're using email
or a custom unique identifier property. Include that property's value as the id
and add the other properties you want to set or update.
For example, your request could look like the following:
To associate a contact with other CRM records or an activity, make a PUT
request to /crm/v3/objects/contacts/{contactId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
.
associationTypeId
value, refer to this list of default values, or make a GET
request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels
.
Learn more about the associations API.
To remove an association between a contact and a record or activity, make a DELETE
request to the following URL: /crm/v3/objects/contacts/{contactID}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
.
You can pin an activity on a contact record by including the hs_pinned_engagement_id
field in your request. In the field, include the id
of the activity to pin, which can be retrieved via the engagements APIs. You can pin one activity per record, and the activity must already be associated with the contact prior to pinning.
To set or update a contact's pinned activity, your request could look like:
You can also create a contact, associate it with an existing activity, and pin the activity in the same request. For example:
You can delete contacts individually or in batches, which will add the contact to the recycling bin in HubSpot. You can later restore the contact within HubSpot.
To delete an individual contact by its ID, make a DELETE
request to /crm/v3/objects/contacts/{contactId}
.
Learn more about batch deleting contacts on the Endpoints tab at the top of this article.
Secondary email addresses are used when a contact has more than one email. Additional emails are still unique identifiers for contacts, so multiple contacts cannot have the same secondary email address.
- To view secondary emails for contacts, when you retrieve all or individual contacts, include the
properties
parameter with the propertiesemail
andhs_additional_emails
. A contact's primary email address will be displayed in theemail
field and additional emails will be displayed in thehs_additional_emails
field. - To add secondary emails to a contact, when creating or editing the contact, in your request body, include emails in the
hs_additional_emails
field. Multiple emails can be separated by a semi-colon.
Batch operations are limited to 100 records at a time. For example, you cannot batch update more than 100 contacts in one request. There are also limits for contacts and form submissions.
Thank you for your feedback, it means a lot to us.