Bitcall logoBitcall API
HLR
Add your Key ID and Secret to send test requests.

Cancel a lookup

POST
/v1/hlr/lookups/{lookupId}/cancel

Stops a lookup that is still queued or running; numbers not yet processed are not charged. Only a non-terminal lookup can be cancelled — once it is terminal (completed, partially_completed, cancelled or failed), the call returns 409 CONFLICT and nothing changes.

Authorization

KeyId ApiSecret
x-key-id<token>

Your API key id.

In: header

x-api-secret<token>

Your API key secret.

In: header

Path Parameters

lookupId*string
Length1 <= length

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/string/cancel" \  -H "x-key-id: YOUR_KEY_ID" \  -H "x-api-secret: YOUR_API_SECRET"
{
  "data": {
    "jobId": "00000000-0000-4000-8000-000000000001",
    "status": "cancelled",
    "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"
  }
}
{
  "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-…"
  }
}

List results GET

Returns the per-number results of a lookup, paginated. Use an export for large completed lookups.

Build an export POST

Starts building a downloadable file of a completed lookup's results. A build is a resource keyed by its lookup and format, so this is idempotent BY STATE: repeating it returns the existing build for that `(lookup, format)` instead of starting a second one — unlike submitting a BATCH lookup, whose retry-safety is a replay of the identical request within its replay window after a lost response. A SINGLE lookup is not deduplicated at all: each submission is a fresh, separately-billed lookup. This operation is safe to repeat: repeating it returns the existing state and performs no further action.