Contacts API Overview

There's a new version of the Contacts API. We've redesigned our contacts API and it is out now in developer preview. Check out the new API

What is the Contacts API?

In HubSpot, contacts store information about an individual. From marketing automation to smart content, the lead-specific data found in contact records helps users leverage much of HubSpot's functionality. The Contacts API allows you to manage this data and sync it between HubSpot and other systems.

Use case for this API: Your team is using HubSpot and another software system for their work. They need accurate contact information in both systems, but don't want to spend time making manual updates. You use the Contacts API to integrate the two systems and sync contact information. 

Contacts, along with companies, deals, tickets, line items, products, and quotes, are objects in the HubSpot CRM. Learn more about CRM objects in our Guide to Records.

Limits

There are a few limits in place for contact records, which may affect any testing you do with the Contacts API. For more information, read about contact and form limits.

Batch endpoints

For many methods, there are batch endpoints allowing you to make a GET or POST call that can return or create/update many contacts at once.

Deduplication

The primary identifier for a contact in HubSpot is an email address. The Contacts API automatically de-duplicates email addresses in HubSpot.

Contact properties

Details for your contact records are primarily stored in contact properties. In addition to several default properties, HubSpot users can store any necessary custom data by creating custom contact properties.

Note: To allow for new functionality, HubSpot will occasionally update existing default properties, and users may also change their custom properties from time to time. If your integration works with contacts, it's recommended that you use the Contact Properties API to periodically poll for updates.

Contact owners

The owner of a contact record is controlled through the contact owner property, which uses the internal name of hubspot_owner_id. When using this property through the Contacts API, you will need the internal ID of the owner. Owner details, including IDs and email addresses, can be obtained using the Owners API.

Associations between contacts and other objects

Contacts can be associated with companies, deals, engagements, and tickets. You can create and manage object associations using the CRM Associations API.

Response details

Contacts will return the following data, and with the exception of the individual contact property values, this data will be read-only.

{
  "vid": 3234574,
  // Integer; The internal ID of the contact record.
  "canonical-vid": 3234574,
  // Integer; The internal ID of the contact record.
  // Contacts may have multiple vids, but the canonical-vid will be the primary ID for a record.
  "merged-vids": [3234574,407546],
  // A list of vids that have been merged into this contact record.
  "portal-id": 62515,
  // Integer; The Portal ID (Hub ID) that the record belongs to.
  "is-contact": true,
  // Boolean; Indicates if the record is a valid contact record.
  // Any record where this is set to false is not a valid contact. Those records will only have placeholder data and cannot be updated.
  "profile-token": "AO_T-GsyaBk",
  // DEPRECATED - this field is no longer used
  "profile-url": "https://app.hubspot.com/contacts/62515/contact/12630274",
  // String; A URL that can be used to view the contact in HubSpot
  "properties": {
  // An object containing objects representing the properties that are set for the contact record.
  // The keys in the object represent the API name of the contact property
  // Contacts will only contain an entry for a property if that property has been set for the record.
  // Each property listing will have the following format:
    "createdate": {
    // String; The internal API name of the contact property
      "value": "1484026585538",
      // String; The current value of the property for this contact.
      // Values are always stored internally as a string, regardless of the property type.
      "versions": [
      // A list of the historical values of the property
      // A new versions entry will be added each time the property is updated.
      // This data is read-only, and generated automatically when a property is updated.
        {
          "value": "1484026585538",
          // String; The historical value of the property.
          "source-type": "API",
          // String; The method by which the property was changed.
          // See the type list below for more details.
          "source-id": "Contacts",
          // String or null; Additional data realted to the source-type. May not be populated for all source-types.
          "source-label": null,
          // String or null; Additional data realted to the source-type. May not be populated for all source-types.
          "timestamp": 1484026585538,
          // Integer; A Unix timestamp in milliseconds representing when the property was updated.
          "selected": false
          // This field is deprecated and should not be used.
        }
      ]
    },
    "state": {
      "value": "MA",
      "versions": [
        {
          "value": "MA",
          "source-type": "API",
          "source-id": null,
          "source-label": null,
          "timestamp": 1484026585536,
          "selected": false
        }
      ]
    },
    "zip": {
      "value": "02139",
      "versions": [
        {
          "value": "02139",
          "source-type": "API",
          "source-id": null,
          "source-label": null,
          "timestamp": 1484026585536,
          "selected": false
        }
      ]
    }
  },
  "form-submissions": [
  // A list of form submissions for the contact
  // This list will be empty for records with no form submissions
  // Each submission will have the following format:
    {
      "conversion-id": "06629267-198f-414e-8f2e-90bf2d2bd693",
      // String; A Unique ID for the specific form conversion
      "timestamp": 1484080167266,
      // Integer; A Unix timestamp in milliseconds of the time the submission occurred
      "form-id": "2c5403f2-30fd-4b98-9861-791234aad6d7",
      // String; The GUID of the form that the subission belongs to.
      "portal-id": 62515,
      // Integer; the Portal ID (Hub ID) that the submission belongs to
      "page-url": "https://example.com/landing-page-url",
      // String; The URL that the form was submitted on.
      // This field may be missing if no URL was provided in the submission
      "title": "A new test form",
      // String; The title of the page that the form was submitted on
      // This will default to the name of the form if no title is provided
      "meta-data": []
      // This is a deprecated field and should not be used.
    }
  ],
  "list-memberships": [
  // A list of objects representing the contact's membership in contact lists.
  // This list may be empty if the record is not a member of any lists.
    {
      "static-list-id": 1,
      // Integer; The ID of the contact list
      "internal-list-id": 220441,
      // Integer; DEPRECATED - Use the static ID to look up the contact list.
      "timestamp": 1484026586509,
      // Integer; A Unix timestamp (in milliseconds) for when the contact joined the list.
      "vid": 3234574,
      // Integer; The vid of the contact record.
      "is-member": true
      // Boolean; This will always be true as the API only returns lists that the record is currently a member of.
    }
  ],
  "identity-profiles": [
  // A list of objects representing the identities of the contact
  // Each identity represents an identifier for the object, many records will only have a single identity, but merged records may have multiple 
    {
      "vid": 3234574,
      // Integer; The original vid for this identity
      "saved-at-timestamp": 1484026585613,
      // Integer; A Unix timestamp (in milliseconds) of when the identity was last updated.
      "deleted-changed-timestamp": 0,
      // DEPRECATED - This field is no longer used
      "identities": [
      // A list of the individual identies for this pointer.
        {
          "type": "EMAIL",
          // String, one of EMAIL or LEAD_GUID
          // The type of the identity
          // LEAD_GUID identities are an internal reference and should not be used.
          "value": "testingapis@hubspot.com",
          // String; the value of the identity
          "timestamp": 1484026585538
          // Integer; A Unix timestamp (in milliseconds) for when the identity was created.
        }
      ]
    }
  ],
  "merge-audits": [
  // A list of data related to any merges that have happened for the record
  // This list will be empty for records that have not been merged
    {
      "canonical-vid": 3234574,
      // Integer; vid of the primary contact (record that was merged into).
      "vid-to-merge": 407596,
      // Integer; The vid of the secondary contact (record that the data was merged from).
      "timestamp": 1459183894522,
      // Integer; A Unix timestamp (in milliseconds) of when the merge occurred
      "entity-id": "",
      // DEPRECATED - this field is no longer be used
      "user-id": 100097,
      // Integer; The internal ID of the user who initiated the merge.  This will have no value outside of the HubSpot app.
      "num-properties-moved": 32,
      // Integer; The number of properties updating as a result of the merge
      "merged_from_email": {
      // A set of data from the secondary contact
        "value": "merge2@samsung.wales",
        // String; the email address of the secondary contact at the time of the merge
        "source-type": "CONTACTS_WEB",
        // String; The method by which the email property was last updated
        "source-id": "dadams@hubspot.com",
        // String or null; Additional data realted to the source-type. May not be populated for all source-types.
        "source-label": null,
        // String or null; Additional data realted to the source-type. May not be populated for all source-types.
        "source-vids": [
        // A list of integers, where each entry is a vid from the secondary contact
        // This list may contain multiple entries if the secondary record was previously merged
          407596
        ],
        "timestamp": 1459183770094,
        // Integer; A Unix timestamp (in milliseconds) for when the email address was last updated
        "selected": false
        // DEPRECATED - this field is no longer used
      },
      "merged_to_email": {
      // A set of data for the primary contact
        "value": "merge1@whales.wales",
        // String; the email address of the primary contact at the time of the merge
        "source-type": "CONTACTS_WEB",
        // String; The method by which the email property was last updated.
        "source-id": "dadams@hubspot.com",
        // String or null; Additional data realted to the source-type. May not be populated for all source-types.
        "source-label": null,
        // String or null; Additional data realted to the source-type. May not be populated for all source-types.
        "timestamp": 1459183757761,
        // Integer; A Unix timestamp (in milliseconds) for when the email was last updated
        "selected": false
        // DEPRECATED - this field is no longer used`
      }
    }
  ]
}

 

