Lookup

You can use this endpoint to format and check phone numbers. Check a phone number for validity, which mobile network a phone number belongs to, format a phone number in national and international format or check whether a phone number exists and is logged into the mobile network.

Parameters

All the queries listed below only require the phone number as a parameter:

Name
number
Type
string
Description
The number to be queried. Multiple numbers must be separated by commas. You can enter almost any format - our API automatically formats the number correctly.

GET/api/lookup/format

Format

Query the national and international format of any mobile phone number. You will also receive information about the network operator associated with the number (without porting information).

Inquiry

GET

/api/lookup/format

curl "https://gateway.seven.io/api/lookup/format?number=4917612345678" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Response

{
    "success": true,
    "national": "0176 12345678",
    "international": "+4917612345678",
    "international_formatted": "+49 176 12345678",
    "country_name": "Germany",
    "country_code": "49",
    "country_iso": "DE",
    "carrier": "O2",
    "network_type": "mobile"
}

GET/api/lookup/rcs

RCS capabilities

You can use this endpoint to query the RCS capability of a phone number. Before sending an RCS, you should always query the capabilities of a phone number first and cache the result if necessary.

Agents who have not yet been activated can only query the capabilities of the stored test numbers.

Optional parameters

Name
from
Type
string
Description
To check the RCS capabilities of a phone number, the respective agent identifier is always required. By default, our API uses the first RCS sender ID in your account. You can use a different agent with this parameter.

Request

GET

/api/lookup/rcs

curl "https://gateway.seven.io/api/lookup/rcs?number=4917612345678" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Response

{
  "success": true,
  "national": "0176 12345679",
  "international": "+49176123456789",
  "international_formatted": "+49 179 123456789",
  "country_name": "Germany",
  "country_code": "49",
  "country_iso": "DE",
  "carrier": "O2",
  "network_type": "mobile",
  "rcs_capabilities": [
    "RICHCARD_STANDALONE",
    "ACTION_CREATE_CALENDAR_EVENT",
    "ACTION_DIAL",
    "ACTION_OPEN_URL",
    "ACTION_SHARE_LOCATION",
    "ACTION_VIEW_LOCATION",
    "RICHCARD_CAROUSEL"
  ]
}

Overview of all features

Feature	Description
`FEATURE_UNSPECIFIED`	Not specified.
`REVOCATION`	If this feature is supported, you can revoke a sent message before it has been delivered.
`RICHCARD_STANDALONE`	Standalone Rich Cards
`RICHCARD_CAROUSEL`	Carousel of Rich Cards
`ACTION_CREATE_CALENDAR_EVENT`	The suggested action for creating a calendar event.
`ACTION_DIAL`	Suggested action for dialing a number.
`ACTION_OPEN_URL`	The suggested action for opening a URL.
`ACTION_SHARE_LOCATION`	Suggested action to share the location.
`ACTION_VIEW_LOCATION`	Suggested action to view a location in a map app.

GET/api/lookup/hlr

HLR

Get detailed information about a mobile phone number via a query in the HLR database. The query is possible for numbers from almost all countries/networks worldwide.

It can happen that the roaming query returns "No roaming" even though the number is in roaming. This usually means that home routing has been activated with the network operator. Home routing ensures that the network reports the number as being at home, regardless of where it is currently located.

Request

GET

/api/lookup/hlr

curl "https://gateway.seven.io/api/lookup/hlr?number=4917612345678" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Response

{
    "status": true,
    "status_message": "success",
    "lookup_outcome": true,
    "lookup_outcome_message": "success",
    "international_format_number": "4917612345678",
    "international_formatted": "+49 176 12345678",
    "national_format_number": "0176 12345678",
    "country_code": "DE",
    "country_name": "Germany",
    "country_prefix": "49",
    "current_carrier":
    {
        "network_code": "26207",
        "name": "Telefonica Germany GmbH & Co. OHG",
        "country": "DE",
        "network_type": "mobile"
    },
    "original_carrier":
    {
        "network_code": "26207",
        "name": "Telefonica Germany GmbH & Co. OHG",
        "country": "DE",
        "network_type": "mobile"
    },
    "valid_number": "valid",
    "reachable": "unknown",
    "ported": "assumed_not_ported",
    "roaming": "not_roaming",
    "gsm_code": null,
    "gsm_message": null
}

GET/api/lookup/mnp

MNP

Use our MNP (Mobile Number Ported) API to query the network operator of any international phone number.

Inquiry

GET

/api/lookup/mnp

curl "https://gateway.seven.io/api/lookup/mnp?number=4917612345678" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Response

{
    "success": true,
    "code": 100,
    "price": 0.005,
    "mnp":
    {
        "country": "DE",
        "number": "+4917612345678",
        "national_format": "0176 12345678",
        "international_formatted": "+49 176 12345678",
        "network": "Telekom Deutschland GmbH",
        "mccmnc": "26201",
        "isPorted": true,
        "network_type": "mobile"
    }
}

GET/api/lookup/cnam

CNAM

You can use CNAM Lookup to query the caller ID name for any telephone number worldwide. Please note that there may not be an entry for every telephone number. Since the data is compiled from various sources, geographical locations, company names or the network operator may be stored here.

Inquiry

GET

/api/lookup/cnam

curl "https://gateway.seven.io/api/lookup/cnam?number=4917612345678" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Response

{
	"success": "true",
	"code": "100",
	"number": "4917612345678",
	"name": "GERMANY"
}

Coverage

CNAM is originally a North American network feature. For numbers within the NANP (country code +1), the caller ID name is maintained by the carriers themselves, so the returned name is usually the actual subscriber - a person's name or a company name.

There is no equivalent network-side name database outside the NANP. Our data is compiled from various sources, so for international numbers the response is often a geographical designation (as in the example above: GERMANY), a company name where one is publicly available, or the network operator. An international lookup therefore almost always returns a value, but that value is not necessarily a subscriber name.

We do not publish a fixed hit rate: it depends heavily on your country mix and on the type of numbers you look up (landline, mobile, business). If the quality matters for your use case, run a representative sample of your own number pool first and evaluate the name values you get back.

Behaviour when no entry exists

If the data source returns no result - or is unavailable - the entry in the response contains only the error code, without success, number or name:

Response without a result

{
	"code": "600"
}

Always check for success before reading name instead of relying on the field being present.

Code	Meaning
`100`	Lookup successful, `name` contains the caller ID name.
`202`	The number is invalid and could not be looked up. Not charged.
`500`	Insufficient balance.
`600`	The lookup returned no result or the data source was unavailable.

Billing and batch queries

Every lookup of a valid number is charged, regardless of whether a name is found. Only invalid numbers (code 202) are free of charge.

Numbers passed in one request are looked up sequentially, and each individual query has a timeout of five seconds. Keep your batches small enough for your own HTTP timeout, and split large volumes across parallel requests instead of one long list. Duplicate numbers within a request are only looked up - and only charged - once.

Since caller ID names rarely change, we recommend caching the results on your side rather than looking up the same number repeatedly.