Receiving the code

A code can arrive seconds or minutes after you order. There are two ways to get it: ask, or be told.

Polling

/sms/check answers for one order. It returns 200 for any order you own — branch on status, not on the HTTP code.

curl https://numestri.com/api/v1/sms/check -H "Authorization: Bearer $NUMESTRI_KEY" -d orderid=JRJ5UEXS

{ "status": 1, "resend": 0, "time_left": 1188 }

{
  "status": 3,
  "sms": "140722",
  "full_sms": "140722 is your Telegram verification code."
}

Poll every 3–5 seconds and stop on 3, 2, 5 or 6.

Many orders at once

/request/active returns every outstanding order in one call — the right choice once you have more than one in flight.

curl https://numestri.com/api/v1/request/active -H "Authorization: Bearer $NUMESTRI_KEY"

[
  { "order_code": "JRJ5UEXS", "phonenumber": "12025550123", "code": "140722", "status": "completed", "time_left": 1102 }
]

status is one of pending, processing, activating, completed, resend, expired, cancelled or refunded. processing and activating are not ready yet: wait for pending, using ready_at_estimate as a guide.

Before buying, /request/price lists each option's readiness: instant, or activates with the typical ready_in_seconds, plus how soon a first code usually lands.

A complete loop

const api = "https://numestri.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.NUMESTRI_KEY}` };

const order = await fetch(`${api}/purchase/sms`, {
  method: "POST", headers, body: new URLSearchParams({ service: "telegram", country: "US" }),
}).then((r) => r.json());
if (!order.success) throw new Error(order.message);

let asked = false; // 7 / 8: activating, not ready to receive yet.
while (true) {
  const check = await fetch(`${api}/sms/check`, {
    method: "POST", headers, body: new URLSearchParams({ orderid: order.order_id }),
  }).then((r) => r.json());

  if (check.status === 1 && !asked) { /* Ready: ask the platform for the code now. */ asked = true; }
  if (check.status === 3) { console.log("code:", check.sms); break; }
  if ([2, 5, 6].includes(check.status)) throw new Error("No code; the order was refunded.");
  await new Promise((r) => setTimeout(r, 4000));
}