Alerts - Subscribing API Reference

Action Needed For Vonage Customers Using US Shared Short Codes

Effective immediately, Vonage will no longer accept new programs for Shared Short Codes for A2P messaging. T-Mobile and AT&T's new code of conduct prohibits the use of shared originators for A2P (application to person) traffic. Please migrate any existing Shared Short Code traffic to one of our alternative solutions. To help you with this transition, please use the Vonage guide to alternatives. Please contact us to migrate to a new solution.

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
Parameters
Authentication information
Security
Encoding

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`.
`page-size`	Return this amount of results in the response. The default value is 100.	No
`page`	Return `page-size` results from this zero-based index in the response. If your request returns 300 Calls, set `page` to 2 in order to return Calls 201 to 300. The default value is 0.	No

Authentication information

If you are not using applications, you use the following parameters for calls to Vonage 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 Vonage API requests.

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:

Response - the status of your request to Vonage in JSON or XML format.

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:

In a specific Format
With Keys and values

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`