Anruferkennung: Kunden per API nach Rufnummer und Name suchen

Mit der Anruferkennung zeigt Ihre Telefonanlage bei einem Anruf direkt den passenden Kunden aus CATAMA an. Die Anlage fragt CATAMA im Moment des Anrufs ab. Eine Kopie Ihres Kundenstamms beim Telefonie-Anbieter ist dafür nicht nötig.

Schlüssel erzeugen

  1. Öffnen Sie die Systemeinstellungen und wechseln Sie zum Bereich API.
  2. Klappen Sie Anruferkennung auf.
  3. Klicken Sie auf Schlüssel erzeugen.
  4. Kopieren Sie den Schlüssel und geben Sie ihn an Ihren Telefonie-Anbieter weiter. Er wird nur dieses eine Mal angezeigt.

Diesen Bereich sehen nur Administratoren. Der Schlüssel gilt ausschließlich für die Kundensuche. Mit Schlüssel zurückziehen sperren Sie ihn sofort. Erzeugen Sie einen neuen Schlüssel, wird der bisherige ungültig.

Suche nach Rufnummer

GET https://IHRE-INSTANZ/api/customers/search?phone=%2B493023125000&token=SCHLUESSEL

Durchsucht werden Telefon privat, Telefon geschäftlich und Mobil. Die Schreibweise spielt keine Rolle: +49, 0049 und die nationale Form mit 0 finden denselben Kunden, ebenso Nummern mit Leerzeichen, Bindestrich, Schrägstrich oder Klammern. Das Plus schreiben Sie in der Adresse am besten als %2B, ein unkodiertes + wird aber ebenfalls erkannt.

Enthält ein Feld zwei Nummern, zum Beispiel durch Komma oder „oder“ getrennt, werden beide gefunden. Ist eine Nummer in CATAMA ohne Vorwahl gespeichert, wird sie nicht gefunden.

Suche nach Name

GET https://IHRE-INSTANZ/api/customers/search?name=Mustermann&token=SCHLUESSEL

Durchsucht werden Nachname, Vorname, Firma und Kundennummer. Geben Sie mindestens zwei Zeichen an. Bei mehreren Wörtern muss jedes Wort vorkommen. Sind beide Parameter gesetzt, gilt die Rufnummer.

Antwort

Sie erhalten höchstens zehn Treffer. Gelöschte Kunden erscheinen nicht. Gesperrte und inaktive Kunden erkennen Sie an locked und active. Bankdaten, Geburtstag und Fahrzeuge sind nicht enthalten.

{
  "data": [
    {
      "id": 4711,
      "customer_number": "K-10023",
      "title": "Herr",
      "company": "Musterbau GmbH",
      "forename": "Max",
      "lastname": "Mustermann",
      "zip": "10115",
      "city": "Berlin",
      "phone_primary": "030 / 2312 5000",
      "phone_mobile": "0171 1234567",
      "phone_secondary": "",
      "email_primary": "max@example.com",
      "active": 1,
      "locked": 0,
      "url": "https://IHRE-INSTANZ/?crm_customer_id=4711"
    }
  ],
  "status": 1,
  "message": "Success"
}

Das Feld url öffnet die Kundenakte direkt. Wer noch nicht angemeldet ist, landet nach der Anmeldung in der Akte. Haben Sie in den Systemeinstellungen einen eigenen Login-Pfad festgelegt, funktioniert der Link nur, wenn Sie bereits angemeldet sind.

Grenzen und Fehler

  • Abfragen: 120 je Minute und Schlüssel.
  • 400: Weder phone noch name angegeben.
  • 401: Schlüssel falsch oder zurückgezogen.
  • 429: Zu viele Abfragen. Der Header Retry-After nennt die Wartezeit in Sekunden.

Statt in der Adresse können Sie den Schlüssel auch im Header Authorization: Bearer SCHLUESSEL übergeben. So taucht er nicht in Server-Logs auf.

Die technische Beschreibung aller Kunden-Endpunkte finden Sie im Artikel API Dokumentation – Kunden.

Ähnliche Artikel