DEV Community

2FASMS
2FASMS

Posted on

How to get SMS verification numbers with the 2FASMS API

#showdev #api

Need a phone number to receive an SMS verification code, and want to do it from code instead of clicking through a website? This tutorial shows how to use the 2FASMS REST API to check your balance, list available services, buy a virtual number and read the SMS code.

All requests below use curl, so you can follow along from any terminal. A ready-made Postman collection is linked at the end.

Prerequisites

  • A 2FASMS account
  • Your API key, shown in your account settings

Store the key in an environment variable so you never paste it into commands or commit it by accident:

export API_KEY="YOUR_API_KEY"
Enter fullscreen mode Exit fullscreen mode

The base URL for every request is https://api.2fasms.com. Authenticated endpoints expect your key in the Authorization header as a Bearer token.

Step 1: Check your balance 

curl -H "Authorization: Bearer $API_KEY" \
     "https://api.2fasms.com/order/api/get_balance"
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "balance": 25.50,
  "user_id": 123
}
Enter fullscreen mode Exit fullscreen mode

If the key is missing you get a 400, and an invalid key returns a 401.

Step 2: List the available services

This endpoint does not need authentication. Pass an optional country slug to get the services for one country:

curl "https://api.2fasms.com/order/api/services?country=france"
Enter fullscreen mode Exit fullscreen mode

Response (shortened):

{
  "country": "france",
  "services": [
    {
      "name": "whatsapp",
      "providers": ["provider_5", "provider_7", "provider_9"],
      "min_price": 15.20,
      "max_price": 33.50
    }
  ],
  "total": 89,
  "from_cache": true
}
Enter fullscreen mode Exit fullscreen mode

The name field is the service slug you will use in the next step. If you want the list of countries and their slugs, call GET /order/api/countries.

Step 3: Buy a number

Send a POST with the country and service slugs:

curl -X POST \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"country":"france","service":"whatsapp"}' \
     "https://api.2fasms.com/order/api/get_number"
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "orderId": 12345,
  "number": "+33123456789",
  "status": "ok"
}
Enter fullscreen mode Exit fullscreen mode

Keep the orderId: you need it to read the SMS. Use the number in the app or website where you want to receive the code.

Possible errors: 400 for invalid parameters, 406 for insufficient funds, and 500 if the service or country is unavailable.

Step 4: Read the SMS code

Once you have requested the code on the target service, poll the order:

curl -X POST \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"orderId":12345}' \
     "https://api.2fasms.com/order/api/check_order"
Enter fullscreen mode Exit fullscreen mode

When the SMS has arrived, the response contains the code:

{
  "status": "success",
  "data": [{ "orderId": 12345, "sms": "123456" }]
}
Enter fullscreen mode Exit fullscreen mode

Here is a small shell loop that polls every 5 seconds, for up to 2 minutes:

for i in $(seq 1 24); do
  curl -s -X POST \
       -H "Authorization: Bearer $API_KEY" \
       -H "Content-Type: application/json" \
       -d '{"orderId":12345}' \
       "https://api.2fasms.com/order/api/check_order"
  echo
  sleep 5
done
Enter fullscreen mode Exit fullscreen mode

You get a 404 if the order does not exist and a 400 if orderId is missing.

Prefer a webhook to polling

Instead of polling, you can register an HTTPS endpoint and 2FASMS will POST each received SMS to it:

curl -X POST \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"url":"https://your-app.com/sms-hook"}' \
     "https://api.2fasms.com/user/webhook"
Enter fullscreen mode Exit fullscreen mode

The payload contains the order ID, service, country, the full SMS text, the extracted code, the number and the reception time. Failed deliveries (non-2xx responses) are retried up to 3 times. Send an empty url to disable the webhook.

Step 5: Finish the order

When you are done, close the order:

curl -X POST \
     -H "Authorization: Bearer $API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"orderId":12345}' \
     "https://api.2fasms.com/order/api/finish_order"
Enter fullscreen mode Exit fullscreen mode 
{
  "message": "order has been finished"
}
Enter fullscreen mode Exit fullscreen mode

A 406 means the order was already cancelled or expired, or that the SMS is still pending.

Try it in Postman

I put the four main requests (balance, services, buy a number, read the SMS) in a public Postman collection. The key is a {{api_key}} variable, so just set it to your own key:

https://documenter.getpostman.com/view/59423970/2sBYHXRJZs

Wrapping up

That is the whole flow: balance, services, number, code. From here you can plug it into your own test suite, a signup automation for your staging environment, or any workflow that needs a throwaway number.

You can create an account and get your API key here: 2FASMS

Disclosure: I work on the 2FASMS team.

Top comments (0)