Alerts - Subscribing API Reference

This defines the API for Campaign Subscription Management:

  • Request - request the list of phone numbers opted out from your campaign, or remove a phone number from the list
  • Response - the list of opted out phone numbers or confirmation that the number has been removed.

Request

You use the opt-in API to:

  • Retrieve the list of phone numbers who have opted out from your campaign:

    https://rest.nexmo.com/sc/us/alert/opt-in/query/json?api_key=xxxxxxxx&api_secret=xxxxxxxx
    
  • Remove a phone number from your opt-out list:

    https://rest.nexmo.com/sc/us/alert/opt-in/manage/json?api_key=xxxxxxxx&api_secret=xxxxxxxx&msisdn=xxxxxxxxxxxx
    

This request contains:

Base URL

All requests to the Short Code Event Based Alert API must contain:

  • Either:

    • https://rest.nexmo.com/sc/us/alert/opt-in/query
    • https://rest.nexmo.com/sc/us/alert/opt-in/manage
  • A response object: json or xml

Your base URL becomes either:

https://rest.nexmo.com/sc/us/alert/opt-in/query/json
https://rest.nexmo.com/sc/us/alert/opt-in/manage/json
https://rest.nexmo.com/sc/us/alert/opt-in/query/xml
https://rest.nexmo.com/sc/us/alert/opt-in/manage/xml

Parameters

The following table shows the parameters you use in the request:

Parameter Description Required
msisdn The phone number to resubscribe to your campaign and remove from the opt-out list. If Your base URL contains https://rest.nexmo.com/sc/us/alert/opt-in/manage.

Authentication information

If you are not using applications, you use the following parameters for calls to Nexmo API:

Parameter Description
api_key Your Key. For example: api_key=NEXMO_API_KEY
api_secret Your Secret. For example: api_secret=NEXMO_API_SECRET

Note: You find your Key and Secret in Dashboard.

If you are using signatures to verify your requests use:

Parameter Description
api_key Your Key. For example: api_key=NEXMO_API_KEY
sig The hash of the request parameters in alphabetical order, a timestamp and the signature secret. For example: sig=SIGNATURE

Security

To ensure privacy, you must use HTTPS for all Nexmo API requests.

Encoding

Encoding

You submit all requests with a POST or GET call using UTF-8 encoding and URL encoded values. The expected Content-Type for POST is application/x-www-form-urlencoded. For calls to a JSON endpoint, we also support:

  • application/json
  • application/jsonrequest
  • application/x-javascript
  • text/json
  • text/javascript
  • text/x-javascript
  • text/x-json when posting parameters as a JSON object.

Response

Each request you make using this API returns a:

The response is returned either:

  • Directly to you. For example, if you are using the command line, you see the response on the command line.
  • To a webhook endpoint if you set it in Dashboard.

Each response comes:

Format

You set the response type using the (link:#request text: Base URL). The following table shows example responses in JSON or XML:

{
  "opt-in-count":"3",
  "opt-in-list":[
    {
      "msisdn":"15558937009",
      "opt-in":"false",
      "opt-out":"true",
      "opt-out-date":"2014-06-27      18:31:33"
    },
    {
      "msisdn":"15554908975",
      "opt-in":"false",
      "opt-out":"true",
      "opt-out-date":"2014-07-18 16:20:20"
    },
    {
      "msisdn":"15559912501",
      "opt-in":"false",
      "opt-in-date": "2014-07-18 15:28:23",
      "opt-out":"true",
      "opt-out-date":"2014-08-18 23:17:40"
    }
  ]
}
<?xml version="1.0" encoding="UTF-8"?>
<opt-in-list opt-in-count="3">
  <opt-in
    msisdn="121326336101"
    opt-in="false"
    opt-out="true"
    opt-out-date="2014-07-22 12:41:48"
  />
  <opt-in
    msisdn="121326336102"
    opt-in="false"
    opt-out="true"
    opt-out-date="2014-07-22 13:00:04"
  />
  <opt-in
    msisdn="12132633680"
    opt-in="false"
    opt-out="true"
    opt-out-date="2014-07-22 11:02:50"
  />
</opt-in-list>
{
  "msisdn":"15559301529",
  "opt-in":"true",
  "opt-in-date":"2014-08-21 17:34:47",
  "opt-out":"false"
}
<opt-in
  msisdn="13065897298"
  opt-in="true"
  opt-in-date="2015-09-26 04:46:27"
  opt-out="false"
/>

Keys and Values

The response contains the following keys and values:

Key Value Response type
opt-in-count The number of parts the message was split into. JSON
opt-in-list Contains each opt-in part. For an XML response, the count attribute contains the value of opt-in-count JSON key. BOTH
opt-in A single opt-in part. XML
msisdn The phone number that was unsubscribed or resubscribed to your campaign. BOTH
opt-in true if msisdn is subscribed to your campaign. BOTH
opt-in-date The date msisdn was subscribed to your campaign. BOTH
opt-out true if msisdn is NOT subscribed to your campaign. BOTH
opt-out-date The date msisdn was removed from your campaign. BOTH