> For the complete documentation index, see [llms.txt](https://multisource.gitbook.io/multisource-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://multisource.gitbook.io/multisource-api/integration/call-lookup.md).

# Call Lookup

Call Lookup ermittelt basierend auf einer Telefonnummer die dazugehörigen öffentlich publizierten Angaben (Name, Adresse etc.). Dies ist besonders nützlich für die Erkennung eingehender Anrufe in Systemen wie:

* Telefonieanlagen
* CRMs
* Helpdesk-Systemen

## Integrationen / Templates

Fertige Vorlagen – direkt einsetzbar, ohne eigene Entwicklung.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><strong>3CX</strong></td><td>Serverseitige CRM-Vorlage – Anrufer-Erkennung direkt im 3CX Web Client, Desktop- und Mobile-App.</td><td><a href="/pages/ryf9ki9AYYC37S7LAikc">/pages/ryf9ki9AYYC37S7LAikc</a></td><td data-object-fit="cover"><a href="/files/XpsJZzuFjXpZ4x1xT8jK">/files/XpsJZzuFjXpZ4x1xT8jK</a></td></tr><tr><td><strong>Weitere Integrationen folgen.</strong> </td><td></td><td></td><td></td></tr></tbody></table>

## Eigene Implementierung

Ihr System ist nicht dabei, oder Sie möchten Call Lookup direkt in eine eigene Anwendung einbinden? Die API lässt sich mit jedem System verbinden, das REST-Aufrufe unterstützt – die folgenden Abschnitte zeigen Authentifizierung, Endpoint und Response-Format im Detail.

### Authentifizierung mit API-Key

Für den Zugriff auf die API wird ein API-Key benötigt.

* Der API-Key wird nach erfolgreichem [Onboarding](https://www.multisource.ch/call-lookup-start) von uns bereitgestellt.
* Der API-Key muss bei jedem Request im Header übermittelt werden.

Beispiel:&#x20;

{% code overflow="wrap" %}

```http
curl --location 'https://api.multisource.ch/v2/search/calllookup?number=+41791234567' \
--header 'Auth-Key: <API-KEY>'
```

{% endcode %}

### API-Endpoint

## GET /search/calllookup

>

```json
{"openapi":"3.0.1","info":{"title":"multisource•api","version":"v2"},"tags":[{"name":"Search"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints.","name":"auth-key","in":"header"}},"schemas":{"SearchOutputOfListOfOutputCalllookup":{"type":"object","properties":{"hitCount":{"type":"integer","format":"int32"},"resultCount":{"type":"integer","format":"int32"},"data":{"type":"array","items":{"$ref":"#/components/schemas/OutputCalllookup"}}}},"OutputCalllookup":{"type":"object","properties":{"dwhId":{"type":"string","nullable":true},"companyname":{"type":"string","nullable":true},"firstname":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"houseNumber":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"category":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"email":{"type":"string"},"url":{"type":"string"},"phoneNumbers":{"type":"array","items":{"type":"string"},"nullable":true},"mobileNumbers":{"type":"array","items":{"type":"string"},"nullable":true}}}}},"paths":{"/search/calllookup":{"get":{"tags":["Search"],"parameters":[{"name":"number","in":"query","required":true,"schema":{"type":"string"}},{"name":"outputFormat","in":"query","description":"Optional.","schema":{"enum":[1,2],"type":"integer","description":"**Allowed values:**\n- `1` = `Local`\n- `2` = `E164`","format":"int32","default":1}},{"name":"format","in":"query","description":"Optional.","schema":{"type":"string","default":""}}],"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/SearchOutputOfListOfOutputCalllookup"}},"application/json":{"schema":{"$ref":"#/components/schemas/SearchOutputOfListOfOutputCalllookup"}},"text/json":{"schema":{"$ref":"#/components/schemas/SearchOutputOfListOfOutputCalllookup"}}}}}}}}}
```

### Parameter

<table><thead><tr><th width="145.41796875">Parameter</th><th width="88.2578125">Typ</th><th width="290.1484375">Beschreibung</th><th>Beispiel</th></tr></thead><tbody><tr><td><code>number</code></td><td>string</td><td>Die Telefonnummer im lokalen Format (ohne Ländervorwahl) oder im E.164-Format (mit +) </td><td><p><code>0791234567</code></p><p><code>+41791234567</code></p></td></tr><tr><td><code>outputFormat</code></td><td>string</td><td><p>Format der zurückgegebenen Telefonnummer:</p><ul><li><code>1</code> = Lokales Format (ohne Ländervorwahl)</li><li><code>2</code> = E.164 (mit + und Ländervorwahl)</li></ul></td><td><p><code>1</code> = <code>0791234567</code></p><p><code>2</code> = <code>+41791234567</code> </p></td></tr><tr><td><code>format</code></td><td>string</td><td><p>Ausgabeformat der Response:</p><ul><li><code>json</code> = Strukturierte Daten (Standard) – zur Weiterverarbeitung in der eigenen Applikation</li><li><code>html</code> = Fertig gerendertes HTML-Snippet</li></ul></td><td><code>json</code><br><code>html</code></td></tr></tbody></table>

### Response Felder

#### Root-Level Felder

<table><thead><tr><th width="145">Feld</th><th width="88.3046875">Typ</th><th width="290">Beschreibung</th><th width="227.31640625">Beispiel</th></tr></thead><tbody><tr><td><code>hitCount</code></td><td>integer</td><td>Gesamtanzahl der Treffer in der Datenbank für die angefragte Telefonnummer</td><td><code>1</code></td></tr><tr><td><code>resultCount</code></td><td>integer</td><td>Anzahl der tatsächlich zurückgegebenen Einträge im <code>data</code>-Array</td><td><code>1</code></td></tr><tr><td><code>data</code></td><td>array</td><td>Array mit den gefundenen Verzeichniseinträgen</td><td>siehe Ausgabefelder unten</td></tr></tbody></table>

#### Ausgabe-Felder

<table><thead><tr><th width="145">Feld</th><th width="88">Typ</th><th width="290">Beschreibung</th><th>Beispiel</th></tr></thead><tbody><tr><td><code>dwhId</code></td><td>string</td><td>Eindeutige ID des Eintrags</td><td><code>ABC123456789</code></td></tr><tr><td><code>companyname</code></td><td>string</td><td>Firmenname bei Unternehmenseinträgen</td><td><code>Swisscom Directories AG</code></td></tr><tr><td><code>firstname</code></td><td>string</td><td>Vorname bei Privatpersonen</td><td><code>Lara</code></td></tr><tr><td><code>name</code></td><td>string</td><td>Nachname bei Privatpersonen</td><td><code>Graf</code></td></tr><tr><td><code>street</code></td><td>string</td><td>Strassenname</td><td><code>Förrlibuckstrasse</code></td></tr><tr><td><code>houseNumber</code></td><td>string</td><td>Hausnummer</td><td><code>62</code></td></tr><tr><td><code>zip</code></td><td>string</td><td>Postleitzahl (PLZ)</td><td><code>8005</code></td></tr><tr><td><code>location</code></td><td>string</td><td>Ortsname</td><td><code>Zürich</code></td></tr><tr><td><code>phoneNumbers</code></td><td>array</td><td>Array mit einer oder mehreren Festnetznummern</td><td><p><code>[</code></p><p><code>“*08001234567",</code></p><p><code>"*0587654321"</code></p><p><code>]</code></p></td></tr><tr><td><code>mobileNumbers</code></td><td>array</td><td>Array mit einer oder mehreren Mobilnummern</td><td><p><code>[</code></p><p><code>“+41791234567"</code></p><p><code>]</code></p></td></tr></tbody></table>

#### Werbesperre-Kennzeichnung

Nummern, die mit einem vorangestellten Stern (`*`) ausgegeben werden (z. B. `*0791234567`), sind mit einer Werbesperre versehen. Der Inhaber hat der Nutzung seiner Nummer zu Werbezwecken widersprochen. Diese Nummern sollten nicht für Telefonwerbung verwendet werden. Der Stern ist aktuell Teil des Nummern-Strings und kein separates Feld – bei der Verarbeitung sollte er entsprechend berücksichtigt (geparst) werden.

## Voraussetzungen für erfolgreiche Ergebnisse

Die angegebene Telefonnummer muss in unseren öffentlichen Verzeichnissen (local.ch oder search.ch) eingetragen und für die Rückwärtssuche freigegeben sein.

### Telefonnummern als Arrays

* `phoneNumbers` und `mobileNumbers` sind immer Arrays, auch bei nur einer Nummer
* Leere Arrays `[]` bedeuten, dass keine Nummern dieser Art vorhanden sind

### Umgang mit mehreren Einträgen

Eine Telefonnummer kann mehrere Einträge haben (z.B. mehrere Personen in einem Haushalt oder verschiedene Abteilungen einer Firma). Wenn mehrere Einträge zurückgegeben werden (resultCount > 1), empfehlen wir folgende Anzeigelogik für die Integration:

#### Option 1: Ersten Eintrag anzeigen

Der erste Eintrag im data-Array ist in der Regel der Haupteintrag und eignet sich für eine einfache Anzeige im Telefoniesystem.

#### Option 2: Alle Einträge anbieten

Bei erweiterten Integrationen können alle zurückgegebenen Einträge in einer Dropdown-Liste oder als Auswahlmöglichkeit angezeigt werden.

#### Beispiel: Output mit mehreren Einträgen

```json
{
  "id": "123",
  "status": 200,
  "info": [],
  "result": {
    "hitCount": 2,
    "resultCount": 2,
    "data": [
      {
        "dwhId": "ABC1234567890",
        "companyname": "Swisscom Directories AG",
        "firstname": "",
        "name": "",
        "street": "Förrlibuckstrasse",
        "houseNumber": "62",
        "zip": "8005",
        "location": "Zürich",
        "phoneNumbers": [],
        "mobileNumbers": [
          "+41791234567"
        ]
      },
      {
        "dwhId": "CBA0987654321",
        "companyname": "",
        "firstname": "Lara",
        "name": "Graf",
        "street": "Förrlibuckstrasse",
        "houseNumber": "62",
        "zip": "8005",
        "location": "Zürich",
        "phoneNumbers": [],
        "mobileNumbers": [
          "+41791234567"
        ]
      }
    ]
  }
}
```

## Metrics & Usage

**Ihre Nutzung im Blick** Mit dem Endpoint `metrics/usage` können Sie jederzeit Ihre Anzahl Requests und zurückgelieferte Datensätze für dieses Modul abrufen – aufgeschlüsselt nach Zeitraum. [**Mehr erfahren**](/multisource-api/integration/metrics-and-usage.md)