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.

Extension property types

Each property you define for your object type will have a definition in the propertyDefinitions list on an object type. An example definition is below:

{
  "propertyDefinitions": [
    {
      "name": "example_property",
      "label": "Example property",
      "dataType": "STRING"
    },
    //...
  ]
}
  • name: The application-friendly name of the property. This must match the key of the property value of Sales Objects in the data fetch response.
  • label: The label of the property that will show up for the user.
  • dataType: The type of property this is. Can be one of CURRENCY, DATE, DATETIME, EMAIL, LINK, NUMERIC, STATUS, or STRING. The following sections provide details on each type of property.

Then in the response to the data fetch request, the value for this property will look like:

{
  "results": [
    {
      "example_property": "Example value",
      //...
    },
    //...
  ]
  //...
}

This property will show up in the UI like:

example_property sceenshot

Properties may also be specified on a per-object basis. This is handy for data points unique to a specific object. These properties may be defined in the response to the data fetch request, in the properties list on a specific Sales Object.

{
  "results": [
    {
      "properties": [
        {
          "label": "Example custom property",
          "dataType": "STRING",
          "value": "Example custom value"
        }
      ]
      //...
    }
    //...
  ]
  //...
}
  • label: The label of the property that will show up for the user.
  • dataType: The type of property this is. Can be one of CURRENCY, DATE, DATETIME, EMAIL, LINK, NUMERIC, STATUS or STRING. The following sections provide details on each type of property.
  • value: The value for this property.

No name field is needed for custom properties.

This custom property will display as:

example custom property screenshot

Currency Properties

Currency properties are used to show currency values. When specifying a value for a currency, a currency code must be provided. The currency code must be a valid ISO 4217 currency code. These will be shown to the user with the correct currency symbol and the number formatted according to the user's locale.

Example property definition on an object type:

{
  "name": "example_currency_property",
  "label": "Example currency property",
  "dataType": "CURRENCY"
}

Example property value:

{
  "results": [
    {
      "example_currency_property": {
        "value": 99.56,
        "currencyCode": "USD"
      },
      //...
    },
    //...
  ]
  //...
}

Example custom property value:

{
  "results": [
    {
      "properties": [
        {
          "label": "Example custom currency property",
          "dataType": "CURRENCY",
          "value": 99.56,
          "currencyCode": "USD"
        }
      ]
      //...
    }
    //...
  ]
  //...
}

Example display:

example currency property

Date Properties

Date properties indicate a whole day. Integrators can use datetime properties if they need to indicate a specific time. The value for date properties should be in the format: yyyy-mm-dd. These properties will be displayed as a date in a format appropriate to the user's locale.

Example property definition on an object type:

{
  "name": "example_date_property",
  "label": "Example date property",
  "dataType": "DATE"
}

Example property value:

{
  "results": [
    {
      "example_date_property": "2016-10-01",
      //...
    },
    //...
  ]
  //...
}

Example custom property value:

{
  "results": [
    {
      "properties": [
        {
          "label": "Example custom date property",
          "dataType": "DATE",
          "value": "2016-10-01"
        }
      ]
      //...
    }
    //...
  ]
  //...
}

Example display:

example date property

Datetime Properties

Datetime properties indicate a specific time. Datetime properties must be provided as milliseconds since epoch. These properties will be displayed in a format appropriate to the user's locale.

Example property definition on an object type:

{
  "name": "example_datetime_property",
  "label": "Example datetime property",
  "dataType": "DATETIME"
}

Example property value:

{
  "results": [
    {
      "example_datetime_property": 1475447180000,
      //...
    },
    //...
  ]
  //...
}

Example custom property value:

{
  "results": [
    {
      "properties": [
        {
          "label": "Example custom datetime property",
          "dataType": "DATETIME",
          "value": 1475447180000
        }
      ]
      //...
    }
    //...
  ]
  //...
}

Example display:

example datetime property

Email Properties

