Access and test APIs in beta. 

Please note: The GDPR endpoint for the Contacts API (listed below) is currently in public beta and is subject to change based on testing and feedback. By using this endpoint you agree to adhere to our Developer TermsDeveloper BetaTerms. You also acknowledge and understand the risk associated with testing an unstable API. All other Contacts API endpoints are in general availability. 

Permanently delete a contact: POST /crm/v3/objects/contacts/gdpr-delete


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

Contacts can be associated with companies, deals, engagements, and tickets. 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 page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.