OTP Overview

Find the service and country

Browse either way round — services, or countries first:

await api('GET', '/v1/otp/services', { query: { q: 'whatsapp' } });
await api('GET', '/v1/otp/countries');

Take the slug of the service you want (whatsapp) and the countryCode of the country (US_1).

Pick an offer, and take its serviceId

const { data } = await api('GET', '/v1/otp/services/whatsapp/US_1');

// data.pools is one entry per pool that sells this service here:
// [{ serviceId: 'CHARLIE-US-whatsapp', price: 0.42, availableCount: 12, successRate: 87 }, …]
const offer = data.pools[0];

Each entry in pools is one offer — the same service and country, from a different pool, at its own price, availability and success rate. Choose one, and keep its serviceId: that single value is what you buy.

serviceId is opaque. It happens to read as pool‑country‑service, but do not assemble one yourself — the segments are spelled the way the selling side spells them, and a value you build will not resolve. Send back exactly what the catalog gave you.

Request a number

const { data: order } = await api('POST', '/v1/otp/request', {
  body: { serviceId: offer.serviceId },
});

This one spends money: send an Idempotency-Key header so a retry cannot rent a second number — it is required here, and a call without one is a 400 IDEMPOTENCY_KEY_REQUIRED. See Idempotency.

The response is the order: orderId, the rented phoneNumber, the price charged, and status: "waiting". serviceId comes back on it too, so a later order tells you which offer it was placed against — and you can re-request the same one.

Poll for the code

await api('GET', '/v1/otp/status');

Poll until an order reaches received and read its code.

Cancel if unused

await api('POST', '/v1/otp/cancel', { body: { order_id: order.orderId } });