# NumberCodes API

> NumberCodes API is a high-speed virtual phone number gateway for automated SMS verification, compatible with modern JSON REST API, instant Webhooks, and the legacy SMS-Activate / SMSHub protocol. Unified balance in USD managed via [@NumberCodes_bot](https://t.me/NumberCodes_bot).

## Overview
- [Website and Docs](/docs): Interactive API reference and live Playground with shadcn/ui.
- [OpenAPI Specification](/openapi.json): Standard OpenAPI 3.0 schema.
- [Full LLM Documentation](/llms-full.txt): Complete unabridged API specification and code examples.

## Key Concepts
- Unified USD balance synchronized with the [@NumberCodes_bot](https://t.me/NumberCodes_bot) Telegram bot.
- Rate limits: 120 requests/minute per API key (sliding window 60s, returns HTTP 429 when exceeded).
- Safe concurrency & Idempotency: supports `Idempotency-Key` header and atomic balance deductions.
- Order rental window: 20 minutes with automatic cancellation and full refund if no SMS is received.
- Real-time Webhooks: instant HTTP POST callbacks on SMS reception or order cancellation.

## Authentication
API keys begin with `ak_live_` and are issued in [@NumberCodes_bot](https://t.me/NumberCodes_bot) under "Profile" -> "🔑 API разработчикам" or `/api`.
Pass the token in one of three ways:
- Header `X-API-Key: ak_live_...` (recommended for REST API)
- Header `Authorization: Bearer ak_live_...`
- Query param `?api_key=ak_live_...` (for SMS-Activate protocol)

## Core REST Endpoints
- [GET /api/v1/balance](/docs#tag/rest-api/balance): Retrieve current account balance in USD.
- [GET /api/v1/services](/docs#tag/rest-api/services): Catalog of available services (tg, wa, vk, ya, etc.) with live prices.
- [GET /api/v1/countries](/docs#tag/rest-api/countries): Supported countries list with numeric IDs, names, and popularity flags.
- [GET /api/v1/availability](/docs#tag/rest-api/availability): Real-time phone number stock count and pricing.
- [POST /api/v1/orders/buy](/docs#tag/rest-api/buy): Purchase a single phone number for SMS activation (HTTP 201). Supports `callback_url` and `Idempotency-Key`.
- [POST /api/v1/orders/buy-bulk](/docs#tag/rest-api/buy-bulk): Batch purchase 1 to 20 phone numbers in a single call (HTTP 201).
- [GET /api/v1/orders](/docs#tag/rest-api/orders): Paginated list of user orders with status filters (`waiting_sms`, `received`, `cancelled`, `all`).
- [GET /api/v1/orders/{order_id}](/docs#tag/rest-api/order-status): Check order status and retrieve received SMS verification code.
- [POST /api/v1/orders/{order_id}/cancel](/docs#tag/rest-api/cancel): Cancel number before SMS arrives and instantly refund 100% of the cost.
- [POST /api/v1/orders/{order_id}/finish](/docs#tag/rest-api/finish): Mark order as successfully completed.
- [POST /api/v1/orders/{order_id}/retry](/docs#tag/rest-api/retry): Request additional/second SMS code for the same number.
- [POST /api/v1/orders/{order_id}/outbound-call](/docs#tag/rest-api/outbound-call): Initiate flash-call / call-drop confirmation from purchased number.
- [PUT /api/v1/orders/{order_id}/webhook](/docs#tag/rest-api/webhook): Attach or update Webhook callback URL for an active order.
- [GET /api/v1/transactions](/docs#tag/rest-api/transactions): Paginated transaction history of purchases and refunds.

- [GET /api/v1/operators](/api#tag/rest-api/operators): Mobile operators to pick on purchase (`operator` field).
- [GET /api/v1/rental/tiers](/api#tag/rest-api/rental-tiers): Rental terms (instant 20 min, 1h, 24h, 7d, 30d) and prices; buy with `rental_tier`.
- [GET /api/v1/orders/active](/api#tag/rest-api/orders-active): Orders still waiting for an SMS.
- [GET /api/v1/orders/{order_id}/wait](/api#tag/rest-api/wait): Long-poll (up to 30 s) until the code arrives instead of polling every 2 s.
- [POST /api/v1/deposits](/api#tag/rest-api/deposits): Create a CryptoBot or xRocket top-up invoice (`Idempotency-Key` required); `GET /api/v1/deposits/{id}` checks payment.
- [PUT /api/v1/webhook](/api#tag/rest-api/webhook): One account-wide webhook for all events (`sms_received`, `order_cancelled`, `rental_finished`, `rental_expiring`, `balance_topped_up`). Requests are signed: header `X-NumberCodes-Signature: t=<unix>,v1=<hex>`, `hex = HMAC-SHA256(secret, "<t>.<raw body>")`. Failed deliveries are retried; see `GET /api/v1/webhook/deliveries`, `POST /api/v1/webhook/test`, `POST /api/v1/webhook/secret`.

## SMS-Activate Gateway
Compatible endpoint for third-party software (TG-Expert, Telegram Prime, SMS-Activate scripts).
- Endpoint: `GET/POST /stubs/handler_api.php`
- Actions: `getBalance`, `getPrices`, `getNumber`, `getStatus`, `getStatusV2`, `getFullSms`, `setStatus`, `getActiveActivations`.
- Repeat code: `setStatus` with `status=3` starts waiting for another SMS; `getStatus` answers `STATUS_WAIT_RETRY:<previous code>` until it arrives, then `STATUS_OK:<new code>`. A `sms_received` webhook is also sent. REST equivalent: `POST /api/v1/orders/{id}/retry` then `GET /api/v1/orders/{id}/wait`.

## Optional
- [Playground](/docs#sandbox): In-browser interactive sandbox to test requests with live status codes, latency, and cURL / Python / JS snippet generation.
- [Support](https://t.me/cyuqid): Technical support and integration assistance.