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: 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:
        - 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
