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.

CRM Object Properties API Overview

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

HubSpot allows you to create custom properties to store specialized information for any CRM object. The CRM Object Properties API allows you to manage any custom properties you may need for tickets, products, and line items, as well as viewing the details for any default properties that are built into HubSpot.

Property groups

Property groups are used to group related properties. When viewing records in HubSpot, any properties in the same group will appear next to each other. If your integration creates any custom properties, it's a good practice to create a custom property group. This makes it easy to tell what data is related to your integration.

Properties will have the following data:

{
  "name": "example_custom_property",
  // String; The internal name of the property. This name must be used whenever referencing the property via the API
  "label": "Example custom product property",
  // String; A human readable label for the property. This will be used when viewing records in HubSpot.
  "description": "This is an example property",
  // String; A description of the property. Displayed as help text when viewing records in HubSpot.
  "groupName": "productinformation",
  // String; The name of the property group that the property belongs to.
  "type": "string",
  // String, one of string, number, date, datetime, or enumeration
  // The data type of the property. See creating a property for more details.
  "fieldType": "text",
  // String, one of textarea, text, date, file, number, select, radio, checkbox, or booleancheckbox
  // Controls how the property appears in HubSpot when viewing CRM records.
  "options": [
  // A list of valid options for the property.
  // Required for enumerated properties.
  // This list will be empty for other property types.
  // Each option will have the following format
    {
      "description": null,
      // String; A description of the option
      "label": "First",
      // String; The label of the option.  The label will be displayed inside the HubSpot app.
      "displayOrder": 0,
      // Integer; Options are displayed in order starting with the lowest positive integer value.
      // Values of -1 will cause the option to be displayed after any positive values.
      "hidden": false,
      // Boolean; Hidden options will not be displayed in HubSpot.
      "readOnly": null,
      // DEPRECATED, has no effect on the option.
      "doubleData": null,
      // DEPRECATED, has no effect on the option.
      "value": "first"
      // String; the internal value of the option.  The value of the option must be used when setting the value of the property through the API.
    }
  ],
  "hidden": false,
  // Boolean; If True, the property will not be visible and cannot be used in HubSpot.
  // It is recommended that this be set to false for custom properties.
  "hubspotDefined": null,
  // Boolean or null; This will be true for default properties that are built into HubSpot.
  "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.
  "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,
  // DEPRECATED, has no effect on the property
  "favoritedOrder": -1,
  // DEPRECATED, has no effect on the property
  "displayMode": "current_value",
  // DEPRECATED, has no effect on the property
  "showCurrencySymbol": null,
  // Boolean or null; if true, the property will display the currency symbol set in the portal settings.
  "createdUserId": null,
  // Integer, read-only. The internal user ID of the user that created the property in HubSpot.
  // This field may not exist if the property was not created inside HubSpot.
  "textDisplayHint": null,
  // This field is not currently used.
  "numberDisplayHint": null,
  // This field is not currently used.
  "optionsAreMutable": null,
  // Boolean or null; If true, the options for the property can be modified, even if the other property settings can't be modified
  // Custom properties should not set this field.
  "referencedObjectType": null,
  // String or null; If this property is related to other objects, the object will be listed here.
  // Custom properties should not set this field.
  "isCustomizedDefault": false,
  // This field is not currently used.
  "formField": false,
  // Boolean; Has no effect for properties for these objects.
  "displayOrder": 8,
  // Integer; Properties are displayed in order starting with the lowest positive integer value.
  // Values of -1 will cause the property to be displayed after any positive values.
  "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 externally to the property settings.
  // Has no effect on custom properties
  "deleted": null,
  // Boolean; Whether or not the property is deleted. This will effectively always be false, as deleted properties will not appear in the API.
  "createdAt": 1522555200000,
  // Integer; A Unix timestamp in milliseconds representing when the property was created.
  "updatedAt": 1522555200000,
  // Integer; A Unix timestamp in milliseconds representing when the property was last updated.
  "updatedUserId": null
  // Integer, read-only. The internal user ID of the user that updated the property in HubSpot.
  // This field may not exist if the property was not updated inside HubSpot.
}

Property groups will have the following data:

{
  "portalId": 62515,
  // Integer; The portal ID of the group.
  "name": "examplegroup",
  // String; The internal name of the group.
  "displayName": "An example property group",
  // String; The name displayed for the group when viewing records in HubSpot
  "displayOrder": 2
  // Integer; Groups are displayed in order starting with the lowest positive integer value.
  // Values of -1 will cause the property to be displayed after any positive values.
}

CRM Object Properties API docs

Get all object properties
Create a new object property
Update an object property
Delete an object property
Get all object property groups
Create a object property group
Update an object property group
Delete an object property group

Docs for this section or API