Test OTP flows with a receive SMS API

2026-10-05

OTP steps are a common reason end-to-end tests are flaky. This guide shows how to test them on staging with public phone numbers and when to let the API wait for the code for you.

Before you start

The numbers are public and shared. Anyone can see the messages they receive, so use them only for testing on staging, never for accounts you need to keep. Some services block public numbers, so a missing SMS does not always mean your app failed.

Step 1: pick a number

List public numbers and filter by country.

curl -s "https://axioapi.com/api/v1/sms/numbers?country=US&limit=5" \
  -H "Authorization: Bearer $AXIOAPI_KEY"

Step 2: read the messages

Enter the exact number returned by the list in your staging form, then read the latest messages for that number.

curl -s "https://axioapi.com/api/v1/sms/numbers/+12025550192/messages" \
  -H "Authorization: Bearer $AXIOAPI_KEY"

Step 3: let the API wait for the code

Instead of writing a polling loop, call the verify endpoint. It waits for a matching SMS on that number, extracts a 4 to 8 digit code and returns it with the sender and full message. Pass a since timestamp so older messages are ignored.

curl -s -X POST "https://axioapi.com/api/v1/verify/wait" \
  -H "Authorization: Bearer $AXIOAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": "+12025550192", "since": "2026-10-05T09:00:00Z"}'

Handling timeouts

A timeout means no matching message arrived during the wait. The call does not create a new number, so retry the whole flow with another number if you need to. Check the endpoint table on the SMS and OTP API pages for the current prices.