Create or update a group of contacts

Last updated December 30, 2019

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

Required Scope:

contacts

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 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 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:  "https://api.hubapi.com/contacts/v1/contact/batch/?hapikey=demo"

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.

These code samples use a demo API key. Using this key for anything but GET requests will result in an error. For all other requests (such as POST or PUT), you'll need to use your own API key or OAuth. For more details, please see here