In HubSpot, contacts store information about individuals. From marketing automation to smart content, the lead-specific data found in contact records helps users leverage much of HubSpot's functionality. The contacts endpoints allow you to manage this data and sync it between HubSpot and other systems.

Contacts, along with companies, deals, tickets, line items, products, quotes, and custom objects are objects in the HubSpot CRM. Learn more about object properties, associations, relationships, and more in our Understanding the CRM guide. For a more detailed look at HubSpot record types, you can use our Guide to Records.

Example use case: Your team is using HubSpot and another software system for their work. They need accurate contact information in both systems, but don't want to spend time making manual updates. You can use the contacts endpoints to integrate the two systems and sync contact information. 


There are a few limits in place for contact records, which may affect any testing you do with contacts endpoints. For more information, read about contact and form limits.

Batch operations for creating, updating, and archiving are limited to batches of 10.

Unique identifiers and deduplication

An email address is the primary unique identifier for a contact in HubSpot. For existing contacts, the contact ID is also unique and will deduplicate contacts. To update a contact via the API, you can use either the contact ID or the contact's email.

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.

Contact properties

Contact details are stored in contact properties. In addition to default properties, you can store custom data by creating custom contact properties. These can be managed through the CRM object properties endpoints.

Lifecycle stage

To change a contact's lifecycle stage via the API, set the value of lifecyclestage to the lifecycle stage's internal name. The internal IDs will also be returned when you retrieve the lifecycle stage property via API.

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 stages are numeric values. You can find a stage's internal ID in your lifecycle stage settings.

Checking for updates

To allow for new functionality, HubSpot will occasionally update existing default properties, and users may also change their custom properties from time to time. If your integration works with contacts, it's recommended that you use the object properties endpoints to periodically check for updates.

Associations between contacts and other objects

Contacts can be associated with companies, deals, engagements, tickets, and custom objects. You can manage object associations using the CRM associations endpoints. 

For visual representation of how objects relate to one another in HubSpot, check out the Object Relationships section on the "Understanding the CRM" page.

Note: The archivedAt value returned for these contacts endpoints is actually the last modified date of the specific object. We'll update the changelog and this documentation when this value reflects the actual deletion datetime of the object.

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