HTTP API for SMS Verification

Overview

Two equivalent base paths, both GET and POST. Client libraries for this protocol hard-code the first, so an existing integration usually moves here by changing the base URL and the key alone.

https://smsprime.pro/stubs/handler_api.php
https://smsprime.pro/api

• Responses are plain text. Four actions answer JSON instead: getPrices, getPricesFull, getCountries and getOperators.
• The HTTP status is 200 even for errors — BAD_KEY is a 200 whose body is BAD_KEY. Only the rate limit answers 429. Parse the body, not the status.
• Parameters are read from the query string and from a POST body alike — send a given name in one place or the other, never in both.
• Plain http:// answers 308, but only after the request has crossed the network: treat a key sent that way as compromised.

Authentication

Every request carries api_key; a missing or wrong key answers BAD_KEY. The key is on your profile page, where reissuing it kills the old one immediately.

GET https://smsprime.pro/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getBalance

Rate limit

Counted per second, set per account, 100 requests per second by default; your own figure is in your account, first card on the home page, under “API rate limit”. A change to it takes up to a minute to apply.

There are two counters, each allowed your full limit: getNumber with getStatus, and getBalance, getPrices, setStatus, getPricesFull, getCountries, getOperators and any unrecognised action together. Neither sees the other, so a 429 names the group you outran, and pacing both loops against one budget spends less than you are entitled to.

getPricesFull also has a second, much tighter limit of its own — 6 per minute, not per second, because that one answer is megabytes where every other action is a few hundred bytes. It is counted separately, so running it out costs you nothing on the calls above; details are in getPricesFull.

HTTP/2 429
Retry-After: 1

ERROR_RATE_LIMIT:1

The number after the colon is seconds to wait. The window is a fixed one second; then the counter is back to zero.

Which headers arrive depends on the action:

getBalance — current balance

?api_key=YOUR_API_KEY&action=getBalance

getNumber — request a number

?api_key=YOUR_API_KEY&action=getNumber&service=SERVICE&country=COUNTRY&operator=&maxPrice=

An empty operator, and the word any, are exactly the same as leaving it out; channels are below.

NO_NUMBERS deliberately does not distinguish causes — out of stock, upstream silent, upstream broken, or a pair we do not sell all answer the same, because the difference between replies would let anyone work out whose numbers we resell. It is a normal working reply, not an incident, and on rare pairs the usual one.

How long the number lives

Five minutes, the same for every activation, whichever upstream served it. On expiry the activation is cancelled automatically and costs nothing. The closure reaches upstream six to seven minutes after the order — a grace minute past the deadline, so an SMS arriving in the last seconds is not lost, plus a sweeper that runs once a minute. The reliable close signal is STATUS_CANCEL, not your own clock.

Services — what to put in service=

Every code below is a valid service value. Codes are lower case and stable — once issued, a code is not renamed, because it is what your integration sends. The name beside it is only a label for people and may be reworded.

From is the cheapest a pair of this service can cost you, across all countries and all channels. It is a floor, not a quote: the price of a particular country is in getPrices, and without operator what you are charged is decided by the draw (see Channels).

240 services

Country codes — what to put in country=

Two letters, ISO 3166-1 alpha-2, case does not matter: country=RU and country=ru are the same request. An unknown code answers NO_NUMBERS, the same reply as a pair we do not sell — the two are deliberately indistinguishable.

Or the word any, which means «any country you have» — see the note under getNumber for what it charges. The reply does not change shape. It is a word on purpose: a magic number would sit in the same numbering as real countries, where a value carried over from another service is already very likely to be a real country here, just not the one you meant. 1000 is not a country of ours, so it answers NO_NUMBERS like any other unknown number.

Which countries a service sells is per service, so it is not a single list to print here — there are 253 of them, and the answer differs by service. Fetch the one you need, no key required:

GET https://smsprime.pro/catalog/vk/countries

It answers JSON: iso2, the country name, and the price range for that pair. The picker on our site walks the same route, so what you get is exactly what a person sees. If you would rather choose by hand, the same lists are on the services pages.

country= also takes a number — ours, one per country, listed by getCountries. The two forms are interchangeable, so nothing here changes if you send ISO codes; read the warning under that action before you send numbers.

