There's a new version of the HubSpot API

Check out the new API
View Beta Docs

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 January 7, 2025

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:

crm.objects.contacts.write

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

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.

About

Jobs

Learn Inbound

Support

Locations

HubSpot, Inc.
25 First Street, 2nd Floor
Cambridge, MA 02141
European Headquarters
Ground Floor, Two Dockland Central
Guild Street, Dublin 1
Asia/Pacific Office
20 Hunter St, Level 7
Sydney NSW 2000
View our other locations
Example POST URL: https://api.hubapi.com/contacts/v1/contact/batch/ Example POST body: This includes updates to some standard properties for two contacts, one existing contact identified by the contact vid, and another contact that may or may not exist, identified by email: [ { "vid": "259429", "properties": [ { "property": "firstname", "value": "Harper" }, { "property": "lastname", "value": "Wolfberg" }, { "property": "website", "value": "http://hubspot.com" }, { "property": "company", "value": "HubSpot" }, { "property": "phone", "value": "555-122-2323" }, { "property": "address", "value": "25 First Street" }, { "property": "city", "value": "Cambridge" }, { "property": "state", "value": "MA" }, { "property": "zip", "value": "02139" } ] }, { "email": "testingapis@hubspot.com", "properties": [ { "property": "firstname", "value": "Codey" }, { "property": "lastname", "value": "Huang" }, { "property": "website", "value": "http://hubspot.com" }, { "property": "company", "value": "HubSpot" }, { "property": "phone", "value": "555-122-2323" }, { "property": "address", "value": "25 First Street" }, { "property": "city", "value": "Cambridge" }, { "property": "state", "value": "MA" }, { "property": "zip", "value": "02139" } ] } ] Returns a 202 Accepted response with no content on success.
import requests import json url = "https://api.hubapi.com/contacts/v1/contact/batch" querystring = {"hapikey":"demo"} payload = json.dumps( [ { "vid": "259429", "properties": [ { "property": "firstname", "value": "Harper" }, { "property": "lastname", "value": "Wolfberg" }, { "property": "website", "value": "http://hubspot.com" }, { "property": "company", "value": "HubSpot" }, { "property": "phone", "value": "555-122-2323" }, { "property": "address", "value": "25 First Street" }, { "property": "city", "value": "Cambridge" }, { "property": "state", "value": "MA" }, { "property": "zip", "value": "02139" } ] }, { "email": "testingapis@hubspot.com", "properties": [ { "property": "firstname", "value": "Codey" }, { "property": "lastname", "value": "Huang" }, { "property": "website", "value": "http://hubspot.com" }, { "property": "company", "value": "HubSpot" }, { "property": "phone", "value": "555-122-2323" }, { "property": "address", "value": "25 First Street" }, { "property": "city", "value": "Cambridge" }, { "property": "state", "value": "MA" }, { "property": "zip", "value": "02139" } ] } ] ); headers = { 'Content-Type': "application/json", } response = requests.request("POST", url, data=payload, headers=headers, params=querystring) print(response.status_code)
var request = require("request"); var options = { method: 'POST', url: 'https://api.hubapi.com/contacts/v1/contact/batch/', qs: { hapikey: 'demo' }, headers: { 'Content-Type': 'application/json' }, body: [ { vid: '259429', properties: [ { property: 'firstname', value: 'Harper' }, { property: 'lastname', value: 'Wolfberg' }, { property: 'website', value: 'http://hubspot.com' }, { property: 'company', value: 'HubSpot' }, { property: 'phone', value: '555-122-2323' }, { property: 'address', value: '25 First Street' }, { property: 'city', value: 'Cambridge' }, { property: 'state', value: 'MA' }, { property: 'zip', value: '02139' } ] }, { email: 'testingapis@hubspot.com', properties: [ { property: 'firstname', value: 'Codey' }, { property: 'lastname', value: 'Huang' }, { property: 'website', value: 'http://hubspot.com' }, { property: 'company', value: 'HubSpot' }, { property: 'phone', value: '555-122-2323' }, { property: 'address', value: '25 First Street' }, { property: 'city', value: 'Cambridge' }, { property: 'state', value: 'MA' }, { property: 'zip', value: '02139' } ] } ], json: true }; request(options, function (error, response, body) { if (error) throw new Error(error); console.log(response.statusCode); });