Two-factor Authentication API Reference

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:

• A Base URL
• Parameters
• Authentication information
• Security
• Encoding

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:

Parameters

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

Authentication information

To authenticate your request, you must provide the following parameters:

You can find your Key and Secret in the Dashboard.

If you are using signatures to verify your requests use:

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.

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

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
• Keys and Values

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: