There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Contact Properties API Overview

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

Contact properties store specific information for contact records in HubSpot. Contacts, along with companies, deals, tickets, line items, products, and quotes, are an object in the HubSpot CRM. Contacts have several default properties, but you can also create custom properties to store more specialized data. The Contact Properties API allows bi-directional syncing of contact property data between HubSpot and other systems, even as fields are added or updated. You can also use it to create new custom properties.

Use case for this API: Let's say your integration needs to keep track of wedding anniversaries for contacts. You can use the Contact Properties API to create a new "anniversary date" contact property and then segment contacts based on this.

Using contact properties

Properties are used as the criteria for contact lists, to segment contacts, and as the starting criteria for workflows. 

If your integration works with contacts, it's recommended that you periodically poll for updates to contact properties, as users may update their custom properties or default property settings may change in HubSpot. 

See our user guide for more details on using properties.

Response details

Each property will return the following data: 

{
  "name": "favorite_color",
    // String; The internal name of the property.  The name should be used when referencing the property through the API
  "label": "Favorite Color",
    // String; A human readable label for the property.  The label is used to display the property in the HubSpot UI.
  "description": "",
    // String; A description of the property. May be an empty string.
  "groupName": "colors",
    // String; The property group that the property belongs to.
  "type": "enumeration",
    // String, one of string, number, date, datetime, or enumeration
    // The data type of the property. See creating a property for more details.
  "fieldType": "select",
    // String, one of textarea, text, date, file, number, select, radio, checkbox, or booleancheckbox
    // Controls how the property appears in a form when the property is used as a form field.
  "options": [
    // A list of valid options for the property.
    // Required for enumerated properties.
    // This will be an empty list for other property types

    { // Each option will have the following data
      "description": null,
        // String or null; a description of the option.
      "doubleData": 0,
        // Integer; DEPRECATED, has no effect on the option.
      "label": "Blue",
        // String; A human readable label for the option. The label is displayed in the HubSpot UI.
      "readOnly": false,
        // Boolean; DEPRECATED, has no effect on the option.
      "displayOrder": -1,
        // Integer; Options are displayed in numerical order based on this value, options with -1 appear after options with positive values
      "hidden": false,
        // Boolean; hidden values will not be displayed in HubSpot
      "value": "blue"
        // String; The internal value of the option.  The value must be used to set the value of the property.
    }
  ],

  "deleted": false,
    // Boolean; This will effectively be false for all properties, as deleted properties will not appear in the API
  "formField": true,
    // Boolean; controls whether or not the property will show up as an option to be used in forms.
  "displayOrder": -1,
    // Integer; Properties are displayed based this value, properties with negative values appear in the order they're created after properties with positive values.
  "readOnlyValue": false,
    // Boolean; A value of true means that the value cannot be set manually, and that only the HubSpot system can update the property.
    // Custom properties should always have this set to false, or the value can't be updated through the API.
  "readOnlyDefinition": false,
    // Boolean; A value of true means that the property settings can't be modified.
    // Custom properties should always have this as false, or the property can't be updated or deleted.
  "hidden": false,
    // Boolean; Hidden fields do not appear in the HubSpot UI
  "mutableDefinitionNotDeletable": false,
    // Boolean; true indicates that the property settings can be modified, but the property cannot be deleted
    // Custom properties should use false
  "favorited": false,
    // Boolean; DEPRECATED, has no effect on the property
  "favoritedOrder": -1,
    // Integer; DEPRECATED, has no effect on the property
  "calculated": false,
    // Boolean; For system properties, true indicates that the property is calculated by a HubSpot process
    // Has no effect for custom properties
  "externalOptions": false,
    // Boolean; For system properties, true indicates that the options are stored 
    // Has no effect on custom properties 
  "displayMode": "current_value"
    // String; DEPRECATED, has no effect on the property
}

Docs for this section or API