OTPPINDocumentationManage API keys ↗OTPPINDocumentationManage API keys ↗Inspect request and response schemas from the application's OpenAPI document. Requests sent using the interactive client are real: purchase operations can debit your balance. Start with a read-only account request.
JSON REST API under /api/v1/*. Authenticate with an API key generated from the OTPPin dashboard, sent in the X-API-Key header (or as Authorization: Bearer <key>). Each endpoint also needs a matching permission on the key; a key without it gets 403. Every error is JSON { "error": "<CODE>", "message": "<human text>" }. Read endpoints are limited to 600 requests per minute per user and order creation to 120 per minute; a 429 carries a Retry-After header. A separate handler_api.php SMS-activation protocol (SMS-Activate compatible) is served at /stubs/handler_api.php and is documented on the API docs page.
Authenticated account info.
GET /api/v1/account Get account info
Returns the authenticated account and current balance. Requires account:read.
GET /api/v1/balance Get balance
Returns only the current balance in USD. Requires balance:read or account:read.
Browse supported countries, services, operators and live pricing.
GET /api/v1/countries List countries
Returns every country OTPPin currently supports. Requires numbers:read.
GET /api/v1/services List services
Returns every service (app) OTPPin currently supports. Requires numbers:read.
GET /api/v1/operators List operators (with prices) for a country + service
Returns every operator that can actually be bought for the given (service, country) pair (route on sale, supplier active), with its "Operator N" number, label, per-OTP price in whole cents and a provider-reported count estimate. Counts are routing signals, not guarantees that the next allocation will succeed. Operator N is the same number the dashboard buy page shows. It is a position in the current ranking, so it can change as prices and stock move: list, then order promptly, and set max_price to guard the price. Use the operator field when creating an order to pin a specific operator. Requires numbers:read.
GET /api/v1/numbers Check live price & availability
Browse current inventory by country and service. When both country and service are supplied, the response includes the live per-OTP price and provider-reported aggregate availability for that pair. Availability is a changing estimate, not a guarantee that an allocation will succeed. This is the price POST /api/v1/orders charges when no operator is pinned, in whole cents. price is null and available is 0 when the route is not sold. Requires numbers:read.
Create and poll one-time number orders. Cancel is available after 2 minutes. Finish and resend exist as routes but are not available.
GET /api/v1/orders List your orders
Paginated list of your orders, newest first. Requires orders:read.
POST /api/v1/orders Create an order
Reserve a virtual number for the given country and service. **This debits your balance.** Requires orders:create. Limited to 120 orders per minute per user. Send an Idempotency-Key header (8-128 characters of A-Z a-z 0-9 _ . : -) to make retries safe: a retry with the same key returns the original response (with Idempotent-Replayed: true) instead of buying again. Successful orders also commit a hashed replay receipt atomically with the debit, so a lost cache write cannot turn a retry into a second charge. Never reuse a key for a different purchase. A concurrent duplicate gets 409 IDEMPOTENCY_IN_PROGRESS, failed attempts are not remembered so they can be retried, and 503 UNAVAILABLE means the idempotency store is down and nothing was charged.
GET /api/v1/orders/{id} Get order status
Poll every 3–5 seconds until otpCode is populated or status leaves active. Requires orders:read.
DELETE /api/v1/orders/{id} Cancel an order
Cancels a pending or active order that has no code. Accepted only 2 minutes or more after purchase (CANCEL_TOO_EARLY with Retry-After otherwise). The charge is credited to your account balance, not to the original payment method. Orders that receive no code expire after 20 minutes and are credited the same way.
POST /api/v1/orders/{id}/cancel Cancel an order (POST form)
Same as DELETE /api/v1/orders/{id}, for clients that cannot send DELETE.
POST /api/v1/orders/{id}/finish Finish a completed order (not available)
Not available: finishing an order is not supported, so this request cannot succeed.
POST /api/v1/orders/{id}/resend Request another SMS (not available)
Not available: requesting another SMS is not supported, so this request cannot succeed.
Rent a number for a fixed duration and read every SMS it receives. A rental can be cancelled for a full credit only inside its cancel window and before any SMS arrives.
GET /api/v1/rent/prices Rental prices
With service alone, the countries it can be rented in and the lowest price in each. With service and country, the durations on offer and the price of each. Only the listed durations can be bought. Requires numbers:read.
GET /api/v1/rent List your rentals
Paginated list of your rentals, newest first. Requires orders:read.
POST /api/v1/rent Rent a number
Rent a number for one service in one country for a listed duration. **This debits your balance.** Requires orders:create and shares the 120 per minute purchase limit with order creation. Send an Idempotency-Key header (8-128 characters of A-Z a-z 0-9 _ . : -) to make a retry safe: for 24 hours the same key returns the original response (with Idempotent-Replayed: true) instead of renting again. A concurrent duplicate gets 409 IDEMPOTENCY_IN_PROGRESS, and 503 UNAVAILABLE means the idempotency store is down and nothing was charged.
GET /api/v1/rent/{id} Get a rental and its SMS
One rental with the SMS it has received. Poll it to read incoming messages. messages is null when the inbox could not be read right now, which is different from an empty inbox. Requires orders:read.
DELETE /api/v1/rent/{id} Cancel a rental
Cancels an active rental that has received no SMS and credits the full charge to your account balance. When the rental has a cancel window (cancellableFrom, cancellableUntil) a cancel is accepted only inside it. Requires orders:cancel.
POST /api/v1/rent/{id}/cancel Cancel a rental (POST alias)
Cancels an active rental that has received no SMS and credits the full charge to your account balance. When the rental has a cancel window (cancellableFrom, cancellableUntil) a cancel is accepted only inside it. Requires orders:cancel.
The machine-readable document is at /api/openapi. Guides and examples are in the API documentation.