Last modified: August 28, 2025

Run in Postman

 In HubSpot, contacts store information about the individual people that interact with your business. The contacts endpoints allow you to create and manage contact records in your HubSpot account, as well as sync contact data between HubSpot and other systems. Learn more about objects, records, properties, and associations APIs in the Understanding the CRM guide. For more general information about objects and records in HubSpot, learn how to manage your CRM database.

​
Create contacts

To create new contacts, make a POST request to /crm/v3/objects/contacts. In your request, include your contact data in a properties object. You can also add an associations object to associate your new contact with existing records (e.g., companies, deals), or activities (e.g., meetings, notes).

​
Properties

Contact details are stored in contact properties. There are default HubSpot contact properties, but you can also create custom contact properties. When creating a new contact, you should include at least one of the following properties in your request: email, firstname, or lastname. It is recommended to always include email, because email address is the primary unique identifier to avoid duplicate contacts in HubSpot. To view all available properties, you can retrieve a list of your account’s contact properties by making a GET request to /crm/v3/properties/contacts. Learn more about the the properties API.

​
Please note:

If you’ve included lifecyclestage in your request, values must refer to the lifecycle stage’s internal name. 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 stagesare numeric values. You can find a stage’s internal ID in your lifecycle stage settings,or by retrieving the lifecycle stage property via API.
For example, to create a new contact, your request may look similar to the following: 
///Example request body
{
"properties": {
"email": "example@hubspot.com",
"firstname": "Jane",
"lastname": "Doe",
"phone": "+18884827768",
"company": "HubSpot",
"website": "hubspot.com",
"lifecyclestage": "marketingqualifiedlead"
}
}

​
Associations

When creating a new contact, you can also associate the contact with existing records or activities by including an associations object. For example, to associate a new contact with an existing company and email, your request would look like the following: 
///Example request body
{
"properties": {
"email": "example@hubspot.com",
"firstname": "Jane",
"lastname": "Doe",
"phone": "+18884827768",
"company": "HubSpot",
"website": "hubspot.com",
"lifecyclestage": "marketingqualifiedlead"
},
"associations": [
{
"to": {
"id": 123456
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 279
}
]
},
{
"to": {
"id": 556677
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 197
}
]
}
]
}
In the associations object, you should include the following:
ParameterDescription
toThe record or activity you want to associate with the contact, specified by its unique id value.
typesThe type of the association between the contact and the record/activity. Include the associationCategoryand associationTypeId. Default association type IDs are listed here, or you can retrieve the value for custom association types (i.e. labels) via the associations API.

​
Retrieve contacts by record ID, email, or custom unique value property

You can retrieve contacts individually or in batches.
  • To retrieve an individual contact, make a GET request to /crm/v3/objects/contacts/{contactId} or /crm/v3/objects/contacts/{email}?idProperty=email.
  • To request a list of all contacts, make a GET request to /crm/v3/objects/contacts.
For these endpoints, you can include the following query parameters in the request URL:
ParameterDescription
propertiesA comma separated list of the properties to be returned in the response. If a requested property isn’t defined, it won’t be included in the response. If a requested property is defined but a contact doesn’t have a value, it will be returned as null.
propertiesWithHistoryA comma separated list of the current and historical properties to be returned in the response. If a requested property isn’t defined, it won’t be included in the response. If a requested property is defined but a contact doesn’t have a value, it will be returned as null.
associationsA comma separated list of objects to retrieve associated IDs for. Any specified associations that don’t exist will not be returned in the response. Learn more about the associations API.
  • To retrieve a batch of specific contacts by record ID, email address, or a custom unique identifier property, make a POST request to crm/v3/objects/contacts/batch/read. The batch endpoint cannot retrieve associations. Learn how to batch read associations with the associations API.
For the batch read endpoint, you can use the optional idProperty parameter to retrieve contacts by email or a custom unique identifier property. By default, the id values in the request refer to the record ID (hs_object_id), so the idProperty parameter is not required when retrieving by record ID. If you’re using email or a custom unique value property to retrieve contacts, you must include the idProperty parameter. For example, to retrieve a batch of contacts based on their record ID values, your request could look like the following (current values only, or current and historical values): To retrieve contacts based on email address or a custom unique identifier property (e.g., a customer ID number unique for your business), your request would look like:

​
Update contacts

