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 },
});

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

const { data } = await api('GET', '/v1/otp/status', {
  query: { orderId: order.orderId },
});

Poll until the order reaches received, then read its code.

orderId narrows the answer to that one order. Leave it off and you get all of them, newest first — useful for a dashboard, wasteful for a single rental.

The response is a list either way, so a filtered poll is data[0]. An order that has not been placed, or that belongs to someone else, is simply not in the list — there is no separate "not found" to handle.

Cancel if unused

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