Quotes and public lists

A quote for one platform and country

/request/price answers "what would /purchase/sms charge right now?" and shows every option behind the answer. It is public: no key needed.

curl "https://numestri.com/api/v1/request/price?service=telegram&country=US"

{
  "success": 1,
  "service": { "id": "telegram", "name": "Telegram" },
  "country": { "id": "US", "name": "United States" },
  "price": "0.99",
  "price_cents": 99,
  "high_price": "1.30",
  "success_rate": null,
  "quality": null,
  "option": "5sQY4PwqkxD3gE7O",
  "options": [
    { "option": "5sQY4PwqkxD3gE7O", "provider": "prv_k3Jd9QmXa2", "rank": 1, "price": "0.99", "price_cents": 99, "quality": null, "success_rate": null, "stock": "plenty", "in_stock": true },
    { "option": "Hq2LmW8eRt5YxP0c", "provider": "prv_9TfXk2LwQa", "rank": 2, "price": "1.30", "price_cents": 130, "quality": null, "success_rate": null, "stock": "limited", "in_stock": true }
  ],
  "shared_inbox": { "price": "0.05", "price_cents": 5 }
}

When there is no answer

{
  "success": 0,
  "message": "No Telegram numbers in United States right now.",
  "type": "OUT_OF_STOCK",
  "options": [
    { "option": "5sQY4PwqkxD3gE7O", "provider": "prv_k3Jd9QmXa2", "rank": 1, "price": "0.99", "price_cents": 99, "quality": null, "success_rate": null, "stock": "none", "in_stock": false }
  ],
  "shared_inbox": null
}

Public prices and your prices

Without a key, a quote shows the public list price. With your key it shows your account's price — the same unless your account has negotiated pricing — which is exactly what an order from that account will be charged.

# Public list price
curl "https://numestri.com/api/v1/request/price?service=telegram&country=US"

# The price your account pays
curl "https://numestri.com/api/v1/request/price?service=telegram&country=US" -H "Authorization: Bearer $NUMESTRI_KEY"

A key that is wrong is refused with 403 rather than quietly showing public prices. Without a key, quotes count against the per-address limit of 10 requests per second; see Authentication.

From quote to order: max_price

A quote is not a reservation. Prices and stock move, and the price you are charged is always worked out on our side when the order is placed — you never send a price. To make sure you pay no more than you expect, pass max_price (in dollars) to /purchase/sms:

curl https://numestri.com/api/v1/purchase/sms -H "Authorization: Bearer $NUMESTRI_KEY" \
  -d service=telegram -d country=US -d max_price=0.99

• At or below max_price, the order goes through and cost in the response is what was charged.

• Above it, the order is refused before anything is charged:

  {
    "success": 0,
    "message": "The price for this number is $1.05, above your maximum.",
    "type": "PRICE_NOT_FOUND",
    "code": "PRICE_ABOVE_MAX"
  }

• max_price must be a positive dollar amount like 0.75; anything else is a 400 with param: "max_price".

To lock in one exact offer rather than a ceiling, pass that offer's option id: it is bought at its listed price or not at all (OPTION_GONE).

Public lists, no key needed

These keep the shape most verification APIs use, so a storefront can list what is on sale without an API key.

ID is the exact id the ordering endpoints take. These two always show public prices, and are cached for a few minutes.