Attentive Subscribers API

openapi: 3.0.3
info:
  description: For any questions, reach out to your Attentive point of contact (if applicable) or [api@attentivemobile.com](mailto:api@attentivemobile.com).
  title: Attentive Access Token Subscribers API
  version: ''
servers:
- url: https://api.attentivemobile.com/v1
  description: Attentive API
security:
- bearerAuth: []
tags:
- name: Subscribers
  description: 'Use the Subscribers API to manage subscriptions. With this API, you can programmatically subscribe and unsubscribe users from subscriptions.

    '
  x-beta: false
paths:
  /subscriptions:
    post:
      x-external: true
      x-emits-event: true
      security:
      - OAuthFlow:
        - subscriptions:write
      summary: Subscribe user
      description: "Make a call to this endpoint to opt-in a user to a subscription. \n\nNotes:\n- A legal disclosure is required when a user is opted-in programmatically.\n    - For marketing messages, required [legal language](https://docs.attentivemobile.com/pages/legal-docs/legal-disclosure-language/) must be included.\n\n    - For transactional messages, you must include a [transactional opt-in unit](https://docs.attentivemobile.com/pages/legal-docs/legal-transactional/).\n  \n- By default, if a subscription already exists, it will try and record the attempt to create the subscription again. For TEXT subscriptions, this will result in a message being sent to the person indicating that they are already subscribed.\n- Requests to opt-in subscribers must either contain a) a sign-up source id or b) both a locale and a subscription type.\n    - The unique identifier of a sign-up source can be found in the Sign-up Units tab of the Attentive platform in the ID column. \n    If this value is provided in the request, then this sign-up unit will be used for opting in the user in the request.\n\n    - Callers of this endpoint have the option to omit `signUpSourceId` and, instead, provide both a `locale` and a `subscriptionType` (see below for field details). \n    Given the locale and subscription type, Attentive will resolve any matching API opt-in units. To opt-in a user to a subscription without a `signUpSourceId` and exclusively based on locale and subscription type,\n    there must be exactly one API sign-up unit that matches the provided locale and subscription type. Conversely, requests that contain a locale and a subscription type\n    that do not have a corresponding sign-up unit or that have multiple matching sign-up units will receive a `400` response and will not opt a user into a subscription.\n\n- Phone numbers must be submitted in [e164 format](https://en.wikipedia.org/wiki/E.164).\n    - valid examples: `+19148440001`, `+442071838750`, `+551155256325`\n    - invalid examples: `19148440001`, `+1---914---844---0001`, `1 () 914 844 0001`\n"
      operationId: addSubscriptions
      tags:
      - Subscribers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddSubscriptionsRequestDto'
      responses:
        '202':
          description: Accepted a create subscription(s) request. The response body will contain info about which subscription(s) already exist, and which subscription(s) will be created (asynchronously).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddSubscriptionsResponseDto'
        '400':
          $ref: '#/components/responses/InvalidParameter'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccessDenied'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    get:
      x-external: true
      x-emits-event: true
      security:
      - OAuthFlow:
        - subscriptions:read
      summary: Get subscription eligibility for a user
      description: 'Make a call to this endpoint to list all subscription types and channels a user is subscribed to. You can query for a subscriber using either their phone number or email. One of the query parameters is required in order to look up a subscriber. As an example, you can use this endpoint to check if a subscriber is eligible to receive SMS or email campaigns, and then send them a message based on that eligibility.

        '
      operationId: getSubscriptions
      tags:
      - Subscribers
      parameters:
      - in: query
        name: phone
        schema:
          type: string
          example: '%2B13115552368'
        description: A user's phone number we use to fetch subscription eligibility.
      - in: query
        name: email
        schema:
          type: string
          example: test@gmail.com
        description: A user's email we use to fetch subscription eligibility.
      responses:
        '200':
          description: Successfully accepted get subscriptions request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSubscriptionsResponseDto'
        '400':
          $ref: '#/components/responses/InvalidParameter'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccessDenied'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /subscriptions/unsubscribe:
    post:
      x-external: true
      x-emits-event: true
      security:
      - OAuthFlow:
        - subscriptions:write
      summary: Unsubscribe subscriptions for a user
      description: "Make a call to this endpoint to unsubscribe a user from a subscription type or channel. If no subscriptions\nare present in the request, the user is unsubscribed from all subscriptions. If subscriptions are present\nin the request, the user is unsubscribed from the requested type or channel combination. By default, if a\nsubscription exists, but the user is already unsubscribed, it records the attempt to unsubscribe the\nsubscription again. For TEXT subscriptions, a message is sent to the person indicating that they are\nunsubscribed.\n\nFor the user object, the email data point determines which email subscriptions a user has and the phone data point \ndetermines which text (or sms) subscriptions a user has. Passing in an email does not locate, nor unsubscribe, \na user from any sms subscriptions. Similarly, passing in a phone does not locate, nor unsubscribe, a user from any email subscriptions.\n"
      operationId: unsubscribeSubscriptions
      tags:
      - Subscribers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnsubscribeSubscriptionsRequestDto'
      responses:
        '202':
          description: Accepted an unsubscribe subscription(s) request. The response body will contain info about which subscription(s) are already unsubscribed, and which subscription(s) will be unsubscribed (asynchronously).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsubscribeSubscriptionsResponseDto'
        '400':
          $ref: '#/components/responses/InvalidParameter'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccessDenied'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    NewExternalIdentifierDto:
      type: object
      description: External Identifiers for a user
      properties:
        clientUserId:
          type: string
          description: 'Notes:

            Sending duplicate values could lead to unintentionally bridging users together.

            Don''t use customIdentifiers to send attributes (e.g., first name, last name). To send those types of attributes, use our Custom Attributes API.

            Avoid sending null values or empty strings. If you don''t have a valid identifier, you should omit the field from the payload.

            '
        shopifyId:
          type: string
          description: 'Notes:

            Sending duplicate values could lead to unintentionally bridging users together.

            Don''t use customIdentifiers to send attributes (e.g., first name, last name). To send those types of attributes, use our Custom Attributes API.

            Avoid sending null values or empty strings. If you don''t have a valid identifier, you should omit the field from the payload.

            '
        klaviyoId:
          type: string
          description: 'Notes:

            Sending duplicate values could lead to unintentionally bridging users together.

            Don''t use customIdentifiers to send attributes (e.g., first name, last name). To send those types of attributes, use our Custom Attributes API.

            Avoid sending null values or empty strings. If you don''t have a valid identifier, you should omit the field from the payload.

            '
        customIdentifiers:
          type: array
          items:
            $ref: '#/components/schemas/CustomIdentifierDto'
    EligibilityDto:
      type: object
      description: A user's eligibility to receive messages for a subscription.
      properties:
        isEligible:
          type: boolean
          description: A boolean representing a user's eligibility to receive messages for a subscription.
    GetSubscriptionsResponseDto:
      type: object
      description: A list of the subscriptions that a subscriber is eligible to receive messages for.
      properties:
        subscriptionEligibilities:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionEligibilityDto'
    UnsubscribeSubscriptionsRequestDto:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserDto1'
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionDto'
        notification:
          $ref: '#/components/schemas/NotificationConfigDto'
      required:
      - user
    AddSubscriptionsResponseDto:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserDto1'
        externalIdentifiers:
          $ref: '#/components/schemas/NewExternalIdentifierDto'
        subscriptionResponses:
          type: array
          items:
            $ref: '#/components/schemas/AddSubscriptionResponseDto'
    UnsubscribeSubscriptionsResponseDto:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserDto1'
        subscriptionResponses:
          type: array
          items:
            $ref: '#/components/schemas/UnsubscribeSubscriptionResponseDto'
    SubscriptionCreationStatus:
      type: string
      enum:
      - NEWLY_CREATED
      - PREVIOUSLY_CREATED
    LocaleDto:
      type: object
      properties:
        language:
          type: string
          description: Two-letter language code of the locale. [ISO 639-1 alpha 2](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) is required. Values are case sensitive and must match exactly.
          example: en
        country:
          type: string
          description: Two-letter country code of the locale. [ISO-3166-1 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) is required. Values are case sensitive and must match exactly.
          example: US
    AddSubscriptionsRequestDto:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserDto1'
        signUpSourceId:
          type: string
          description: "The unique identifier of the sign-up source. This can be found in the Sign-up Units tab of the Attentive platform in the ID column for any API sign-up method.\nThis field is required if locale is not present. \n\nOr, you can contact our White Glove team (whiteglove@attentivemobile.com)\nor your Client Strategy Manager at Attentive to request a sign-up source for either marketing or\ntransactional opt-ins. Our team will review API opt-in units with\n[compliance in mind](https://docs.attentivemobile.com/pages/legal-docs/legal-disclosure-language/).\n"
        externalIdentifiers:
          $ref: '#/components/schemas/NewExternalIdentifierDto'
        locale:
          $ref: '#/components/schemas/LocaleDto'
        subscriptionType:
          type: string
          enum:
          - MARKETING
          - TRANSACTIONAL
        singleOptIn:
          type: boolean
          description: "Opt in subscriber silently (do not send a Reply Y to subscribe text).\n\nNOTE: This property is disabled (set to false) by default. We strongly recommend maintaining the standard \ndouble opt-in flow, as it serves important legal and compliance purposes. If you want to enable single opt-in, \nwe encourage you to speak with your dedicated Client Strategy Manager (CSM) or our White Glove team \n(whiteglove@attentivemobile.com) before you enable it. If this property is set to true, subscribers will be \nadded without receiving the initial “Reply Y” confirmation text message. This setting bypasses only the \n“Reply Y” message. The mandatory legal message will still be sent.\n"
      required:
      - user
    SubscriptionUnsubscribeStatus:
      type: string
      enum:
      - NEWLY_UNSUBSCRIBED
      - PREVIOUSLY_UNSUBSCRIBED
    NotificationConfigDto:
      type: object
      description: Optional notification properties to override
      properties:
        language:
          type: string
          description: Standard language tags as defined by the ISO. Currently only supports en-US and fr-CA. Case sensitive, must match exactly.
        disabled:
          type: boolean
          description: A boolean representing if a user should not receive a confirmation message upon unsubscribing. Assumed false by default.
    UnsubscribeSubscriptionResponseDto:
      type: object
      description: A subscription and a status indicating whether the subscription for this particular user was newly unsubscribed or was previously unsubscribed (i.e. already opted-out)
      properties:
        subscription:
          $ref: '#/components/schemas/SubscriptionDto'
        subscriptionUnsubscribeStatus:
          $ref: '#/components/schemas/SubscriptionUnsubscribeStatus'
    SubscriptionDto:
      type: object
      description: A type and channel combination.
      properties:
        type:
          type: string
          enum:
          - MARKETING
          - TRANSACTIONAL
          - CHECKOUT_ABANDONED
        channel:
          type: string
          enum:
          - TEXT
          - EMAIL
    AddSubscriptionResponseDto:
      type: object
      description: A subscription and a status indicating whether the subscription for this particular user was newly created or was previously created (i.e. already existed)
      properties:
        subscription:
          $ref: '#/components/schemas/SubscriptionDto'
        subscriptionCreationStatus:
          $ref: '#/components/schemas/SubscriptionCreationStatus'
    CustomIdentifierDto:
      type: object
      description: Namespaced custom identifier and value
      properties:
        name:
          type: string
        value:
          type: string
    UserDto1:
      type: object
      description: User associated with the action. Note that this is a visitor to the site and does not need to be actively subscribed to Attentive.
      properties:
        phone:
          type: string
          description: Phone number of the user associated with the action. [E.164 format](https://en.wikipedia.org/wiki/E.164) is required. This field is required if email is not provided.
          example: '+13115552368'
        email:
          type: string
          description: Email of the user associated with the action. This field is required if phone is not provided.
          example: test@gmail.com
    SubscriptionEligibilityDto:
      type: object
      description: A subscription and a boolean indicating whether the user is eligible to receive messages for that subscription.
      properties:
        subscription:
          $ref: '#/components/schemas/SubscriptionDto'
        eligibility:
          $ref: '#/components/schemas/EligibilityDto'
  responses:
    NotFound:
      description: The specified resource was not found
    InvalidParameter:
      description: Invalid parameter in request query or body
    InternalError:
      description: Internal Server Error
    Unauthorized:
      description: Unauthorized
    TooManyRequests:
      description: The user has sent too many requests in a given amount of time
    AccessDenied:
      description: Access Denied
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    OAuthFlow:
      type: oauth2
      description: This API uses OAuth 2 with the authorization code grant flow. [More info](https://docs.attentivemobile.com/pages/authentication/)
      flows:
        authorizationCode:
          authorizationUrl: https://ui-devel.attentivemobile.com/integrations/oauth-install?client_id={clientId}&redirect_uri={redirectUri}&scope={scope}
          tokenUrl: https://api.attentivemobile.com/v1/authorization-codes/tokens
          scopes:
            attributes:write: read and write custom attributes
            subscriptions:write: read and write subscriptions
            events:write: read and write custom events
            ecommerce:write: read and write ecommerce events
            segments:write: read and write segments
            segments:read: read segments
x-readme:
  explorer-enabled: false