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.

Please note: you cannot create a contact and associate it with a record or activity in the same request. To associate your contact with other records or activities, create the contact, then update the contact or create an association via the associations API.

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

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

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.

For example, to retrieve contacts with their email addresses and associated companies, your request URL would look like: https://api.hubspot.com/crm/v3/objects/contacts?properties=email&associations=companies.

Learn more about retrieving contacts by clicking the Endpoints tab at the top of this article.

Update contacts

You can update contacts individually or in batches. For existing contacts, email and the contact ID are both unique values, so you can use either email or id to update the contact 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.

Please note: the idProperty query parameter doesn't appear on the Endpoints tab due to technical limitations, but it can be used for contacts exclusively with email. To use an email address as the unique identifier, set the idProperty as email and enter the email address in place of the contact ID. This should be set as a query parameter rather than added to the request body.

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

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.