Keep credentials on your server.
Create an API key in your dashboard and select the permissions the integration needs. Send the key in the X-API-Key header. Do not embed it in public JavaScript, commit it to source control, or include it in support messages.
Requests are scoped to the account and permissions behind the key. An authenticated key can still receive a permission error for an action it is not allowed to perform.
Your first request.
This read-only example fetches your account. Replace the environment variable with your own secret at runtime. Examples use standard HTTP libraries; no proprietary SDK is required.
curl 'https://otppin.com/api/v1/account' \
--header "X-API-Key: $API_KEY"The response is JSON. Check the HTTP status before reading the result. The interactive reference provides request fields, response schemas and additional examples from the application’s OpenAPI document.
Follow the order’s state.
- Read the catalog and available operators for the country and service you need.
- Review the current price and account balance before creating an order.
- Send a purchase request only when you intend to buy. Keep the returned order ID.
- Read that order to follow its status, SMS code and expiry. An order that expires without a code is credited to your account balance. A pending or active order can be cancelled with DELETE /api/v1/orders/:id once 2 minutes have passed and no code has arrived. Resend and finish are not available, and webhooks are not self-serve; poll the order instead.
Availability counts are provider-reported snapshots and can change between selection and purchase; only a successful order response confirms a number. If a network request times out, inspect your recent orders before retrying a purchase; an uncertain response does not prove that no order was created.
The core endpoints.
| Method and path | Purpose |
|---|---|
GET/api/v1/account | Read the authenticated account and balance. |
GET/api/v1/balance | Read the current USD balance. |
GET/api/v1/countries | Read the supported country catalog. |
GET/api/v1/services | Read service codes used for selection. |
GET/api/v1/operators | Compare operator prices and provider-reported availability estimates. |
GET/api/v1/numbers | Quote a country and service; availability is an estimate, not an allocation. |
POST/api/v1/orders | Purchase an order using country, service and an optional operator. This debits your balance. |
GET/api/v1/orders | Read your recent orders. |
GET/api/v1/orders/{id} | Read one order, its SMS state and expiry. |
DELETE/api/v1/orders/{id} | Cancel an order 2 minutes or more after purchase if no code has arrived; the charge is credited to your account balance. |
POST/api/v1/orders/{id}/cancel | POST form of the same cancellation route, for clients that cannot send DELETE. |
POST/api/v1/orders/{id}/finish | Not available: finishing an order is not supported. |
POST/api/v1/orders/{id}/resend | Not available: requesting another SMS is not supported. |
Design for real responses.
- 401 · Authentication
- Check that the key is present and valid.
- 403 · Permission
- Check the key’s scope and the account’s access to the requested operation.
- 400 · Request validation
- Review the required fields and identifier formats in the reference.
- 429 · Rate limit
- Wait before retrying and honor the Retry-After header when it is supplied. Do not retry purchases blindly.
- Order-specific failures
- Handle insufficient balance, unavailable numbers, expiry and supplier errors using the returned error and order state.
See the API reference for the complete schema. For help, contact support with the request or order ID and a redacted error response.