Create a new contact | Contacts API

Method Details

HTTP Methods:

POST

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Headers

Products:

Marketing & CRM

Required Scope:

crm.objects.contacts.write

The create a new contact endpoint is used to create a new contact in HubSpot. The new contact will be assigned a unique ID (vid), which can be used to look it up later.

Use case for this endpoint: This endpoint can be used to perform a one-time sync of new contacts from an external system into HubSpot.

Need to create or update multiple contacts? Try the Batch API.

Note: This endpoint is designed for offline contacts and does not support lead tracking. If your contacts come through online forms, use the form submission endpoint.

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 properties	"properties": [...] Used in the request body	A list of contact properties that you want to set for the new contact record. Each entry in the list must include the internal name of the property, and the value that you want to set for that property. Note: You must include at least one property for the new contact or you will receive an error.

Optional parameters	How to use	Description
Email address	Used in the request body	While we recommend that all contact records include an email address, it is possible to create contacts without an email address by leaving out the email property.

Example URL to POST to: https://api.hubapi.com/contacts/v1/contact/?hapikey=demo

Response details

Returns a 200 response on success, which will include the details for the created contact
Returns a 409 Conflict if there is an existing contact with the email address included in the request. The response body will have the identityProfile details of the contact, which will include the vid of the existing record.
Returns a 400 error when there is a problem with the data in the request body, including when there are no properties included in the request data.

Example POST URL: https://api.hubapi.com/contacts/v1/contact/ Example POST body: The code sample below represents some example JSON with standard fields to pass in the body of your request in order to create a new contact: { "properties": [ { "property": "email", "value": "testingapis@hubspot.com" }, { "property": "firstname", "value": "Adrian" }, { "property": "lastname", "value": "Mott" }, { "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 an HTTP 200 response on success, with the response body containing the details of the new contact record: { "identity-profiles": [ { "identities": [ { "timestamp": 1331075050646, "type": "EMAIL", "value": "fumanchu@hubspot.com" }, { "timestamp": 1331075050681, "type": "LEAD_GUID", "value": "22a26060-c9d7-44b0-9f07-aa40488cfa3a" } ], "vid": 61574 } ], "properties": { "website": { "value": "http: //hubspot.com", "versions": [ { "timestamp": 1331075050646, "selected": false, "source-label": null, "value": "http: //hubspot.com", "source-type": "API", "source-id": null } ] }, "city": { "value": "Cambridge", "versions": [ { "timestamp": 1331075050646, "selected": false, "source-label": null, "value": "Cambridge", "source-type": "API", "source-id": null } ] }, "firstname": { "value": "Adrian", "versions": [ { "timestamp": 1331075050646, "selected": false, "source-label": null, "value": "Adrian", "source-type": "API", "source-id": null } ] }, "zip": { "value": "02139", "versions": [ { "timestamp": 1331075050646, "selected": false, "source-label": null, "value": "02139", "source-type": "API", "source-id": null } ] }, "lastname": { "value": "Mott", "versions": [ { "timestamp": 1331075050646, "selected": false, "source-label": null, "value": "Mott", "source-type": "API", "source-id": null } ] }, "company": { "value": "HubSpot", "versions": [ { "timestamp": 1331075050646, "selected": false, "source-label": null, "value": "HubSpot", "source-type": "API", "source-id": null } ] }, "phone": { "value": "555-122-2323", "versions": [ { "timestamp": 1331075050646, "selected": false, "source-label": null, "value": "555-122-2323", "source-type": "API", "source-id": null } ] }, "state": { "value": "MA", "versions": [ { "timestamp": 1331075050646, "selected": false, "source-label": null, "value": "MA", "source-type": "API", "source-id": null } ] }, "address": { "value": "25FirstStreet", "versions": [ { "timestamp": 1331075050646, "selected": false, "source-label": null, "value": "25FirstStreet", "source-type": "API", "source-id": null } ] }, "email": { "value": "fumanchu@hubspot.com", "versions": [ { "timestamp": 1331075050646, "selected": false, "source-label": null, "value": "fumanchu@hubspot.com", "source-type": "API", "source-id": null } ] } }, "form-submissions": [ ], "vid": 61574 }

import requests import json endpoint = 'https://api.hubapi.com/contacts/v1/contact/?hapikey=demo' headers = {} headers["Content-Type"]="application/json" data = json.dumps({ "properties": [ { "property": "email", "value": "testingapis@hubspot.com" }, { "property": "firstname", "value": "test" }, { "property": "lastname", "value": "testerson" }, { "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" } ] }) r = requests.post( url = endpoint, data = data, headers = headers ) print(r.text)

˂?php $arr = array( 'properties' => array( array( 'property' => 'email', 'value' => 'apitest@hubspot.com' ), array( 'property' => 'firstname', 'value' => 'hubspot' ), array( 'property' => 'lastname', 'value' => 'user' ), array( 'property' => 'phone', 'value' => '555-1212' ) ) ); $post_json = json_encode($arr); $hapikey = readline("Enter hapikey: (demo for the demo portal): "); $endpoint = 'https://api.hubapi.com/contacts/v1/contact?hapikey=' . $hapikey; $ch = @curl_init(); @curl_setopt($ch, CURLOPT_POST, true); @curl_setopt($ch, CURLOPT_POSTFIELDS, $post_json); @curl_setopt($ch, CURLOPT_URL, $endpoint); @curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json')); @curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = @curl_exec($ch); $status_code = @curl_getinfo($ch, CURLINFO_HTTP_CODE); $curl_errors = curl_error($ch); @curl_close($ch); echo "curl Errors: " . $curl_errors; echo "\nStatus code: " . $status_code; echo "\nResponse: " . $response; ?>

var request = require("request"); var options = { method: 'POST', url: 'https://api.hubapi.com/contacts/v1/contact/', qs: { hapikey: 'demo' }, headers: { 'Content-Type': 'application/json' }, body: { properties: [ { property: 'email', value: 'testingapis@hubspot.com' }, { property: 'firstname', value: 'test' }, { property: 'lastname', value: 'testerson' }, { 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(body); });