There's a new version of the HubSpot API

We're also working on a new documentation website, you're invited to check it out and give us your feedback.

Create or update a group of contacts

Last updated May 12, 2023

POST /contacts/v1/contact/batch/

Method Details

HTTP Methods:


Content Type:


Response Format:


Requires Authentication?


Rate Limited?





Marketing & CRM

Required Scope:


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 keep in mind that any errors with a single contact in your batch will prevent the entire batch from processing. If this happens, we'll return a 400 response with additional details as to the cause.

Note: Changes made through this endpoint are processed asynchronously, so can take several minutes for changes to be applied to contact records.

Note: The batch size should not exceed 1000 contacts per request.

Required parameters How to use Description
OAuth access token or private app access token Authorization: Bearer {token} header Used to authenticate the request. Please see this page for more details about authentication.
Contact JSON Used in the request body This is JSON that represents a contact that you're creating or updating. This should be of the format seen below in the code sample given.
Email address or contact vid Used in the request body Each set of property data must include either an email address or a vid. When the vid is used, the existing contact record with that vid will be updated. When an email address is used, and there is an existing contact with the same email address, that contact will be updated. If an email address is used, and there is not an existing record with that email address, then a new contact record will be created.
If you're working with a known contact, using the vid is preferred.
Optional parameters How to use Description
Change source &auditId=X A string that allows you to represent these change sources however you'd like.

Example URL to POST to:  ""

Response details

  • Returns a 202 Accepted response on success. No data will appear in the response body.
  • Returns a 400 Bad request response for any failures. You might get this response if you pass an invalid email address, if a property in your request doesn't exist, or if you pass an invalid property value. More details about the specific issue will be in the body of the response. NOTE: If you receive an error, the entire batch will be rejected and no updates will be made.