sv-number

# SV Number

You are an AI agent. SV Number rents you a real phone number for as long as one signup
takes. You pick the country and the service, the number is yours alone, the verification
code arrives through the API, and you hand the number back. If the code never arrives,
you cancel and the money returns to your balance.

- Base URL: `https://sms-verification-number.com/stubs/handler_api`
- Docs: [sms-verification-number.com/en/api-sms-activate](https://sms-verification-number.com/en/api-sms-activate/)
- Human console: [sms-verification-number.com](https://sms-verification-number.com/en/)

---

## Before you start

Two scenarios. Know which one you're in:

1. You already have an API key. It may be in your environment as `SVN_API_KEY`, or your
   human shared one earlier. Skip to [Quick start](#quick-start).
2. You don't have a key. Your human creates an account at
   [sms-verification-number.com/en/register](https://sms-verification-number.com/en/register/),
   tops up the balance, and copies the key from
   [their profile](https://sms-verification-number.com/en/user/profile/). Ask them for it,
   then store it in an environment variable, never in chat, never in a file you commit.

There is no free tier on this API: every number costs money, so a funded balance is the
prerequisite. Check it with `getBalance` before you plan any work.

---

## How it works

One number = one activation = one service. The lifecycle is short and always the same:

```
choose country + service
        │
        ▼
   getNumber ──────────────► ACCESS_NUMBER:id:phone   (money is held)
        │
        ▼
   give the phone number to the service you are registering with
        │
        ▼
   getStatus (poll) ───────► STATUS_WAIT_CODE … STATUS_OK:123456
        │                                    │
        │ no code came                       │ code arrived
        ▼                                    ▼
   setStatus 8 (cancel)              setStatus 6 (finish)
   money returns                     activation closed
```

The number lives about 20 minutes. Measured on 08 August 2026: an unused activation was still
`STATUS_WAIT_CODE` at 20.9 minutes and had expired by 21.1. Expiry costs you nothing and needs
nothing from you, the money goes back on its own. Afterwards `getStatus` answers
`STATUS_CANCEL`, the same answer as for a cancellation you made yourself, and `setStatus`
answers `BAD_STATUS`. Plan the whole flow: request the code from the target service
immediately after you get the number, not ten minutes later.

Always send `lang`, even though the API answers without it. It picks the currency, and
the default is not `en`: the same balance came back as 3188.81 with `lang=en` and as 270.20
with no `lang` at all (checked 07 August 2026). Read prices in one currency and pay in
another, and every number you compare is wrong.

Both GET and POST work. Every example below uses GET for readability.

---

## Quick start

Replace `APIKEY` with your real key.

### Step 1: check the balance

```bash
curl 'https://sms-verification-number.com/stubs/handler_api?api_key=APIKEY&action=getBalance&lang=en'
# → 463.02
```

A bare number comes back, and that's your balance in the currency of `lang`.

### Step 2: find the country and the service code

Countries and their operators:

```bash
curl 'https://sms-verification-number.com/stubs/handler_api?api_key=APIKEY&action=getCountryAndOperators&lang=en'
# → [{"id":2,"name":"Russia","operators":{"any":"any","tele2":"tele2",...}}, ...]
```

Service codes, prices, how many numbers are online right now, and the field worth reading closely, the share of SMS that actually arrived for other users:

```bash
curl 'https://sms-verification-number.com/stubs/handler_api?api_key=APIKEY&action=getServicesAndCostWithStatistics&country=6&lang=en'
# → [{"id":"tg","name":"Telegram","price":0.71,"quantity":1429,"deliverability":"25.82",
#      "cheap_prices_countries":[{"country_id":6,"country_name":"Indonesia","price":"0.20"}, ...]}]
```

Order the code that belongs to the site you are actually signing up with. Each code has
its own pool of numbers behind it, and a number bought for Telegram does not receive a
Discord message. Look the code up every time instead of recalling it: the codes are short
and arbitrary, and a wrong guess buys a number that will never ring. `uk` is Airbnb, not
the United Kingdom. `re` is Coinbase, `tn` is LinkedIn, `mt` is Steam, `lf` is TikTok,
`dr` is ChatGPT.

Match on `name`, not on the code, and search for the bare name rather than the domain:
`discord` finds it, `discord.com` does not. One entry can cover several sites, so read the
whole name (`Google,youtube,Gmail` is one code).

The catalogue is not the same in every country. A service missing here can exist a country
over, so check a second country before deciding we do not carry it.

When the site really is not in the catalogue, order `ot`, "Not on list". That pool receives
SMS from any sender that is not in the list itself. It is not a wildcard: a site that has
its own code sends to that code, and `ot` will not pick it up.

`deliverability` is the share of codes that arrived for other users on that exact
service and country. Where it carries a number, trust it over price: a pair that answers
80% of the time beats one that is three cents cheaper and answers half as often.

**A zero means "no statistics yet", not "nothing gets through".** The field is filled in
for a small slice of pairs (74 out of 3835 on 07 August 2026), so most of what you read
will be `0`. Do not throw those away. When there is no number, fall back to `quantity`:
a large live pool is the pair that other agents are using successfully right now.

`cheap_prices_countries` tells you where the same service costs least, so use it when the
country doesn't matter to the service you're signing up for.

### Step 3: order the n