Update an existing contact

Last updated November 13, 2019

POST /contacts/v1/contact/vid/:vid/profile

Method Details

HTTP Methods:


Content Type:


Response Format:


Requires Authentication?


Rate Limited?





Marketing & CRM

Required Scope:


Update an existing contact in HubSpot. This method lets you update the properties of a contact in HubSpot. For example, this endpoint could be used to update an existing contact when you are syncing between an external database and HubSpot, and the corresponding record has been changed. 

To update a contact, you should make an HTTP POST call to this endpoint with some JSON in the request payload. This JSON should contain properties from the contact that you want to add to or update. See the sample JSON to the right for an example of this snippet of JSON.

If you are trying to close a contact into a customer via the API, you should be updating the 'lifecyclestage' property and setting the value of this property to 'customer'.

Remember, if a property doesn't yet exist, you can create a new custom property through the API by using the 'Create Property' method.

Required Parameters How to use Description
OAuth Access Token or API Key Authorization: Bearer {token} header
or hapikey={key} query parameter.
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).
Optional Parameters How to use Description
None None No optional parameters for this method.

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.

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

If the request succeeds, you'll get an HTTP 204 response, which represents that you have successfully updated the contact in the system.

The response from this API call are 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.

  • 204 when a contact is updated
  • 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.
  • 401 when an unauthorized request is made, such as an expired access token of wrong API key.
  • 404 when there is no existing contact with the specified vid.
  • 500 when an internal server error occurs. Please alert us in the API Forum if you receive an HTTP 500 error.

These code samples use a demo API key. Using this key for anything but GET requests will result in an error. For all other requests (such as POST or PUT), you'll need to use your own API key or OAuth. For more details, please see here