Subscriptions
Subscriptions allow contacts to control what forms of communications they receive
COMMUNITYBEARER0 INSTALLS
OpenAPI Specificationv3.0
{
"openapi": "3.0.1",
"servers": [
{
"url": "https://api.hubapi.com/"
}
],
"info": {
"description": "Subscriptions allow contacts to control what forms of communications they receive. Contacts can decide whether they want to receive communication pertaining to a specific topic, brand, or an entire HubSpot account.",
"title": "Subscriptions",
"version": "v3",
"x-logo": {
"url": "https://api.apis.guru/v2/cache/logo/https_developers.hubspot.com_hubfs_assets_hubspot.com_buzz_HubSpotOpenGraph.png"
},
"x-origin": [
{
"format": "openapi",
"url": "https://api.hubspot.com/api-catalog-public/v1/apis/communication-preferences/v3",
"version": "3.0"
}
],
"x-providerName": "hubapi.com",
"x-serviceName": "communication-preferences"
},
"tags": [
{
"description": "Whether a contact has subscribed or unsubscribed from a given subscription type.",
"name": "Status"
},
{
"description": "The different subscription types that are defined in a portal.",
"name": "Definition"
}
],
"paths": {
"/communication-preferences/v3/definitions": {
"get": {
"description": "Get a list of all subscription definitions for the portal",
"operationId": "get-/communication-preferences/v3/definitions_getPage",
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"subscriptionDefinitions": [
{
"createdAt": "2019-08-05T13:01:15.875Z",
"description": "Receive timely updates with the latest blog posts.",
"id": "1805677",
"isActive": true,
"isDefault": false,
"isInternal": false,
"name": "Default HubSpot Blog Subscription",
"updatedAt": "2019-08-05T13:01:15.875Z"
},
{
"communicationMethod": "Email",
"createdAt": "2019-08-05T13:01:15.875Z",
"description": "Receive feedback requests and customer service information.",
"id": "1805669",
"isActive": true,
"isDefault": true,
"isInternal": true,
"name": "Customer Service Communication",
"purpose": "Service",
"updatedAt": "2019-08-05T13:01:15.875Z"
},
{
"communicationMethod": "Email",
"createdAt": "2019-08-05T13:01:15.875Z",
"description": "One to One emails",
"id": "1805670",
"isActive": true,
"isDefault": true,
"isInternal": true,
"name": "One to One",
"purpose": "Sales",
"updatedAt": "2019-08-05T13:01:15.875Z"
}
]
},
"schema": {
"$ref": "#/components/schemas/SubscriptionDefinitionsResponse"
}
}
},
"description": "successful operation"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"security": [
{
"hapikey": []
},
{
"private_apps_legacy": []
},
{
"oauth2_legacy": [
"communication_preferences.read_write"
]
},
{
"private_apps_legacy": []
},
{
"oauth2_legacy": [
"communication_preferences.read"
]
}
],
"summary": "Get subscription definitions",
"tags": [
"Definition"
]
}
},
"/communication-preferences/v3/status/email/{emailAddress}": {
"get": {
"description": "Returns a list of subscriptions and their status for a given contact.",
"operationId": "get-/communication-preferences/v3/status/email/{emailAddress}_getEmailStatus",
"parameters": [
{
"explode": false,
"in": "path",
"name": "emailAddress",
"required": true,
"schema": {
"type": "string"
},
"style": "simple"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"recipient": "example@example.com",
"subscriptionStatuses": [
{
"description": "Receive timely updates with the latest blog posts.",
"id": "7148714",
"legalBasis": "CONSENT_WITH_NOTICE",
"legalBasisExplanation": "At users request, we opted them in",
"name": "Default HubSpot Blog Subscription",
"preferenceGroupName": "Initial Group",
"sourceOfStatus": "SUBSCRIPTION_STATUS",
"status": "SUBSCRIBED"
},
{
"description": "One to One emails",
"id": "7148715",
"legalBasis": "CONSENT_WITH_NOTICE",
"legalBasisExplanation": "User has requested to be opted out",
"name": "One to One",
"sourceOfStatus": "SUBSCRIPTION_STATUS",
"status": "NOT_SUBSCRIBED"
}
]
},
"schema": {
"$ref": "#/components/schemas/PublicSubscriptionStatusesResponse"
}
}
},
"description": "successful operation"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"security": [
{
"hapikey": []
},
{
"private_apps_legacy": []
},
{
"oauth2_legacy": [
"communication_preferences.read_write"
]
},
{
"private_apps_legacy": []
},
{
"oauth2_legacy": [
"communication_preferences.read"
]
}
],
"summary": "Get subscription statuses for a contact",
"tags": [
"Status"
]
}
},
"/communication-preferences/v3/subscribe": {
"post": {
"description": "Subscribes a contact to the given subscription type. This API is not valid to use for subscribing a contact at a brand or portal level and will return an error.",
"operationId": "post-/communication-preferences/v3/subscribe_subscribe",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicUpdateSubscriptionStatusRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"description": "Receive timely updates with the latest blog posts.",
"id": "7148714",
"legalBasis": "CONSENT_WITH_NOTICE",
"legalBasisExplanation": "At users request, we opted them in",
"name": "Default HubSpot Blog Subscription",
"preferenceGroupName": "Initial Group",
"sourceOfStatus": "SUBSCRIPTION_STATUS",
"status": "SUBSCRIBED"
},
"schema": {
"$ref": "#/components/schemas/PublicSubscriptionStatus"
}
}
},
"description": "successful operation"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"security": [
{
"oauth2_legacy": [
"communication_preferences.write"
]
},
{
"hapikey": []
},
{
"oauth2_legacy": [
"communication_preferences.read_write"
]
},
{
"private_apps_legacy": []
},
{
"private_apps_legacy": []
}
],
"summary": "Subscribe a contact",
"tags": [
"Status"
]
}
},
"/communication-preferences/v3/unsubscribe": {
"post": {
"description": "Unsubscribes a contact from the given subscription type. This API is not valid to use for unsubscribing a contact at a brand or portal level and will return an error.",
"operationId": "post-/communication-preferences/v3/unsubscribe_unsubscribe",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublicUpdateSubscriptionStatusRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"description": "Receive timely updates with the latest blog posts.",
"id": "7148714",
"legalBasis": "CONSENT_WITH_NOTICE",
"legalBasisExplanation": "At users request, we opted them out",
"name": "Default HubSpot Blog Subscription",
"preferenceGroupName": "Initial Group",
"sourceOfStatus": "SUBSCRIPTION_STATUS",
"status": "NOT_SUBSCRIBED"
},
"schema": {
"$ref": "#/components/schemas/PublicSubscriptionStatus"
}
}
},
"description": "successful operation"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"security": [
{
"oauth2_legacy": [
"communication_preferences.write"
]
},
{
"hapikey": []
},
{
"oauth2_legacy": [
"communication_preferences.read_write"
]
},
{
"private_apps_legacy": []
},
{
"private_apps_legacy": []
}
],
"summary": "Unsubscribe a contact",
"tags": [
"Status"
]
}
}
},
"components": {
"responses": {
"Error": {
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "An error occurred."
}
},
"schemas": {
"Error": {
"example": {
"category": "VALIDATION_ERROR",
"correlationId": "aeb5f871-7f07-4993-9211-075dc63e7cbf",
"links": {
"knowledge-base": "https://www.hubspot.com/products/service/knowledge-base"
},
"message": "Invalid input (details will vary based on the error)"
},
"properties": {
"category": {
"description": "The error category",
"type": "string"
},
"context": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "Context about the error condition",
"example": {
"invalidPropertyName": [
"propertyValue"
],
"missingScopes": [
"scope1",
"scope2"
]
},
"type": "object"
},
"correlationId": {
"description": "A unique identifier for the request. Include this value with any error reports or support tickets",
"example": "aeb5f871-7f07-4993-9211-075dc63e7cbf",
"format": "uuid",
"type": "string"
},
"errors": {
"description": "further information about the error",
"items": {
"$ref": "#/components/schemas/ErrorDetail"
},
"type": "array"
},
"links": {
"additionalProperties": {
"type": "string"
},
"description": "A map of link names to associated URIs containing documentation about the error or recommended remediation steps",
"type": "object"
},
"message": {
"description": "A human readable message describing the error along with remediation steps where appropriate",
"example": "An error occurred",
"type": "string"
},
"subCategory": {
"description": "A specific category that contains more specific detail about the error",
"type": "string"
}
},
"required": [
"category",
"correlationId",
"message"
],
"type": "object"
},
"ErrorDetail": {
"properties": {
"code": {
"description": "The status code associated with the error detail",
"type": "string"
},
"context": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "Context about the error condition",
"example": {
"missingScopes": [
"scope1",
"scope2"
]
},
"type": "object"
},
"in": {
"description": "The name of the field or parameter in which the error was found.",
"type": "string"
},
"message": {
"description": "A human readable message describing the error along with remediation steps where appropriate",
"type": "string"
},
"subCategory": {
"description": "A specific category that contains more specific detail about the error",
"type": "string"
}
},
"required": [
"message"
],
"type": "object"
},
"PublicSubscriptionStatus": {
"description": "The status of a subscription for a contact.",
"properties": {
"brandId": {
"description": "The ID of the brand that the subscription is associated with, if there is one.",
"format": "int64",
"type": "integer"
},
"description": {
"description": "A description of the subscription.",
"type": "string"
},
"id": {
"description": "The ID for the subscription.",
"type": "string"
},
"legalBasis": {
"description": "The legal reason for the current status of the subscription.",
"enum": [
"LEGITIMATE_INTEREST_PQL",
"LEGITIMATE_INTEREST_CLIENT",
"PERFORMANCE_OF_CONTRACT",
"CONSENT_WITH_NOTICE",
"NON_GDPR",
"PROCESS_AND_STORE",
"LEGITIMATE_INTEREST_OTHER"
],
"type": "string"
},
"legalBasisExplanation": {
"description": "A more detailed explanation to go with the legal basis.",
"type": "string"
},
"name": {
"description": "The name of the subscription.",
"type": "string"
},
"preferenceGroupName": {
"description": "The name of the preferences group that the subscription is associated with.",
"type": "string"
},
"sourceOfStatus": {
"description": "Where the status is determined from e.g. PORTAL_WIDE_STATUS if the contact opted out from the portal.",
"enum": [
"PORTAL_WIDE_STATUS",
"BRAND_WIDE_STATUS",
"SUBSCRIPTION_STATUS"
],
"type": "string"
},
"status": {
"description": "Whether the contact is subscribed.",
"enum": [
"SUBSCRIBED",
"NOT_SUBSCRIBED"
],
"type": "string"
}
},
"required": [
"description",
"id",
"name",
"sourceOfStatus",
"status"
],
"type": "object"
},
"PublicSubscriptionStatusesResponse": {
"description": "A collection of subscription statuses for a contact.",
"properties": {
"recipient": {
"description": "Email address of the contact.",
"type": "string"
},
"subscriptionStatuses": {
"description": "A list of all of the contact's subscriptions statuses.",
"items": {
"$ref": "#/components/schemas/PublicSubscriptionStatus"
},
"type": "array"
}
},
"required": [
"recipient",
"subscriptionStatuses"
],
"type": "object"
},
"PublicUpdateSubscriptionStatusRequest": {
"description": "A request to change the status of a contact's subscription.",
"properties": {
"emailAddress": {
"description": "Contact's email address.",
"type": "string"
},
"legalBasis": {
"description": "Legal basis for updating the contact's status (required for GDPR enabled portals).",
"enum": [
"LEGITIMATE_INTEREST_PQL",
"LEGITIMATE_INTEREST_CLIENT",
"PERFORMANCE_OF_CONTRACT",
"CONSENT_WITH_NOTICE",
"NON_GDPR",
"PROCESS_AND_STORE",
"LEGITIMATE_INTEREST_OTHER"
],
"type": "string"
},
"legalBasisExplanation": {
"description": "A more detailed explanation to go with the legal basis (required for GDPR enabled portals).",
"type": "string"
},
"subscriptionId": {
"description": "ID of the subscription being updated for the contact.",
"type": "string"
}
},
"required": [
"emailAddress",
"subscriptionId"
],
"type": "object"
},
"SubscriptionDefinition": {
"properties": {
"communicationMethod": {
"description": "The method or technology used to contact.",
"type": "string"
},
"createdAt": {
"description": "Time at which the definition was created.",
"format": "date-time",
"type": "string"
},
"description": {
"description": "A description of the subscription.",
"type": "string"
},
"id": {
"description": "The ID of the definition.",
"type": "string"
},
"isActive": {
"description": "Whether the definition is active or archived.",
"type": "boolean"
},
"isDefault": {
"description": "A subscription definition created by HubSpot.",
"type": "boolean"
},
"isInternal": {
"description": "A default description that is used by some HubSpot tools and cannot be edited.",
"type": "boolean"
},
"name": {
"description": "The name of the subscription.",
"type": "string"
},
"purpose": {
"description": "The purpose of this subscription or the department in your organization that uses it.",
"type": "string"
},
"updatedAt": {
"description": "Time at which the definition was last updated.",
"format": "date-time",
"type": "string"
}
},
"required": [
"createdAt",
"description",
"id",
"isActive",
"isDefault",
"isInternal",
"name",
"updatedAt"
],
"type": "object"
},
"SubscriptionDefinitionsResponse": {
"description": "A collection of subscription definitions for the portal.",
"properties": {
"subscriptionDefinitions": {
"description": "A list of all subscription definitions.",
"items": {
"$ref": "#/components/schemas/SubscriptionDefinition"
},
"type": "array"
}
},
"required": [
"subscriptionDefinitions"
],
"type": "object"
}
},
"securitySchemes": {
"hapikey": {
"in": "query",
"name": "hapikey",
"type": "apiKey"
},
"oauth2_legacy": {
"flows": {
"authorizationCode": {
"authorizationUrl": "https://app.hubspot.com/oauth/authorize",
"scopes": {
"communication_preferences.read": "Read contact subscription preferences",
"communication_preferences.read_write": "Update contact subscription preferences",
"communication_preferences.write": "Update contact subscription preferences"
},
"tokenUrl": "https://api.hubapi.com/oauth/v1/token"
}
},
"type": "oauth2"
},
"private_apps_legacy": {
"in": "header",
"name": "private-app-legacy",
"type": "apiKey"
}
}
},
"x-hubspot-available-client-libraries": [
"PHP",
"Node",
"Python",
"Ruby"
]
}