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. The format is almost arbitrary - 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.

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 skills

FeatureDescription
FEATURE_UNSPECIFIEDNot specified.
REVOCATIONIf this feature is supported, you can revoke a sent message before it has been delivered.
RICHCARD_STANDALONEStandalone Rich Cards
RICHCARD_CAROUSELCarousel of Rich Cards
ACTION_CREATE_CALENDAR_EVENTThe suggested action for creating a calendar event.
ACTION_DIALSuggested action for dialing a number.
ACTION_OPEN_URLThe suggested action for opening a URL.
ACTION_SHARE_LOCATIONSuggested action to share the location.
ACTION_VIEW_LOCATIONSuggested 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.

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 an entry is not stored for every telephone number. As the data is collected from various sources, geographical locations, company names/names or the network operator are sometimes 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,
    "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"
    }
} %