There's a new version of the HubSpot API

Check out the new API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Update an existing contact by email

Last updated May 15, 2023

POST /contacts/v1/contact/email/:email/profile

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 allows you to update an existing contact in HubSpot, identified by email.

Use case for this endpoint: Because this method allows you to update contact properties, it could be used by an integration to synchronize contact data from an external CRM by email address.

Note: This endpoint will return a 404 if there is no existing record with the specified email address. If you're looking to automatically create or update contacts using an email address, you can use this 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.
Email Used in the request URL The email address of the record that you want to update.
Contact JSON Used in the request body This is JSON that represents a contact that you're updating. This should be of the format seen below in the code sample given. Properties can have an optional timestamp indicating when the property was set (this will be the current time if not specified).

Property notes

There are some properties that are worth noting in terms of updating a contact:

  • Lifecycle Stage - This property denotes the stage at which the contact is in. Stages include 'subscriber', 'lead', 'marketingqualifiedlead', 'salesqualifiedlead', 'opportunity' and 'customer'. These values are described in HubSpot's Contacts application under "Contacts > Manage Settings > Lifecycle Stages". Once a contact does become a "customer", it will be reflected in HubSpot's Sources application as such.
  • Please Note The Lifecycle stage is not designed to move backwards. If you need to set this property to an previous stage, you will first need to set the value to "" (an empty string) and then set the new Stage
  • HubSpot Score - This property cannot be updated through the API.
  • Email address - It is possible to update the email address of contacts using this endpoint. The current email address must be used in the URL to identify the existing contact in HubSpot, and the new email would go in the JSON in the request body.
  • If a property doesn't exist yet, you can create a new custom property through the API by using the create property method.

Example URL to POST to:  https://api.hubapi.com/contacts/v1/contact/email/testingapis@hubspot.com/profile

Response details

This endpoint returns standard REST-style HTTP response codes that mark success or failure, with meta information about the call that was made. There will be no data in the response body.

  • Returns a 204 response with no response body when a contact is successfully updated.
  • Returns a 400 if there is a problem with the data in the request body. You'll get a message in the response body detailing the issues with the data.
  • Returns a 401 when an unauthorized request is made, such as an expired access token.
  • Returns a 404 when there is no existing record with the email address specified in the request URL.
  • Returns a 500 when an internal server error occurs. Please alert us in the API Forum if you receive an HTTP 500 error.

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/email/testingapis@hubspot.com/profile Example POST body: { "properties": [ { "property": "firstname", "value": "Updated" }, { "property": "lastname", "value": "Record" }, { "property": "website", "value": "http://updated.example.com" }, { "property": "lifecyclestage", "value": "customer" } ] } Returns a 204 No Content response on success.
import requests import json url ='https://api.hubapi.com/contacts/v1/contact/email/tester123@hubspot.com/profile?hapikey=demo' headers = {} headers['Content-Type']= 'application/json' data=json.dumps({ "properties": [ { "property": "email", "value": "tester123@hubspot.com" }, { "property": "firstname", "value": "test" }, { "property": "lastname", "value": "testerson" }, { "property": "website", "value": "http://updated.example.com" }, { "property": "lifecyclestage", "value": "customer" } ] }) r = requests.post(data=data, url=url, headers=headers) print(r.status_code)