{ "openapi": "3.0.3", "info": { "title": "Bitcall HLR API", "version": "1.0.0", "description": "Home Location Register lookups and number intelligence.\n\nEvery endpoint is reached through the Bitcall gateway and authenticated with your\nkey id and secret, sent as the `x-key-id` and `x-api-secret` headers.\n\nSingle resources return `{ \"data\": … }`. Lists return `{ \"data\": [ … ], \"meta\": { … } }`\nwith one-based `page` and `pageSize` (default 50, maximum 200).\n\nErrors return `{ \"error\": { \"code\", \"message\", \"requestId\" } }`. Every response carries\nan `x-request-id` header; quote it when contacting support." }, "servers": [ { "url": "https://api.bitcall.io", "description": "Bitcall API gateway" } ], "tags": [ { "name": "Products" }, { "name": "Lookups" }, { "name": "Exports" } ], "security": [ { "KeyId": [], "ApiSecret": [] } ], "paths": { "/v1/hlr/products": { "get": { "tags": [ "Products" ], "operationId": "listHlrProducts", "summary": "List products", "description": "Returns every lookup product available to you, each with the unit price that applies to your account.", "responses": { "200": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "productCode": { "type": "string", "minLength": 1 }, "category": { "type": "string", "enum": [ "hlr", "nt", "mnp" ] }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false } }, "required": [ "productCode", "category" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 1 }, "pageSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 50 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 137 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 3 }, "hasNext": { "type": "boolean", "example": true } }, "required": [ "page", "pageSize", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": [ { "productCode": "hlr:DV8", "category": "hlr", "price": { "amount": 1.0025, "currency": "EUR" } }, { "productCode": "hlr:IP1", "category": "hlr", "price": { "amount": 1.0025, "currency": "EUR" } } ], "meta": { "page": 1, "pageSize": 9, "hasNext": false } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } } } }, "/v1/hlr/products/{productCode}": { "get": { "tags": [ "Products" ], "operationId": "getHlrProduct", "summary": "Get a product", "description": "Returns one lookup product with the unit price that applies to your account.", "responses": { "200": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "productCode": { "type": "string", "minLength": 1 }, "category": { "type": "string", "enum": [ "hlr", "nt", "mnp" ] }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false } }, "required": [ "productCode", "category" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "productCode": "hlr:DV8", "category": "hlr", "price": { "amount": 1.0025, "currency": "EUR" } } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "404": { "description": "NOT_FOUND", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "No such resource.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "parameters": [ { "name": "productCode", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v1/hlr/lookups": { "post": { "tags": [ "Lookups" ], "operationId": "createLookup", "summary": "Submit a lookup", "description": "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.\n\nRetry 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`.\n\nA 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.", "responses": { "202": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "jobId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled", "partially_completed" ] }, "counts": { "type": "object", "properties": { "input": { "type": "number" }, "processed": { "type": "number" }, "accepted": { "type": "number" }, "rejected": { "type": "number" }, "failed": { "type": "number" } }, "additionalProperties": false }, "actions": { "type": "object", "properties": { "canCancel": { "type": "boolean" }, "canExport": { "type": "boolean" } }, "required": [ "canCancel", "canExport" ], "additionalProperties": false }, "lookupType": { "type": "string" }, "category": { "type": "string", "enum": [ "hlr", "nt", "mnp" ] }, "productCode": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "result": { "type": "object", "properties": { "connectivityStatus": { "nullable": true, "type": "string" }, "processingStatus": { "nullable": true, "type": "string" }, "mccmnc": { "nullable": true, "type": "string" }, "mcc": { "nullable": true, "type": "string" }, "mnc": { "nullable": true, "type": "string" }, "imsi": { "nullable": true, "type": "string" }, "msc": { "nullable": true, "type": "string" }, "originalNetwork": { "nullable": true, "type": "string" }, "originalCountryName": { "nullable": true, "type": "string" }, "originalCountryCode": { "nullable": true, "type": "string" }, "originalCountryPrefix": { "nullable": true, "type": "string" }, "currentNetwork": { "nullable": true, "type": "string" }, "ported": { "nullable": true, "type": "boolean" }, "portedNetworkName": { "nullable": true, "type": "string" }, "portedCountryName": { "nullable": true, "type": "string" }, "portedCountryCode": { "nullable": true, "type": "string" }, "portedCountryPrefix": { "nullable": true, "type": "string" }, "presentInNetwork": { "nullable": true, "type": "boolean" }, "reachable": { "nullable": true, "type": "boolean" }, "roaming": { "nullable": true, "type": "boolean" }, "roamingNetworkName": { "nullable": true, "type": "string" }, "roamingCountryName": { "nullable": true, "type": "string" }, "roamingCountryCode": { "nullable": true, "type": "string" }, "roamingCountryPrefix": { "nullable": true, "type": "string" }, "dataSource": { "nullable": true, "type": "string" }, "numberType": { "nullable": true, "type": "string" }, "queryStatus": { "nullable": true, "type": "string" }, "valid": { "nullable": true, "type": "boolean" }, "invalidReason": { "nullable": true, "type": "string" }, "carrier": { "nullable": true, "type": "string" }, "countryCode": { "nullable": true, "type": "string" }, "countryName": { "nullable": true, "type": "string" }, "possiblyPorted": { "nullable": true, "type": "boolean" }, "vanityNumber": { "nullable": true, "type": "boolean" }, "qualifiesForHlrLookup": { "nullable": true, "type": "boolean" }, "regions": { "nullable": true, "type": "array", "items": { "type": "string" } }, "timezones": { "nullable": true, "type": "array", "items": { "type": "string" } }, "infoText": { "nullable": true, "type": "string" }, "portedDate": { "nullable": true, "type": "string" } }, "additionalProperties": false }, "startedAt": { "type": "string" }, "completedAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "jobId", "status", "counts", "actions" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "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 } } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "404": { "description": "NOT_FOUND", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "No such resource.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT · INSUFFICIENT_BALANCE · PRODUCT_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "lookupType": { "type": "string", "enum": [ "hlr-single", "nt-single", "mnp-single" ] }, "productCode": { "type": "string", "minLength": 1 }, "number": { "type": "string", "pattern": "^\\+?[1-9]\\d{5,14}$" }, "name": { "type": "string" } }, "required": [ "lookupType", "productCode", "number" ], "additionalProperties": false, "title": "One number" }, { "type": "object", "properties": { "lookupType": { "type": "string", "enum": [ "hlr-batch", "nt-batch", "mnp-batch" ] }, "productCode": { "type": "string", "minLength": 1 }, "numbers": { "minItems": 1, "maxItems": 10000, "type": "array", "items": { "type": "string", "pattern": "^\\+?[1-9]\\d{5,14}$" } }, "name": { "type": "string" } }, "required": [ "lookupType", "productCode", "numbers" ], "additionalProperties": false, "title": "A batch of numbers" } ] }, "examples": { "hlr-single": { "summary": "hlr-single", "value": { "lookupType": "hlr-single", "productCode": "hlr:V11", "number": "21650000001" } }, "nt-single": { "summary": "nt-single", "value": { "lookupType": "nt-single", "productCode": "nt:V11", "number": "21650000001" } }, "mnp-single": { "summary": "mnp-single", "value": { "lookupType": "mnp-single", "productCode": "mnp:V11", "number": "21650000001" } }, "hlr-batch": { "summary": "hlr-batch", "value": { "lookupType": "hlr-batch", "productCode": "hlr:V11", "numbers": [ "21650000001", "21650000002" ], "name": "Example HLR batch" } }, "nt-batch": { "summary": "nt-batch", "value": { "lookupType": "nt-batch", "productCode": "nt:V11", "numbers": [ "21650000001", "21650000002" ], "name": "Example NT batch" } }, "mnp-batch": { "summary": "mnp-batch", "value": { "lookupType": "mnp-batch", "productCode": "mnp:V11", "numbers": [ "21650000001", "21650000002" ], "name": "Example MNP batch" } } } } } } }, "get": { "tags": [ "Lookups" ], "operationId": "listLookups", "summary": "List lookups", "description": "Returns your lookups, newest first, filterable by category, status and date range.", "responses": { "200": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "jobId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled", "partially_completed" ] }, "counts": { "type": "object", "properties": { "input": { "type": "number" }, "processed": { "type": "number" }, "accepted": { "type": "number" }, "rejected": { "type": "number" }, "failed": { "type": "number" } }, "additionalProperties": false }, "actions": { "type": "object", "properties": { "canCancel": { "type": "boolean" }, "canExport": { "type": "boolean" } }, "required": [ "canCancel", "canExport" ], "additionalProperties": false }, "lookupType": { "type": "string" }, "category": { "type": "string", "enum": [ "hlr", "nt", "mnp" ] }, "productCode": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "result": { "type": "object", "properties": { "connectivityStatus": { "nullable": true, "type": "string" }, "processingStatus": { "nullable": true, "type": "string" }, "mccmnc": { "nullable": true, "type": "string" }, "mcc": { "nullable": true, "type": "string" }, "mnc": { "nullable": true, "type": "string" }, "imsi": { "nullable": true, "type": "string" }, "msc": { "nullable": true, "type": "string" }, "originalNetwork": { "nullable": true, "type": "string" }, "originalCountryName": { "nullable": true, "type": "string" }, "originalCountryCode": { "nullable": true, "type": "string" }, "originalCountryPrefix": { "nullable": true, "type": "string" }, "currentNetwork": { "nullable": true, "type": "string" }, "ported": { "nullable": true, "type": "boolean" }, "portedNetworkName": { "nullable": true, "type": "string" }, "portedCountryName": { "nullable": true, "type": "string" }, "portedCountryCode": { "nullable": true, "type": "string" }, "portedCountryPrefix": { "nullable": true, "type": "string" }, "presentInNetwork": { "nullable": true, "type": "boolean" }, "reachable": { "nullable": true, "type": "boolean" }, "roaming": { "nullable": true, "type": "boolean" }, "roamingNetworkName": { "nullable": true, "type": "string" }, "roamingCountryName": { "nullable": true, "type": "string" }, "roamingCountryCode": { "nullable": true, "type": "string" }, "roamingCountryPrefix": { "nullable": true, "type": "string" }, "dataSource": { "nullable": true, "type": "string" }, "numberType": { "nullable": true, "type": "string" }, "queryStatus": { "nullable": true, "type": "string" }, "valid": { "nullable": true, "type": "boolean" }, "invalidReason": { "nullable": true, "type": "string" }, "carrier": { "nullable": true, "type": "string" }, "countryCode": { "nullable": true, "type": "string" }, "countryName": { "nullable": true, "type": "string" }, "possiblyPorted": { "nullable": true, "type": "boolean" }, "vanityNumber": { "nullable": true, "type": "boolean" }, "qualifiesForHlrLookup": { "nullable": true, "type": "boolean" }, "regions": { "nullable": true, "type": "array", "items": { "type": "string" } }, "timezones": { "nullable": true, "type": "array", "items": { "type": "string" } }, "infoText": { "nullable": true, "type": "string" }, "portedDate": { "nullable": true, "type": "string" } }, "additionalProperties": false }, "startedAt": { "type": "string" }, "completedAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "jobId", "status", "counts", "actions" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 1 }, "pageSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 50 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 137 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 3 }, "hasNext": { "type": "boolean", "example": true } }, "required": [ "page", "pageSize", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "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 } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 10000 }, "example": 1 }, { "name": "pageSize", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "example": 50 }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "hlr", "nt", "mnp" ] }, "example": "hlr" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled", "partially_completed" ] }, "example": "queued" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/v1/hlr/lookups/{lookupId}": { "get": { "tags": [ "Lookups" ], "operationId": "getLookup", "summary": "Get a lookup", "description": "Returns a lookup's status, per-outcome counts and price. Poll this after submitting.", "responses": { "200": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "jobId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled", "partially_completed" ] }, "counts": { "type": "object", "properties": { "input": { "type": "number" }, "processed": { "type": "number" }, "accepted": { "type": "number" }, "rejected": { "type": "number" }, "failed": { "type": "number" } }, "additionalProperties": false }, "actions": { "type": "object", "properties": { "canCancel": { "type": "boolean" }, "canExport": { "type": "boolean" } }, "required": [ "canCancel", "canExport" ], "additionalProperties": false }, "lookupType": { "type": "string" }, "category": { "type": "string", "enum": [ "hlr", "nt", "mnp" ] }, "productCode": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "result": { "type": "object", "properties": { "connectivityStatus": { "nullable": true, "type": "string" }, "processingStatus": { "nullable": true, "type": "string" }, "mccmnc": { "nullable": true, "type": "string" }, "mcc": { "nullable": true, "type": "string" }, "mnc": { "nullable": true, "type": "string" }, "imsi": { "nullable": true, "type": "string" }, "msc": { "nullable": true, "type": "string" }, "originalNetwork": { "nullable": true, "type": "string" }, "originalCountryName": { "nullable": true, "type": "string" }, "originalCountryCode": { "nullable": true, "type": "string" }, "originalCountryPrefix": { "nullable": true, "type": "string" }, "currentNetwork": { "nullable": true, "type": "string" }, "ported": { "nullable": true, "type": "boolean" }, "portedNetworkName": { "nullable": true, "type": "string" }, "portedCountryName": { "nullable": true, "type": "string" }, "portedCountryCode": { "nullable": true, "type": "string" }, "portedCountryPrefix": { "nullable": true, "type": "string" }, "presentInNetwork": { "nullable": true, "type": "boolean" }, "reachable": { "nullable": true, "type": "boolean" }, "roaming": { "nullable": true, "type": "boolean" }, "roamingNetworkName": { "nullable": true, "type": "string" }, "roamingCountryName": { "nullable": true, "type": "string" }, "roamingCountryCode": { "nullable": true, "type": "string" }, "roamingCountryPrefix": { "nullable": true, "type": "string" }, "dataSource": { "nullable": true, "type": "string" }, "numberType": { "nullable": true, "type": "string" }, "queryStatus": { "nullable": true, "type": "string" }, "valid": { "nullable": true, "type": "boolean" }, "invalidReason": { "nullable": true, "type": "string" }, "carrier": { "nullable": true, "type": "string" }, "countryCode": { "nullable": true, "type": "string" }, "countryName": { "nullable": true, "type": "string" }, "possiblyPorted": { "nullable": true, "type": "boolean" }, "vanityNumber": { "nullable": true, "type": "boolean" }, "qualifiesForHlrLookup": { "nullable": true, "type": "boolean" }, "regions": { "nullable": true, "type": "array", "items": { "type": "string" } }, "timezones": { "nullable": true, "type": "array", "items": { "type": "string" } }, "infoText": { "nullable": true, "type": "string" }, "portedDate": { "nullable": true, "type": "string" } }, "additionalProperties": false }, "startedAt": { "type": "string" }, "completedAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "jobId", "status", "counts", "actions" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "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" } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "404": { "description": "NOT_FOUND", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "No such resource.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "parameters": [ { "name": "lookupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v1/hlr/lookups/{lookupId}/results": { "get": { "tags": [ "Lookups" ], "operationId": "listLookupResults", "summary": "List results", "description": "Returns the per-number results of a lookup, paginated. Use an export for large completed lookups.", "responses": { "200": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "lookupId": { "type": "string", "minLength": 1 }, "number": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "accepted", "rejected", "failed", "invalid" ] }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "processedAt": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code" ], "additionalProperties": false }, "result": { "type": "object", "properties": { "connectivityStatus": { "nullable": true, "type": "string" }, "processingStatus": { "nullable": true, "type": "string" }, "mccmnc": { "nullable": true, "type": "string" }, "mcc": { "nullable": true, "type": "string" }, "mnc": { "nullable": true, "type": "string" }, "imsi": { "nullable": true, "type": "string" }, "msc": { "nullable": true, "type": "string" }, "originalNetwork": { "nullable": true, "type": "string" }, "originalCountryName": { "nullable": true, "type": "string" }, "originalCountryCode": { "nullable": true, "type": "string" }, "originalCountryPrefix": { "nullable": true, "type": "string" }, "currentNetwork": { "nullable": true, "type": "string" }, "ported": { "nullable": true, "type": "boolean" }, "portedNetworkName": { "nullable": true, "type": "string" }, "portedCountryName": { "nullable": true, "type": "string" }, "portedCountryCode": { "nullable": true, "type": "string" }, "portedCountryPrefix": { "nullable": true, "type": "string" }, "presentInNetwork": { "nullable": true, "type": "boolean" }, "reachable": { "nullable": true, "type": "boolean" }, "roaming": { "nullable": true, "type": "boolean" }, "roamingNetworkName": { "nullable": true, "type": "string" }, "roamingCountryName": { "nullable": true, "type": "string" }, "roamingCountryCode": { "nullable": true, "type": "string" }, "roamingCountryPrefix": { "nullable": true, "type": "string" }, "dataSource": { "nullable": true, "type": "string" }, "numberType": { "nullable": true, "type": "string" }, "queryStatus": { "nullable": true, "type": "string" }, "valid": { "nullable": true, "type": "boolean" }, "invalidReason": { "nullable": true, "type": "string" }, "carrier": { "nullable": true, "type": "string" }, "countryCode": { "nullable": true, "type": "string" }, "countryName": { "nullable": true, "type": "string" }, "possiblyPorted": { "nullable": true, "type": "boolean" }, "vanityNumber": { "nullable": true, "type": "boolean" }, "qualifiesForHlrLookup": { "nullable": true, "type": "boolean" }, "regions": { "nullable": true, "type": "array", "items": { "type": "string" } }, "timezones": { "nullable": true, "type": "array", "items": { "type": "string" } }, "infoText": { "nullable": true, "type": "string" }, "portedDate": { "nullable": true, "type": "string" } }, "additionalProperties": false } }, "required": [ "lookupId", "number", "status", "result" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 1 }, "pageSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 50 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 137 }, "totalPages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "example": 3 }, "hasNext": { "type": "boolean", "example": true } }, "required": [ "page", "pageSize", "hasNext" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": [ { "lookupId": "00000000-0000-4000-8000-000000000001:0", "number": "21650000001", "status": "accepted", "price": { "amount": 1.0025, "currency": "EUR" }, "processedAt": "2026-09-15T22:27:33.323Z", "result": { "connectivityStatus": "UNDETERMINED", "mccmnc": "60501", "mcc": "605", "mnc": "01", "imsi": null, "msc": null, "originalNetwork": "Orange", "originalCountryName": "Tunisia", "originalCountryCode": "TN", "originalCountryPrefix": "216", "currentNetwork": "Orange", "ported": false, "portedNetworkName": null, "portedCountryName": null, "portedCountryCode": null, "portedCountryPrefix": null, "presentInNetwork": true, "reachable": false, "roaming": false, "roamingNetworkName": null, "roamingCountryName": null, "roamingCountryCode": null, "roamingCountryPrefix": null, "countryCode": "TN", "countryName": "Tunisia" } } ], "meta": { "page": 1, "pageSize": 2, "hasNext": false } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "404": { "description": "NOT_FOUND", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "No such resource.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "parameters": [ { "name": "lookupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 10000 }, "example": 1 }, { "name": "pageSize", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 }, "example": 50 }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "accepted", "rejected", "failed", "invalid" ] }, "example": "accepted" } ] } }, "/v1/hlr/lookups/{lookupId}/cancel": { "post": { "tags": [ "Lookups" ], "operationId": "cancelLookup", "summary": "Cancel a lookup", "description": "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.", "responses": { "200": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "jobId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled", "partially_completed" ] }, "counts": { "type": "object", "properties": { "input": { "type": "number" }, "processed": { "type": "number" }, "accepted": { "type": "number" }, "rejected": { "type": "number" }, "failed": { "type": "number" } }, "additionalProperties": false }, "actions": { "type": "object", "properties": { "canCancel": { "type": "boolean" }, "canExport": { "type": "boolean" } }, "required": [ "canCancel", "canExport" ], "additionalProperties": false }, "lookupType": { "type": "string" }, "category": { "type": "string", "enum": [ "hlr", "nt", "mnp" ] }, "productCode": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "number", "example": 1.0025 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "result": { "type": "object", "properties": { "connectivityStatus": { "nullable": true, "type": "string" }, "processingStatus": { "nullable": true, "type": "string" }, "mccmnc": { "nullable": true, "type": "string" }, "mcc": { "nullable": true, "type": "string" }, "mnc": { "nullable": true, "type": "string" }, "imsi": { "nullable": true, "type": "string" }, "msc": { "nullable": true, "type": "string" }, "originalNetwork": { "nullable": true, "type": "string" }, "originalCountryName": { "nullable": true, "type": "string" }, "originalCountryCode": { "nullable": true, "type": "string" }, "originalCountryPrefix": { "nullable": true, "type": "string" }, "currentNetwork": { "nullable": true, "type": "string" }, "ported": { "nullable": true, "type": "boolean" }, "portedNetworkName": { "nullable": true, "type": "string" }, "portedCountryName": { "nullable": true, "type": "string" }, "portedCountryCode": { "nullable": true, "type": "string" }, "portedCountryPrefix": { "nullable": true, "type": "string" }, "presentInNetwork": { "nullable": true, "type": "boolean" }, "reachable": { "nullable": true, "type": "boolean" }, "roaming": { "nullable": true, "type": "boolean" }, "roamingNetworkName": { "nullable": true, "type": "string" }, "roamingCountryName": { "nullable": true, "type": "string" }, "roamingCountryCode": { "nullable": true, "type": "string" }, "roamingCountryPrefix": { "nullable": true, "type": "string" }, "dataSource": { "nullable": true, "type": "string" }, "numberType": { "nullable": true, "type": "string" }, "queryStatus": { "nullable": true, "type": "string" }, "valid": { "nullable": true, "type": "boolean" }, "invalidReason": { "nullable": true, "type": "string" }, "carrier": { "nullable": true, "type": "string" }, "countryCode": { "nullable": true, "type": "string" }, "countryName": { "nullable": true, "type": "string" }, "possiblyPorted": { "nullable": true, "type": "boolean" }, "vanityNumber": { "nullable": true, "type": "boolean" }, "qualifiesForHlrLookup": { "nullable": true, "type": "boolean" }, "regions": { "nullable": true, "type": "array", "items": { "type": "string" } }, "timezones": { "nullable": true, "type": "array", "items": { "type": "string" } }, "infoText": { "nullable": true, "type": "string" }, "portedDate": { "nullable": true, "type": "string" } }, "additionalProperties": false }, "startedAt": { "type": "string" }, "completedAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "jobId", "status", "counts", "actions" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "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" } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "404": { "description": "NOT_FOUND", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "No such resource.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "parameters": [ { "name": "lookupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v1/hlr/lookups/{lookupId}/exports": { "post": { "tags": [ "Exports" ], "operationId": "createLookupExport", "summary": "Build an export", "description": "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.", "responses": { "202": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "ready", "failed", "expired" ] }, "format": { "type": "string", "minLength": 1 }, "sizeBytes": { "type": "number" }, "checksum": { "type": "string", "minLength": 1 }, "downloadUrl": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "string" } }, "required": [ "status", "format" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "status": "ready", "format": "csv", "downloadUrl": "https://api.bitcall.io/v1/hlr/lookups/d5582f70-c53c-493d-8bbd-64d435778379/exports/csv/content" } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "404": { "description": "NOT_FOUND", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "No such resource.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "parameters": [ { "name": "lookupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "csv", "xlsx" ] } }, "required": [ "format" ], "additionalProperties": false }, "example": { "format": "csv" } } } } } }, "/v1/hlr/lookups/{lookupId}/exports/{format}": { "get": { "tags": [ "Exports" ], "operationId": "getLookupExport", "summary": "Get an export", "description": "Returns whether the export is ready, with its size and checksum once it is. Fetch the file itself from this export's `/content`.", "responses": { "200": { "description": "Success.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "ready", "failed", "expired" ] }, "format": { "type": "string", "minLength": 1 }, "sizeBytes": { "type": "number" }, "checksum": { "type": "string", "minLength": 1 }, "downloadUrl": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "string" } }, "required": [ "status" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "status": "ready", "format": "csv", "sizeBytes": 283, "checksum": "sha256:ce67c0b9ce3876c74d97e979a921e1c1fbe93127d2e6ea53a362561590ccc53e", "downloadUrl": "https://api.bitcall.io/v1/hlr/lookups/d5582f70-c53c-493d-8bbd-64d435778379/exports/csv/content" } } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "404": { "description": "NOT_FOUND", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "No such resource.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "parameters": [ { "name": "lookupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "format", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "json", "csv", "xlsx" ] } } ] } }, "/v1/hlr/lookups/{lookupId}/exports/{format}/content": { "get": { "tags": [ "Exports" ], "operationId": "downloadLookupExport", "summary": "Download an export", "description": "Returns the export file itself, as an attachment. Build it first, and check it is `ready` — an export still building answers 409.", "responses": { "200": { "description": "The file, as an attachment.", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "content-disposition": { "description": "Always `attachment`, with a filename derived from the lookup and format.", "schema": { "type": "string" } } }, "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "string", "format": "binary" }, "example": [ { "inputValue": "21650000001", "normalizedInput": "21650000001", "resultStatus": "success", "mcc": "605", "mnc": "01", "originalNetwork": "Orange", "currentNetwork": "Orange", "ported": false, "roaming": false, "reachable": false, "presentInNetwork": true, "errorCode": null, "processedAt": "2026-09-15T22:27:33.323Z", "sellingPrice": 1.0025, "currency": "EUR" } ] }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "VALIDATION_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_ERROR", "message": "The request is not valid. See `fields` for what to correct.", "requestId": "9f1c7b2e-…" } } } } }, "401": { "description": "AUTHENTICATION_REQUIRED · INVALID_API_KEY", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_REQUIRED", "message": "This endpoint requires an API key.", "requestId": "9f1c7b2e-…" } } } } }, "404": { "description": "NOT_FOUND", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "No such resource.", "requestId": "9f1c7b2e-…" } } } } }, "409": { "description": "CONFLICT", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CONFLICT", "message": "The resource is not in a state that allows this operation.", "requestId": "9f1c7b2e-…" } } } } }, "429": { "description": "RATE_LIMITED", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" }, "retry-after": { "description": "Whole seconds to wait before retrying.", "required": true, "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the interval in `Retry-After`.", "requestId": "9f1c7b2e-…" } } } } }, "500": { "description": "INTERNAL_ERROR", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong on our side.", "requestId": "9f1c7b2e-…" } } } } }, "502": { "description": "SERVICE_RESPONSE_INVALID", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_RESPONSE_INVALID", "message": "The upstream service returned an unexpected response.", "requestId": "9f1c7b2e-…" } } } } }, "503": { "description": "SERVICE_UNAVAILABLE", "headers": { "x-request-id": { "$ref": "#/components/headers/RequestId" }, "cache-control": { "$ref": "#/components/headers/CacheControlNoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again shortly.", "requestId": "9f1c7b2e-…" } } } } } }, "parameters": [ { "name": "lookupId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "format", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "json", "csv", "xlsx" ] } } ] } } }, "components": { "securitySchemes": { "KeyId": { "type": "apiKey", "in": "header", "name": "x-key-id", "description": "Your API key id." }, "ApiSecret": { "type": "apiKey", "in": "header", "name": "x-api-secret", "description": "Your API key secret." } }, "headers": { "RequestId": { "description": "Correlation id for this request. Quote it when contacting support.", "schema": { "type": "string" } }, "CacheControlNoStore": { "description": "Always `no-store, private`. This body may carry order, eSIM or activation material — an activation code is a bearer credential — so it must not be written to any cache, proxy or log, yours included.", "schema": { "type": "string", "enum": [ "no-store, private" ] } }, "CacheControlPrivate": { "description": "Always `private, max-age=300`. Catalogue data: your own client may reuse it for five minutes. `private`, never `public` — prices resolve per account, so a shared cache must not serve one account's body to another. Paired with `Vary: x-key-id`. Error responses on this route are `no-store`.", "schema": { "type": "string", "enum": [ "private, max-age=300" ] } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "VALIDATION_ERROR", "AUTHENTICATION_REQUIRED", "INVALID_API_KEY", "NOT_FOUND", "CONFLICT", "CANCELLATION_NOT_AVAILABLE_YET", "REACTIVATION_UNAVAILABLE", "INSUFFICIENT_BALANCE", "PRODUCT_UNAVAILABLE", "RATE_LIMITED", "SERVICE_RESPONSE_INVALID", "SERVICE_UNAVAILABLE", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" }, "description": "Request-validation failures only: the field paths at fault, never their values." } } } } } } } }