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.
idProperty query parameter doesn't appear on the Endpoints tab due to technical limitations, but it can be used for contacts exclusively with
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.
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.,
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
For visual representation of how objects relate to one another in HubSpot, check out the Object Relationships section on the "Understanding the CRM" page.
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.
Thank you for your feedback, it means a lot to us.