Channels — choosing a supply route

A channel is one of our supply routes. The same service and country pair often reaches you through several, and they are not interchangeable: each has its own price, and each may or may not be able to serve a given order. You name one by number in the operator parameter, which getNumber and getPrices both take.

Elsewhere in this protocol operator names a mobile network, and an unknown value is usually ignored. Here it is a channel number, so a network name carried over from another service answers BAD_OPERATOR instead of quietly charging you for a route you did not choose.

One word is accepted beside a number: any, in upper case, lower case or mixed. It means “no preference” and behaves in every respect as if the parameter had been left out — same draw, same price rule, same replies. Send it if your client insists on filling the field in. It is the only such word: all, auto, a network name or a near miss such as anyone still answers BAD_OPERATOR, because guessing what you meant would charge you for a route you did not choose.

Leaving operator out: same request, price in a range

Omit it, send it empty, or send any, and the request behaves as it did before channels existed — same parameters, same replies, same set of pairs. You are charged the price of the channel we drew, uniformly at random among those serving your pair, so two identical requests can cost different amounts. The channel that served you is in your order history.

Channels you cannot afford are removed before the draw, so a small balance is served only by the cheaper ones, and NO_BALANCE comes back only when no channel at all is within reach — not when merely the dearest is.

Name a channel and none of that applies: you pay that channel’s price, known before you order, and it is the only channel we try — no fall-through to a neighbour, no retry inside the request, and an empty result is NO_NUMBERS. A retry carrying the same operator stays on that channel at that price; without operator every attempt is a fresh draw.

Capping the price: maxPrice

Without operator the draw decides what you pay, and the spread can be wide — a pair whose channels run from $0.300 to $1.364 will sometimes charge you four times the cheapest. maxPrice is your ceiling: channels dearer than the amount you name never enter the draw, so you are charged no more than you said. Everything else about the request is unchanged.

GET /stubs/handler_api.php?api_key=…&action=getNumber&service=vk&country=RU&maxPrice=0.300

The limit is inclusive: maxPrice=0.300 buys a 0.300 channel. Amounts take up to three decimals, the same as every price we print; a fourth is refused rather than rounded, because rounding one way tightens your limit and the other way loosens it, and neither is ours to choose.

The bare token WRONG_MAX_PRICE, with no amount, means the value itself was unusable: not a number, negative, more than three decimals, sent twice, or sent as an array such as maxPrice[]=0.300. That last one is refused, unlike operator[]=2 which is ignored: an unread operator means “no channel chosen”, but an unread maxPrice would mean “charge me anything” — in the very request where you asked us not to. No amount is suggested there, because we did not understand what you asked for. Money comes first: if you cannot afford any channel at all, the answer is NO_BALANCE even when a limit is also in play — top up first, then worry about the ceiling.

With operator the two work together: name a channel dearer than your limit and the order is refused, not silently charged. Both numbers came from you, and we honour both or neither.

When operator is refused

Three causes answer BAD_OPERATOR and are deliberately indistinguishable: a number we never issued, one switched off, and one switched on but selling nothing anywhere. No timing or header difference separates them.

Spaces and leading zeros are trimmed, so operator=%202%20 and operator=007 order channels 2 and 7. The same trimming happens before any is recognised, so operator=%20ANY%20 is that word; but it has to be the whole value, and the letters have to be the plain ASCII ones — anyone, any1 and a look-alike typed in another alphabet are all BAD_OPERATOR. Sending operator twice is refused with BAD_OPERATOR even when both values are identical — decided on the raw request, before the value is parsed, so watch for an HTTP client that appends a default to a URL already carrying one; two copies of any are refused just the same. Anything that is not a plain scalar, such as operator[]=2, is disregarded rather than refused, and the order proceeds without a channel.

Which channels exist

Channel numbers come from us: they are on the site where you order, and you can discover them over the API. getPrices with an operator answers with a price list when that number is a channel you can order from, and BAD_OPERATOR otherwise — walking the numbers is a supported way to find out which.

For the channels that can serve a particular service and country, ask getOperators instead — walking operator tells you which channels exist, not which ones your order can use, and those are different questions: a channel that exists but does not serve your pair answers NO_NUMBERS, not BAD_OPERATOR.

