Numbers overview

A number is a phone number that receives SMS for your project. There are three types, chosen with type:

Type	For	Lifetime	How you get it	Charged
`temporary`	One verification, for example a sign-up code	About 20 minutes	`POST /numbers/rent`	At rent; refunded if no SMS arrives
`monthly`	A number you keep	Until you release it; renews monthly	`POST /numbers/rent`	At rent, every month, and per SMS
`device`	Your own SIM in an Android phone	Until you disconnect it; renews monthly	Connect with the Android app	At connection, every month, and per SMS

Whatever the type, you read the SMS the same way: GET /numbers/sms/wait.

The catalog

Catalog endpoints show what you can rent and what it costs. They are free.

Endpoint	Returns
`GET /numbers/catalog/countries?type=`	Countries available for `temporary` or `monthly`
`GET /numbers/catalog/services?country=&q=`	The services (Telegram, Google and so on) a `temporary` number can receive SMS for. `q` searches names and codes
`GET /numbers/catalog/operators?country=`	Mobile operators for `temporary` numbers
`GET /numbers/catalog/prices`	Your price for a number. `price` is `null` when nothing is in stock
`GET /numbers/catalog/available`	`monthly` numbers you can rent, filterable by `line_type`, `area_code` and `contains`

Countries are ISO 3166-1 alpha-2 codes (US, GB). Service codes are short strings such as tg.

Renting

POST /numbers/rent takes the type, the country and the type’s own fields:

{ "type": "temporary", "country": "GB", "service": "tg", "operator": "o2", "max_price": 0.5, "metadata": { "order": 7 } }
{ "type": "monthly", "country": "US", "phone_number": "+14155550100", "line_type": "local" }

device numbers are not rented; they are connected. The response is { success, item, price, balance }: the number, what you were charged and what is left.

The inventory

Your project’s numbers are listed with GET /numbers/items and read with GET /numbers/items/{id}. A number stays in the list after it is released or expires. Filter with status, type, capability (comma-separated lists), phone_number and metadata.

An item looks like this:

{
  "id": "0190...",
  "phone_number": "+447380312345",
  "type": "temporary",
  "status": "ACTIVE",
  "status_reason": null,
  "country": "GB",
  "capabilities": { "voice": false, "sms": true, "mms": false, "fax": false },
  "assigned_at": "2026-10-25T10:00:00.000Z",
  "ended_at": null,
  "expires_at": "2026-10-25T10:20:00.000Z",
  "renews_at": null,
  "released_reason": null,
  "temporary": { "service": "tg", "operator": "any", "first_sms_at": null },
  "device": null,
  "metadata": { "order": 7 },
  "metadata_version": 0
}

temporary and device hold the type-specific details and are null for other types. expires_at is set for temporary numbers and renews_at for monthly and device numbers.

Status

`status`	Meaning
`ACTIVE`	Receiving SMS
`OFFLINE`, `SIM_REMOVED`	`device` only: the phone is unreachable, or its SIM was taken out
`EXPIRED`	A `temporary` number whose time ran out, until the record is closed (within a minute)
`RELEASED`	You released it, it expired, a renewal failed, or it was withdrawn. See `released_reason`
`MOVED`, `UNASSIGNED`	The number is no longer assigned to this project

released_reason is user, expired, renewal_failed, or supplier_missing when the number was withdrawn. Changes are announced by number.status_changed webhook events.

Releasing and resending

POST /numbers/items/{id}/release ends a number: a temporary number is cancelled (refunded if no SMS arrived), a monthly number is given up and stops renewing, a device number is disconnected and its monthly charge stops. Only this endpoint, and the console, release a number. Returns { item, refunded }.
POST /numbers/items/{id}/resend asks for a temporary number’s SMS again, at no charge. Other types answer 409 resend_not_supported.