NumPool API

https://numpool.com/api/v1Copy

Get an API key

Your key authenticates every request. Keep it secret. If you are logged in to numpool.com in this browser, you can create one right here:

Copy

Authentication

Send your key in the X-API-Key header on every request.

# every request needs this header
curl https://numpool.com/api/v1/balance \
  -H "X-API-Key: np_live_your_key_here"Copy

Errors & rate limits

Errors return a non-2xx status and a JSON body with an error field. Rate limit is 60 requests per minute per key.

Service codes

Pass one of these as the service value. This is the full list of officially supported services; the live list is also available at GET /services.

Country codes

Pass the numeric id as the country value. The most common ones are below. For the complete list of every country code, call GET /countries with no service parameter:

curl https://numpool.com/api/v1/countries \
  -H "X-API-Key: np_live_..."

// [{ "id": 0, "name": "Russia" }, { "id": 28, "name": "England" }, { "id": 187, "name": "USA" }, ...]Copy

Country availability and the exact price vary per service — use GET /countries?service=... to see which countries are in stock for a given service and what they cost.

Verifications (Server 1)

The fast path: rent a number for a single SMS code, then release it. Typical flow: services → countries → buy → poll /sms.

List services

Returns the supported services and their short codes (use the id as the service value elsewhere).

curl https://numpool.com/api/v1/services \
  -H "X-API-Key: np_live_..."

// [{ "id": "wa", "name": "WhatsApp", "domain": "whatsapp.com" }, ...]Copy

List countries for a service

curl "https://numpool.com/api/v1/countries?service=wa" \
  -H "X-API-Key: np_live_..."

// [{ "id": 187, "name": "USA", "flag": "US", "price": 0.43, "stock": 338400, "currency": "USD" }]Copy

Buy a number

curl -X POST https://numpool.com/api/v1/buy \
  -H "X-API-Key: np_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "service": "wa", "country": 187 }'

// {
//   "order_id": "a1b2c3...",
//   "number": "+1XXXXXXXXXX",
//   "cost": 0.43,
//   "status": "pending",
//   "poll_url": "https://numpool.com/api/v1/sms/a1b2c3..."
// }Copy

Your wallet is charged on purchase. If no code arrives, cancel the order to get refunded.

Poll for the code

Poll every few seconds until status is received. Statuses: waiting, received, cancelled.

curl https://numpool.com/api/v1/sms/a1b2c3 \
  -H "X-API-Key: np_live_..."

// { "order_id": "a1b2c3", "status": "received", "code": "123456", "full_sms": "Your code is 123456", "number": "+1..." }Copy

A complete loop in JavaScript:

const H = { "X-API-Key": "np_live_...", "Content-Type": "application/json" };
const base = "https://numpool.com/api/v1";

const order = await (await fetch(base + "/buy", {
  method: "POST", headers: H,
  body: JSON.stringify({ service: "wa", country: 187 })
})).json();

let code = null;
while (!code) {
  await new Promise(r => setTimeout(r, 4000));
  const s = await (await fetch(base + "/sms/" + order.order_id, { headers: H })).json();
  if (s.status === "received") code = s.code;
}
console.log("OTP:", code);Copy

Cancel a number

Cancels a pending order and refunds your wallet. Only works while status is pending.

curl -X POST https://numpool.com/api/v1/cancel/a1b2c3 \
  -H "X-API-Key: np_live_..."

// { "ok": true, "order_id": "a1b2c3", "refunded": 0.43 }Copy

List your orders

curl "https://numpool.com/api/v1/orders?limit=20" \
  -H "X-API-Key: np_live_..."Copy

US Number Rentals

Rent a US number for a fixed period and receive its full SMS inbox for the whole window. Durations:

oneDaythreeDaysevenDay fourteenDaythirtyDay

List rental services

curl https://numpool.com/api/v1/rentals/services \
  -H "X-API-Key: np_live_..."

// [{ "service": "discord", "name": "Discord" }, ...]Copy

Get rental prices

curl "https://numpool.com/api/v1/rentals/prices?service=discord" \
  -H "X-API-Key: np_live_..."

// { "service": "discord", "durations": [{ "duration": "oneDay", "days": 1, "price": 1.20 }, ...] }Copy

Create a rental

curl -X POST https://numpool.com/api/v1/rentals \
  -H "X-API-Key: np_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "service": "discord", "duration": "sevenDay" }'

// {
//   "rental_id": "r1...",
//   "number": "+1XXXXXXXXXX",
//   "days": 7,
//   "cost": 4.50,
//   "ends_at": "2026-06-20T...",
//   "inbox_url": "https://numpool.com/api/v1/rentals/r1.../sms"
// }Copy

The full rental price is charged once on creation. Rentals are non-refundable.

List your rentals

curl https://numpool.com/api/v1/rentals \
  -H "X-API-Key: np_live_..."Copy

Read the rental inbox

curl https://numpool.com/api/v1/rentals/r1/sms \
  -H "X-API-Key: np_live_..."

// { "rental_id": "r1", "messages": [
//   { "from": "Discord", "body": "Your code is 123456", "code": "123456", "at": "2026-06-13T..." }
// ]}Copy

Account balance

curl https://numpool.com/api/v1/balance \
  -H "X-API-Key: np_live_..."

// { "balance": 12.40, "currency": "USD" }Copy

Need a higher rate limit or a feature that is not here yet? Reach out from your NumPool account.