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.

Responses, pagination, errors and retry behaviour follow the shared Conventions and Errors 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/${lookupId}`);

A lookup ends in completed, partially_completed, failed, or cancelled. Cancel a non‑terminal lookup with POST /v1/hlr/lookups/{lookupId}/cancel — a queued lookup refunds in full.

Read the results

await api('GET', `/v1/hlr/lookups/${lookupId}/results`, {
  query: { page: 1, pageSize: 50 },
});

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

Export a finished job

const { data } = await api('POST', `/v1/hlr/lookups/${lookupId}/exports`, {
  body: { format: 'csv' },
});
await api('GET', `/v1/hlr/lookups/${lookupId}/exports/${data.exportId}`);

An export is a child of its lookup: POST the collection with the format you want (json, csv, or xlsx) and it returns an exportId. Building is idempotent and asynchronous — the POST returns 200 when the file is ready or 202 while it builds, and the GET on that exportId returns a presigned download URL once it is.

Pricing

Lookups are billed per number against your effective pricing plan. Read the products available to you, each with the unit price that applies to your account, before submitting a lookup:

await api('GET', '/v1/hlr/products');
// or one product directly:
await api('GET', `/v1/hlr/products/${productCode}`);

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 submit the batch again. Nothing was queued or charged.
`409 PRODUCT_UNAVAILABLE`	That product cannot be sold to you right now.	Check `GET /v1/hlr/products` for what is available.
`404 NOT_FOUND`	No such lookup — or not yours.	Check the id.

Full schemas are in the HLR API Reference.

HLR

On this page