OTPIXA
Developer API

OTPIXA API

A REST API for buying virtual numbers, reading SMS and managing your wallet programmatically. This documentation is public and always free to read.

Authentication

Every request is authenticated with an API key sent in the Authorization header. Keys are issued per account and can be revoked at any time. Requests without a valid key are rejected server-side with 401.

curl https://api.otpixa.com/v1/balance \
  -H "Authorization: Bearer otpx_live_xxxxxxxx"

Countries

Returns the active country catalog with ISO alpha-2, ISO alpha-3, calling code and sort order. Inactive countries are omitted.

GET /v1/countries

{
  "data": [
    { "iso2": "PK", "iso3": "PAK", "name": "Pakistan", "calling_code": "+92" }
  ]
}

Services

Lists services configured by the marketplace, with slug, display name, logo URL and starting price.

GET /v1/services?country=PK

Inventory

Reports availability per service, country and operator. Values are authoritative and change continuously; never cache stock as truth.

GET /v1/inventory?service=whatsapp&country=PK

Create Order

Reserves a number and debits the wallet with the server-calculated price. Send an idempotency key to make retries safe.

POST /v1/orders
{
  "service": "whatsapp",
  "country": "PK",
  "operator": null
}

Get Order

Returns the order with its number, price, status, SMS status and any received messages.

GET /v1/orders/{order_id}

Cancel Order

Cancels an eligible order. Refund eligibility is decided server-side based on order state and elapsed time.

POST /v1/orders/{order_id}/cancel

Order / SMS Status

Poll for SMS delivery, or subscribe to webhooks to avoid polling. Status values: pending, waiting_sms, completed, cancelled, expired, refunded.

GET /v1/orders/{order_id}/sms

Balance

Returns the authoritative wallet balance for the authenticated account in USD, the base accounting currency.

GET /v1/balance

{ "available": "0.00", "pending": "0.00", "currency": "USD" }

Webhooks

Register an HTTPS endpoint to receive sms.received, order.completed, order.expired and deposit.completed events. Every delivery is signed; verify the signature before trusting the payload.

X-OTPIXA-Signature: sha256=<hmac>

{ "event": "sms.received", "order_id": "...", "code": "..." }

Errors

Errors use standard HTTP status codes with a machine-readable code: 400 invalid_request, 401 unauthorized, 402 insufficient_balance, 403 subscription_required, 404 not_found, 409 conflict, 429 rate_limited, 5xx server_error.

{ "error": { "code": "insufficient_balance", "message": "..." } }

Rate Limits

Limits are applied per API key and returned on every response via X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Back off on 429 responses.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118

Examples

A complete buy-and-read flow: create an order, poll or receive the webhook, then read the verification code.

# 1. create
curl -X POST https://api.otpixa.com/v1/orders \
  -H "Authorization: Bearer $OTPIXA_KEY" \
  -d '{"service":"whatsapp","country":"PK"}'

# 2. read sms
curl https://api.otpixa.com/v1/orders/ord_123/sms \
  -H "Authorization: Bearer $OTPIXA_KEY"