Options and providers

What an option is, why one provider can offer several, how they are ranked, what quality and stock mean, and how prices are set.

Embed
Preview of the card
<a href="https://numestri.com/docs/options-and-providers"><img src="https://numestri.com/docs/_api/public/orgs/25229885-9620-4c08-bd2e-a0d0d74ac8b6/spaces/ef21e0c3-966d-4b03-b6d2-e66d449835d4/pages/72649c08-28f2-4638-b3d5-373eed856383/social-card.svg?v=3e7ae33eec8b" alt="Options and providers" width="600" height="315"></a>

An option is one specific way to fill an order: one provider, selling one platform in one country, from one of its own pools, at one price. A provider is the anonymous supplier behind a set of options.

Why one provider can have several options

Suppliers often sell the same platform from several pools of numbers — at different prices, with different stock. Each pool with numbers in it is its own option, so you can choose between them rather than being handed whichever is cheapest.

How options are ranked

Within a platform and country, options are listed best first:

  1. In stock before sold out.

  2. Proven before providers held in reserve for a poor delivery record on this exact platform and country.

  3. Delivery record on this pairing — learned from real orders, so a provider that is excellent for Telegram in the UK can rank last for WhatsApp in the US.

  4. Price, to break ties.

An order that names no option tries them in this order and fails over to the next if one cannot deliver.

Fields

These appear on each option, in the catalogue tree and in /request/price. Providers carry the same quality and success_rate, since a provider's record is per platform and country.

Field

Meaning

option

The id to send as option to buy exactly this. Opaque: copy it, don't build it.

provider

The provider's anonymous handle (prv_…), the same across platforms and countries. Send it as provider to order only from it. (In the tree it is in the path rather than on each option.)

rank

Position within the platform and country, 1 first.

price / price_cents

What you pay, per number.

quality

excellent, good, fair or poor — or null until enough real orders back a rating. We would rather show nothing than a guess.

success_rate

The share of orders that received a code, rounded to 5%, once there is enough evidence; otherwise null.

stock

plenty, limited, none or unknown. Exact counts are not exposed.

in_stock

/request/price only: whether the option can be bought right now.

How prices are set

Every price is set by us, and you never send one: the amount you are charged is worked out on our side at the moment you order.

  • Public prices. Without an API key, the catalogue and quotes show the public list price.

  • Your prices. With your key, they show your account's prices. These are the same as the public list unless your account has negotiated pricing, in which case they can differ.

  • What you see is what you pay. An order is charged the price your account was shown for it: an exact option at its listed price, a provider at its cheapest option in stock, otherwise the best option's price (the price of /request/price). If the market moved between your look and your order, the order is priced at the current figure — pass max_price and anything above your ceiling is refused with PRICE_ABOVE_MAX before you are charged.

Choosing well

Cheapest is usually fine. If a pairing matters — a platform that rejects many numbers, say — prefer an option with a proven quality, or pin a provider that has worked for you before.

Updated