Create or update a group of contacts

POST /contacts/v1/contact/batch/

Method Details

HTTP Methods:

POST

Content Type:

application/json

Response Format:

N/A

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing & CRM

Create a group of contacts or update them if they already exist. Particularly useful for periodic syncs from another contacts database to HubSpot.

Performance is best when calls are limited to 100 or fewer contacts.

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: While there is not hard cap on the number of records that can be updated, requests should be limited to 10mb for the request size.

Required Parameters How to use Description
OAuth Access Token or API Key Authorization: Bearer {token} header
or hapikey={key} query parameter.
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 udpdating. 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.
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:  "https://api.hubapi.com/contacts/v1/contact/batch/?hapikey=demo"

Responses:
  • 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.