# Call Lookup

Identifies publicly available information (such as name, address, etc.) based on a phone number. This is especially useful for recognizing incoming calls in systems such as:

* Telephony systems
* CRMs
* Helpdesk systems

## Authentication with API Key

To access the API, an API key is required.

{% stepper %}
{% step %}

### Obtaining the API Key

The API key is provided after successful onboarding.
{% endstep %}

{% step %}

### Using the API Key in the request

The API key must be included in the header of each request.

Example:

{% code overflow="wrap" %}

```json
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"}}}}}}}}}
```

## Parameters

<table><thead><tr><th width="144.58203125">Parameter</th><th width="88.16796875">Type</th><th width="289.94921875">Description</th><th>Example</th></tr></thead><tbody><tr><td><code>number</code></td><td>string</td><td>The phone number in local format (without country code) or in E.164 format (with +)</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 of the returned phone number:</p><ul><li><code>1</code> = Local format (without country code)</li><li><code>2</code> = E.164 (with + and country code)</li></ul></td><td><code>1</code> = <code>0791234567</code><br><code>2</code> = <code>+41791234567</code></td></tr></tbody></table>

## Response Fields

### Root-Level Fields

<table><thead><tr><th width="145">Field</th><th width="88">Type</th><th width="290">Description</th><th>Example</th></tr></thead><tbody><tr><td><code>hitCount</code></td><td>integer</td><td>Total number of matches in the database for the requested phone number</td><td><code>1</code></td></tr><tr><td><code>resultCount</code></td><td>integer</td><td>Number of entries actually returned in the <code>data</code> array</td><td><code>1</code></td></tr><tr><td><code>data</code></td><td>array</td><td>Array containing the found directory entries</td><td>see Entry Fields below</td></tr></tbody></table>

### Entry Fields

<table><thead><tr><th width="145">Field</th><th width="88">Type</th><th width="290">Description</th><th>Example</th></tr></thead><tbody><tr><td><code>dwhId</code></td><td>string</td><td>Unique ID of the entry</td><td><code>ABC123456789</code></td></tr><tr><td><code>companyname</code></td><td>string</td><td>Company name for business entries</td><td><code>Swisscom Directories AG</code></td></tr><tr><td><code>firstname</code></td><td>string</td><td>First name for private individuals</td><td><code>Lara</code></td></tr><tr><td><code>name</code></td><td>string</td><td>Last name for private individuals</td><td><code>Graf</code></td></tr><tr><td><code>street</code></td><td>string</td><td>Street name</td><td><code>Förrlibuckstrasse</code></td></tr><tr><td><code>houseNumber</code></td><td>string</td><td>House number</td><td><code>62</code></td></tr><tr><td><code>zip</code></td><td>string</td><td>Postal code</td><td><code>8005</code></td></tr><tr><td><code>location</code></td><td>string</td><td>City/Town name</td><td><code>Zürich</code></td></tr><tr><td><code>phoneNumbers</code></td><td>array</td><td>Array with one or more landline numbers</td><td><p><code>[</code></p><p><code>“*0800 123 456",</code></p><p><code>"*058 123 45 67"</code></p><p><code>]</code> </p></td></tr><tr><td><code>mobileNumbers</code></td><td>array</td><td>Array with one or more mobile numbers</td><td><p><code>[</code></p><p><code>“*079  123 45 67"</code></p><p><code>]</code></p></td></tr></tbody></table>

## Requirements for Successful Results

The provided phone number must be listed in our public directories (local.ch or search.ch) and enabled for reverse lookup.

### Notes

#### Phone Numbers as Arrays

* `phoneNumbers` and `mobileNumbers` are always arrays, even with only one number
* Empty arrays `[]` indicate that no numbers of this type are available

### Handling Multiple Entries

A phone number can have multiple entries (e.g., multiple people in one household or different departments of a company). When multiple entries are returned (resultCount > 1), we recommend the following display logic for integration:

#### Option 1: Display First Entry

The first entry in the data array is typically the main entry and is suitable for simple display in telephone systems.

#### **Option 2:** Offer All Entries

For advanced integrations, all returned entries can be displayed in a dropdown list or as selectable options.

#### Example: Output with Multiple Entries

```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": [
          "*079 123 45 67"
        ]
      },
      {
        "dwhId": "CBA0987654321",
        "companyname": "",
        "firstname": "Lara",
        "name": "Graf",
        "street": "Förrlibuckstrasse",
        "houseNumber": "62",
        "zip": "8005",
        "location": "Zürich",
        "phoneNumbers": [],
        "mobileNumbers": [
          "*079 123 45 67"
        ]
      }
    ]
  }
}
```