API

A REST API that follows the de-facto standard for virtual-number services. Point an existing client at our base URL, swap the key, and you are done.

Get your API key

Point your existing client at us

Change two lines — the base URL and the token — and every call your client already makes keeps working. Paths, query parameters, JSON field names and error strings are identical.

Base URL

https://otphub-api.43.203.247.133.nip.io/v1

Authentication

Send your key as a bearer token on every request.

Request

curl -H "Authorization: Bearer $OTPHUB_KEY" -H "Accept: application/json" "https://otphub-api.43.203.247.133.nip.io/v1/user/profile"

Quickstart

Create a key on your account page, export it, then buy a number.

Quickstart

export OTPHUB_KEY="your-api-key"

# 1. what is in stock
curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/products/england/any"

# 2. buy a number
curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/buy/activation/england/any/facebook"

# 3. poll it until the code lands
curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/check/11631253"

Endpoints

Guest

GET/v1/guest/countriesNo token

Every country we carry, with its dialling prefix and the operators serving it.

Request

curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/countries"

Response

{
  "england": {
    "iso": { "gb": 1 },
    "prefix": { "+44": 1 },
    "text_en": "England",
    "text_ru": "England",
    "vodafone": { "activation": 1 }
  }
}

GET/v1/guest/products/{country}/{operator}No token

Services available for a country and operator, with quantity and price. Both segments accept any.

Request

curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/products/england/any"

Response

{
  "1day":     { "Category": "hosting",    "Qty": 14,  "Price": 80 },
  "facebook": { "Category": "activation", "Qty": 133, "Price": 21 }
}

GET/v1/guest/prices?country=&product=No token

The full price matrix, nested country to service to operator. Filter it with country or product.

Request

curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/prices?country=england&product=facebook"

Response

{
  "england": {
    "facebook": {
      "vodafone": { "cost": 21, "count": 1260, "rate": 99.99 }
    }
  }
}

GET/v1/guest/flash/{lang}No token

The current site notice, in the language you ask for.

Request

curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/flash/en"

Account

GET/v1/user/profileBearer token

Your balance, frozen balance, rating and defaults.

Request

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/profile"

Response

{
  "id": 1,
  "email": "you@example.com",
  "vendor": "otphub",
  "default_forwarding_number": "",
  "balance": 100,
  "rating": 96,
  "default_country": { "name": "england", "iso": "gb", "prefix": "+44" },
  "default_operator": { "name": "" },
  "frozen_balance": 0
}

GET/v1/user/orders?category=&limit=&offset=&order=&reverse=Bearer token

Your order history, newest first.

Request

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/orders?category=activation&limit=25"

Response

{ "Data": [ /* orders */ ], "ProductNames": [], "Statuses": [], "Total": 3 }

GET/v1/user/payments?limit=&offset=&order=&reverse=Bearer token

Ledger entries for top-ups and adjustments.

Request

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/payments?limit=25"

Response

{
  "Data": [
    {
      "ID": 30011934,
      "TypeName": "charge",
      "ProviderName": "admin",
      "Amount": 100,
      "Balance": 100,
      "CreatedAt": "2026-08-17T15:37:08.149895Z"
    }
  ],
  "PaymentTypes": [{ "Name": "charge" }],
  "PaymentProviders": [{ "Name": "admin" }],
  "Total": 1
}

GET/v1/user/max-pricesBearer token

Your per-service price ceilings.

Request

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/max-prices"

Response

[{ "id": 14, "product": "facebook", "price": 11, "CreatedAt": "2026-08-17T15:37:08Z" }]

POST/v1/user/max-pricesBearer token

Set a ceiling for one service. Purchases above it are refused.

Request

curl -X POST "https://otphub-api.43.203.247.133.nip.io/v1/user/max-prices" \
  -H "Authorization: Bearer $OTPHUB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_name":"facebook","price":30}'

DELETE/v1/user/max-pricesBearer token

Remove a ceiling.

Request

curl -X DELETE "https://otphub-api.43.203.247.133.nip.io/v1/user/max-prices" \
  -H "Authorization: Bearer $OTPHUB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_name":"facebook"}'

Purchase

GET/v1/user/buy/activation/{country}/{operator}/{product}Bearer token

Buy a one-time verification number. Returns the order with its phone number.

