SMS API Reference

Dive into our full API Reference Documentation and seamlessly integrate SMS functionalities into your website or application.

Our APIs use HTTP verbs and a RESTful endpoint structure. An access key and secret are used as the API Authorization framework. Request and response payloads are formatted as JSON, using UTF-8 encoding and URL encoded values.

API Endpoint

In order to use 2FA.link APIs, you need to first sign up for free at app.2fa.link

https://api.2fa.link/sms

Credentials

All requests to 2FA.link’s REST API need to be authenticated using HTTP Basic Authentication.

API key/secret pair are credentials you can create and revoke in the admin dashboard. These are typically easier to work with for your projects. You can quickly delete them to revoke access if they are compromised or create mutiple key/secret pairs for different use cases. You can also suspend an API key if neccesary to temporary block access.

API Key API Secret
Username Password

One of the most common mistakes that is made with API keys is to inadvertently check them into public repositories on platforms such as GitHub. From these public repositories, fraudsters can search and steal your API access key and use it to send Spam messages and also drain your account balance. The main takeaway is don’t hard-code your API access key and don’t check it into a public code repository.

HTTP Method

2FA.link only support the POST HTTP methods on various resources.

You can create or query a resource using the HTTP POST method on a resource URI. All you need is to provide the relevant fields in JSON! Here’s a POST request that will create a Verify Request using the 2FA.link API.

Send SMS

Use this to create a new SMS request.

curl -X POST "https://API_KEY:API_SECRET@https://api.2fa.link/sms" 
-H "accept: application/json" 
-H "Content-Type: application/json; charset=utf-8" 
-d '{
    "from":"2FA",
    "to":"6598765432",
    "mode":"sms",
    "content":"This is a SMS send from 2FA.link"
}'

$fields = [
    'from' => '2FA',
    'to' => '6598765432',
    'mode' => 'sms',
    'content' => 'This is a test SMS from 2FA.link'
];
$headers = [
    'Accept: application/json',
    'Content-Type: application/json; charset=utf-8'
];
$url = "https://API_KEY:API_SECRET@api.2fa.link/sms";
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($fields));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($curl);
curl_close($curl);

Request-body (content-type: application/json)
Key Mandatory Accepted Format Description
mode Yes “sms” Mode of operation
from No
[A-Za-z0-9 ]{2,11}
Sender ID (Default: “2FA”)
to Yes
[0-9]{10,15}
Receiver in E.164 Format
content No string SMS Content
base64 No 0 or 1 Content is base64 encoded (Default: 0)
udh No string User Data Header (Advance usage)

base64 encoded content: This is recommended to avoid encoding issue for non-latin characters.

Response-body (Positive)
{
    "errorcode":100,
    "errormsg":"Success",
    "request_id":"600EC8DB-FFMRSQGCNG"
}
Response-body (Negative)
{
    "errorcode":207,
    "errormsg":"Incorrect MODE Field Format"
}
Response-body
Key Description
errorcode Error code of Verify request
errormsg Error message of Verify request
request_id ID for SMS request

SMS Status Query

Use this API call to query SMS delivery status.

curl -X POST "https://API_KEY:API_SECRET@https://api.2fa.link/sms" 
-H "accept: application/json" 
-H "Content-Type: application/json; charset=utf-8" 
-d '{
    "request_id":"600CCE4E-PKUXGZIHYJ",
    "mode":"query"
}'

$fields = [
    'request_id' => '600CCE4E-PKUXGZIHYJ',
    'mode' => 'query'
];
$headers = [
    'Accept: application/json',
    'Content-Type: application/json; charset=utf-8'
];
$url = "https://API_KEY:API_SECRET@api.2fa.link/sms";
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($fields));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($curl);
curl_close($curl);

