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"
}