Developers

OTPBox API

Buy numbers, check status, and manage your wallet programmatically. Every key shares the same wallet balance and refund rules as the normal site — nothing behaves differently just because you're calling it from code.

Getting a key

Get your API key →

Authentication

Send your key as a bearer token on every request. All amounts are in Nigerian Naira (NGN).

Authorization: Bearer YOUR_API_KEY

Endpoints

GET/api/v1/balance

Check your balance

Returns your current wallet balance.

Request

curl https://www.otpboxofficial.com/api/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "balance": 5000,
  "currency": "NGN"
}

GET/api/v1/prices

Get prices

Prices for a service, by country name. Omit the service param to list all available service codes.

Request

curl "https://www.otpboxofficial.com/api/v1/prices?service=tg" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "service": "tg",
  "currency": "NGN",
  "prices": {
    "Poland": 5050,
    "United Kingdom": 1800,
    "USA": 4700
  }
}

POST/api/v1/numbers

Buy a number

Debits your wallet and requests a number from the given service/country. Fails with 402 if your balance is too low, 404 if that combo isn't available, 409 if no numbers are in stock right now.

Request

curl -X POST https://www.otpboxofficial.com/api/v1/numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "tg", "country": "Poland"}'

Response

{
  "id": "ef84d5ff-f806-4561-a29e-adad14f2daaf",
  "phoneNumber": "48739271067",
  "service": "tg",
  "country": "Poland",
  "price": 5050,
  "currency": "NGN",
  "status": "pending",
  "expiresInSeconds": 1199,
  "canResend": true
}

GET/api/v1/numbers/:id

Check status / get the code

Poll this until status is 'delivered' (otp will be set) or 'refunded' (no code arrived in time — your wallet is credited automatically).

Request

curl https://www.otpboxofficial.com/api/v1/numbers/ef84d5ff-f806-4561-a29e-adad14f2daaf \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "ef84d5ff-f806-4561-a29e-adad14f2daaf",
  "status": "delivered",
  "otp": "384921",
  "phoneNumber": "48739271067",
  "service": "tg",
  "country": "Poland"
}

POST/api/v1/numbers/:id/cancel

Cancel and refund

Cancels a pending purchase and refunds your wallet. Only works after the first ~2 minutes (409 if too early) and only while a number is still pending — once a code has been delivered, that purchase is final.

Request

curl -X POST https://www.otpboxofficial.com/api/v1/numbers/ef84d5ff-f806-4561-a29e-adad14f2daaf/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "ef84d5ff-f806-4561-a29e-adad14f2daaf",
  "status": "refunded"
}

Errors

Errors come back as { "error": "..." } with a matching status code: 401 invalid/missing key, 402 insufficient balance, 404 not found, 409 temporarily unavailable or too early to cancel.

Help · Rules · Terms of Service