Skip to main content
GET
/
communication-preferences
/
v4
/
definitions
Retrieve all subscription status definitions
curl --request GET \
  --url https://api.hubapi.com/communication-preferences/v4/definitions \
  --header 'Authorization: Bearer <token>'
{
  "completedAt": "2023-11-07T05:31:56Z",
  "results": [
    {
      "createdAt": "2023-11-07T05:31:56Z",
      "description": "<string>",
      "id": "<string>",
      "isActive": true,
      "isDefault": true,
      "isInternal": true,
      "name": "<string>",
      "updatedAt": "2023-11-07T05:31:56Z",
      "businessUnitId": 123,
      "communicationMethod": "<string>",
      "purpose": "<string>",
      "subscriptionTranslations": [
        {
          "createdAt": 123,
          "description": "<string>",
          "languageCode": "<string>",
          "name": "<string>",
          "subscriptionId": 123,
          "updatedAt": 123
        }
      ]
    }
  ],
  "startedAt": "2023-11-07T05:31:56Z",
  "status": "CANCELED",
  "errors": [
    {
      "category": "<string>",
      "context": {},
      "errors": [
        {
          "message": "<string>",
          "code": "<string>",
          "context": "{missingScopes=[scope1, scope2]}",
          "in": "<string>",
          "subCategory": "<string>"
        }
      ],
      "links": {},
      "message": "<string>",
      "status": "<string>",
      "id": "<string>",
      "subCategory": {}
    }
  ],
  "links": {},
  "numErrors": 123,
  "requestedAt": "2023-11-07T05:31:56Z"
}

Supported products

Requires one of the following products or higher.
Marketing HubMarketing Hub -Starter
Sales HubSales Hub -Free
Service HubService Hub -Free
Content HubContent Hub -Free
Data HubData Hub -Free

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Query Parameters

businessUnitId
integer<int64>

If you have the business unit add-on, include this parameter to filter results by business unit ID. The default Account business unit will always use 0.

includeTranslations
boolean

Set to true to return subscription translations associated with each definition.

Response

successful operation

completedAt
string<date-time>
required

The date and time when the operation was completed.

results
object[]
required

An array containing the results of the operation.

startedAt
string<date-time>
required

The date and time when the operation started.

status
enum<string>
required

The current status of the operation, which can be PENDING, PROCESSING, CANCELED, or COMPLETE.

Available options:
CANCELED,
COMPLETE,
PENDING,
PROCESSING
errors
object[]

An array of errors that occurred during the operation.

A collection of related links associated with the operation.

numErrors
integer<int32>

The number of errors encountered during the operation.

requestedAt
string<date-time>

The date and time when the operation was requested.

Last modified on December 16, 2025