*MCP › Reference › CRM › Contacts*

# Look up contacts by external reference

> From a list of your references, says which ones already exist in Filmo and which do not.

`notFound` are the ones to create. It is the primitive of any synchronization: without it, the alternative is one call per reference and guessing from the 404. It writes NOTHING, even though it is a POST: the list of references does not fit in a query string.

TOOL `filmo_contacts_lookup` · `contacts:read` · 120/min · Server annotation: Read-only · Server annotation: Idempotent

## Arguments

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `references` | string[] | Yes | External references to look up. At least one, at most 200. |

## Result

On success the result carries `structuredContent` with `data` and `meta`. These are the attributes of `data`.

| Name | Type | Description |
| --- | --- | --- |
| `contacts` | object[] | Contacts that matched at least one reference. |
| `contacts.id` | string | Identifier of the contact in Filmo. |
| `contacts.name` | string | Contact name. |
| `contacts.contactNumber` | string | Filmo contact number. |
| `notFound` | string[] | References that did not match any contact. These are the ones to create. |

*Call · filmo_contacts_lookup*

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_contacts_lookup",
    "arguments": {
      "references": [
        "<references>"
      ]
    }
  }
}
```

*Result (generated from the schema)*

```json
{
  "structuredContent": {
    "data": {
      "contacts": [
        {
          "id": "id_8f2a1c",
          "name": "Example",
          "contactNumber": "<contactNumber>"
        }
      ],
      "notFound": [
        "<notFound>"
      ]
    },
    "meta": {
      "rateLimit": {
        "limit": 120,
        "remaining": 119,
        "reset": 42
      }
    }
  }
}
```

## Sample prompts

*Prompt*

```text
Is there already a contact with the email ana@example.com?
```

## The same operation by REST

This tool runs [`POST /api/v1/contacts/lookup`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/look-up-contacts-by-external-reference).

---

Canonical URL: https://docs.filmo.io/mcp/tools/contacts/filmo-contacts-lookup  
Last updated: 2026-10-25