Request

curl -H "Authorization: Bearer $OTPHUB_KEY" \
  "https://otphub-api.43.203.247.133.nip.io/v1/user/buy/activation/england/any/facebook?maxPrice=30"

Response

{
  "id": 11631253,
  "phone": "+447350690992",
  "operator": "vodafone",
  "product": "facebook",
  "price": 21,
  "status": "PENDING",
  "expires": "2026-08-17T08:28:38.809469028Z",
  "sms": null,
  "created_at": "2026-08-17T08:13:38.809469028Z",
  "forwarding": false,
  "forwarding_number": "",
  "country": "england"
}

GET/v1/user/buy/hosting/{country}/{operator}/{product}Bearer token

Rent a number for a period: 3hours, 1day, 10days or 1month.

Request

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/buy/hosting/england/any/1day"

GET/v1/user/reuse/{product}/{number}Bearer token

Buy the same number again for the same service, when the operator allows it.

Request

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/reuse/facebook/447350690992"

Order management

GET/v1/user/check/{id}Bearer token

Poll an order for new messages.

Request

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/check/11631253"

Response

{
  "id": 11631253,
  "phone": "+447350690992",
  "operator": "vodafone",
  "product": "facebook",
  "price": 21,
  "status": "PENDING",
  "expires": "2026-08-17T08:28:38.809469028Z",
  "sms": null,
  "created_at": "2026-08-17T08:13:38.809469028Z",
  "forwarding": false,
  "forwarding_number": "",
  "country": "england"
}

GET/v1/user/finish/{id}Bearer token

Close an order you are done with. The held amount is charged.

Request

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/finish/11631253"

GET/v1/user/cancel/{id}Bearer token

Cancel before any SMS arrives. The hold is released.

Request

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/cancel/11631253"

GET/v1/user/ban/{id}Bearer token

Report a number as already used. The hold is released and the number leaves rotation.

Request

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/ban/11631253"

GET/v1/user/sms/inbox/{id}Bearer token

Every message on a rented number.

Request

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/sms/inbox/11631253"

Response

{
  "Data": [
    {
      "ID": 1,
      "created_at": "2026-08-17T17:23:25.106597Z",
      "date": "2026-08-17T17:23:15Z",
      "sender": "Facebook",
      "text": "Use 415127 as your login code",
      "code": "415127",
      "is_wave": false,
      "wave_uuid": ""
    }
  ],
  "Total": 1
}

Order statuses

Every purchase moves through these states. The strings below are exactly what the API returns.

Status	Meaning
`PENDING`Waiting	The number is live and listening for an SMS.
`RECEIVED`Code received	At least one code arrived.
`CANCELED`Cancelled	Cancelled — the hold was released.
`TIMEOUT`Timed out	No SMS within the window — you were refunded.
`FINISHED`Completed	Closed — the purchase was charged.
`BANNED`Reported	Reported as already used — you were refunded.

Errors

Failures return a bare text body with the reason, exactly as the standard protocol specifies.

Error body	Returned when
`no free phones`	Nothing in stock for that country, operator and service.
`not enough user balance`	Your balance does not cover the price.
`not enough rating`	Your rating is at zero; ordering unlocks 24 hours later.
`select country`	The country segment was empty.
`select operator`	The operator segment was empty.
`bad country`	That country slug is not in the catalog.
`bad operator`	That operator slug is not in the catalog.
`no product`	That service slug is not in the catalog.
`server offline`	The upstream provider is unreachable.
`order not found`	No order with that id belongs to you.
`order expired`	The order passed its expiry window.
`order has sms`	A message already arrived, so the order cannot be cancelled.
`hosting order`	That call is not valid on a rental order.
`reuse not possible`	The operator does not allow reusing this number.
`reuse false`	The original order was not bought with reuse enabled.
`reuse expired`	The reuse window on that number has closed.

Rate limits

100 requests per second per API key. Sustained abuse results in a temporary block.

100 requests per second per IP address, then 503.
100 requests per second per API key, then 429.
100 purchases per second across the account.
Hit a limit five times in ten minutes and the key is blocked for ten minutes.

Drop-in compatibility

Paths, JSON shapes and error strings match the standard virtual-number protocol exactly, including the capitalised keys and plain-text error bodies. Existing client libraries need no changes.