Number Check

The number check endpoint validates and enriches a phone number with formatting, network, and operator data. The connectionType provided in the request determines what type of data to be retrieved.

hlr: A Home Location Register lookup. Returns real-time network status, including whether the number is active and whether the subscriber is currently roaming, along with static data derived from the phone number.
mnp: A Mobile Number Portability lookup. Returns ported status including data about the ported-to operator, along with static data derived from the phone number.
static: No lookup conducted. Returns static data derived from the phone number itself. This is the default.

Request

URL

POST https://api.cm.com/number-validation/v1/number/check

Headers

Content-Type: application/json
Authorization: Bearer GENERATED_TOKEN_HERE

Body

{
    "phoneNumber": "+31612345678",
    "connectionType": "hlr"
}

Parameters

Property	Type	Required	Description
phoneNumber	string	Yes	The phone number to check. Must start with a `+`.
connectionType	string	No	The type of connection to use when retrieving the data. Possible values are `static`, `hlr`, and `mnp`. Defaults to `static`.

Response

Depending on the connectionType provided in the request, some fields may be null if unknown.

{
    "format": {
        "e164": "+31612345678",
        "international": "+31 6 12345678",
        "national": "06 12345678",
        "rfc3966": "tel:+31-6-12345678"
    },
    "type": "mobile",
    "country": "Netherlands",
    "callingCode": 31,
    "regionCode": "nl",
    "operator": "Vodafone",
    "mcc": "204",
    "mnc": "04",
    "source": "hlr",
    "roaming": null,
    "isValid": true,
    "isActive": true,
    "isPorted": null
}

Parameters

Property	Example	Description
format	{ "e164": "+31612345678", ... }	The phone number in various formats, including `e164`, `international`, `national`, and `rfc3966`.
type	mobile	The type of phone number. Possible values: `mobile`, `fixed_line`, `fixed_line_or_mobile`, `toll_free`, `premium_rate`, `shared_cost`, `voip`, `personal_number`, `pager`, `uan`, `voicemail`, `unknown`.
country	Netherlands	The country associated with the phone number.
callingCode	31	The international calling code of the country.
regionCode	nl	The ISO 3166-1 alpha-2 code.
operator	Vodafone	The name of the network operator.
mcc	204	The Mobile Country Code of the operator.
mnc	04	The Mobile Network Code of the operator.
source	hlr	The source of the returned data. Possible values: `hlr`, `mnp`, `prefix`, `external`, `mnp_database`, `static`.
roaming	{ "country": "Germany", ... }	Roaming details. Only present when the subscriber is currently roaming (HLR only). `null` if not roaming. See Roaming for the object structure.
isValid	true	Whether the phone number is a valid number.
isActive	true	Whether the number is currently active on the network. Only available for `hlr`.
isPorted	false	Whether the number has been ported to another operator. Only available for `mnp`.

Roaming

When the subscriber is currently roaming and connectionType was hlr, the roaming field contains details about the visited network:

{
  "roaming": {
    "country": "Germany",
    "callingCode": 49,
    "regionCode": "de",
    "operator": "T-Mobile DE",
    "mcc": "262",
    "mnc": "01"
  }
}

Property	Example	Description
country	Germany	The country the subscriber is currently roaming in.
callingCode	49	The international calling code of the roaming country.
regionCode	de	The ISO 3166-1 alpha-2 code of the roaming country..
operator	T-Mobile DE	The name of the roaming network operator.
mcc	262	The Mobile Country Code of the roaming operator.
mnc	01	The Mobile Network Code of the roaming operator.