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.

Update an existing contact

Last updated May 12, 2023

POST /contacts/v1/contact/vid/:vid/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 is used to update an existing contact in HubSpot. It only updates the properties specified in the request.

Use case for this endpoint: Let's say you've been updating contact records in an external database and now you want to sync those updates to HubSpot. You can use the update an existing contact endpoint to complete the sync and avoid making manual updates.

Example URL to POST to: https://api.hubapi.com/contacts/v1/contact/vid/2340324/profile

Property updates

To update a contact, make an HTTP POST call to this endpoint. The request should specify the relevant contact properties. (See the sample JSON to the right.)

If a property doesn't exist yet, you can create a new custom property through the API using the create property method.

For more information about notable contact properties, see the notes below the required parameters table.

Response details

  • Returns a 204 with no response body when a contact is updated successfully.
  • Returns a 400 if there is a problem with the data in the request body. You'll get a message in the response body with more details.
  • Returns a 401 when an unauthorized request is made, such as an expired access token.
  • Returns a 404 when there is no existing contact with the specified vid (visitor ID).
  • Returns a 500 when an internal server error occurs. Please alert us in the developer forum if this happens.

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 VID Used in the request URL The VID of the specific contact 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).

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 a 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.

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/vid/2340324/profile Example POST body: { "properties": [ { "property": "email", "value": "new-email@hubspot.com" }, { "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/vid/11510974/profile 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)
var request = require("request"); var options = { method: 'POST', url: 'https://api.hubapi.com/contacts/v1/contact/vid/11845824/profile', qs: { hapikey: 'demo' }, headers: { 'Content-Type': 'application/json' }, body: { properties: [ { property: 'email', value: 'new-email@hubspot.com' }, { property: 'firstname', value: 'Updated' }, { property: 'lastname', value: 'Record' }, { property: 'website', value: 'http://updated.example.com' }, { property: 'lifecyclestage', value: 'customer' } ] }, json: true }; request(options, function (error, response, body) { if (error) throw new Error(error); console.log(response.statusCode); });