Contacts API Overview

What is the Contacts API?

Contacts are the fundamental building block to HubSpot - they store lead-specific data that makes it possible to leverage much of the functionality in HubSpot, from marketing automation, to lead scoring to smart content.

If you've come across contacts in a CRM or Marketing Automation system before, you're already familiar with the core concepts. For an in depth look at the way HubSpot customers use their contacts database, refer to our Contacts User Guide.

Please note that there are a few limits for contact records in place that may affect any testing you do with the Contacts API. Please see the list of contact and form limits.

Using the Contacts API

Because of the central role contacts play in the HubSpot application, it is not surprising that most integrations with HubSpot either read or write Contacts data. As such the two most important endpoints in the API are the create and get Contacts endpoints. You are also able to store any custom data that is pertinent by creating custom fields for contacts. For many methods, there are also batch endpoints that allow you to make a GET or POST that can return or create/update many contacts at once.

One important distinction to note about the HubSpot Contacts API is that the primary key for a contact in the HubSpot system is an email address. The API automatically de-duplicates on email address to assure data cleanliness inside of HubSpot.

For any specific questions about the Contacts API, refer to our developer forum, where many of the common questions have already been asked.

Contacts will have the following data. Note: With the exception of the individual contact property values, all of 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": [],
  // 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-mNpfeDlBFPw-gwIYuc2emT2JH3FQHoCSCf0ZK7A_VX_yekUULeY_I7OGDxcGjmPzycvDOdCJao5iBvXx5Nl5EgcXFtfO60pA312dcjTKvJxJ_0TC2MyD5GII4BKtAfLd-GsyaBk",
  // String; A unique token that can be used to view the contact without logging into HubSpot. See the profile-url below.
  "profile-url": "https://app.hubspot.com/contacts/62515/lists/public/contact/_AO_T-mNpfeDlBFPw-gwIYuc2emT2JH3FQHoCSCf0ZK7A_VX_yekUULeY_I7OGDxcGjmPzycvDOdCJao5iBvXx5Nl5EgcXFtfO60pA312dcjTKvJxJ_0TC2MyD5GII4BKtAfLd-GsyaBk/",
  // String; A URL that can be used to view the contact data without logging in. Anyone with this link would be able to view (but not edit) the record
  // Note: You can force a login for the public link by changing the Public View Login option in your Contact Settings
  "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`
      }
    }
  ]
}

Source-type

The source type of a property version indicates how the property was changed.

  • 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 calcualted 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