{ "openapi": "3.1.0", "info": { "title": "Contact intelligence API", "version": "1.0" }, "servers": [ { "url": "https://number-api.bind.hr" } ], "components": { "securitySchemes": { "default": { "type": "apiKey", "in": "header", "name": "X-API-KEY" } }, "schemas": { "MsisdnRequest": { "type": "object", "required": [ "msisdn" ], "properties": { "msisdn": { "type": "array", "items": { "type": "string" }, "description": "A list of MSISDNs to look up." }, "callback_url": { "type": "string", "format": "uri", "description": "An optional URL to receive a callback with the results." } } }, "ContactIntelligenceRecord": { "type": "object", "required": [ "msisdn", "metadata" ], "properties": { "msisdn": { "type": "string", "description": "The MSISDN to validate.", "example": "385911234567" }, "metadata": { "type": "string", "description": "Client reference echoed back on this number's result. Required — records missing `msisdn` or `metadata` are ignored.", "example": "ref-001" }, "country_iso": { "type": "string", "description": "Optional ISO 3166-1 alpha-2 country code for this number (e.g. `HR`). Falls back to the top-level `country_iso` when omitted.", "example": "HR" } } }, "ContactIntelligenceRequest": { "type": "object", "description": "Submit either a `msisdn` array **or** a `records` array — not both (a mixed request is rejected with response code 6). A maximum of 100 numbers can be validated per request.", "properties": { "msisdn": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "A list of MSISDNs to validate. Mutually exclusive with `records`." }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/ContactIntelligenceRecord" }, "maxItems": 100, "description": "A list of records to validate, each carrying its own `metadata` and optional `country_iso`. Mutually exclusive with `msisdn`. A record is only processed when it contains both `msisdn` and `metadata`." }, "country_iso": { "type": "string", "description": "Optional default ISO 3166-1 alpha-2 country code (e.g. `HR`) applied to every submitted number. For `records`, a record's own `country_iso` takes precedence over this value.", "example": "HR" }, "metadata": { "type": "string", "description": "Optional client reference echoed back on every result. Applies to the `msisdn` array form; for `records` use the per-record `metadata` field instead." }, "callback_url": { "type": "string", "format": "uri", "description": "Optional URL to receive an asynchronous callback with the results. When provided, the endpoint responds with `202` and `{ \"id\": \"\" }`, then POSTs `{ \"id\": \"\", \"data\": [ ... ] }` to this URL once processing completes." } } } } }, "security": [ { "default": [] } ], "paths": { "/lookup/contact-verification": { "post": { "summary": "Contact verification", "description": "**Introduction**\n\nThe contact verification api provides insight into how credible the number is.\n\n### `date`\n\n**Type:** `string` (ISO 8601 timestamp)\n**Example:** `2025-06-21T17:21:56.526Z`\n**Description:** The exact date and time when this record was generated or last updated.\n\n***\n\n### `msisdn`\n\n**Type:** `string`\n**Format:** Country code + subscriber number (no separators)\n**Example:** `38591XXXXXXX`\n**Description:** Mobile Station International Subscriber Directory Number – the full telephone number including country code.\n\n***\n\n### `phone`\n\nAn object containing detailed telecom metadata about the number.\n\n| Field | Type | Example | Description |\n| :---- | :--- | :------ | :---------- |\n| `country_calling_code` | `string` | `385` | International dialing code for the country. |\n| `country_name` | `string` | `Croatia` | Official country name. |\n| `current_network_mobile_code` | `string` | `01` | Mobile network code (MNC) of the network the number is currently registered on. |\n| `first_seen` | `string` | `2017-03-05` | Date the number was first observed in our system. |\n| `current_network_name` | `string` | `T-Mobile` | Human-readable name of the network the number currently uses. |\n| `initial_network_name` | `string` | `A1` | Name of the network where the number was first issued. |\n| `initial_network_mobile_code` | `string` | `10` | Mobile network code (MNC) of the initial network. |\n| `first_ported` | `string` | `2017-03-05` | Date the number was first ported from its original network. |\n| `last_ported` | `string` | `2024-02-06` | Date the number was most recently ported to a different network. |\n| `mobile_country_code` | `string` | `219` | Mobile Country Code (MCC) assigned to the country/operator. |\n| `ported_times` | `integer` | `4` | Total number of times the number has been ported between networks. |\n| `type` | `string` | `mobile` | Phone type; e.g. `landline`, `mobile`, `toll_free`, `shared_cost`, `voip`, `emergency`, `n/a`. |\n\n### `response`\n\n| Value | Description | Action |\n| :---- | :------------------ | :------------------------------------------------------------------------------------------------------------------ |\n| 0 | Success | :airplane: |\n| 1 | General error | Repeating the request won't yield different result |\n| 2 | Pricing not set | Contact [procurement@bind.hr](mailto:procurement@bind.hr) |\n| 3 | Out of balance | Contact [procurement@bind.hr](mailto:procurement@bind.hr) |\n| 4 | Throttled | You are sending at higher rate per second than allocated. Contact [procurement@bind.hr](mailto:procurement@bind.hr) |\n| 5 | Invalid number | Number length not valid |\n| 6 | Not resolved | Number cannot be resolved due to missing coverage |\n| 7 | Timeout | Number cannot be resolved due to timeout |\n| 8 | Missing permissions | Contact [procurement@bind.hr](mailto:procurement@bind.hr) |\n\n***\n\n### `scoring`\n\nAn object describing quality or trust metrics for the number.\n\n| Field | Type | Example | Description |\n| :------------ | :------- | :------ | :---------------------------------------------------------- |\n| `credibility` | `string` | `high` | Values: `very_low`, `low`, `intermediate`, `high`, `very_high` |\n\nThe higher the credibility the more the number is a credible / trusted number.\n\n***\n\n### `security`\n\nAn object detailing any security-related flags or breach history.\n\n| Field | Type | Example | Description |\n| :--------------------------- | :-------- | :----------- | :--------------------------------------------------------------------------------------- |\n| `data_breaches_count` | `integer` | `3` | Number of known data breaches involving this number or associated account. |\n| `data_breaches_first_breach` | `string` | `2018-10-16` | Date of the earliest recorded breach. |\n| `data_breaches_last_breach` | `string` | `2021-04-08` | Date of the most recent recorded breach. |\n| `is_disposable` | `string` | `no` | Indicates whether the number is from a disposable/temporary service (`yes`/`no` / `n/a`) |\n\n### `social_presence`\n\nAn object mapping major platforms to presence indicators.\n\n- **`has`** may be:\n - `yes` – profile found\n - `no` – profile explicitly not found\n - `n/a` – lookup wasn’t possible (information unavailable)\n- **`is_business`** (where applicable): `yes`/`no`", "operationId": "contact-verification", "tags": [ "Contact verification" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MsisdnRequest" }, "examples": { "default": { "value": { "msisdn": [ "4473481234567" ] } }, "with_callback": { "value": { "msisdn": [ "4473481234567" ], "callback_url": "https://example.com/callback" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "examples": { "Success": { "summary": "Success", "value": [ { "date": "2025-09-01T09:06:46.285Z", "msisdn": "4473481234567", "phone": { "country_calling_code": "44", "country_name": "United Kingdom", "current_network_mobile_code": "33", "current_network_name": "EE", "first_ported": "2017-03-05", "first_seen": "2017-03-05", "initial_network_name": "Vodafone UK", "initial_network_mobile_code": "15", "last_ported": "2024-02-06", "mobile_country_code": "234", "ported_times": 4, "type": "mobile" }, "response": 0, "scoring": { "credibility": "high" }, "security": { "data_breaches_count": 3, "data_breaches_first_breach": "2018-10-16", "data_breaches_last_breach": "2021-04-08", "is_disposable": "no" }, "social_presence": { "amazon": { "has": "yes" }, "apple": { "has": "yes" }, "bukalapak": { "has": "n/a" }, "facebook": { "has": "yes" }, "flipkart": { "has": "n/a" }, "google": { "has": "n/a" }, "instagram": { "has": "no" }, "linkedin": { "has": "n/a" }, "snapchat": { "has": "n/a" }, "telegram": { "has": "yes" }, "viber": { "has": "n/a" }, "whatsapp": { "has": "yes", "is_business": "no" }, "x": { "has": "yes" } } } ] }, "General error": { "value": [ { "date": "2025-09-13T09:13:04.806Z", "msisdn": "4473481234567", "response": 1 } ] }, "Pricing not set": { "value": [ { "date": "2025-09-13T09:13:04.806Z", "msisdn": "4473481234567", "response": 2 } ] }, "Out of balance": { "value": [ { "date": "2025-09-13T09:13:04.806Z", "msisdn": "4473481234567", "response": 3 } ] }, "Throttled": { "value": [ { "date": "2025-09-13T09:13:04.806Z", "msisdn": "4473481234567", "response": 4 } ] }, "Invalid number": { "value": [ { "date": "2025-09-13T09:13:04.806Z", "msisdn": "4473481234567", "response": 5 } ] }, "Not resolved": { "value": [ { "date": "2025-09-13T09:13:04.806Z", "msisdn": "4473481234567", "response": 6 } ] }, "Timeout": { "value": [ { "date": "2025-09-13T09:13:04.806Z", "msisdn": "4473481234567", "response": 7 } ] }, "Missing permissions": { "value": [ { "date": "2025-09-13T09:13:04.806Z", "msisdn": "4473481234567", "response": 8 } ] } }, "schema": { "type": "array", "items": { "type": "object", "required": [ "date", "msisdn", "response" ], "properties": { "date": { "type": "string", "example": "2025-09-01T09:06:46.285Z" }, "msisdn": { "type": "string", "example": "4473481234567" }, "response": { "type": "integer", "example": 0 }, "phone": { "type": "object", "properties": { "country_calling_code": { "type": "string", "example": "44" }, "country_name": { "type": "string", "example": "United Kingdom" }, "current_network_mobile_code": { "type": "string", "example": "33" }, "current_network_name": { "type": "string", "example": "EE" }, "first_ported": { "type": "string", "example": "2017-03-05" }, "first_seen": { "type": "string", "example": "2017-03-05" }, "initial_network_name": { "type": "string", "example": "Vodafone UK" }, "initial_network_mobile_code": { "type": "string", "example": "15" }, "last_ported": { "type": "string", "example": "2024-02-06" }, "mobile_country_code": { "type": "string", "example": "234" }, "ported_times": { "type": "integer", "example": 4 }, "type": { "type": "string", "example": "mobile" } } }, "scoring": { "type": "object", "properties": { "credibility": { "type": "string", "example": "high" } } }, "security": { "type": "object", "properties": { "data_breaches_count": { "type": "integer", "example": 3 }, "data_breaches_first_breach": { "type": "string", "example": "2018-10-16" }, "data_breaches_last_breach": { "type": "string", "example": "2021-04-08" }, "is_disposable": { "type": "string", "example": "no" } } }, "social_presence": { "type": "object", "properties": { "amazon": { "type": "object", "properties": { "has": { "type": "string", "example": "yes" } } }, "apple": { "type": "object", "properties": { "has": { "type": "string", "example": "yes" } } }, "bukalapak": { "type": "object", "properties": { "has": { "type": "string", "example": "n/a" } } }, "facebook": { "type": "object", "properties": { "has": { "type": "string", "example": "yes" } } }, "flipkart": { "type": "object", "properties": { "has": { "type": "string", "example": "n/a" } } }, "google": { "type": "object", "properties": { "has": { "type": "string", "example": "n/a" } } }, "instagram": { "type": "object", "properties": { "has": { "type": "string", "example": "no" } } }, "linkedin": { "type": "object", "properties": { "has": { "type": "string", "example": "n/a" } } }, "snapchat": { "type": "object", "properties": { "has": { "type": "string", "example": "n/a" } } }, "telegram": { "type": "object", "properties": { "has": { "type": "string", "example": "yes" } } }, "viber": { "type": "object", "properties": { "has": { "type": "string", "example": "n/a" } } }, "whatsapp": { "type": "object", "properties": { "has": { "type": "string", "example": "yes" }, "is_business": { "type": "string", "example": "no" } } }, "x": { "type": "object", "properties": { "has": { "type": "string", "example": "yes" } } } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "examples": { "Unauthorized": { "value": "Unauthorized", "summary": "Unauthorized" } } } } } }, "parameters": [ { "name": "X-API-KEY", "in": "header", "required": true, "description": "API key", "schema": { "type": "string", "format": "password", "default": "" } } ] } }, "/enterprise/contact-intelligence": { "post": { "summary": "Contact intelligence", "description": "**Introduction**\n\nContact intelligence is a single enterprise endpoint that combines a real-time (HLR) query with a database fallback. For every MSISDN you submit it returns the number's country, current and original network, portability status and \u2014 when a live query succeeds \u2014 its real-time availability and GSM-level diagnostic.\n\nSend a `POST` request with a JSON body containing the MSISDNs to validate \u2014 the same payload used by the other Contact intelligence lookups, so many numbers can be validated in one call. The endpoint is served from `https://cleansing-api.bind.hr`.\n\n**Request**\n\nAuthenticate with your enterprise API key in the `X-API-KEY` header and send a JSON body. Provide numbers in **one** of two mutually exclusive forms — a simple `msisdn` array, or a `records` array where each entry carries its own `metadata` and optional `country_iso`. A maximum of 100 numbers can be validated per request; a request that mixes `msisdn` and `records` is rejected with response code 6.\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msisdn` | string[] | conditional | One or more MSISDNs to validate. Provide either `msisdn` or `records`, not both. |\n| `records` | object[] | conditional | Records to validate. Provide either `msisdn` or `records`, not both. A record is only processed when it contains both `msisdn` and `metadata`. |\n| `records[].msisdn` | string | yes | The MSISDN for this record. |\n| `records[].metadata` | string | yes | Client reference echoed back on this number's result; records missing it are ignored. |\n| `records[].country_iso` | string | no | ISO 3166-1 alpha-2 country code for this number; falls back to the top-level `country_iso`. |\n| `country_iso` | string | no | Default ISO 3166-1 alpha-2 country code applied to every submitted number. |\n| `metadata` | string | no | Client reference echoed back on every result (for the `msisdn` array form). |\n| `callback_url` | string (uri) | no | An optional URL to receive an asynchronous callback with the results. When set, the endpoint returns `202` with an `id` and POSTs the results to this URL when ready. |\n\n**Response object**\n\nThe endpoint returns a JSON array with one object per submitted MSISDN. Each object contains:\n\n- `date` \u2014 time when the request was executed (ISO 8601)\n- `msisdn` \u2014 the number as submitted\n- `normalizedMsisdn` \u2014 the number in normalized form\n- `country` \u2014 `ISO2`, `countryDialCode`, `mcc`, `name`\n- `number` \u2014 `type` (e.g. `Mobile`)\n- `currentNetwork` \u2014 `mnc`, `name`: the network the number currently belongs to\n- `originalNetwork` \u2014 `mnc`, `name`: the network the number was originally issued on\n- `ported` \u2014 `true` when the current network differs from the original network\n- `availability` \u2014 high-level reachability summary (see below)\n- `diagnostic` \u2014 GSM-level detail (see below)\n- `source` \u2014 `type`: how the result was resolved (see below)\n- `cost` \u2014 the price for this lookup\n- `response` \u2014 the result code (see below)\n\n**Live vs. Database results**\n\n`source.type` tells you how the result was resolved and how much of it you can rely on:\n\n- **`Live`** \u2014 the number was queried in real time. `diagnostic.gsmErrorAvailable` is `true` and `diagnostic.gsmError` carries the GSM error code returned by the network, which drives the `availability` fields.\n- **`Database`** \u2014 live reachability could not be checked, so the result was resolved from database information only (format, country, network and portability). `diagnostic.gsmError` is `null`, `diagnostic.gsmErrorAvailable` is `false`, and `availability.status` / `availability.condition` are `Unknown`.\n\n**`availability` object**\n\nDerived from the GSM error code (see the table below):\n\n- `status` \u2014 `Available`, `Unavailable`, `Uncertain` or `Unknown`\n- `condition` \u2014 `Active`, `Permanent`, `Temporary` or `Unknown`\n- `reason` \u2014 short human-readable explanation\n\n**`diagnostic` object**\n\n- `gsmError` \u2014 the GSM error code (integer), or `null` for database-sourced results\n- `gsmErrorAvailable` \u2014 whether a live GSM error code is available\n- `gsmErrorName` \u2014 the symbolic name of the code (e.g. `REACHABLE`, `ABSENT_SUBSCRIBER`), or `null`\n- `gsmErrorDescription` \u2014 a plain-language description of the code\n\n**`response` values**\n\n| Value | Description | Action |\n|------:|-------------|--------|\n| 0 | Success | \u2708\ufe0f |\n| 1 | General error | Repeating the request won't yield a different result |\n| 2 | Pricing not set | Contact procurement@bind.hr |\n| 3 | Out of balance | Contact procurement@bind.hr |\n| 4 | Throttled | Contact procurement@bind.hr |\n| 5 | Invalid number | Number length not valid |\n| 6 | Not resolved | Number cannot be resolved due to missing coverage |\n| 7 | Timeout | Number cannot be resolved due to timeout |\n| 8 | Missing permissions | Contact procurement@bind.hr |\n\n**GSM error codes**\n\n`diagnostic.gsmError` is populated for `Live` results and drives the `availability` fields as follows:\n\n| Code | Name | Status | Condition | Reason | Description |\n| ---: | --- | --- | --- | --- | --- |\n| 0 | REACHABLE | Available | Active | Number is reachable. | The number appears to be active and reachable on the mobile network. |\n| 1 | UNKNOWN_SUBSCRIBER | Unavailable | Permanent | Number is unknown. | The number is not recognized by the mobile network. It is likely inactive, disconnected, or not assigned. |\n| 5 | UNIDENTIFIED_SUBSCRIBER | Unavailable | Permanent | Subscriber could not be identified. | The network could not identify the subscriber. The number is likely not valid or not active on the network. |\n| 9 | ILLEGAL_SUBSCRIBER | Unavailable | Permanent | Subscriber is not allowed on the network. | The subscriber is rejected by the network. This usually indicates a blocked, invalid, or unauthorized subscription. |\n| 11 | TELESERVICE_NOT_PROVISIONED | Unavailable | Permanent | Messaging service is not enabled. | The number may exist, but the requested mobile service is not enabled for this subscriber. |\n| 13 | CALL_BARRED | Unavailable | Temporary | Service is barred. | The number may exist, but the requested service is currently blocked or restricted by the operator. |\n| 21 | FACILITY_NOT_SUPPORTED | Uncertain | Unknown | Requested service is not supported. | The network does not support the requested service or lookup type, so the subscriber status cannot be confirmed. |\n| 27 | ABSENT_SUBSCRIBER | Unavailable | Temporary | Subscriber is temporarily unreachable. | The number appears to exist, but the subscriber is currently not reachable on the network. |\n| 31 | SUBSCRIBER_BUSY_FOR_MT_SMS | Unavailable | Temporary | Subscriber is temporarily busy. | The number appears to exist, but the subscriber is temporarily busy or cannot receive the service at this moment. |\n| 32 | DELIVERY_FAILURE | Uncertain | Unknown | Network returned an inconclusive failure. | The network returned a generic delivery failure. The final subscriber status cannot be reliably determined. |\n| 34 | SYSTEM_FAILURE | Uncertain | Unknown | Network system failure. | The network or lookup provider returned a system failure. The subscriber status could not be confirmed. |\n| 36 | UNEXPECTED_DATA_VALUE | Uncertain | Unknown | Unexpected network response. | The network returned an unexpected value, so the subscriber status could not be reliably interpreted. |\n| 37 | MEMORY_CAPACITY_EXCEEDED | Unavailable | Temporary | Device memory may be full. | The number appears to exist, but the device or network reports that message storage capacity has been exceeded. |\n| 38 | PREFIX_NOT_RESOLVED | Unknown | Unknown | Number prefix could not be resolved. | The number prefix could not be matched to a valid country or network. Network and subscriber status are unknown. |\n| 39 | IMSI_BLACKLISTED | Unavailable | Permanent | Subscriber identity is blacklisted. | The subscriber identity is blocked or blacklisted. The number should not be treated as reachable. |\n| 40 | DEST_ADDRESS_BLACKLISTED | Unavailable | Permanent | Destination number is blacklisted. | The destination number is blocked or blacklisted and should not be contacted. |\n| 41 | TIME_OUT | Uncertain | Unknown | Lookup timed out. | The lookup did not complete within the expected time. The subscriber status could not be confirmed. |\n| 43 | INVALID_ORIGINATOR_ADDRESS | Uncertain | Unknown | Sender address was rejected. | The lookup or message was rejected because the sender/originator address was invalid. This does not reliably confirm the destination number status. |\n| 100 | GENERAL_ERROR | Uncertain | Unknown | General processing error. | A general error occurred during processing. The subscriber status could not be confirmed. |\n| 200 | EQUIPMENT_PROTOCOL_ERROR | Uncertain | Unknown | Network protocol error. | A technical protocol error occurred between network systems. The subscriber status could not be confirmed. |\n| 201 | UNKNOWN_MSC | Uncertain | Unknown | Serving network node is unknown. | The network could not identify the serving mobile switching node. The subscriber status could not be confirmed. |\n| 202 | CONGESTION_ERROR | Uncertain | Temporary | Network congestion. | The network is congested or temporarily overloaded. The lookup should be retried later. |\n| 203 | PARAMETER_MISSMATCH | Uncertain | Unknown | Request parameter mismatch. | The request contained parameters that did not match expected network values. The subscriber status could not be confirmed. |\n| 204 | INITIATING_RELEASE | Uncertain | Unknown | Network released the request. | The network released the request before a clear subscriber status was returned. |\n| 205 | POTENTIAL_VERSION_INCOMPATIBILITY | Uncertain | Unknown | Network compatibility issue. | A compatibility issue occurred between network systems. The subscriber status could not be confirmed. |\n| 206 | REMOTE_NODE_NOT_REACHABLE | Uncertain | Temporary | Remote network node is not reachable. | A required network node could not be reached. The lookup may succeed if retried later. |\n| 207 | MTP_FAILURE | Uncertain | Temporary | Network transport failure. | A signalling transport failure occurred in the network. The lookup may succeed if retried later. |\n| 208 | NETWORK_CONGESTION | Uncertain | Temporary | Network congestion. | The network is temporarily congested. The lookup should be retried later. |\n| 209 | SIGNALLING_FAILURE | Uncertain | Temporary | Network signalling failure. | A signalling failure occurred in the mobile network. The lookup may succeed if retried later. |\n| 210 | ABNORMAL_MAP_DIALOG | Uncertain | Unknown | Abnormal network dialogue. | The network session ended abnormally, so the subscriber status could not be confirmed. |\n| 211 | INVALID_PDU_FORMAT | Uncertain | Unknown | Invalid network message format. | The network rejected the request format. The subscriber status could not be confirmed. |\n| 300 | ABORTED_RETRY | Uncertain | Temporary | Lookup was aborted and should be retried. | The lookup was aborted before a final result was received. A retry may return a clearer result. |\n| 301 | VALIDITY_PERIOD_EXPIRED | Uncertain | Temporary | Request validity expired. | The request expired before a final network result was received. A retry may be required. |\n\n> The `DATABASE_SOURCE` code (`9999`) is never returned as a `gsmError` value \u2014 for database-sourced results `gsmError` is `null`. Its description (_\"Database source does not provide live reachability status.\"_) is what surfaces in `availability` and `diagnostic` when `source.type` is `Database`.", "operationId": "one-lookup", "tags": [ "Contact intelligence" ], "servers": [ { "url": "https://cleansing-api.bind.hr" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactIntelligenceRequest" }, "examples": { "default": { "summary": "Records with metadata and per-record country", "value": { "records": [ { "msisdn": "447459100106", "metadata": "ref-001", "country_iso": "GB" } ] } }, "with_callback": { "summary": "MSISDN array with callback", "value": { "msisdn": [ "447459100106" ], "callback_url": "https://example.com/callback" } }, "msisdn_with_country": { "summary": "MSISDN array with default country", "value": { "msisdn": [ "911234567", "912345678" ], "country_iso": "HR" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Success - Live (reachable)": { "value": [ { "availability": { "condition": "Active", "reason": "Number is reachable", "status": "Available" }, "cost": 0.005, "country": { "ISO2": "GB", "countryDialCode": "44", "mcc": "234", "name": "United Kingdom" }, "currentNetwork": { "mnc": "30", "name": "MNO - EE (Everything Everywhere)" }, "date": "2026-06-12T05:06:46.359Z", "diagnostic": { "gsmError": 0, "gsmErrorAvailable": true, "gsmErrorDescription": "The number appears to be active and reachable on the mobile network", "gsmErrorName": "REACHABLE" }, "msisdn": "447459100106", "normalizedMsisdn": "447459100106", "number": { "type": "Mobile" }, "originalNetwork": { "mnc": "26", "name": "MVNO - LycaMobile" }, "ported": true, "response": 0, "source": { "type": "Live" } } ] }, "Success - Database (no live status)": { "value": [ { "availability": { "condition": "Unknown", "reason": "Database source does not provide live reachability status", "status": "Unknown" }, "cost": 0.005, "country": { "ISO2": "HR", "countryDialCode": "385", "mcc": "219", "name": "Croatia" }, "currentNetwork": { "mnc": "01", "name": "T-Mobile" }, "date": "2026-06-12T05:06:45.817Z", "diagnostic": { "gsmError": null, "gsmErrorAvailable": false, "gsmErrorDescription": "The result was resolved using database information. The system can identify number format, country, network and portability information where available, but live reachability was not checked", "gsmErrorName": null }, "metadata": "ref-001", "msisdn": "385981315559", "normalizedMsisdn": "385981315559", "number": { "type": "Mobile" }, "originalNetwork": { "mnc": "01", "name": "T-Mobile" }, "ported": false, "response": 0, "source": { "type": "Database" } } ] }, "Success - Live (absent subscriber)": { "value": [ { "availability": { "condition": "Temporary", "reason": "Subscriber is temporarily unreachable", "status": "Unavailable" }, "cost": 0.005, "country": { "ISO2": "SI", "countryDialCode": "386", "mcc": "293", "name": "Slovenia" }, "currentNetwork": { "mnc": "41", "name": "Mobitel" }, "date": "2026-06-12T05:06:46.302Z", "diagnostic": { "gsmError": 27, "gsmErrorAvailable": true, "gsmErrorDescription": "The number appears to exist, but the subscriber is currently not reachable on the network", "gsmErrorName": "ABSENT_SUBSCRIBER" }, "msisdn": "38631360036", "normalizedMsisdn": "38631360036", "number": { "type": "Mobile" }, "originalNetwork": { "mnc": "41", "name": "Mobitel" }, "ported": false, "response": 0, "source": { "type": "Live" } } ] }, "Invalid number": { "value": [ { "cost": 0, "date": "2026-06-12T05:15:49.216Z", "msisdn": "123", "response": 5 } ] } }, "schema": { "type": "array", "items": { "type": "object", "required": [ "date", "msisdn", "response" ], "properties": { "date": { "type": "string", "example": "2026-06-12T05:06:46.359Z" }, "msisdn": { "type": "string", "example": "447459100106" }, "normalizedMsisdn": { "type": "string", "example": "447459100106" }, "metadata": { "type": "string", "description": "The client reference supplied for this number (top-level `metadata` for the `msisdn` form, or the per-record `metadata`). Only present when metadata was supplied in the request.", "example": "ref-001" }, "cost": { "type": "number", "example": 0.005 }, "response": { "type": "integer", "example": 0 }, "ported": { "type": "boolean", "example": true }, "country": { "type": "object", "properties": { "ISO2": { "type": "string", "example": "GB" }, "countryDialCode": { "type": "string", "example": "44" }, "mcc": { "type": "string", "example": "234" }, "name": { "type": "string", "example": "United Kingdom" } } }, "number": { "type": "object", "properties": { "type": { "type": "string", "example": "Mobile" } } }, "currentNetwork": { "type": "object", "properties": { "mnc": { "type": "string", "example": "30" }, "name": { "type": "string", "example": "MNO - EE (Everything Everywhere)" } } }, "originalNetwork": { "type": "object", "properties": { "mnc": { "type": "string", "example": "26" }, "name": { "type": "string", "example": "MVNO - LycaMobile" } } }, "source": { "type": "object", "properties": { "type": { "type": "string", "example": "Live" } } }, "availability": { "type": "object", "properties": { "status": { "type": "string", "example": "Available" }, "condition": { "type": "string", "example": "Active" }, "reason": { "type": "string", "example": "Number is reachable" } } }, "diagnostic": { "type": "object", "properties": { "gsmError": { "type": [ "integer", "null" ], "example": 0 }, "gsmErrorAvailable": { "type": "boolean", "example": true }, "gsmErrorName": { "type": [ "string", "null" ], "example": "REACHABLE" }, "gsmErrorDescription": { "type": "string", "example": "The number appears to be active and reachable on the mobile network" } } } } } } } } }, "202": { "description": "Accepted — the request is being processed asynchronously. Returned only when `callback_url` is supplied; the results are POSTed to that URL as `{ \"id\": \"\", \"data\": [ ... ] }` once ready.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier for this asynchronous request; echoed back in the callback payload.", "example": "3f1c2b9a-7d4e-4a2b-9c1f-2e5a8b0d6c11" } } }, "examples": { "Accepted": { "value": { "id": "3f1c2b9a-7d4e-4a2b-9c1f-2e5a8b0d6c11" } } } } } }, "401": { "description": "401", "content": { "text/plain": { "examples": { "Unauthorized": { "value": "" } } } } }, "500": { "description": "500", "content": { "text/plain": { "examples": { "Result": { "value": "" } } } } } }, "deprecated": false } } } }