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

* The API key is provided after successful onboarding.
* The API key must be included in the header of each request.

Example:

{% 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"}}}}}}}}}
```

## 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 output fields below</td></tr></tbody></table>

### Output 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>“*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 with one or more mobile numbers</td><td><p><code>[</code></p><p><code>“*0791234567"</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.

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

## Metrics & Usage

**Monitor your usage** Use the `metrics/usage` endpoint to retrieve the number of requests sent and data elements returned for this module – broken down by time period. [**Learn more**](/multisource-integration-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-integration-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.