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.

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

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

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": {
    }
}
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": [
    ]
}