USA Reseller API

Build your USA number platform

Your customers buy from your platform. Your backend orders a USA number from Temp Number, your Temp Number wallet pays for it, and your backend retrieves the SMS code for your customer. You control your own retail prices and customer billing.

This API covers the USA dashboard's short-term numbers. Global numbers, long-term rentals, dedicated numbers and temporary email are not available through this API. Version 1 uses polling; customer webhook delivery is not provided.

1. Generate an API key and save it in your server's environment variables.
2. Fund your wallet, then fetch services and current NGN prices.
3. Save a unique order key in your database, order a number, and store the returned rental id.
4. Poll for the code and deliver it to the customer who owns that order on your platform.

https://tempnumber.ng/api/v1

Authenticate every request with X-API-Key: tn_.... Send JSON for POST requests. API keys are for server-to-server use; never embed them in a frontend, mobile app, public repository, or URL.

Quick start

Prices and IDs below are examples. Choose a service and spending cap from the live catalog.

# Run on your server. Keep the same order key and body for retries.
export TEMP_NUMBER_API_KEY='tn_REPLACE_WITH_YOUR_KEY'

curl 'https://tempnumber.ng/api/v1/prices' \
  -H "X-API-Key: $TEMP_NUMBER_API_KEY"

curl 'https://tempnumber.ng/api/v1/rent' \
  -H "X-API-Key: $TEMP_NUMBER_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-platform-order-1001' \
  -d '{"service":"whatsapp","max_price_ngn":2000}'

# Replace 12345 with the id from your order response.
curl 'https://tempnumber.ng/api/v1/status' \
  -H "X-API-Key: $TEMP_NUMBER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"id":12345}'

Pricing, retries and limits

All amounts are NGN. API orders use reseller wholesale pricing, giving you room to add your own retail profit margin. The live API catalog is authoritative. The quoted price is reserved before the provider receives the purchase and is the total charged for that order. A lower provider cost does not change the accepted quote. Existing orders keep the price accepted when they were placed.

One Idempotency-Key per customer order. Use 8–128 letters, digits, dots, colons, underscores or hyphens. Save the key and request body before sending. If the connection drops, retry with exactly the same key and body. Successful retries return the original HTTP 201 response with Idempotency-Replayed: true; its balance is the original snapshot. Use /balance for current funds. A different body with the same key returns 409.

If provisioning cannot be confirmed, order_pending includes a request_id and the reserved amount. Keep the original key. The reservation prevents a second purchase while the outcome is checked. Contact support with the request ID if the state persists. A confirmed rejection releases the reservation; use a new key only for a deliberately new order.

60 requests per minute per account, shared by all endpoints and keys. Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds); 429 includes Retry-After. There is a limit of 10 active or pending USA rentals, including USA dashboard rentals. Stagger polling and back off to stay within your account limit.

Confirmed expiry or cancellation without a code returns funds to your Temp Number wallet once. Receiving a code completes the order and does not refund it. Your platform must separately decide how to credit your own customer. Revoking a key stops future API authentication; existing orders remain in your account and can be accessed with a new key.

For unresolved orders, email support@tempnumber.ng with your request ID. Never send your API key.

Wallet balance

Available funds in your Temp Number wallet. Reservations for pending orders are already deducted. Top up in the dashboard before purchasing.

Example response

{
  "balance_ngn": 15000,
  "currency": "NGN"
}

USA services and live prices

Use api_name as the service when ordering. price_ngn is your purchase price in Naira; stock can change before you order. ttl is the rental duration in minutes. Only USA short-term services are returned.

Example response

[
  {
    "api_name": "whatsapp",
    "service_name": "WhatsApp",
    "country": "USA",
    "currency": "NGN",
    "price_ngn": 2000,
    "stock": 12,
    "ttl": 20,
    "multiple_sms": false
  }
]

Order a USA number

Requires Idempotency-Key. service is required; max_price_ngn is an optional spending cap in NGN. The server checks current stock and pricing, reserves your funds, then provisions the number. Other fields, including country, provider and USD max_price, are rejected. Returns HTTP 201 on success.

JSON request

{
  "service": "whatsapp",
  "max_price_ngn": 2000
}

Example response

{
  "id": 12345,
  "number": "+12025550123",
  "service_name": "WhatsApp",
  "country": "USA",
  "price_ngn": 2000,
  "currency": "NGN",
  "status": "active",
  "code": null,
  "end_time": "2026-09-06T12:20:00Z",
  "new_balance": 13000,
  "request_id": "81"
}

Receive the SMS code

Use the id returned by /rent or /rentals. Poll every 10 seconds, slowing down when you have several active rentals. Stop at completed, cancelled or expired. Codes are strings, preserving leading zeros. A provider outage returns 502; it does not imply expiry or a refund.

JSON request

{
  "id": 12345
}

Example response

{
  "id": 12345,
  "number": "+12025550123",
  "service_name": "WhatsApp",
  "country": "USA",
  "status": "completed",
  "code": "012345",
  "end_time": "2026-09-06T12:20:00Z",
  "price_ngn": 2000,
  "currency": "NGN",
  "rented_at": "2026-09-06 12:00:00",
  "refunded": false,
  "refund_ngn": 0,
  "new_balance": 13000
}

Cancel and check the outcome

Requests cancellation from the provider. Only a confirmed cancellation or expiry without an SMS credits the wallet. The response can remain active if cancellation is not yet confirmed, or become completed if an SMS arrived. Repeating a terminal cancellation does not refund again. refunded describes a credit made by this request, not the rental's entire refund history.

JSON request

{
  "id": 12345
}

Example response

{
  "id": 12345,
  "number": "+12025550123",
  "service_name": "WhatsApp",
  "country": "USA",
  "status": "cancelled",
  "code": null,
  "end_time": "2026-09-06T12:20:00Z",
  "price_ngn": 2000,
  "currency": "NGN",
  "rented_at": "2026-09-06 12:00:00",
  "refunded": true,
  "refund_ngn": 2000,
  "new_balance": 15000
}

USA rental history

Returns your USA short-term rentals, including dashboard purchases, newest first. Global, dedicated and long-term numbers are excluded. Optional query parameters: limit (1–100, default 50) and before (the previous next_cursor). Continue until next_cursor is null. The cursor is a pagination token; use each rental's id for status and cancellation.

Example response

{
  "data": [
    {
      "id": 12345,
      "number": "+12025550123",
      "service_name": "WhatsApp",
      "country": "USA",
      "status": "completed",
      "code": "012345",
      "end_time": "2026-09-06T12:20:00Z",
      "price_ngn": 2000,
      "currency": "NGN",
      "rented_at": "2026-09-06 12:00:00"
    }
  ],
  "next_cursor": null
}

Errors

{
  "error": "Top up your Temp Number wallet.",
  "code": "insufficient_balance",
  "price_ngn": 2000
}

Use HTTP status and code in your integration; error text can change. Unknown routes and unsupported methods may return framework-level errors, so handle non-JSON responses too.