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.

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. In the associations object, include the following fields:

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

For these endpoints, you can include the following query parameters in the request URL: 

For the batch read endpoint, you can also 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 record ID values, your request could look like:

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. For existing contacts, email and record ID are both unique values, so you can use id or email to update contacts via API. If you've created a custom unique identifier property, you can also use those unique values to update contacts. When using email or a custom unique value property, include the idProperty parameter to specify the property you're using (e.g., "idProperty": "email").

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.

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