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

Build an export

POST
/v1/hlr/lookups/{lookupId}/exports
*object

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.

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

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/string/exports" \  -H "x-key-id: YOUR_KEY_ID" \  -H "x-api-secret: YOUR_API_SECRET" \  -H "Content-Type: application/json" \  -d '{    "format": "csv"  }'
{
  "data": {
    "status": "ready",
    "format": "csv",
    "downloadUrl": "https://api.bitcall.io/v1/hlr/lookups/d5582f70-c53c-493d-8bbd-64d435778379/exports/csv/content"
  }
}
{
  "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-…"
  }
}

Cancel a lookup POST

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.

Get an export GET

Returns whether the export is ready, with its size and checksum once it is. Fetch the file itself from this export's `/content`.