> For the complete documentation index, see [llms.txt](https://multisource.gitbook.io/multisource-integration-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-integration-api/integration/call-lookup.md).

# 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

## Integrations / Templates

Ready-to-use templates – no development required.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>3CX</strong></td><td>Server-side CRM template – caller identification directly in the 3CX Web Client, desktop app, and mobile app.</td><td><a href="https://145843038-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaKvS0w0duT7N2oY0PNRV%2Fuploads%2FlWnyDJTgprCVsMYPfDV2%2F3cx.avif?alt=media&amp;token=d47d7593-e6da-4db3-ab15-75d40b0ab9b5">3cx.avif</a></td><td><a href="/multisource-integration-api/integration/call-lookup/3cx-integration.md">3CX Integration</a></td></tr><tr><td><strong>More integrations are on the way.</strong></td><td></td><td></td><td></td></tr></tbody></table>

## Own Implementation

Your system isn't listed, or you'd like to integrate Call Lookup directly into your own application? The API can be connected to any system that supports REST calls – the following sections cover authentication, endpoint, and response format in detail.

### 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":{"Phoneformat":{"enum":[1,2],"type":"integer","description":"**Allowed values:**\n- `1` = `Local`\n- `2` = `E164`","format":"int32","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},"country":{"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":{"$ref":"#/components/schemas/Phoneformat"}},{"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>string</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><tr><td><code>format</code></td><td>string</td><td><p>Response output format:</p><ul><li><code>json</code> = Structured data (default) – for further processing in your own application</li><li><code>html</code> = Ready-to-use HTML snippet</li></ul></td><td><code>json</code><br><code>html</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>

#### Advertising block marker

Numbers returned with a leading asterisk (`*`) (e.g. `*0791234567`) are flagged with an advertising block. The subscriber has objected to their number being used for advertising purposes. These numbers should not be used for telemarketing. The asterisk is part of the number string rather than a separate field – please account for this (parse it out) when processing the data.

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

## Number Ranges

Many companies have not just individual extensions, but contiguous number ranges – blocks of 10, 100, 1,000, or even 10,000 numbers. Not every number within such a range has its own entry in our directories.

Reverse lookup also takes these ranges into account: if a number range is enabled for reverse lookup and contains at least one active directory entry, a lookup for any number in that range returns the main entry – even if the specific number queried has no entry of its own.

### Example

A company owns the block of 10 `099 999 10 00` – `099 999 10 09`. The main number `099 999 10 00` is listed and enabled for reverse lookup, as is `099 999 10 05`, which has its own separate entry.

<table><thead><tr><th width="170.0703125">Number queried</th><th width="225.390625">Own entry?</th><th width="421.09375">Result</th></tr></thead><tbody><tr><td><code>099 999 10 00</code></td><td>Yes (main entry)</td><td>Own entry is returned</td></tr><tr><td><code>099 999 10 03</code></td><td>No</td><td>Main entry of the range (<code>099 999 10 00</code>) is returned</td></tr><tr><td><code>099 999 10 05</code></td><td>Yes (separate entry)</td><td>Own entry is returned</td></tr><tr><td><code>099 999 10 07</code></td><td>No</td><td>Main entry of the range (<code>099 999 10 00</code>) is returned</td></tr></tbody></table>

`099 999 10 03` and `099 999 10 07` have no entry of their own but fall within the enabled range, so they are matched to the main entry `099 999 10 00`. `099 999 10 05`, on the other hand, has its own entry and is returned accordingly, even though it is also part of the range.

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