Email properties are for values that contain an email address. These properties will be displayed as "mailto:" links.

Example property definition on an object type:

{
  "name": "example_email_property",
  "label": "Example email property",
  "dataType": EMAIL
}

Example property value:

{
  "results": [
    {
      "example_email_property": "test@example.com",
      //...
    },
    //...
  ]
  //...
}

Example custom property value:

{
  "results": [
    {
      "properties": [
        {
          "label": "Example custom email property",
          "dataType": "EMAIL",
          "value": "test@example.com"
        }
      ]
      //...
    }
    //...
  ]
  //...
}

Example display:

example email property

Link properties can be used to display links to the user. These links will open in new windows. A linkLabel may be specified as part of the property value, otherwise the provided URI will be displayed to the user.

Example property definition on an object type:

{
  "name": "example_link_property",
  "label": "Example link property",
  "dataType": LINK
}

Example property value:

{
  "results": [
    {
      "example_link_property": {
        "value": "https://www.example.com/link",
        "linkLabel": "Test Link"
      }
      //...
    },
    //...
  ]
  //...
}

Example custom property value:

{
  "results": [
    {
      "properties": [
        {
          "label": "Example custom link property",
          "dataType": "LINK",
          "value": "https://www.example.com/link",
          "linkLabel": "Test Link"
        }
      ]
      //...
    }
    //...
  ]
  //...
}

Example display:

example link property

Numeric Properties

Numeric properties can be used to display numbers. Numbers will be displayed in format appropriate to the user's locale.

Example property definition on an object type:

{
  "name": "example_numeric_property",
  "label": "Example numeric property",
  "dataType": NUMERIC
}

Example property value:

{
  "results": [
    {
      "example_numeric_property": 123.45,
      //...
    },
    //...
  ]
  //...
}

Example custom property value:

{
  "results": [
    {
      "properties": [
        {
          "label": "Example custom numeric property",
          "dataType": "NUMERIC",
          "value": 123.45
        }
      ]
      //...
    }
    //...
  ]
  //...
}

Example display:

example numeric property

Status Properties

Status properties will be shown to the user as a colored status indicator. To define a status property on the object type the integrator must provide a list of options, that describe the possible statuses.

Example property definition on an object type:

{
  "name": "example_status_property",
  "label": "Example status property",
  "dataType": "STATUS",
  "options": [
    {
      "name": "in_progress",
      "label": "In progress",
      "type": "SUCCESS"
    },
    {
      "name": "resolved",
      "label": "Resolved",
      "type": "DEFAULT"
    }
  ]
}

Each option contains a:

  • name: The program-friendly name of this option. The incoming value will need to match an option name.
  • label: The label to be shown to the user.
  • type: The option's type controls what color the status indicator will appear as:
    • DEFAULT - Grey
    • SUCCESS - Green
    • WARNING - Yellow
    • DANGER - Red
    • INFO - Blue

Example property value:

{
  "results": [
    {
      "example_status_property": "in_progress",
      //...
    },
    //...
  ]
  //...
}

Example custom property value. Custom status properties do not need to define all possible statuses, just the current value:

{
  "results": [
    {
      "properties": [
        {
          "label": "Example custom status property",
          "dataType": "STATUS",
          "value": "Errors occuring",
          "optionType": "DANGER"
        }
      ]
      //...
    }
    //...
  ]
  //...
}

Example display:

example status property

String Properties

String properties display basic string data to the user.

Example property definition on an object type:

{
  "name": "example_string_property",
  "label": "Example string property",
  "dataType": STRING
}

Example property value:

{
  "results": [
    {
      "example_string_property": "test value",
      //...
    },
    //...
  ]
  //...
}

Example custom property value:

{
  "results": [
    {
      "properties": [
        {
          "label": "Example custom string property",
          "dataType": "STRING",
          "value": "test value"
        }
      ]
      //...
    }
    //...
  ]
  //...
}

Example display:

example string property