List lookups
Returns your lookups, newest first, filterable by category, status and date range.
Authorization
KeyId ApiSecret Your API key id.
In: header
Your API key secret.
In: header
Query Parameters
11 <= value <= 10000501 <= value <= 200"hlr" | "nt" | "mnp""queued" | "running" | "completed" | "failed" | "cancelled" | "partially_completed"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/hlr/lookups?page=1&pageSize=50&category=hlr&status=queued" \ -H "x-key-id: YOUR_KEY_ID" \ -H "x-api-secret: YOUR_API_SECRET"{
"data": [
{
"jobId": "00000000-0000-4000-8000-000000000001",
"status": "completed",
"counts": {
"input": 1,
"processed": 1,
"accepted": 1,
"rejected": 0,
"failed": 0
},
"actions": {
"canCancel": false,
"canExport": true
},
"lookupType": "hlr-single",
"category": "hlr",
"productCode": "hlr:V11",
"price": {
"amount": 1.0025,
"currency": "EUR"
},
"startedAt": "2026-09-15T22:27:32.945Z",
"completedAt": "2026-09-15T22:27:33.326Z",
"createdAt": "2026-09-15T22:27:32.944Z",
"updatedAt": "2026-09-15T22:27:33.363Z"
},
{
"jobId": "00000000-0000-4000-8000-000000000002",
"status": "completed",
"counts": {
"input": 1,
"processed": 1,
"accepted": 1,
"rejected": 0,
"failed": 0
},
"actions": {
"canCancel": false,
"canExport": true
},
"lookupType": "mnp-batch",
"category": "mnp",
"productCode": "mnp:IP4",
"name": "Example MNP batch",
"price": {
"amount": 1.0025,
"currency": "EUR"
},
"startedAt": "2026-09-15T12:59:55.137Z",
"completedAt": "2026-09-15T12:59:55.353Z",
"createdAt": "2026-09-15T12:59:55.133Z",
"updatedAt": "2026-09-15T12:59:55.353Z"
}
],
"meta": {
"page": 1,
"pageSize": 2,
"hasNext": true
}
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "The request is not valid. See `fields` for what to correct.",
"requestId": "9f1c7b2e-…"
}
}{
"error": {
"code": "AUTHENTICATION_REQUIRED",
"message": "This endpoint requires an API key.",
"requestId": "9f1c7b2e-…"
}
}{
"error": {
"code": "CONFLICT",
"message": "The resource is not in a state that allows this operation.",
"requestId": "9f1c7b2e-…"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Retry after the interval in `Retry-After`.",
"requestId": "9f1c7b2e-…"
}
}{
"error": {
"code": "INTERNAL_ERROR",
"message": "Something went wrong on our side.",
"requestId": "9f1c7b2e-…"
}
}{
"error": {
"code": "SERVICE_RESPONSE_INVALID",
"message": "The upstream service returned an unexpected response.",
"requestId": "9f1c7b2e-…"
}
}{
"error": {
"code": "SERVICE_UNAVAILABLE",
"message": "The service is temporarily unavailable. Try again shortly.",
"requestId": "9f1c7b2e-…"
}
}Get a product GET
Returns one lookup product with the unit price that applies to your account.
Submit a lookup POST
Submits one number or a batch. A single number is looked up immediately and its `result` comes back on this response; a batch is queued, and the lookup is polled for results. It is charged per number as results arrive. Retry behaviour differs by shape. A BATCH is idempotent on the request: if a response is lost — a network drop, or a slow lookup that timed out — re-send the identical batch (while it is running, or within ~1 minute of it completing) and you get the SAME lookup back by its `jobId`, never a second charge. A replay returns the job (its id and status), NOT a fresh inline `result`: read the outcome — `result`, price and per-number status — from that job with `GET /v1/hlr/lookups/{lookupId}` and its `/results`. A SINGLE lookup is NOT deduplicated: every call performs a fresh, separately-billed lookup, by design. Do NOT blind-retry a single lookup to recover a dropped response — you would be charged a second time. If a single lookup's response is lost, find it with `GET /v1/hlr/lookups` (your recent lookups) rather than re-posting.