Subscribers

Use the Subscribers API to manage subscriptions. With this API, you can programmatically subscribe and unsubscribe users from subscriptions.

Subscribe user

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.

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

    • valid examples: +19148440001, +442071838750, +551155256325
    • invalid examples: 19148440001, +1---914---844---0001, 1 () 914 844 0001
Request
Security:
OAuthFlow (subscriptions:write)
Request Body schema: application/json
required
object (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.

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.

object (NewExternalIdentifierDto)

External Identifiers for a user

object (LocaleDto)
subscriptionType
string
Enum: "MARKETING" "TRANSACTIONAL"
singleOptIn
boolean

Opt in subscriber silently (do not send a Reply Y to subscribe text).

NOTE: This property is disabled by default. We strongly recommend maintaining the double opt-in flow. The double opt in serves a couple of important purposes from a legal/compliance perspective. Contact your dedicated Client Strategy Manager (CSM) or our whiteglove@attentivemobile.com team to enable it. If wanting to skip legal/reply y language, set this to be true. We will not send reply y message or legal message to subscribers added with this flag set to true.

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

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

post/subscriptions
Request samples
application/json
{
  • "user": {
    },
  • "signUpSourceId": "string",
  • "externalIdentifiers": {
    },
  • "locale": {
    },
  • "subscriptionType": "MARKETING",
  • "singleOptIn": true
}
Response samples
application/json
{
  • "user": {
    },
  • "externalIdentifiers": {
    },
  • "subscriptionResponses": [
    ]
}

Get subscription eligibility for a user

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.

Request
Security:
OAuthFlow (subscriptions:write)
query Parameters
phone
string

A user's phone number we use to fetch subscription eligibility.

Example: phone=+13115552368
email
string

A user's email we use to fetch subscription eligibility.

Example: email=test@gmail.com
Responses
200

Successfully accepted get subscriptions request

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

get/subscriptions
Request samples
curl -i -X GET \
  'https://api.attentivemobile.com/v1/subscriptions?phone=%2B13115552368&email=test%40gmail.com' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "subscriptionEligibilities": [
    ]
}

Unsubscribe subscriptions for a user

Make a call to this endpoint to unsubscribe a user from a subscription type or channel. If no subscriptions are present in the request, the user is unsubscribed from all subscriptions. If subscriptions are present in the request, the user is unsubscribed from the requested type or channel combination. By default, if a subscription exists, but the user is already unsubscribed, it records the attempt to unsubscribe the subscription again. For TEXT subscriptions, a message is sent to the person indicating that they are unsubscribed.

For the user object, the email data point determines which email subscriptions a user has and the phone data point determines which text (or sms) subscriptions a user has. Passing in an email does not locate, nor unsubscribe, a user from any sms subscriptions. Similarly, passing in a phone does not locate, nor unsubscribe, a user from any email subscriptions.

Request
Security:
OAuthFlow (subscriptions:write)
Request Body schema: application/json
required
object (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.

Array of objects (SubscriptionDto)
object (NotificationConfigDto)

Optional notification properties to override

Responses
202

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

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

post/subscriptions/unsubscribe
Request samples
application/json
{
  • "user": {
    },
  • "subscriptions": [
    ],
  • "notification": {
    }
}
Response samples
application/json
{
  • "user": {
    },
  • "subscriptionResponses": [
    ]
}