Create a new contact | Hubspot Contacts API – Hubspot Create Contact Endpoint
Hi there! Hope you are doing good. If you are here that means you are looking for a way to create contacts in HubSpot. Good news! You are at the perfectly right place. In this article, I will help you set up the Hubspot Contact API and will walk you through on how to use HubSpot Create Contact endpoint of Hubspot Contact API to create a new contact.
When to use Hubspot Create Contact API?
If your contact data is present in another system apart from Hubspot CRM. You will want to bring all the contact data into one place for better analysis and tracing of campaigns, sales, etc.
Hubspot provides flexibility to integrate data from your other system into it. You can use Hubspot Create Contact API (i.e Create Contact endpoint of Hubspot Contact API) to create third-party or offline contact into HubSpot even if the data doesn’t fit the Hubspot default properties. There are some constraints though which will be discussed later.
The Hubspot Create Contact API can also be used to create contacts that are collected by other domains of the same company (i.e cross-domain functionality). This API can create hundreds of contact in seconds thus saving a lot of time.
So let’s get started!
Before we see different ways of using the create a contact endpoint of Hubspot Contact API. We need to have some must-needed HubSpot credentials. In Hubspot, an API call can be made successfully in two ways. First, by using the HubSpot API key. Second, By creating a HubSpot API call with an Access token. In this article, I will be discussing both ways. You can choose whichever suits you the best.
NOTE: Hubspot Access Token has a 30-minute expiry. That means you need to refresh the Access Token after 30 min.
To get the HubSpot API or Hubspot Access Token you can see my guide on getting started with Hubspot API. In the getting started guide I have listed the step-by-step procedure of getting the Hubspot API and a way of generating the Access Tokens.
I assume, by now you will have the Hubspot API key or Hubspot Access Token. So let’s proceed with creating a new contact in HubSpot using the Hubspot Contact API’s Create a New Contact endpoint. More details Create a New Contact endpoint can be found here.
Create a new Hubspot contact using Hubspot API Key
As we mentioned we will be making Hubspot API calls using python. So we start with creating a python file. In this article, I will be naming that file as create-hs-contact-api.py. This will be our executable file.
First, create a function that uses the Hubspot Contact API and a post-call. As you can see from the below code we are using the Hubspot API key and “https://api.hubapi.com/contacts/v1/contact/?” (i.e Create a New Contact endpoint of Hubspot Contact API).
def create_contact(apikey):
try:
url = "https://api.hubapi.com/contacts/v1/contact/?"
parameter_dict = {"hapikey": apikey}
headers = {"Content-Type": "application/json"}
parameters = urllib.parse.urlencode(parameter_dict)
get_url = url + parameters
data = json.dumps(contact_dt)
response = requests.post(url=get_url, data=data, headers=headers)
return response
except:
print("\n *** Function (create_contact) Failed *** ",sys.exc_info()())
On the creation of a new contact, the response will consist of status code 200 and some details about the newly created contact. The most important detail you need to note down is the vid. VID is the contact unique id that you can use to query and shortlist contacts in the HubSpot dashboard.
Remember!
Hubspot Create a Contact endpoint that is mostly used to create offline contact. Hence does not support lead tracking. If you want to syn online contact I suggest you use the Form Submission Endpoint of Hubspot Contact API.
Let’s move forward, we saw the futon that will use the HubSpot contact API to create a new contact. Let us see how to call this function.
To call the above function we will add a function call within if __name__ == ‘__main__’ under create-hs-contact-api.py . The if __name__ == ‘__main__’ code is attached below.
NOTE:
You can directly call the above function somewhere in python after the function declaration.
if __name__ == '__main__':
try:
timestamp = datetime.datetime.strftime(datetime.datetime.now(),'%Y-%m-%d %H:%M')
print("DATE : ",timestamp,"\n")
print("HubSpot Contact creation using Hubspot Contact Create API")
hapikey = 'Replace with the Hubspot API Key'
status = create_contact(hapikey)
print("\n Create Contact :\n",status)
contact_detail = json.loads(status.text)
print(contact_detail)
#print(contact_detail['vid'])
print("\nCreate contact processing Finished \n")
except:
print("\n *** Create contact processing Failed *** ", sys.exc_info())
You are not done yet. The most important part is the new contact payload. A sample of the contact payload is provided below.
contact_dt = {
"properties":
[
{
"property": "email",
"value": "[email protected]"
},
{
"property": "firstname",
"value": "CreateContactDemo2022-03-24_1"
},
{
"property": "lastname",
"value": "CreateContactDemo2022-03-24_1"
},
{
"property": "website",
"value": "http://CreateContactTestDemo2022-03-24_1.com"
},
{
"property": "company",
"value": "CreateContactDemoGONE"
},
{
"property": "phone",
"value": "555-122-2323"
},
{
"property": "address",
"value": "25 First Street"
},
{
"property": "city",
"value": "ContactCity"
},
{
"property": "state",
"value": "ContactState"
},
{
"property": "zip",
"value": "ContactZip"
},
{
"property": "hs_analytics_source",
"value": "ORGANIC_SEARCH"
}
]
}
Above the contact payload, you can directly place it in create-hs-contact-api.py. If you want to put it in a separate JSON file you can do that too. Just remember to read that JSON file in a python file properly.
Note:
As per my understanding of the Hubspot Create Contact endpoint, you can’t update the default property of a contact. For example, you can’t set “first page seen”, “last page seen”, “referrals”, “form title”, etc. Basically, you can’t control or edit the non-editable fields of the HubSpot contact property.
Finally, to run the code successfully you will need to import the below python library.
import sys import datetime import json import urllib import requests
Another thing I would like to mention is if you are creating an already existing contact the HubSpot create contact API will not create a duplicate contact. In this case, the response status will be 200 but the contact details will be of an already existing contact VID.
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 identity profile 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.
Create a new Hubspot contact using Hubspot Access Token
NOTE: The code to use HubSpot to create a contact endpoint remains the same.
#!/usr/local/bin/python3
# command to run this code $ python3 ./create-contact-api.py
import sys
import datetime
import json
import requests
contact_dt = {
"properties":
[
{
"property": "email",
"value": "[email protected]"
},
{
"property": "firstname",
"value": "CreateContactDemo2022-03-24_1"
},
{
"property": "lastname",
"value": "CreateContactDemo2022-03-24_1"
},
{
"property": "website",
"value": "http://CreateContactTestDemo2022-03-24_1.com"
},
{
"property": "company",
"value": "CreateContactDemoGONE"
},
{
"property": "phone",
"value": "555-122-2323"
},
{
"property": "address",
"value": "25 First Street"
},
{
"property": "city",
"value": "ContactCity"
},
{
"property": "state",
"value": "ContactState"
},
{
"property": "zip",
"value": "ContactZip"
},
{
"property": "hs_analytics_source",
"value": "ORGANIC_SEARCH"
}
]
}
def create_contact(access_token):
try:
url = "https://api.hubapi.com/contacts/v1/contact/?"
headers = {"Content-Type": "application/json","Authorization": "Bearer "+access_token}
data = json.dumps(contact_dt)
response = requests.post(url=url, data=data, headers=headers)
return response
except:
print("\n *** Function (create_contact) Failed *** ",sys.exc_info()())
if __name__ == '__main__':
try:
timestamp = datetime.datetime.strftime(datetime.datetime.now(),'%Y-%m-%d %H:%M')
print("DATE : ",timestamp,"\n")
print("HubSpot Contact creation using Hubspot Contact Create API")
access_token = 'Replace with you Hubspot Access Token'
status = create_contact(access_token)
print("\n Create Contact :\n",status)
contact_detail = json.loads(status.text)
print(contact_detail)
#print(contact_detail['vid'])
print("\nCreate contact processing Finished \n")
except:
print("\n *** Create contact processing Failed *** ", sys.exc_info())
Hope I was able to solve the problem. If you like this article and think it was easy to understand do share it with your friends and connection. Thank you! see you soon.
If you have any questions or comments feel free to reach me at.
Checkout out my other API Integration and Coding Solution Guide