Request a number
API keyPOST /api/v1/activationsBuys a number for a service in a country and charges your balance. Send a unique Idempotency-Key header per purchase: repeating a request with the same key returns the same activation instead of charging twice. `price` must equal a current price (see Get current prices); if it changed you get PRICE_CHANGED with the new prices.
Requires your API key in the Authorization: Bearer header (generate it in Settings).
Parameters
service* — Service code, e.g. tg (from List services).country* — Country id (from List services).price* — The price you agree to pay, in 1/10,000 units.Idempotency-Key* — Header: 16–64 letters, digits, _ or -.
Possible errors
401 UNAUTHORIZED— Missing, invalid or revoked API key.429 RATE_LIMITED— Too many requests — wait and retry.402 INSUFFICIENT_FUNDS— Top up your balance.409 PRICE_CHANGED— Price moved; `prices` lists current ones.409 NO_NUMBERS— Out of stock — retry or pick another country.502 PROVIDER_ERROR— Upstream problem; you were not charged.
Example response
curl -X POST https://your-domain/api/v1/activations \
-H "Authorization: Bearer rk_live_…" \
-H "Idempotency-Key: 7f3c9a1e5b2d4f6a8c0e" \
-H "Content-Type: application/json" \
-d '{"service":"tg","country":"12","price":4200}'
201 { "order": { "id": "…", "phoneNumber": "1…", "status": "active",
"price": 4200, "currency": "USD", "expiresAt": "…", … } }