Order one-time numbers
from your own code.

Authenticate with an API key

Create a key in your dashboard after you register. Send it in an X-API-Key header, or as Authorization: Bearer. Each key carries permissions (read the catalog, create orders, read orders, read balance), so grant only what the integration needs.

Keep the key on your server. A missing or invalid key returns 401, and a key without the needed permission returns 403.

Read the catalog and listed prices

GET /api/v1/services and GET /api/v1/countries return the service and country codes to use. GET /api/v1/numbers with service and country returns the listed price for that pair, and GET /api/v1/operators lists operators for it.

Listed prices and availability are cached supplier estimates. A number is assigned only when the order is placed, and allocation can fail. The availableIsEstimate field in the response says the same thing: treat any availability figure as an estimate, not a reservation.

curl "https://otppin.com/api/v1/services" \
  --header "X-API-Key: $API_KEY"

curl "https://otppin.com/api/v1/countries" \
  --header "X-API-Key: $API_KEY"

# Listed price for one service and country (ISO-2 country code)
curl "https://otppin.com/api/v1/numbers?service=SERVICE_CODE&country=US" \
  --header "X-API-Key: $API_KEY"

Place one order

POST /api/v1/orders takes service and country, and optionally operator and max_price (USD). It debits your account balance and returns a number. One order is one number for one service. An order stays open for 20 minutes.

Send an Idempotency-Key header (8 to 128 characters) so a retried request after a timeout does not become a second purchase.

curl -X POST "https://otppin.com/api/v1/orders" \
  --header "X-API-Key: $API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: your-unique-key-123" \
  --data '{ "service": "SERVICE_CODE", "country": "US" }'

{
  "id": "...",
  "phoneNumber": "...",
  "country": "US",
  "service": "SERVICE_CODE",
  "price": 0.00,
  "balance": 0.00,
  "status": "active",
  "expires_in": 1200,
  "expiresAt": "..."
}

Read the status and the SMS

Poll GET /api/v1/orders/ORDER_ID until the order has a code. status is one of pending, active, completed, cancelled or expired. When an SMS arrives, otpCode and message are filled in. GET /api/v1/orders lists your recent orders.

The response also carries canCancel, canResend and canFinish flags. Check them rather than assuming. canCancel is true while an order is pending or active, and cancellableAt is when a cancel will be accepted (2 minutes after purchase, and only if no code has arrived). canResend and canFinish are not offered, so plan for an order to run until it completes, is cancelled or expires.

curl "https://otppin.com/api/v1/orders/ORDER_ID" \
  --header "X-API-Key: $API_KEY"

{
  "id": "...",
  "status": "completed",
  "otpCode": "...",
  "message": "...",
  "expiresAt": "...",
  "completedAt": "..."
}

Errors, and what happens on expiry

Errors come back as JSON: { "error": "CODE", "message": "..." }. Common codes are VALIDATION_ERROR (400), UNAUTHORIZED (401), FORBIDDEN (403), NO_BALANCE, NO_NUMBERS and RATE_LIMITED (429, with a Retry-After header). A failed allocation is possible even for a listed price, so handle NO_NUMBERS and supplier errors.

If no SMS arrives before the order expires, the charge is credited back to your account balance automatically. It is not returned to the payment method you topped up with. Balance top-ups are currently accepted by cryptocurrency only. The minimum top-up is $2.

What the API does not do.

Full details.

The API docs cover authentication and workflow. The API reference lists every endpoint and field. Check current prices before you build against a service.

Buying for a company? See business purchasing.