Contact Intelligence

Contact intelligence

post

Introduction

Contact 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 — when a live query succeeds — its real-time availability and GSM-level diagnostic.

Send a POST request with a JSON body containing the MSISDNs to validate — 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.

Request

Authenticate 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.

Field	Type	Required	Description
msisdn	string[]	conditional	One or more MSISDNs to validate. Provide either msisdn or records, not both.
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.
records[].msisdn	string	yes	The MSISDN for this record.
records[].metadata	string	yes	Client reference echoed back on this number's result; records missing it are ignored.
records[].country_iso	string	no	ISO 3166-1 alpha-2 country code for this number; falls back to the top-level country_iso.
country_iso	string	no	Default ISO 3166-1 alpha-2 country code applied to every submitted number.
metadata	string	no	Client reference echoed back on every result (for the msisdn array form).
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.

Response object

The endpoint returns a JSON array with one object per submitted MSISDN. Each object contains:

• date — time when the request was executed (ISO 8601)

• msisdn — the number as submitted

• normalizedMsisdn — the number in normalized form

• country — ISO2, countryDialCode, mcc, name

• number — type (e.g. Mobile)

• currentNetwork — mnc, name: the network the number currently belongs to

• originalNetwork — mnc, name: the network the number was originally issued on

• ported — true when the current network differs from the original network

• availability — high-level reachability summary (see below)

• diagnostic — GSM-level detail (see below)

• source — type: how the result was resolved (see below)

• cost — the price for this lookup

• response — the result code (see below)

Live vs. Database results

source.type tells you how the result was resolved and how much of it you can rely on:

• Live — 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.

• Database — 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.

availability object

Derived from the GSM error code (see the table below):

• status — Available, Unavailable, Uncertain or Unknown

• condition — Active, Permanent, Temporary or Unknown

• reason — short human-readable explanation

diagnostic object

• gsmError — the GSM error code (integer), or null for database-sourced results

• gsmErrorAvailable — whether a live GSM error code is available

• gsmErrorName — the symbolic name of the code (e.g. REACHABLE, ABSENT_SUBSCRIBER), or null

• gsmErrorDescription — a plain-language description of the code

response values

Value	Description	Action
0	Success	✈️
1	General error	Repeating the request won't yield a different result
2	Pricing not set	Contact [e-mail]
3	Out of balance	Contact [e-mail]
4	Throttled	Contact [e-mail]
5	Invalid number	Number length not valid
6	Not resolved	Number cannot be resolved due to missing coverage
7	Timeout	Number cannot be resolved due to timeout
8	Missing permissions	Contact [e-mail]

GSM error codes

diagnostic.gsmError is populated for Live results and drives the availability fields as follows:

Code	Name	Status	Condition	Reason	Description
0	REACHABLE	Available	Active	Number is reachable.	The number appears to be active and reachable on the mobile network.
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.
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.
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.
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.
13	CALL_BARRED	Unavailable	Temporary	Service is barred.	The number may exist, but the requested service is currently blocked or restricted by the operator.
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.
27	ABSENT_SUBSCRIBER	Unavailable	Temporary	Subscriber is temporarily unreachable.	The number appears to exist, but the subscriber is currently not reachable on the network.
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.
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.
34	SYSTEM_FAILURE	Uncertain	Unknown	Network system failure.	The network or lookup provider returned a system failure. The subscriber status could not be confirmed.
36	UNEXPECTED_DATA_VALUE	Uncertain	Unknown	Unexpected network response.	The network returned an unexpected value, so the subscriber status could not be reliably interpreted.
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.
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.
39	IMSI_BLACKLISTED	Unavailable	Permanent	Subscriber identity is blacklisted.	The subscriber identity is blocked or blacklisted. The number should not be treated as reachable.
40	DEST_ADDRESS_BLACKLISTED	Unavailable	Permanent	Destination number is blacklisted.	The destination number is blocked or blacklisted and should not be contacted.
41	TIME_OUT	Uncertain	Unknown	Lookup timed out.	The lookup did not complete within the expected time. The subscriber status could not be confirmed.
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.
100	GENERAL_ERROR	Uncertain	Unknown	General processing error.	A general error occurred during processing. The subscriber status could not be confirmed.
200	EQUIPMENT_PROTOCOL_ERROR	Uncertain	Unknown	Network protocol error.	A technical protocol error occurred between network systems. The subscriber status could not be confirmed.
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.
202	CONGESTION_ERROR	Uncertain	Temporary	Network congestion.	The network is congested or temporarily overloaded. The lookup should be retried later.
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.
204	INITIATING_RELEASE	Uncertain	Unknown	Network released the request.	The network released the request before a clear subscriber status was returned.
205	POTENTIAL_VERSION_INCOMPATIBILITY	Uncertain	Unknown	Network compatibility issue.	A compatibility issue occurred between network systems. The subscriber status could not be confirmed.
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.
207	MTP_FAILURE	Uncertain	Temporary	Network transport failure.	A signalling transport failure occurred in the network. The lookup may succeed if retried later.
208	NETWORK_CONGESTION	Uncertain	Temporary	Network congestion.	The network is temporarily congested. The lookup should be retried later.
209	SIGNALLING_FAILURE	Uncertain	Temporary	Network signalling failure.	A signalling failure occurred in the mobile network. The lookup may succeed if retried later.
210	ABNORMAL_MAP_DIALOG	Uncertain	Unknown	Abnormal network dialogue.	The network session ended abnormally, so the subscriber status could not be confirmed.
211	INVALID_PDU_FORMAT	Uncertain	Unknown	Invalid network message format.	The network rejected the request format. The subscriber status could not be confirmed.
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.
301	VALIDITY_PERIOD_EXPIRED	Uncertain	Temporary	Request validity expired.	The request expired before a final network result was received. A retry may be required.

The DATABASE_SOURCE code (9999) is never returned as a gsmError value — 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.

Authorizations

default

X-API-KEYstringRequired

Body

application/json

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.

msisdnstring[] · max: 100Optional

A list of MSISDNs to validate. Mutually exclusive with records.

country_isostringOptional

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

metadatastringOptional

Optional client reference echoed back on every result. Applies to the msisdn array form; for records use the per-record metadata field instead.

callback_urlstring · uriOptional

Optional URL to receive an asynchronous callback with the results. When provided, the endpoint responds with 202 and { "id": "<uuid>" }, then POSTs { "id": "<uuid>", "data": [ ... ] } to this URL once processing completes.

Responses

200

200

application/json

datestringRequiredExample: 2026-06-12T05:06:46.359Z

msisdnstringRequiredExample: 447459100106

normalizedMsisdnstringOptionalExample: 447459100106

metadatastringOptional

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

costnumberOptionalExample: 0.005

responseintegerRequiredExample: 0

portedbooleanOptionalExample: true

202

Accepted — the request is being processed asynchronously. Returned only when callback_url is supplied; the results are POSTed to that URL as { "id": "<uuid>", "data": [ ... ] } once ready.

application/json

401

401

text/plain

500

500

text/plain

post/enterprise/contact-intelligence

HTTPcURLJavaScriptPython

POST /enterprise/contact-intelligence HTTP/1.1
Host: cleansing-api.bind.hr
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 79

{
  "records": [
    {
      "msisdn": "447459100106",
      "metadata": "ref-001",
      "country_iso": "GB"
    }
  ]
}

Records with metadata and per-record countryMSISDN array with callbackMSISDN array with default country

[
  {
    "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"
    }
  }
]