Two-factor Authentication API Reference

This describes the US Short Code Two-factor Authentication API in the following steps:

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:

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 Nexmo 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:

Response

Each request you make using the US Short Codes API returns a:

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:

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:

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, Nexmo 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 Nexmo 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 Nexmo 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 Nexmo 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.