There's a new version of the HubSpot API
We're also working on a new documentation website, you're invited to check it out and give us your feedback.
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:
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:
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:
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:
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:
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:
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:
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:
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
- GreySUCCESS
- GreenWARNING
- YellowDANGER
- RedINFO
- BlueExample 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:
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: