Bitcall APISubmit a lookup
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.
Authorization
KeyId ApiSecret Your API key id.
In: header
Your API key secret.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/hlr/lookups" \ -H "x-key-id: YOUR_KEY_ID" \ -H "x-api-secret: YOUR_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "lookupType": "hlr-single", "productCode": "hlr:V11", "number": "21650000001" }'{
"data": {
"jobId": "00000000-0000-4000-8000-000000000003",
"status": "completed",
"counts": {},
"actions": {
"canCancel": false,
"canExport": true
},
"price": {
"amount": 1.0025,
"currency": "EUR"
},
"result": {
"connectivityStatus": "UNDETERMINED",
"mccmnc": "60501",
"imsi": null,
"msc": null,
"originalNetwork": "Orange",
"roaming": false
}
}
}{
"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": "NOT_FOUND",
"message": "No such resource.",
"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-…"
}
}