Questions? If you have more questions about the Contacts API, please refer to our developer forum.

Source-type

The source type of a property version indicates how the property was changed. NOTE: This is separate from the original source for a contact record.

  • API - updated through the Contacts API
  • FORM - the value was updated based on a form submission
  • IMPORT - the value was updated through a contact import
  • ANALYTICS - the value was updated by the analytics system. Any data updated by a custom event would show this source-type
  • SALESFORCE - updated by HubSpot's Salesforce connector
  • CONTACTS_WEB - updated manually in the HubSpot Marketing Contacts app
  • CRM_UI -updated manually in the HubSpot Sales Contacts app
  • MOBILE_IOS, MOBILE_ANDROID - updated by a user using one of the HubSpot mobile apps
  • EMAIL - updated based on data collected by an email sent from HubSpot's Email app
  • WORKFLOWS - updated by a workflow
  • SOCIAL - updated by the HubSpot Social Media app
  • COMPANIES - updated by a change to the associated company, or by being associated with a company
  • DEALS - updated by a change to an associated deal, or by being associated with a deal
  • ENGAGEMENTS - updated by a change to an associated engagement, or by being associated with an engagement
  • INTEGRATION, INTEGRATIONS_PLATFORM - updated by an Integrations Platform API, such as by adding a timeline event to the record
  • MERGE_CONTACTS - updated by the contact being merged with another contact
  • MERGE_COMPANIES - updated as the result of an associated company being merged with another company
  • SALES, ,SIGNALS, SIDEKICK - updated by the HubSpot Sales tools (formally called Signals and Sidekick)
  • LEADIN - updated by the Collected Forms or Lead Flows features included with HubSpot Marketing Free and Marketing Starter
  • BCC_TO_CRM, FORWARD_TO_CRM - updated by forwarding an email to the HubSpot Sales tools
  • GMAIL_INTEGRATION - updated by the Gmail plugin
  • SEQUENCES - updated by the Sequences app in the Sales tools
  • CALCULATED - these values are calculated based on other data in the contact record
  • MIGRATION, WAL_INCREMENTAL, TASK, BATCH_UPDATE, BIDEN, DEFAULT, ASSISTS, PORTAL_USER_ASSOCIATOR, HEISENBERG, ACADEMY, SALES_MESSAGES, AVATARS_SERVICE, COMPANY_FAMILIES - These represent updates from internal system processes.

Docs for this section or API