# 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

## Authentifizierung mit API-Key

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

{% stepper %}
{% step %}

### API-Key erhalten

Der API-Key wird nach erfolgreichem [Onboarding](https://www.multisource.ch/call-lookup-start) von uns bereitgestellt.
{% endstep %}

{% step %}

### API-Key im Request verwenden

Der API-Key muss bei jedem Request im Header übermittelt werden.

Beispiel: 

{% code overflow="wrap" %}

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

{% endcode %}
{% endstep %}
{% endstepper %}

## 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"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints","name":"auth-key","in":"header"}},"schemas":{"Phoneformat":{"type":"integer","default":1},"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","schema":{"type":"string"}},{"name":"outputFormat","in":"query","schema":{"$ref":"#/components/schemas/Phoneformat"}}],"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>integer</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></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 Eintragsfelder unten</td></tr></tbody></table>

### Eintrags-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>“+4158123456",</code></p><p><code>"+41581234567"</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>

## 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.

### Hinweise

#### **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"
        ]
      }
    ]
  }
}
```