Contacts

OverviewEndpoints

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 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:

///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 } ] } ] }

In the associations object, you should include the following:

Use this table to describe parameters / fields
ParameterDescription
to

The record or activity you want to associate with the contact, specified by its unique id value.

types

The type of the association between the contact and the record/activity. Include the associationCategoryand 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.

Retrieve contacts by record ID, email, or custom unique value property

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: 

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 address { "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.

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:

// Example request body with record ID // PATCH /crm/v3/objects/contacts/123456789 { "properties": { "favorite_food": "burger", "jobtitle": "Manager", "lifecyclestage": "Customer" } }

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:

// Example request body // POST /crm/v3/objects/contacts/batch/update { "inputs": [ { "id": "123456789", "properties": { "favorite_food": "burger" } }, { "id": "56789123", "properties": { "favorite_food": "Donut" } } ] }

Upsert contacts

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:

// Example request body with email // POST /crm/v3/objects/contacts/batch/upsert { "inputs": [ { "properties": { "phone": "5555555555" }, "id": "test@test.com", "idProperty": "email" }, { "properties": { "phone": "7777777777" }, "id": "example@hubspot.com", "idProperty": "email" } ] }

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.

Secondary emails

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 properties email and hs_additional_emails. A contact's primary email address will be displayed in the email field and additional emails will be displayed in the hs_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.
If you're using the V1 contact APIs, learn how to use the secondary email endpoints in this reference guide.

Limits

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.

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