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, and quotes, 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 operation limits
Batch operations for creating, updating, and archiving should be limited to batches of 10.
An email address is the primary identifier for a contact in HubSpot. These endpoints automatically deduplicate email addresses to keep HubSpot data clean. Learn more here.
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 updates
If you are trying to change a contact into a customer (to reflect an updated deal stage) via the API, you should set the value of the
lifecyclestage property to “customer.”
Checking for updates (recommended)
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.