Anrufernamen abfragen

Rufen Sie einen verfügbaren Anrufernamen für eine Telefonnummer ab. Dies ist eine Abfrage im Produktivbetrieb, die Ihr Konto belasten kann, auch wenn das Ergebnis aus dem Zwischenspeicher des Dienstes stammt. Sie ändert nicht den bei ausgehenden Anrufen angezeigten Namen einer Nummer, die Ihnen gehört.

Ein zurückgegebener Name ist kein Nachweis für Identität, Inhaberschaft oder die Erlaubnis, anzurufen. Namen können fehlen, veraltet oder abgekürzt sein; auch geografische Bezeichnungen oder die Telefonnummer können als Ersatzwert erscheinen.

Anfrage

Verwenden Sie Ihr freigeschaltetes API-Konto von der dafür zugelassenen Quell-IP-Adresse aus. Bewahren Sie Zugangsdaten in einem serverseitigen Geheimnisspeicher auf. Das Beispiel verwendet Umgebungsvariablen und eine fiktive nordamerikanische Nummer; hinterlegen Sie Zugangsdaten weder in URLs noch in öffentlich zugänglichem Browsercode.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  https://api.multitel.net/v3/cnam/12025550123

Geben Sie die vollständige Nummer einschließlich Ländervorwahl als Ziffernfolge an, beispielsweise elf Ziffern beginnend mit 1 für Nordamerika. Verlassen Sie sich nicht darauf, dass die Verarbeitungsroutine Satzzeichen oder ein Pluszeichen normalisiert. Weder ein Anfragekörper noch eine Regionsauswahl ist erforderlich. Klären Sie mit MultiTEL, welche Abdeckung für Ihren vorgesehenen Einsatz unterstützt wird.

Antwort

Die Werte dienen nur der Veranschaulichung; die Kostenangabe ist kein Preisangebot.

{
  "status": {
    "code": 200,
    "msg": ""
  },
  "response": {
    "number": "12025550123",
    "name": "EXAMPLE NAME",
    "cost": 0.0037,
    "balance": 9.9963
  }
}

Felder der Anrufernamensabfrage
Feld	Bedeutung
number	Die abgefragte Nummer.
name	Der verfügbare Name oder Ersatztext. Dies ist keine Identitätsprüfung.
cost	Der für das Konto beziehungsweise den Dienst konfigurierte Abfragepreis, den dieser Verarbeitungspfad meldet. Verwenden Sie den aktuellen Kontotarif und nicht den Beispielwert.
balance	Das für die Antwort berechnete Guthaben. Dies ist keine neue transaktionale Abfrage des Kontoguthabens.

Gebühren und Abgleich

Ergebnisse mit Namen werden zum für das Konto konfigurierten CNAM-Preis berechnet. Eine wiederholte oder aus dem Zwischenspeicher beantwortete Abfrage kann eine weitere Gebühr auslösen; ein Idempotenzschlüssel wird nicht bereitgestellt. Prüfen Sie den aktuellen Kontotarif, bevor Sie automatisierte Abfragen aktivieren.

Bei einem leeren Namen im Zwischenspeicher besteht eine bekannte Einschränkung der Antwort: Die Verarbeitungsroutine kann den API-Code 200 mit einem leeren Namen, Kosten ungleich null und einem verringerten berechneten Guthaben zurückgeben, obwohl dieser Verarbeitungszweig das Konto nicht belastet. Betrachten Sie diese Antwort allein nicht als Beleg für eine Abbuchung. Gleichen Sie das Ergebnis mit den Abrechnungsdaten des Kontos und einer neuen Guthabenabfrage ab, und wenden Sie sich bei unklaren Ergebnissen an den Support.

Die Prüfung des vorausbezahlten Guthabens erfordert derzeit vor der Abfrage ein Guthaben von mindestens 0.004, unabhängig vom konfigurierten Preis pro Abfrage. Ein Konto mit deaktivierten Käufen wird ebenfalls abgewiesen. Diese Prüfungen machen diesen Endpunkt nicht zu einer API für Preisangebote oder Ausgabenlimits.

Fehler und Wiederholungsversuche

Prüfen Sie sowohl den HTTP-Status als auch status.code/status.msg in JSON. Der API-Code 403 kann auf unzureichendes vorausbezahltes Guthaben, untersagte Käufe, ein Problem mit der Kontoberechtigung oder einen nicht gefundenen Anrufernamen hinweisen. Der Verarbeitungspfad ohne gefundenen Namen kann den Code als Zeichenfolge zurückgeben. Prüfen Sie die Meldung, anstatt jeden Code 403 als Hinweis auf falsche Zugangsdaten zu behandeln. Konfigurationskonflikte können den API-Code 500 zurückgeben.

Nach einer kostenpflichtigen Abfrage kann eine Zeitüberschreitung auftreten. Verwenden Sie eine begrenzte Anzahl von Wiederholungsversuchen mit zunehmenden Wartezeiten nur dann, wenn dies für Ihre Anwendung geeignet ist, und gleichen Sie zuerst Versuche mit ungewissem Ausgang ab. Wiederholen Sie Anfragen für eine abgewiesene Nummer oder bei Fehlern aufgrund von Kontoberechtigungen oder Guthaben nicht immer wieder. Ein Antwortzwischenspeicher in Ihrer eigenen Anwendung kann wiederholte Anfragen reduzieren, soweit dies Ihre Vereinbarung und Ihre Anforderungen an die Genauigkeit zulassen.

Weitere Vorgänge für Telefonnummern

Dieser Lesevorgang ist von einer Aktualisierung des Namens für ausgehende Anrufe beziehungsweise der LIDB, einem Verzeichniseintrag oder einer Anruferregistrierung getrennt. Für diese Vorgänge gelten eigene Pflichtfelder, Berechtigungen und Gebühren. Verwenden Sie die Zuteilungsabdeckung zur Prüfung der Vorwahltabelle oder die Nummernsuche für den bestellbaren Nummernbestand. Keiner dieser Vorgänge bestätigt, dass ein Anrufer die Person ist, für die er sich ausgibt.