Request-body (content-type: application/json)
Key Mandatory Accepted Description
mode Yes “query” Mode of operation
request_id Yes
ID of SMS request
Response-body (Positive)
{
    "request_id":"600CCE4E-PKUXGZIHYJ",
    "from":"2FA",
    "to":"6598765432",
    "app_name":"SMS Only",
    "status":"SMS Delivered",
    "statuscode":"701",
    "msg_count":"1",
    "price":"-0.05",
    "timestamp_submitted":"2021-01-24T01:33:03+00:00",
    "timestamp_finalized":"2021-01-24T01:33:10+00:00"
}
Response-body (Negative)
{
    "request_id":"600EC8DB-FFMRSQGCNG",
    "status":"SMS Expired",
    "statuscode":"704"
}
Response-body
Key Description
request_id ID for Verify request
from Sender Name
to Receiver
app_name Application Name
status Status of SMS request
statuscode Status code
msg_count Messages sent
price Price charged (in EURO)
timestamp_submitted Timestamp of Verify request
timestamp_finalized Timestamp of Final status
Status
statuscode status Description
700 SMS Sent SMS Sent to user, pending DLR
701 SMS Delivered SMS Delivered to user
702 SMS Undelivered SMS Undelivered
703 SMS Rejected SMS Rejected by destination operator
704 SMS Expired SMS delivery failed due to VP expired
705 Unknown Status unknown
706 Not Found SMS request not found

SMS Feedback

Use this API call to feedback if SMS is received.

curl -X POST "https://API_KEY:API_SECRET@https://api.2fa.link/sms" 
-H "accept: application/json" 
-H "Content-Type: application/json; charset=utf-8" 
-d '{
    "request_id":"600CCE4E-PKUXGZIHYJ",
    "mode":"feedback"
}'

$fields = [
    'request_id' => '600CCE4E-PKUXGZIHYJ',
    'mode' => 'feedback'
];
$headers = [
    'Accept: application/json',
    'Content-Type: application/json; charset=utf-8'
];
$url = "https://API_KEY:API_SECRET@api.2fa.link/sms";
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($fields));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($curl);
curl_close($curl);

Request-body (content-type: application/json)
Key Mandatory Accepted Description
mode Yes “feedback” Mode of operation
request_id Yes
ID of Verify request
Response-body (Positive)
{
    "request_id":"600ED8FE-YEQJDVLLQI",
    "status":"Success",
    "statuscode":"600"
}
Status
statuscode status Description
600 Success Delivery feedback received

DLR Callback

A callback would be POST to your provided webhook when Delivery Receipt (DLR) is received from the carrier’s network. For security, you can whitelist traffic from only our IP address (168.119.166.186). Do note that more sites may be added in the future and you would be informed accordingly.

Request-body (DLR)
{
    "request_id":"60098C02-BMYUEJQIAN",
    "sender":"2FA",
    "msisdn":"6587654321",
    "status":"SMS delivered",
    "statuscode":"701",
    "timestamp":"2021-01-21T14:13:26+00:00"
 }
Request-body (content-type: application/json)
Key Description
request_id ID of SMS Request
sender Sender Name
msisdn Receiver
status DLR Status
statuscode Status code
timestamp Timestamp of DLR
Status
statuscode status Description
701 SMS Delivered SMS Delivered to user
702 SMS Undelivered SMS Undelivered
703 SMS Rejected SMS Rejected by destination operator
704 SMS Expired SMS delivery failed due to VP expired
705 Unknown Status unknown
Error Codes
errorcode errormsg
100 Success
101 Invalid API Key or Secret
102 Invalid Account
103 Rate Limit Reached
104 Insufficient Credit in Account
201 Missing Mandatory Field(s) for Requested Mode
202 Invalid API Key or Secret Format
203 Incorrect TO Field Format
204 Incorrect FROM Field Format
207 Incorrect MODE Field Format
209 Incorrect BASE64 Field Format
210 Incorrect UDH Field Format
211 Incorrect REQUEST_ID Field Format
301 SMS Rejected
401 Temporary Error, Please try again later!