Walk 1 to 99. That is the whole range we issue from, handed out at random, so a walk that stops at 9 or at 40 simply misses channels. Values above 99 are accepted by the parser but are not numbers we hand out, and 32768 and above are refused outright.

A channel that sells nothing anywhere is not a channel: to answer at all, the route behind a number has to be selling at least one service in at least one country. That is about the channel as a whole, never about your pair — a listed channel can still have nothing for the pair you want, which is an ordinary NO_NUMBERS. Naming a channel never narrows the catalogue either, so the walk tells you which channels you can order from and nothing more.

The channel number is stable

Numbers are stored, not computed, so switching a channel off never renumbers the others, and a switched-off channel stops answering rather than quietly becoming someone else. The one qualification: numbers no client is ordering through do get reassigned, so that the numbering says nothing about us. A number you use is left alone; one you wrote down and then left unused is not reserved for you, and if it is reassigned it will not start failing — it will start buying from a different channel at a different price. Check it against getPrices after a long gap.

getStatus — read the code

?api_key=YOUR_API_KEY&action=getStatus&id=ACTIVATION_ID

Poll once every 2–5 seconds. STATUS_WAIT_CODE is partly served from an 8-second cache, so polling faster than once a second cannot make the code arrive sooner — it only spends your rate limit.

setStatus — confirm or cancel

?api_key=YOUR_API_KEY&action=setStatus&id=ACTIVATION_ID&status=CODE

An unknown activation, or one belonging to someone else, answers NO_ACTIVATION — and the activation is looked up before status is parsed, so an invalid status on an activation that does not exist answers NO_ACTIVATION, not BAD_ACTION.

status=6 does not close the activation. It answers ACCESS_ACTIVATION and leaves the state exactly as it was; you are charged when the code arrives, at STATUS_OK, so sending it is optional and harmless. If your previous service used the other values for intermediate steps, drop them: between issuing the number and the code arriving there is no state worth reporting.

When to cancel

Cancelling by hand is not required — an unclaimed activation closes itself, and nothing is charged either way. But an explicit cancellation closes it on our side immediately and asks upstream to release the number, and an open activation holds the number: on rare destinations, ordering the same pair again may not succeed until it is closed. Cancelling is free until the code arrives: you are charged for the code, so cancelling before it adds no charge, and after it there is nothing left to cancel — the charge stands and is not refunded.

getPrices — the price list

?api_key=YOUR_API_KEY&action=getPrices&operator=

The only action that answers with JSON. First-level key is the country in lower case, second is the service code.

{
  "ru": {
    "go": { "cost": 1.23, "count": 100 },
    "vk": { "cost": 4.56, "count": 100 }
  }
}

The numbers above are invented — read prices from getPrices itself, never from this page. The list is cached, so a price change shows up within a minute, and only pairs we sell appear in it.

Without operator, cost is a ceiling, not a fixed charge — the highest of the prices that pair’s channels charge (see Channels). With operator it is exact: the amount getNumber with the same operator would charge, pairs where that channel has no price of its own keeping the list price. The set of pairs is the same either way, including pairs that channel cannot serve, so nothing here says which channel serves which pair.

count is always the constant 100, for every pair — part of the protocol’s shape, not a stock figure, and nothing can be inferred from it. Elsewhere in the industry the same field is sometimes real.

An operator that is not a channel you can order from answers BAD_OPERATOR in plain text — the one case where this action does not answer JSON.

getPricesFull — the price list broken down by channel

?api_key=YOUR_API_KEY&action=getPricesFull

This action is ours, not part of the protocol. No other service speaking it has an action by this name, so a client library will not know it — you read this response with your own code. It takes no parameters at all, not even operator: every channel is already in the answer.

The shape extends getPrices rather than replacing it. First-level key is the country in lower case, second is the service code; cost and count mean exactly what they mean there, and channels is added beside them.

{
  "ru": {
    "vk": {
      "cost": 4.56,
      "count": 100,
      "channels": { "7": 1.11, "42": 4.56 }
    }
  }
}

The numbers above are invented, as on getPrices — read prices from the action itself, never from this page.

