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.

Create contacts

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).

Properties

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.

Please note: if you've included 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:

///Example request body { "properties": { "email": "example@hubspot.com", "firstname": "Jane", "lastname": "Doe", "phone": "(555) 555-5555", "company": "HubSpot", "website": "hubspot.com", "lifecyclestage": "marketingqualifiedlead" } }

Associations

When creating a new contact, you can also associate the contact with existing records or activities. In the associations object, include the following fields:

Use this table to describe parameters / fields
ParameterDescription
toObjectId

The ID of the record or activity that you want to associate the contact with.

associationTypeId

A unique identifier to indicate the association type between the contact and the other object or activity. Default association types are listed here, or you can retrieve the value by making a GET request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels. Learn more about the associations API.

You can also include the label field to assign a defined association label that describes the association. Learn more about associating records via the associations API.

For example, to associate a new contact with an existing company and email, your request would look like the following:

///Example request body { "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 } ] }] }

Retrieve contacts

You can retrieve contacts individually or in batches.

  • To retrieve an individual contact, make a GET request to /crm/v3/objects/contacts/{contactId}
  • 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: 

Use this table to describe parameters / fields
ParameterDescription
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 to crm/v3/objects/contacts/batch/read. The batch endpoint cannot retrieve associations. Learn how to batch read associations with the associations API.
For the batch read endpoint, you can use the optional 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):

///Example request body with record ID (current values) { "properties": [ "email", "lifecyclestage", "jobtitle" ], "inputs": [ { "id": "1234567" }, { "id": "987456" } ] }
///Example request body with record ID (current and historical values) { "propertiesWithHistory": [ "lifecyclestage", "hs_lead_status" ], "inputs": [ { "id": "1234567" }, { "id": "987456" } ] }

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:

///Example request body with email { "properties": [ "email", "lifecyclestage", "jobtitle" ], "idProperty": "email", "inputs": [ { "id": "lgilmore@thedragonfly.com" }, { "id": "sstjames@thedragonfly.com" } ] }
///Example request body with a unique value property { "properties": [ "email", "lifecyclestage", "jobtitle" ], "idProperty": "internalcustomerid", "inputs": [ { "id": "12345" }, { "id": "67891" } ] }

Update contacts

You can update contacts individually or in batches. For existing contacts, email and record ID are both unique values, so you can use id or email to update contacts via API.

To update an individual contact by its contact ID, make a PATCH request to /crm/v3/objects/contacts/{contactId}, and include the data you want to update.

Associate existing contacts with records or activities

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}.

To retrieve the 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.

Remove an association

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}.

Pin an activity on a contact record

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:

///Example request body PATCH /crm/v3/objects/contacts/{contactId} { "properties": { "hs_pinned_engagement_id": 123456789 } }

You can also create a contact, associate it with an existing activity, and pin the activity in the same request. For example:

///Example request body POST /crm/v3/objects/contacts { "properties": { "email": "example@hubspot.com", "firstname": "Jane", "lastname": "Doe", "phone": "(555) 555-5555", "hs_pinned_engagement_id": 123456789 }, "associations": [ { "to": { "id": 123456789 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 201 }] }] }

Delete contacts

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.

Limits

Batch operations for creating, updating, and archiving are limited to batches of 100. There are also limits for contacts and form submissions.


Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.