# HubSpot docs: APIs Legacy CRM Objects Contacts ## Contacts - [CRM API | Contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/guide.md): Contact records store information about individuals. The contacts endpoints allow you to manage this data and sync it between HubSpot and other systems. - [Create a contact](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/create-contact.md): Create a single contact. Include a `properties` object to define [property values](https://developers.hubspot.com/docs/guides/api/crm/properties) for the contact, along with an `associations` array to define [associations](https://developers.hubspot.com/docs/guides/api/crm/associations/associations-… - [Retrieve a contact](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/get-contact.md): Retrieve a contact by its ID (`contactId`) or by a unique property (`idProperty`). You can specify what is returned using the `properties` query parameter. - [Retrieve contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/get-contacts.md): Retrieve all contacts, using query parameters to specify the information that gets returned. - [Merge two contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/merge-contacts.md): Merge two contact records. Learn more about [merging records](https://knowledge.hubspot.com/records/merge-records). - [Update a contact](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/update-contact.md): Update an existing contact, identified by ID or email/unique property value. To identify a contact by ID, include the ID in the request URL path. To identify a contact by their email or other unique property, include the email/property value in the request URL path, and add the `idProperty` query pa… - [Archive a contact](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/delete-contact.md): Delete a contact by ID. Deleted contacts can be restored within 90 days of deletion. Learn more about the [data impacted by contact deletions](https://knowledge.hubspot.com/privacy-and-consent/understand-restorable-and-permanent-contact-deletions) and how to [restore archived records](https://knowle… ### Batch - [Create a batch of contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/batch/create-contacts.md): Create a batch of contacts. The `inputs` array can contain a `properties` object to define property values for each record, along with an `associations` array to define [associations](https://developers.hubspot.com/docs/guides/api/crm/associations/associations-v4) with other CRM records. - [Retrieve a batch of contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/batch/get-contacts.md): Retrieve a batch of contacts by ID (`contactId`) or unique property value (`idProperty`). - [Update a batch of contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/batch/update-contacts.md): Update a batch of contacts by ID (`contactId`) or unique property value (`idProperty`). Provided property values will be overwritten. Read-only and non-existent properties will result in an error. Properties values can be cleared by passing an empty string. - [Create or update a batch of contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/batch/upsert-contacts.md): Upsert a batch of contacts. The `inputs` array can contain a `properties` object to define property values for each record. - [Archive a batch of contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/batch/delete-contacts.md): Archive a batch of contacts by ID. Archived contacts can be restored within 90 days of deletion. Learn more about the [data impacted by contact deletions](https://knowledge.hubspot.com/privacy-and-consent/understand-restorable-and-permanent-contact-deletions) and how to [restore archived records](ht… ### GDPR - [Permanently delete a contact (GDPR-compliant)](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/gdpr/gdpr-delete-contact.md): Permanently delete a contact and all associated content to follow GDPR. Use optional property `idProperty` set to `email` to identify contact by email address. If email address is not found, the email address will be added to a blocklist and prevent it from being used in the future. Learn more about… ### Search - [Search for contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/search/search-contacts.md): Search for contacts by filtering on properties, searching through associations, and sorting results. Learn more about [CRM search](https://developers.hubspot.com/docs/guides/api/crm/search#make-a-search-request). ### v1 - [Get Lifecycle Stage metrics for Contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/get-contacts-search-v1-external-lifecycle-stages.md): Returns the total number of contacts in the account and the date of the last contact add. - [Get a contact by email address](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/get-contacts-v1-contact-email-contact-email-profile.md): For a given account, return information about a group of contacts by their email addresses. This method will also return you much of the HubSpot lead "intelligence" for each requested contact record. The endpoint accepts many query parameters that allow for customization based on a variety of integr… - [Get a batch of contacts by email address](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/get-contacts-v1-contact-email-s-batch.md): For a given account, return information about a group of contacts by their email addresses. This method will also return you much of the HubSpot lead "intelligence" for each requested contact record. The endpoint accepts many query parameters that allow for customization based on a variety of integr… - [Get a batch of contacts by user token](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/get-contacts-v1-contactbyUtk-batch.md): For a given account, return information about a group of contacts by their user tokens. A visitor's user token is stored in the hubspotutk cookie. This cookie is created automatically by the HubSpot tracking code. The endpoint accepts many query parameters that allow for customization based on a var… - [Get Contact Statistics](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/get-contacts-v1-contacts-statistics.md): Returns an array of secondary email addresses associated with a contact. Note: The secondary email addresses for a contact are included in the hs_additional_emails property for the contact. If you're already pulling other contact data, you can request the hs_additional_emails property in those reque… - [Get a contact by its user token](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/get-contacts-v1-contactutkcontactutk-profile.md): For a given account, return information about a group of contacts by their user tokens. A visitor's user token is stored in the hubspotutk cookie. This cookie is created automatically by the HubSpot tracking code. The endpoint accepts many query parameters that allow for customization based on a var… - [Get a batch of contacts by vid](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/get-contacts-v1-contactvids-batch.md): For a given account, return information about a group of contacts by their unique IDs. A contact's unique ID is stored in a field called 'vid' which stands for 'visitor ID'. The endpoint accepts many query parameters that allow for customization based on a variety of integration use cases. By defaul… - [Get a contact by vid](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/get-contacts-v1-contactvidvid-profile.md): The _get a contact by vid_ endpoint returns information about a single contact by its ID (vid) for a given account. The contact's unique ID is stored in a field called 'vid,' which stands for 'visitor ID.' Use case for this endpoint: An integration could use this endpoint to get all updates made to… - [Get all contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/get-contacts-v1-lists-all-contacts-all.md): For a given account, return all contacts that have been created in the account. A paginated list of contacts will be returned to you, with a maximum of 100 contacts per page. Note: There are 2 fields here to pay close attention to: the "has-more" field that will let you know whether there are more c… - [Get recently created contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/get-contacts-v1-lists-all-contacts-recent.md): For a given account, return all contacts that have been recently created. A paginated list of contacts will be returned to you, with a maximum of 100 contacts per page, as specified by the "count" parameter. Please Note There are 3 fields here to pay close attention to: the "has-more" field that wil… - [Get recently updated and created contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/get-contacts-v1-lists-recent-ly-update-d-contacts-recent.md): The _get recently updated and created contacts_ endpoint is used to return information about all contacts for a given account that were updated or created in the last 30 days. Use case for this endpoint: This endpoint is useful for integrations that need to track changes to contacts and synchronize… - [Search for contacts by email](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/get-contacts-v1-secondary-email-v-id.md): Returns an array of secondary email addresses associated with a contact. Note: The secondary email addresses for a contact are included in the hs_additional_emails property for the contact. If you're already pulling other contact data, you can request the hs_additional_emails property in those reque… - [Delete a secondary email address](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/get-contacts-v1-secondary-email-vid-email-email.md): Remove a secondary email address from a contact. - [Create a new contact](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/patch-contacts-v1-secondary-email-v-id.md): Updates a secondary email address for a contact. You must provide the current secondary email address and the new email address. - [Create or update a group of contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/post-contacts-v1-contact-batch.md): This endpoint is used to create a group of contacts or update existing ones. Performance is best when batch size is limited to 100 contacts or fewer. Use case for this endpoint: It's particularly useful for periodic syncs from another contacts database to HubSpot. When using this endpoint, please ke… - [Create or update a contact by email](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/post-contacts-v1-contact-create-OrUpdate-email-contact-email.md): The _create or update a contact_ endpoint is used to create a new HubSpot contact or update an existing one. Use case for this endpoint: This method is useful when syncing changes to contacts in other CRMs with your HubSpot contacts. - [Update an existing contact by email](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/post-contacts-v1-contact-email-email-profile.md): This endpoint allows you to update an existing contact in HubSpot, identified by email. - [Merge contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/post-contacts-v1-contact-merge-vidscontact-id.md): Merge two contact records. The contact ID in the URL will be treated as the primary contact, and the contact ID in the request body will be treated as the secondary contact. For more details about what happens when you merge two contact records, please see this knowledge article. Note: Merging conta… - [Create a new contact](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/post-contacts-v1-contact.md): The _create a new contact_ endpoint is used to create a new contact in HubSpot. The new contact will be assigned a unique ID (vid), which can be used to look it up later. Use case for this endpoint: This endpoint can be used to perform a one-time sync of new contacts from an external system into Hub… - [Update a contact by vid](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/post-contacts-v1-contactvidvid-profile.md): This endpoint is used to update an existing contact in HubSpot by its vid (visitor ID). It only updates the properties specified in the request. Use case for this endpoint: Let's say you've been updating contact records in an external database and now you want to sync those updates to HubSpot. You c… - [Search for contacts by email, name, phone number, or company](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/post-contacts-v1-search-query.md): The _search contacts_ endpoint is used to search for contacts by email, name, phone number, or company. This endpoint returns search results in a paginated format and accepts a query string to search across contact properties. - [Create a new contact](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/post-contacts-v1-secondary-email-v-id.md): Updates a secondary email address for a contact. You must provide the current secondary email address and the new email address. - [Update a secondary email address](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/post-contacts-v1-secondary-email-vid-email-email.md): Update an existing secondary email address for a contact. - [Update a secondary email address](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/put-contacts-v1-secondary-email-vid-email-email.md): Update an existing secondary email address for a contact. - [Create or update a group of contacts](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/delete-contacts-v1-contact-batch.md): This endpoint is used to create a group of contacts or update existing ones. Performance is best when batch size is limited to 100 contacts or fewer. Use case for this endpoint: It's particularly useful for periodic syncs from another contacts database to HubSpot. When using this endpoint, please ke… - [Delete a contact](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/delete-contacts-v1-contactvidcontact-id.md): Delete an existing contact from a particular HubSpot portal. If a contact with the same email address interacts with the portal again (via a form submission for example) the contact will be added back into the user interface. - [Delete a secondary email address](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/v1/delete-contacts-v1-secondary-email-vid-email-email.md): Remove a secondary email address from a contact. ## OpenAPI Specs - [crm-contacts-v3](/docs/specs/legacy/v3/crm-contacts-v3.json) - [crm-contacts-v1](/docs/specs/legacy/v1/crm-contacts-v1.json)