The catalogue tree

The catalogue is a tree. Each call returns only the level under the choice you made, so you never download the whole market to find one price.

/catalog/platforms                                                         every platform in stock
/catalog/platforms/{platform}/countries                                    where that platform is sold
/catalog/platforms/{platform}/countries/{country}/providers                who sells it there
/catalog/platforms/{platform}/countries/{country}/providers/{provider}/options   what each sells it from

Every id along the way is exact and is what /purchase/sms takes.

curl https://numestri.com/api/v1/catalog/platforms

{
  "success": 1,
  "prices_at": "2026-10-14T01:40:00.000Z",
  "count": 1326,
  "next": "/api/v1/catalog/platforms/{platform}/countries",
  "data": [
    { "id": "discord", "name": "Discord", "countries": 12, "from_price": "0.07", "from_price_cents": 7 }
  ]
}

curl https://numestri.com/api/v1/catalog/platforms/discord/countries

{
  "success": 1,
  "prices_at": "2026-10-14T01:40:00.000Z",
  "platform": "discord",
  "count": 12,
  "next": "/api/v1/catalog/platforms/discord/countries/{country}/providers",
  "data": [
    { "id": "US", "name": "United States", "providers": 2, "from_price": "0.07", "from_price_cents": 7 }
  ]
}

curl https://numestri.com/api/v1/catalog/platforms/discord/countries/US/providers

{
  "success": 1,
  "prices_at": "2026-10-14T01:40:00.000Z",
  "platform": "discord",
  "country": "US",
  "count": 2,
  "next": "/api/v1/catalog/platforms/discord/countries/US/providers/{provider}/options",
  "data": [
    { "id": "prv_k3Jd9QmXa2", "rank": 1, "options": 2, "from_price": "0.07", "from_price_cents": 7, "quality": null, "success_rate": null }
  ]
}

curl https://numestri.com/api/v1/catalog/platforms/discord/countries/US/providers/prv_k3Jd9QmXa2/options

{
  "success": 1,
  "prices_at": "2026-10-14T01:40:00.000Z",
  "platform": "discord",
  "country": "US",
  "provider": "prv_k3Jd9QmXa2",
  "count": 2,
  "order": { "endpoint": "/api/v1/purchase/sms", "params": { "service": "discord", "country": "US", "option": "{option}" } },
  "data": [
    { "option": "k3Jd9QmXa2Lp0cWe", "rank": 1, "price": "0.07", "price_cents": 7, "quality": null, "success_rate": null, "stock": "plenty" },
    { "option": "Vb7nR2sYq0Te4hUa", "rank": 2, "price": "0.10", "price_cents": 10, "quality": null, "success_rate": null, "stock": "plenty" }
  ]
}

Ids: platform, country, provider, option

Both handles are opaque. A provider handle says nothing about who is behind it, and an option id is specific to one platform and country — the same offer elsewhere has a different id — so don't parse them or build them yourself; copy them from the catalogue. An option that no longer exists is refused at order time with code OPTION_GONE.

Rules worth knowing

• Only what is in stock. Every level lists only things you can buy right now. A choice with nothing under it is a 404 whose message points one level up:

  { "success": 0, "errors": [{ "message": "Nothing is in stock for \"discord\" in \"FR\". See /api/v1/catalog/platforms/discord/countries.", "param": "country" }] }

• Exact ids. Telegram, tg, us and United States are not ids. In a catalogue path they find nothing and answer 404; as a service or country parameter to /request/price or /purchase/sms they are refused with 400. Use telegram and US as the catalogue lists them.

• Fresh. Prices and stock are refreshed about every two minutes; prices_at says when the prices you are looking at were read.

• Warming up. Right after a restart the catalogue may answer 503 with Prices are being refreshed. Try again in a few seconds. — retry shortly.

• Shared numbers aren't in the tree. The tree lists private numbers. Whether a cheaper shared, public-inbox number is on offer for a platform and country is in the shared_inbox field of /request/price.

Caching with ETags

Every level carries an ETag and Cache-Control: private, max-age=30. Send the ETag back as If-None-Match, and while nothing at that level has changed you get a bodiless 304 instead of the list:

curl -i https://numestri.com/api/v1/catalog/platforms/discord/countries
# HTTP/1.1 200 OK
# ETag: W/"…"

curl -i https://numestri.com/api/v1/catalog/platforms/discord/countries -H 'If-None-Match: W/"…"'
# HTTP/1.1 304 Not Modified

• Tags are weak and compared weakly: W/"x" and "x" match. If-None-Match may hold a comma-separated list, or *.

• The tag changes whenever the prices behind the level may have changed — including when the prices that apply to you change — so a 304 always means your copy is current.

• Public prices and your account's prices can have different tags. Keep the tag with the response it came from, and don't reuse an anonymous tag on a keyed request.

• A request with key= in the URL is never cacheable; send the key in a header if you want caching.

{
  "success": 1,
  "prices_at": "2026-10-14T01:40:00.000Z",
  "platforms_in_stock": 1326,
  "tree": [
    { "level": 1, "list": "platforms", "path": "/api/v1/catalog/platforms" },
    { "level": 2, "list": "countries for a platform", "path": "/api/v1/catalog/platforms/{platform}/countries" },
    { "level": 3, "list": "providers for a platform in a country", "path": "/api/v1/catalog/platforms/{platform}/countries/{country}/providers" },
    { "level": 4, "list": "a provider's options", "path": "/api/v1/catalog/platforms/{platform}/countries/{country}/providers/{provider}/options" }
  ],
  "ordering": {
    "endpoint": "/api/v1/purchase/sms",
    "choose_by": [
      "service + country: the best option, failing over to the next",
      "service + country + provider: that provider only, its best option first",
      "service + country + option: exactly that option at its listed price, or nothing"
    ]
  }
}

Simpler public lists

If you only need names and ids — a dropdown, say — two flat lists keep the shape most verification APIs use. They take no key at all.

ID is the exact id the ordering endpoints take. Both always show public prices.