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

* 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: 

{% 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 = Local","2 = E164"],"type":"string","description":"**Allowed values:**\n- `1` = `Local`\n- `2` = `E164`","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>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>

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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://multisource.gitbook.io/multisource-api/integration/call-lookup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.