SMS verification API

Buy numbers and read codes from your own software. The API uses your balance, the same prices and the same 20-minute refund rule as the website.

You create the API key inside your account. Numbers bought through the API come out of the same balance at the same prices as the website.

Create an account API key

From $0.0018 per number

Key facts

Lowest price per number: $0.0018
Authentication: API key
Format: JSON over HTTPS
Rate limit: 120 requests a minute
Refund: Same as the website

REST and JSON

Six requests cover balance, services, prices, getting a number, status and cancel.

A key from your account

Create a key on the API key page of your account and send it in the Authorization header.

Same prices as the website

Number prices and the 20-minute refund rule are the same as on the website.

Which requests can I send?

Paths go after the base URL. Every request needs your API key.

Which requests can I send?
Method and path	What it does
GET`/balance`	Your balance in USD
GET`/services`	All services with the lowest price and number of countries
GET`/prices?service=telegram`	The price of one number in every country for a service
POST`/numbers`	Get a number for a service and country; the price is taken from your balance
GET`/numbers/{id}`	Status of a number and every code received so far
POST`/numbers/{id}/cancel`	Cancel before a code arrives; the price returns to your balance

In what order do I call the API?

1
Get a number POST /numbers with service and country. Save the id and number.
2
Enter the number Type the number into the service that sends the code.
3
Check for the code GET /numbers/{id} every 5 seconds until the codes list is not empty.
4
Finish Use the code. If you no longer need the number before a code comes, cancel it.

How do I get an API key?

Log in and open API key in your account. Create a key and copy it right away; it is shown only once. Making a new key turns the old one off.

API key

What is the base URL?

Send every request to this address with the key in the Authorization header (Bearer) or the X-Api-Key header:

https://tomnumber.com/api/v1

Authorization: Bearer <API_KEY>

Request fields

Request fields
Field	Used in	Value
`service`	POST /numbers, GET /prices	Service name from /services, e.g. telegram
`country`	POST /numbers	Two-letter country code, e.g. gb

Response fields and statuses

Response fields and statuses
Value	Meaning
`waiting`	Number is open and no code has arrived yet
`received`	At least one code arrived; more can still come until expires_at
`refunded`	No code within 20 minutes; the price went back to your balance
`canceled`	You canceled before a code arrived; the price went back to your balance

Example response

{  "ok": true,  "id": "R8KQ2M7XWD4P",  "service": "telegram",  "country": "gb",  "number": "+44 7700 900412",  "price": "0.167",  "status": "received",  "expires_at": "2026-11-11T09:20:00.000Z",  "codes": [    { "code": "483920", "text": "Telegram code: 483920", "received_at": "2026-11-11T09:01:12.000Z" }  ]}

Error codes

Error codes
`unauthorized`	Missing or wrong API key
`rate_limited`	More than 120 requests in a minute
`bad_service`	Unknown service name
`bad_country`	Country not available for that service
`low_balance`	Balance is lower than the price
`unavailable`	No number available right now. Nothing was charged
`not_found`	No number with that id on your account
`cannot_cancel`	A code already arrived or the number is closed

Code examples

# get a numbercurl -X POST https://tomnumber.com/api/v1/numbers \  -H "Authorization: Bearer $API_KEY" \  -H "Content-Type: application/json" \  -d '{"service":"telegram","country":"gb"}' # check for codescurl https://tomnumber.com/api/v1/numbers/R8KQ2M7XWD4P \  -H "Authorization: Bearer $API_KEY"

const api = (path, init = {}) =>  fetch("https://tomnumber.com/api/v1" + path, {    ...init,    headers: { Authorization: "Bearer " + process.env.API_KEY, "Content-Type": "application/json" },  }).then((r) => r.json()); const n = await api("/numbers", { method: "POST", body: JSON.stringify({ service: "telegram", country: "gb" }) });console.log(n.number); // enter this number in the app let codes = [];while (!codes.length) {  await new Promise((r) => setTimeout(r, 5000));  const s = await api("/numbers/" + n.id);  if (s.status === "refunded" || s.status === "canceled") break;  codes = s.codes;}console.log(codes.map((c) => c.code));

import os, time, requests API = "https://tomnumber.com/api/v1"H = {"Authorization": "Bearer " + os.environ["API_KEY"]} n = requests.post(API + "/numbers", json={"service": "telegram", "country": "gb"}, headers=H).json()print(n["number"])  # enter this number in the app while True:    time.sleep(5)    s = requests.get(API + "/numbers/" + n["id"], headers=H).json()    if s["codes"] or s["status"] in ("refunded", "canceled"):        breakprint([c["code"] for c in s["codes"]])