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 country_code of the country (US_1).

Pick an offer, and take its serviceId

The catalogue is one collection, filtered — there is no per-country sub-resource:

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

// each row's `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[0].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: activation } = await api('POST', '/v1/otp/activations', {
  body: { serviceId: offer.serviceId },
});

The response is the activation: activationId, 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/activations/${activation.activationId}`);

Poll until the activation reaches received, then read its code. An id that is unknown — or not yours — answers 404, never an empty result.

This addresses one order by path and returns it as an object in data.

Reviewing several orders is a different endpoint: GET /v1/otp/activations, with no id in the path. It takes status, page and pageSize, and returns data as an array with a meta block, newest first — useful for a dashboard. It carries no activationId filter, so a single rental is always polled by path, as above.

Cancel if unused

await api('POST', `/v1/otp/activations/${activation.activationId}/cancel`);