openapi-directory/api/hubapi.com/communication-preferences.json

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

{"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-hubspot-api-use-case":"You want to ensure a contact's opt-in status is updated if they opted out of communications from your business via a service external to HubSpot.","x-hubspot-documentation-banner":"NONE","x-hubspot-introduction":"Use the subscription preferences API to retrieve subscription data for a contact or opt a contact in or out of a specific subscription type.","x-hubspot-product-tier-requirements":{"marketing":"FREE"},"x-hubspot-related-documentation":[{"name":"Subscription Preferences Guide","url":"https://hubspot.dev/guides/api/marketing-api/subscriptions-preferences"}],"x-logo":{"url":"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":"","name":"Status","x-hubspot-tag-name-english-source":"Status"},{"description":"","name":"Definition","x-hubspot-tag-name-english-source":"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","parameters":[],"responses":{"200":{"content":{"application/json":{"example":{"subscriptionDefinitions":[{"createdAt":"2025-06-15T13:48:43.413Z","description":"Receive timely updates with the latest blog posts.","id":"1805677","isActive":true,"isDefault":false,"isInternal":false,"name":"Default HubSpot Blog Subscription","updatedAt":"2025-06-15T13:48:43.413Z"},{"communicationMethod":"Email","createdAt":"2025-06-15T13:48:43.413Z","description":"Receive feedback requests and customer service information.","id":"1805669","isActive":true,"isDefault":true,"isInternal":true,"name":"Customer Service Communication","purpose":"Service","updatedAt":"2025-06-15T13:48:43.413Z"},{"communicationMethod":"Email","createdAt":"2025-06-15T13:48:43.413Z","description":"One to One emails","id":"1805670","isActive":true,"isDefault":true,"isInternal":true,"name":"One to One","purpose":"Sales","updatedAt":"2025-06-15T13:48:43.413Z"}]},"schema":{"$ref":"#/components/schemas/SubscriptionDefinitionsResponse"}}},"description":"successful operation"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"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":[{"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","parameters":[],"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"},"400":{"content":{"application/json":{"example":{"category":"VALIDATION_ERROR","correlationId":"af3df921-1418-4b18-b6f4-35ca117728ae","message":"subscription 7148712 for example@example.com cannot be updated because they have unsubscribed","requestId":"3b0e0c44-fd57-4714-a3c9-42f6fead33c8","status":"error"}}},"description":""},"404":{"content":{"application/json":{"example":{"category":"OBJECT_NOT_FOUND","correlationId":"af3df921-1418-4b18-b6f4-35ca117728ae","message":"example@example.com either has no subscriptions associated with this portal or does not exist","requestId":"3b0e0c44-fd57-4714-a3c9-42f6fead33c8","status":"error"}}},"description":""},"default":{"$ref":"#/components/responses/Error"}},"security":[{"oauth2_legacy":["communication_preferences.write"]},{"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","parameters":[],"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"},"400":{"content":{"application/json":{"example":{"category":"VALIDATION_ERROR","correlationId":"af3df921-1418-4b18-b6f4-35ca117728ae","message":"example@example.com is already unsubscribed to subscription 7148712","requestId":"3b0e0c44-fd57-4714-a3c9-42f6fead33c8","status":"error"}}},"description":""},"404":{"content":{"application/json":{"example":{"category":"OBJECT_NOT_FOUND","correlationId":"af3df921-1418-4b18-b6f4-35ca117728ae","message":"example@example.com either has no subscriptions associated with this portal or does not exist","requestId":"3b0e0c44-fd57-4714-a3c9-42f6fead33c8","status":"error"}}},"description":""},"default":{"$ref":"#/components/responses/Error"}},"security":[{"oauth2_legacy":["communication_preferences.write"]},{"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","example":"VALIDATION_ERROR","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","example":{"knowledge-base":"https://www.hubspot.com/products/service/knowledge-base"},"type":"object"},"message":{"description":"A human readable message describing the error along with remediation steps where appropriate","example":"Invalid input (details will vary based on the error)","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":{"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","Ruby","Python"],"x-hubspot-documentation-banner":"NONE","x-hubspot-product-tier-requirements":{"marketing":"FREE"}}