You can update contacts individually or in batches. To update individual contacts, you can use record ID (id) or the contact’s email address (email).
  • To update an individual contact by its record ID, make a PATCH request to /crm/v3/objects/contacts/{contactId}, and include the data you want to update.
  • To update an individual contact by its email, make a PATCH request to /crm/v3/objects/contacts/{email}?idProperty=email, and include the data you want to update.
For example: 
{
  "properties": {
    "favorite_food": "burger",
    "jobtitle": "Manager",
    "lifecyclestage": "Customer"
  }
}

​
Please note:

If updating the lifecyclestage property, you can only set the value forward in the stage order. To set the lifecycle stage backward, you’ll first need to clear the record’s existing lifecycle stage value. The value can be cleared manually, or may be automatically cleared via a workflow or an integration that syncs contact data.
To update contacts in batches, you can use the contacts’ record ID values (id). To update multiple contacts, make a POST request to /crm/v3/objects/contacts/batch/update. In your request body, include each contact’s record ID as the id ​and include the properties you want to update. For example: 
{
  "inputs": [
    {
      "id": "123456789",
      "properties": {
        "favorite_food": "burger"
      }
    },
    {
      "id": "56789123",
      "properties": {
        "favorite_food": "Donut"
      }
    }
  ]
}

​
Upsert contacts

You can also batch create and update contacts at the same time using the upsert endpoint. For this endpoint, you can use email or a custom unique identifier property. Following the request, if the contacts already exist, they’ll be updated and if the contacts don’t exist, they’ll be created. To upsert contacts, make a POST request to /crm/v3/objects/contacts/batch/upsert. In your request body, include the idProperty parameter to identify whether you’re using email or a custom unique identifier property. Include that property’s value as the id ​and add the other properties you want to set or update.

​
Please note:

Partial upserts are not supported when using email as the idProperty for contacts. To complete a partial upsert, use a custom unique identifier property as the idProperty instead.
For example, your request could look like the following: 
{
  "inputs": [
    {
      "properties": {
        "phone": "+18884827768"
      },
      "id": "test@test.com",
      "idProperty": "email"
    },
    {
      "properties": {
        "phone": "+18888888888"
      },
      "id": "example@hubspot.com",
      "idProperty": "email"
    }
  ]
}

​
Associate existing contacts with records or activities

To associate a contact with other CRM records or an activity, make a PUT request to /crm/v3/objects/contacts/{contactId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}.
To retrieve the associationTypeId value, refer to this list of default values, or make a GET request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels.
Learn more about the associations API.

​
Remove an association

To remove an association between a contact and a record or activity, make a DELETE request to the following URL: /crm/v3/objects/contacts/{contactID}/associations/{toObjectType}/{toObjectId}/{associationTypeId}.

​
Pin an activity on a contact record

You can pin an activity on a contact record by including the hs_pinned_engagement_id field in your request. In the field, include the id of the activity to pin, which can be retrieved via the engagements APIs. You can pin one activity per record, and the activity must already be associated with the contact prior to pinning. To set or update a contact’s pinned activity, your request could look like: 
{
  "properties": {
    "hs_pinned_engagement_id": 123456789
  }
}
You can also create a contact, associate it with an existing activity, and pin the activity in the same request. For example: 
{
  "properties": {
    "email": "example@hubspot.com",
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+18884827768",
    "hs_pinned_engagement_id": 123456789
  },
  "associations": [
    {
      "to": {
        "id": 123456789
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 201
        }
      ]
    }
  ]
}

​
Delete contacts

You can delete contacts individually or in batches, which will add the contact to the recycling bin in HubSpot. You can later restore the contact within HubSpot. To delete an individual contact by its ID, make a DELETE request to /crm/v3/objects/contacts/{contactId}. Learn more about batch deleting contacts in the reference documentation.

​
Additional emails

Additional email addresses are used when a contact has more than one email. These can be added manually on a contact record in HubSpot or can be added automatically following a contact merge. Additional emails are still unique identifiers for contacts, so multiple contacts cannot have the same additional email addresses. To view additional emails for contacts, when you retrieve all or individual contacts, include the properties parameter with the properties email and hs_additional_emails. A contact’s primary email address will be displayed in the email field and additional emails will be displayed in the hs_additional_emails field.

​
Limits

Batch operations are limited to 100 records at a time. For example, you cannot batch update more than 100 contacts in one request. There are also limits for contacts and form submissions.