# SafeCode Numbers API

> Rent a virtual phone number, receive the OTP or SMS sent to it, and get refunded if nothing arrives. REST over HTTPS, JSON in and out, pay-as-you-go from one SafeCode wallet.

Base URL: https://api.safecode.vip/v1
Auth: `Authorization: Bearer sfcd_live_…` (key needs the `otp:receive` scope; `?key=` also accepted)
Envelope: every response is `{ "success": 1|0, "errno": <int>, "message": "…", …data }`

Typical flow: `GET /request/price` → `POST /purchase/sms` → poll `POST /sms/check` until `status` is `3` → read `code`. Cancel with `POST /sms/cancel` before the 20-minute window closes to get the charge back.

## Reference

- [Full API reference (Markdown)](https://safecode.vip/developer-apis/numbers.md): Every endpoint, request field, response shape and errno code. Read this first.
- [Human docs page](https://safecode.vip/developer-apis/numbers): The same content rendered for people.
- [Dashboard](https://safecode.vip/numbers-api): Create API keys and fund the wallet.

## Endpoints

- POST /purchase/sms: buy a number for a `country` + `service`; returns `order_id`, `phonenumber`, `cost`, `expires_in`
- POST /sms/check: poll an `orderid`; `status` 1 waiting, 3 received, 4 expired, 6 cancelled
- POST /sms/cancel: release the number and refund (only before a code arrives)
- POST /sms/resend: ask the service to resend; not supported for WhatsApp (returns errno 8)
- GET /service/retrieve_all: all purchasable services
- GET /country/retrieve_all: all purchasable countries
- GET /request/price?country=&service=: exact price the purchase will charge
- GET /request/balance: wallet balance in USD
- GET /request/history?limit=: recent orders

## Notes for integrators

- `country` and `service` accept names, short codes (`us`, `telegram`, `whatsapp`) or UUIDs from the list endpoints.
- WhatsApp is fulfilled from a dedicated pool: availability is per country, and `/sms/resend` is unavailable for it.
- A number is held for 20 minutes (`expires_in: 1200`). Received codes are cached; re-checking a completed order is free and instant.
- errno 4 covers both "no stock" and "no price yet for this pair"; check `/request/price` first.
- Rate-limited calls return errno 7 with HTTP 429.

## Related

- [Messaging & Bulk SMS API](https://safecode.vip/developer-apis/messaging/llms.txt): The other direction: send SMS or WhatsApp from your own backend.
- [Site index](https://safecode.vip/llms.txt)