---
title: "Subscribe user"
method: POST
path: "/subscriptions"
tags: ["Subscribers"]
---

# Subscribe user

`POST /subscriptions`

Make a call to this endpoint to opt-in a user to a subscription. 

Notes:
- A legal disclosure is required when a user is opted-in programmatically.
    - For marketing messages, required [legal language](https://docs.attentivemobile.com/pages/legal-docs/legal-disclosure-language/) must be included.

    - For transactional messages, you must include a [transactional opt-in unit](https://docs.attentivemobile.com/pages/legal-docs/legal-transactional/).
  
- 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.
- Requests to opt-in subscribers must either contain a) a sign-up source id or b) both a locale and a subscription type.
    - 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. 
    If this value is provided in the request, then this sign-up unit will be used for opting in the user in the request.

    - Callers of this endpoint have the option to omit `signUpSourceId` and, instead, provide both a `locale` and a `subscriptionType` (see below for field details). 
    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,
    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
    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.

- Phone numbers must be submitted in [e164 format](https://en.wikipedia.org/wiki/E.164).
    - valid examples: `+19148440001`, `+442071838750`, `+551155256325`
    - invalid examples: `19148440001`, `+1---914---844---0001`, `1 () 914 844 0001`

## Request body

- AddSubscriptionsRequestDto
  - `user` UserDto1, required — User associated with the action. Note that this is a visitor to the site and does not need to be actively subscribed to Attentive.
    - `phone` string — 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.
    - `email` string — Email of the user associated with the action. This field is required if phone is not provided.
  - `signUpSourceId` string — 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. This field is required if locale is not present. Or, you can contact our White Glove team (whiteglove@attentivemobile.com) or your Client Strategy Manager at Attentive to request a sign-up source for either marketing or transactional opt-ins. Our team will review API opt-in units with [compliance in mind](https://docs.attentivemobile.com/pages/legal-docs/legal-disclosure-language/).
  - `externalIdentifiers` NewExternalIdentifierDto — External Identifiers for a user
    - `clientUserId` string — 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` string — 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` string — 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` CustomIdentifierDto[]
      - `name` string
      - `value` string
  - `locale` LocaleDto
    - `language` string — 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.
    - `country` string — 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.
  - `subscriptionType` 'MARKETING' | 'TRANSACTIONAL'
  - `singleOptIn` boolean — Opt in subscriber silently (do not send a Reply Y to subscribe text). NOTE: This property is disabled (set to false) by default. We strongly recommend maintaining the standard double opt-in flow, as it serves important legal and compliance purposes. If you want to enable single opt-in, we encourage you to speak with your dedicated Client Strategy Manager (CSM) or our White Glove team (whiteglove@attentivemobile.com) before you enable it. If this property is set to true, subscribers will be added without receiving the initial “Reply Y” confirmation text message. This setting bypasses only the “Reply Y” message. The mandatory legal message will still be sent.

## Response `202`

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).

- AddSubscriptionsResponseDto
  - `user` UserDto1 — User associated with the action. Note that this is a visitor to the site and does not need to be actively subscribed to Attentive.
    - `phone` string — 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.
    - `email` string — Email of the user associated with the action. This field is required if phone is not provided.
  - `externalIdentifiers` NewExternalIdentifierDto — External Identifiers for a user
    - `clientUserId` string — 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` string — 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` string — 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` CustomIdentifierDto[]
      - `name` string
      - `value` string
  - `subscriptionResponses` AddSubscriptionResponseDto[]
    - `subscription` SubscriptionDto — A type and channel combination.
      - `type` 'MARKETING' | 'TRANSACTIONAL' | 'CHECKOUT_ABANDONED'
      - `channel` 'TEXT' | 'EMAIL'
    - `subscriptionCreationStatus` 'NEWLY_CREATED' | 'PREVIOUSLY_CREATED'

## Other responses

- `400` — Invalid parameter in request query or body
- `401` — Unauthorized
- `403` — Access Denied
- `404` — The specified resource was not found
- `429` — The user has sent too many requests in a given amount of time
- `500` — Internal Server Error

---

[API](https://skmtc.net/attentive/apis/attentive-api-v2.md) · [All operations](https://skmtc.net/attentive/apis/attentive-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/attentive/attentive-api-v2/revisions/be387e501197/schema)