HLR

The HLR product performs phone‑number lookups — checking a number's status, operator, and portability — through the same gateway you already use. It covers three lookup categories: HLR, MNP (number portability), and NT (number type).

All HLR endpoints are /v1/hlr/* requests authenticated with your key id and secret — see Authentication. A key needs hlr:read to read and hlr:write to make changes; see Permissions.

Responses, pagination, errors and retry behaviour follow the shared Conventions, Errors and Idempotency rules — this page covers only what is specific to HLR.

Every endpoint, with its full request and response schema, is in the HLR API Reference.

A typical flow

Submit a lookup

Every lookup is a job. Single lookups run synchronously; batches are queued and processed in the background.

await api('POST', '/v1/hlr/lookups/jobs', {
  body: { lookupType: 'hlr-single', productKey: 'hlr:E10', msisdn: '21650000001' },
});

The body must match exactly one of six shapes, chosen by lookupType:

`lookupType`	Body
`hlr-single`, `mnp-single`	`{ productKey, msisdn }`
`nt-single`	`{ productKey, number }`
`hlr-batch`, `mnp-batch`	`{ productKey, msisdns[] }`
`nt-batch`	`{ productKey, numbers[] }`

Poll the job

await api('GET', `/v1/hlr/lookups/jobs/${jobId}`);

A job ends in completed, partially_completed, failed, or cancelled. Cancel a non‑terminal job with POST /v1/hlr/lookups/jobs/:jobId/cancel — a queued job refunds in full.

Read the results

await api('GET', `/v1/hlr/lookups/jobs/${jobId}/details`, {
  query: { page: 1, limit: 50 },
});

Results are per‑number and paginated. Past jobs are listed by GET /v1/hlr/lookups/history.

Export a finished job

await api('POST', `/v1/hlr/lookups/exports/${jobId}/csv`);
await api('GET', `/v1/hlr/lookups/exports/${jobId}/csv`);

Exports come in json, csv, or xlsx. Building is idempotent and asynchronous: the POST returns 200 when the file is ready or 202 while it builds, and the GET returns a presigned download URL once it is.

Pricing

Lookups are billed per number against your effective pricing plan. Read your own per‑route selling prices before submitting a job:

await api('GET', '/v1/hlr/pricing/me');

Pricing plans themselves are configured in the Bitcall panel, not through this API.

Errors follow the standard gateway error format. The codes each endpoint can return are listed on that endpoint in the API Reference.

Job statuses

Status	Meaning
`queued`	Accepted, not started.
`running`	In progress; counts are climbing.
`completed`	Every number processed.
`partially_completed`	Finished, some numbers failed. Check per-result statuses.
`failed`	The job could not be processed.
`cancelled`	You cancelled it. Unprocessed numbers were not charged.

queued and running are the non-terminal pair — poll until neither applies. actions tells you what is possible now: canCancel while running, canExport once terminal.

Result statuses

Status	Meaning
`accepted`	The lookup succeeded; `result` holds the data.
`rejected`	The network answered, and the answer was negative.
`failed`	The lookup could not be completed.
`invalid`	The number was not usable for this lookup.

When things go wrong

You see	Meaning	Do
`400 VALIDATION_ERROR`	An empty batch, a batch over the maximum, or a number that is not in international format.	Fix the batch. Numbers are checked before anything is queued or charged, so a rejected submission costs nothing.
`409 INSUFFICIENT_BALANCE`	Not enough balance for the batch.	Top up, then retry with the same idempotency key.
`409 PRODUCT_UNAVAILABLE`	That product cannot be sold to you right now.	Check `GET /v1/hlr/pricing/routes` for what is available.
`404 NOT_FOUND`	No such job — or not yours.	Check the id.

Full schemas are in the HLR API Reference.

HLR

On this page