channels maps the channel number — the same number you send as operator to getNumber (see Channels) — to the price that channel charges for this pair. It is an object, never a list, and a pair served by no numbered channel has it as {} rather than as an empty list.

cost stays the ceiling: the highest of the channel prices below it, which is what an order without operator can cost you at worst. Both readings of the same pair are in one answer, so nothing has to be joined across two requests taken at different moments.

The pairs are the same pairs getPrices returns, in the same order of keys — sorted, which also makes the answer compress far better. Only pairs we actually sell appear, and a channel appears on a pair only if it can serve it.

getCountries — the country list

?api_key=YOUR_API_KEY&action=getCountries

Answers JSON: an object whose key is our number for a country and whose value describes it. It takes no parameters, and it needs a key like every other action.

{
  "185": {
    "id": 185,
    "rus": "Russian Federation",
    "eng": "Russian Federation",
    "chn": "Russian Federation",
    "visible": 1,
    "retry": 0,
    "rent": 0,
    "multiService": 0
  }
}

What each field means here:

Every country we know is listed, including the ones we do not sell today — those carry visible: 0 instead of being left out. That way the list decodes any of our numbers you ever meet, and a country that starts selling tomorrow costs you nothing to pick up. A country we have switched off entirely is not listed at all, because country= would not take its number either.

The answer is small — tens of kilobytes for all 253 countries — and it changes rarely, while the visible flags follow the catalogue within a minute, exactly like getPrices. Fetch it when your program starts, not once per order.

getOperators — which channels serve a service

?api_key=YOUR_API_KEY&action=getOperators&service=SERVICE&country=COUNTRY

Answers JSON. countryOperators maps our number for a country to the channel numbers that can serve this service there — the same numbers you send as operator to getNumber (see Channels).

{
  "status": "success",
  "countryOperators": {
    "185": ["19", "36", "44", "55", "88", "93"]
  }
}

Leave country out and every country we sell this service in is listed — that answer is a few kilobytes, so the parameter saves you bandwidth rather than making the question answerable. It takes an ISO code or our number, exactly like country= at getNumber, and the key in the answer is always our number: ask for RU and the answer is filed under 185. Read the warning under getCountries before you send numbers of your own.

A country we do not sell this service in is simply not in the answer, and so is a country we do not know at all — the answer is then {}, not an error token. There is no refusal token for a country in this protocol, and NO_NUMBERS would be the wrong one to borrow: it means “try again later”, and this will not become true later.

A country listed with an empty array is a real answer, not a bug: we sell the pair, and no numbered channel serves it. Order it without operator and it works — there is simply nothing to name.

Channels we do not publish are not here either. A channel held back for a negotiated price does not appear, though it still serves an order that names it; a channel withdrawn from a pair appears nowhere and serves no one. The list is exactly the channels keys of the same pair in getPricesFull — the same rule read two ways, and it cannot disagree with itself.

The answer is small and changes rarely, and it follows the catalogue within a minute, exactly like getPrices. Fetch it when you set up a service, not once per order.

All responses

There are exactly eight actions: getBalance, getNumber, getStatus, setStatus, getPrices, getPricesFull, getCountries, getOperators. Any other value of action answers BAD_ACTION — including a near miss such as getpricesfull, since the name is matched exactly. Seven of the eight are the protocol’s; getPricesFull is ours. getOperators keeps the protocol’s name and shape but requires service, because our operator is a channel and channels differ per service (see getOperators). Treat an unknown response as an error, not a success — the set of tokens may grow.

Quick start

KEY=$SMS_PRIME_API_KEY
BASE=https://smsprime.pro/stubs/handler_api.php

curl -s "$BASE?api_key=$KEY&action=getBalance"
# ACCESS_BALANCE:10000.000

curl -s "$BASE?api_key=$KEY&action=getNumber&service=vk&country=RU"
# ACCESS_NUMBER:42:79991234567

curl -s "$BASE?api_key=$KEY&action=getStatus&id=42"
# STATUS_WAIT_CODE — repeat every 2-5 s until STATUS_OK:<code> or STATUS_CANCEL

curl -s "$BASE?api_key=$KEY&action=setStatus&id=42&status=8"
# ACCESS_CANCEL