Lookup

Mit diesem Endpunkt können Sie Rufnummern formatieren und überprüfen. Überprüfen Sie eine Rufnummer auf Validität, zu welchen Mobilfunknetz eine Rufnummer gehört, formatieren Sie eine Rufnummer im nationalen und internationalen Format oder prüfen Sie, ob eine Rufnummer existiert und ins mobile Netz eingebucht ist.

Parameter

Alle unten genannten Abfragen benötigen lediglich die Rufnummer als Parameter:

Format

Fragen Sie das nationale und internationale Format beliebiger Mobilrufnummern ab. Zusätzlich erhalten Sie als Information den zugehörigen Netzbetreiber zu der Rufnummer (ohne Portierungsinformationen).

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

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

RCS Fähigkeiten

Über diesen Endpunkt können Sie die RCS Fähigkeit einer Rufnummer abfragen. Vor Versand einer RCS sollten Sie zunächst immer die Fähigkeiten einer Rufnummer abfragen und das Ergebnis gegebenenfalls zwischenspeichern.

Optionale Parameter

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

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

Übersicht aller Fähigkeiten

HLR

Erhalten Sie über eine Abfrage in der HLR Datenbank ausführliche Informationen zu einer Mobilfunknummer. Die Abfrage ist für Nummern aus fast allen Ländern/Netzen weltweit möglich.

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

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

MNP

Fragen Sie über unsere MNP (Mobile Number Ported) API den Netzbetreiber einer beliebigen, internationalen Rufnummer ab.

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

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

CNAM

Per CNAM Lookup können Sie den Caller ID Namen zu beliebigen Rufnummern weltweit abfragen. Bitte beachten Sie, dass nicht zu jeder Rufnummer ein Eintrag hinterlegt ist. Da die Daten aus verschiedensten Quellen zusammengetragen werden, sind hier teils geographische Standorte, Firmennamen/Namen oder der Netzbetreiber hinterlegt.

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

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

Abdeckung

CNAM ist ursprünglich ein nordamerikanisches Netzmerkmal. Für Rufnummern innerhalb des NANP (Ländervorwahl +1) pflegen die Netzbetreiber den Caller ID Namen selbst, der zurückgegebene name ist dort in der Regel der tatsächliche Anschlussinhaber – also ein Personen- oder Firmenname.

Außerhalb des NANP gibt es keine vergleichbare netzseitige Namensdatenbank. Die Daten werden aus verschiedensten Quellen zusammengetragen, deshalb enthält die Antwort bei internationalen Rufnummern häufig eine geographische Bezeichnung (wie im Beispiel oben: GERMANY), einen öffentlich verfügbaren Firmennamen oder den Netzbetreiber. Eine internationale Abfrage liefert also fast immer einen Wert, dieser Wert ist aber nicht zwingend ein Anschlussinhaber.

Verhalten ohne Eintrag

Liefert die Datenquelle kein Ergebnis oder ist sie nicht erreichbar, enthält der Eintrag in der Antwort nur den Fehlercode – ohne success, number und name:

{
	"code": "600"
}

Prüfen Sie deshalb immer auf success, statt sich darauf zu verlassen, dass das Feld name vorhanden ist.

Abrechnung und Sammelabfragen

Mehrere Rufnummern in einer Anfrage werden nacheinander abgefragt, jede einzelne Abfrage hat ein Timeout von fünf Sekunden. Wählen Sie Ihre Sammelabfragen deshalb so klein, dass sie in Ihr eigenes HTTP-Timeout passen, und verteilen Sie große Volumina auf parallele Anfragen statt auf eine lange Liste. Doppelte Rufnummern innerhalb einer Anfrage werden nur einmal abgefragt und auch nur einmal berechnet.

Da sich Caller ID Namen selten ändern, empfehlen wir, die Ergebnisse auf Ihrer Seite zu cachen, statt dieselbe Rufnummer wiederholt abzufragen.