Contacts (Lead / Contact-type Objects)

This section discusses how to interate your contact or lead type objects. This will focus on interacting with individual records, however there are other endpoints available for creating or updating records in bulk. You are also able to store any custom data that is pertinent by creating custom fields for contacts, and populating them when creating or updating contact objects.Please see the Contacts API Overview for more information on all available endpoints.

You are also able to store any custom data that is pertinent by creating custom fields for contacts, and populating them when creating or updating contact objects.

Keeping Your Database Updated

Poll the ‘Get Recently Updated and Created Contacts‘ API every five minutes for any new or updated contacts from HubSpot, and then update your internal database with any new data returned. We recommend keeping a timestamp of the last update to a given contact property within your internal system, and then comparing that with a timestamp taken whenever an update API call is made to ensure that your internal database always has the newest data.

In the event that your system contains more recent data than HubSpot, use the ‘Create or Update a Contact‘ endpoint outlined below to update the data.

Creating a New or Updating an Existing Contact

Create new contacts or update contacts in HubSpot via the ‘Create or Update a Contact‘ endpoint. This will return the ‘vid’, which is the unique identifier of the contact within HubSpot; we recommend that you record this value against the contact within your own infrastructure. Also returned will be a flag, 'isNew' indicating whether the contact was newly created or whether an existing contact was updated.

You're also able to update a contact using the 'Update a Contact' endpoint, passing the vid of the relevant contact with the call. With this endpoint, success will be indicated by the returned HTTP status 204 with the response.

Deleting a Contact

You can delete a contact by using the ‘Delete a Contact’ endpoint, passing ‘vid’ of the relevant contact with the call. Successful deletion of the contact will be indicated by the return of HTTP status 200 with the response, which will be a JSON object with two fields; 'deleted', which will return true when the contact has been successfully deleted, as well as the vid of the deleted contact.

Associating a Contact with a Company

To associate a contact to a company, first create the company using the relevant endpoint, storing the returned ‘companyId’ against the object within your own system. Then, update the relevant contact using the Create or Update a Contact, ensuring to set the ‘associatedCompanyId’ property to the returned ‘companyId’. You can do this in bulk using our batch update API.