Order lifecycle & messages
Know when a number is ready, when a message has arrived and when to stop polling.
Number allocation
purchasing means the system is assigning a number and wallet funds are reserved. phone, operator and expires_at may still be null.
failed means no number was purchased and the reservation was refunded. purchase_unknown means allocation needs review; do not automatically create another purchase. Keep the order ID for support.
Read active orders
PENDING and RECEIVED are active states. Always inspect the sms array: RECEIVED by itself does not guarantee a verification code.
Each message includes sender, text, code and date, and may include id. Preserve the full message when needed and deduplicate messages in your application.
Poll GET /orders/{id} every 10 seconds. Background provider checks continue even if your application disconnects. Refresh an order requests a check, but repeated checks are throttled.
const { order } = await response.json();
for (const sms of order.sms) {
console.log(sms.sender, sms.code, sms.text);
}
// Inspect the status as well; stop polling when the order is terminal.Complete or cancel an order
FINISHED means the order is complete. Finish an active order only after an SMS has arrived and you have used the message.
Cancel is allowed for an active order before an SMS arrives. CANCELED, TIMEOUT and BANNED are terminal statuses; stop polling them.
If an action returns 409, retrieve the order and inspect its current state. It may already be terminal or currently updating. Do not repeatedly submit the same action without checking.
Confirm refunds and review states
Check refunded_at for a recorded refund. A local timer, timeout or browser countdown is not proof of a refund.
If error_code indicates refund_review or an allocation remains unresolved, open a support ticket with the order ID and error message. Never include the API key.
Get an order returns one record. List orders returns up to 20 per page with hasMore; increase offset by 20 while hasMore is true.