Two-factor Authentication 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, therefore, existing Shared Short Code traffic must be migrated by March 1, 2021. To help you with this transition, please use the Vonage guide to alternatives. Please contact us to migrate to a new solution.
This describes the US Short Code Two-factor Authentication API in the following steps:
- Request - send a PIN to your user
- Response - check the response and ensure that you sent the request to Vonage correctly.
- Delivery receipt - see the status and cost of your request.
Request
A 2FA request looks like:
https://rest.nexmo.com/sc/us/2fa/json
https://rest.nexmo.com/sc/us/2fa/xml
This request contains:
Base URL
All requests to the Short Code 2FA API must contain:
https://rest.nexmo.com/sc/us/2fa
- A response object: json or xml
Your base URL becomes either:
JSON | XML |
---|---|
https://rest.nexmo.com/sc/us/2fa/json |
https://rest.nexmo.com/sc/us/2fa/xml |
Parameters
The following table shows the parameters you use in the request:
Parameter | Description | Required |
---|---|---|
to |
The single phone number to send pin to. This is a mobile number in US format with one recipient per request. For example, to=16365553226
|
Yes |
pin |
A numeric password to authenticate your user. | Yes |
client-ref |
A 40 character reference string for your internal reporting. | No |
Authentication information
To authenticate your request, you must provide the following parameters:
Parameter | Description |
---|---|
api_key |
Your Key. For example: api_key=NEXMO_API_KEY
|
api_secret |
Your Secret. For example: api_secret=NEXMO_API_SECRET
|
You can find your Key and Secret in the 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 the US Short Codes API returns a:
- Response - the status and cost of your request to Vonage in JSON or XML format.
- Delivery receipt - the status and cost of the SMS sent by Vonage to your user.
Note: you are only charged for correctly submitted outbound SMS. If status is not 0, you are not charged.
The response is send in the api.txt file when you make a request from the browser.
Each response comes:
- In a specific Format
- With Keys and values
Format
You set the response type using the Base URL. The following table shows example responses in JSON or XML:
{
"message-count":"1",
"messages":[
{
"status":"returnCode",
"message-id":"messageId",
"to":"to",
"client-ref":"client-ref",
"remaining-balance":"remaining-balance",
"message-price":"message-price",
"network":"network",
"error-text":"error-message"
}
]
}
<?xml version='1.0' encoding='UTF-8' ?>
<mt-submission-response>
<messages count='x'>
<message>
<messageId>${messageId}</messageId>
<to>${to}</to>
<clientRef>${client-ref}</clientRef>
<status>${returnCode}</status>
<errorText>${error-message}</errorText>
<remainingBalance>${account-balance}</remainingBalance>
<messagePrice>${message-price}</messagePrice>
<network>${network}</network>
</message>
</messages>
</mt-submission-response>
Keys and Values
The response contains the following keys and values:
Payload
Key | Description | Response type |
---|---|---|
message-count |
The number of parts the message was split into. | JSON |
messages |
Contains each message part. For an XML response, the count attribute contains the value of message-count JSON key. |
BOTH |
message |
A single message part. | XML |
status |
Shows how the SMS send is processing. | BOTH |
message-id |
The ID of the SMS that was submitted (8 to 16 characters). | JSON |
messageId |
The ID of the SMS that was submitted (8 to 16 characters). | XML |
to |
The phone number your request was sent to. | BOTH |
client-ref |
The client-ref you set in your request. | JSON |
clientRef |
The client-ref you set in your request. | XML |
remaining-balance |
The remaining balance in your account. The value is in EUR. | JSON |
remainingBalance |
The remaining balance in your account. The value is in EUR. | XML |
message-price |
The price charged for your request. The value is in EUR. | JSON |
messagePrice |
The price charged for your request. The value is in EUR. | XML |
network |
The Mobile Country Code Mobile Network Code (MCCMNC) for the carrier that to is registered with. | BOTH |
error-text |
If an error occurred, this explains what happened. | JSON |
errorText |
If an error occurred, this explains what happened. | XML |
Delivery receipt
Each request you make using the Short Codes API returns a:
- response - the status and cost of your request to Vonage in JSON or XML format.
- Delivery receipt - if you have set a webhook endpoint, Vonage forwards this delivery receipt to it. Carriers return a delivery receipt (DLR) to Vonage to explain the delivery status of your message. If the message is not received, the delivery receipt explains why your message failed to arrive.
The delivery receipt is sent using a GET HTTP request to your webhook endpoint. When you receive the DLR, you must send a 200 OK
response. If you do not send the 200 OK
, Vonage resends the delivery receipt for the next 72 hours.
A delivery receipt has a:
Format
The following code shows an example of a delivery receipt:
?msisdn=66837000111&to=12150000025
&network-code=52099&messageId=000000FFFB0356D2
&price=0.02000000&status=delivered
&scts=1208121359&err-code=0&message-timestamp=\2020-01-01\+12%3A00%3A00
Keys and Values
The delivery receipt includes:
Key | Value |
---|---|
to |
The SenderID you set in from in your request. |
network-code |
The Mobile Country Code Mobile Network Code (MCCMNC) of the carrier this phone number is registered with. |
messageId |
The Vonage ID for this message. |
msisdn |
The phone number this message was sent to. |
status |
A code that explains where the message is in the delivery process., If status is not delivered check err-code for more information. If status is accepted ignore the value of err-code. Possible values |
err-code |
If the status is not accepted, this key will have one of the these possible values |
price |
How much it cost to send this message. |
scts |
The Coordinated Universal Time (UTC) when the DLR was received from the carrier. The scts is in the following format: YYMMDDHHMM. For example, 1101181426 is 2011 Jan 18th 14:26. |
message-timestamp |
The time at UTC±00:00 when Vonage started to push this Delivery Receipt to your webhook endpoint. The message-timestamp is in the following format YYYY-MM-DD HH:MM:SS. For example, 2020-01-01 12:00:00. |
client-ref |
The client-ref you set in the request. |
status
values
Key | Value |
---|---|
delivered |
this message has been delivered to the phone number. |
expired |
the target carrier did not send a status in the 72 hours after this message was delivered to them. |
failed |
the target carrier failed to deliver this message. |
rejected |
the target carrier rejected this message. |
accepted |
the target carrier has accepted to send this message. |
buffered |
This message is in the process of being delivered. |
unknown |
the target carrier has returned an undocumented status code. |
Code | Description |
---|---|
0 |
Delivered. |
1 |
Unknown - either: An unknown error was received from the carrier who tried to send this this message. Depending on the carrier, that to is unknown. When you see this error, and status is rejected, always check if to in your request was valid. |
2 |
Absent Subscriber Temporary - this message was not delivered because to was temporarily unavailable. For example, the handset used for to was out of coverage or switched off. This is a temporary failure, retry later for a positive result. |
3 |
Absent Subscriber Permanent - to is no longer active, you should remove this phone number from your database. |
4 |
Call barred by user - you should remove this phone number from your database. If the user wants to receive messages from you, they need to contact their carrier directly. |
5 |
Portability Error - there is an issue after the user has changed carrier for to. If the user wants to receive messages from you, they need to contact their carrier directly. |
6 |
Anti-Spam Rejection - carriers often apply restrictions that block messages following different criteria. For example, on SenderID or message content. |
7 |
Handset Busy - the handset associated with to was not available when this message was sent. If status is Failed, this is a temporary failure; retry later for a positive result. If status is Accepted, this message has is in the retry scheme and will be resent until it expires in 24-48 hours. |
8 |
Network Error - a network failure while sending your message. This is a temporary failure, retry later for a positive result. |
9 |
Illegal Number - you tried to send a message to a blacklisted phone number. That is, the user has already sent a STOP opt-out message and no longer wishes to receive messages from you. |
10 |
Invalid Message - the message could not be sent because one of the parameters in the message was incorrect. For example, incorrect type or udh. |
11 |
Unroutable - the chosen route to send your message is not available. This is because the phone number is either currently on an unsupported network or on a pre-paid or reseller account that could not receive a message sent by from. To resolve this issue either email us at support@nexmo.com or create a helpdesk ticket at https://help.nexmo.com. |
12 |
Destination unreachable - the message could not be delivered to the phone number. |
13 |
Subscriber Age Restriction - the carrier blocked this message because the content is not suitable for to based on age restrictions. |
14 |
Number Blocked by Carrier - the carrier blocked this message. This could be due to several reasons. For example, to's plan does not include SMS or the account is suspended. |
15 |
Pre-Paid - Insufficient funds - to’s pre-paid account does not have enough credit to receive the message. |
99 |
General Error - there is a problem with the chosen route to send your message. To resolve this issue either email us at support@nexmo.com or create a helpdesk ticket at https://help.nexmo.com. |