*MCP › Reference › CRM › Contacts* # List contacts > Returns the contacts (customers and suppliers) visible to the key, cursor-paginated. Tenancy inherited from the parent account: a billing account also sees the contacts of its parent account. TOOL `filmo_contacts_list` · `contacts:read` · 120/min · Server annotation: Read-only · Server annotation: Idempotent ## Arguments | Name | Type | Required | Description | | --- | --- | --- | --- | | `limit` | integer | No | Page size (1-500). Defaults to 50. = `50` | | `cursor` | string | No | Opaque cursor of the page to return. Pass the value of `pagination.nextCursor` from the previous response; treat it as opaque. | | `sort` | string | No | Sort order: up to 3 comma-separated fields, each with a leading "-" for descending (e.g. "-updatedAt,name"). Sortable fields: createdAt, updatedAt, name, contactType, role, status, email. Defaults to "-createdAt". Ties are broken by id, so the order is stable across pages, and a cursor is bound to the sort it was issued with. | | `type` | string | No | Filter by contact type: person (individual) or company (business). `person`, `company` | | `role` | string | No | Filter by contact role: client, provider, lead, debtor, creditor, student, teacher or unspecified. `client`, `provider`, `lead`, `debtor`, `creditor`, `student`, `teacher`, `unspecified` | | `email` | string | No | Filter by email: matches against the email addresses of the contact. | | `phone` | string | No | Filter by phone: matches against the phone numbers of the contact. | | `isAppUser` | boolean | No | Filter by whether the contact has access to the app: "true" returns only app users, "false" only those who are not. Omit it to skip the filter. | | `includeTotal` | boolean | No | Set it to true to include `pagination.total`, the number of results that match the filters across all pages. Off by default. = `false` | | `dateFilters` | object | No | Date filters by field. A bare day (YYYY-MM-DD) is read in the business timezone; an ISO 8601 instant with offset is applied as is by gte, lte, gt and lt, while on widens it to the whole business day that contains it. Fields: created, updated. | | `dateFilters.created` | object | No | | | `dateFilters.created.gte` | string | No | From this day or instant, inclusive. | | `dateFilters.created.lte` | string | No | Up to this day or instant, inclusive. | | `dateFilters.created.gt` | string | No | Strictly after; a bare day means after the end of that day. | | `dateFilters.created.lt` | string | No | Strictly before; a bare day means before the start of that day. | | `dateFilters.created.on` | string | No | Exactly that day; an instant means the whole business day that contains it. | | `dateFilters.updated` | object | No | | | `dateFilters.updated.gte` | string | No | From this day or instant, inclusive. | | `dateFilters.updated.lte` | string | No | Up to this day or instant, inclusive. | | `dateFilters.updated.gt` | string | No | Strictly after; a bare day means after the end of that day. | | `dateFilters.updated.lt` | string | No | Strictly before; a bare day means before the start of that day. | | `dateFilters.updated.on` | string | No | Exactly that day; an instant means the whole business day that contains it. | ## Result On success the result carries `structuredContent` with `data` and `meta`. These are the attributes of `data`. | Name | Type | Description | | --- | --- | --- | | `id` | string | Unique identifier of the contact. | | `name` | string | Contact name (person or company). | | `contactType` | string | Contact type: person (individual) or company (business). `person`, `company` | | `role` | string | Contact role: client, provider, lead, debtor, creditor, student, teacher or unspecified. `client`, `provider`, `lead`, `debtor`, `creditor`, `student`, `teacher`, `unspecified` | | `status` | string | Contact status: active (operational), inactive (deactivated) or archived (closed, kept for historical records). `active`, `inactive`, `archived` | | `nif` | string | NIF/CIF or tax identification number; null if not recorded. | | `commercialName` | string | Trade name; null if it matches the name or is not recorded. | | `position` | string | Job title or position of the contact person; null if not recorded. | | `contactNumber` | string | Contact number assigned by the account (internal reference); null if not recorded. | | `emails` | object[] | List of email addresses of the contact. | | `emails.id` | string | Internal identifier of the email within the contact. | | `emails.label` | string | Descriptive label of the email; null if it has none. | | `emails.email` | string | Email address. | | `emails.isPrimary` | boolean | Whether this is the primary email of the contact. | | `billingEmail` | string | Dedicated billing email; null means the primary email is used. | | `phoneNumbers` | object[] | List of phone numbers of the contact. | | `phoneNumbers.id` | string | Internal identifier of the phone number within the contact. | | `phoneNumbers.label` | string | Descriptive label of the phone number; null if it has none. | | `phoneNumbers.number` | string | Phone number. | | `phoneNumbers.countryCode` | string | International country calling code (e.g. "+34"); null if not recorded. | | `phoneNumbers.isPrimary` | boolean | Whether this is the primary phone number of the contact. | | `websites` | object[] | List of websites of the contact. | | `websites.id` | string | Internal identifier of the website within the contact. | | `websites.label` | string | Descriptive label of the website; null if it has none. | | `websites.url` | string | Website URL. | | `addresses` | object[] | List of addresses of the contact. | | `addresses.id` | string | Internal identifier of the address within the contact. | | `addresses.label` | string | Descriptive label of the address; null if it has none. | | `addresses.addressLine1` | string | First line of the address; null if not recorded. | | `addresses.addressLine2` | string | Second line of the address; null if not recorded. | | `addresses.city` | string | City; null if not recorded. | | `addresses.province` | string | Province or region; null if not recorded. | | `addresses.postcode` | string | Postcode; null if not recorded. | | `addresses.country` | string | Country; null if not recorded. | | `addresses.isMain` | boolean | Whether this is the main address of the contact. | | `folder` | string | Folder or organizational grouping; null if the contact is not classified. | | `discountPercentage` | number | General discount percentage of the contact (0-100); null if no discount is configured. | | `preferredLanguage` | string | Preferred language of the contact; null if not recorded. | | `currency` | string | Default currency of the contact as an ISO 4217 code; null if not recorded. | | `paymentMethod` | object | Preferred payment method of the contact; null if not configured. | | `paymentMethod.type` | string | Payment method type: bank_transfer, card, cash, sepa_direct_debit or other. `bank_transfer`, `card`, `cash`, `other`, `sepa_direct_debit` | | `paymentMethod.customValue` | string | Free-text detail when the type is "other" (for example a method recorded before it was configured); null otherwise. | | `paymentDays` | integer[] | Days of the month on which the contact makes payments; null if not configured. | | `expirationDays` | integer | Default due days for the invoices of the contact; null if not configured. | | `subscribedToMarketing` | boolean | Whether the contact is subscribed to marketing communications. | | `isAppUser` | boolean | Whether the contact has access to the app. | | `customFields` | object | Custom field values by custom field identifier; the definitions are in `/api/v1/custom-fields`. | | `createdAt` | string | Creation date in ISO 8601 with offset. | | `updatedAt` | string | Last update date in ISO 8601 with offset. | *Call · filmo_contacts_list* ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "filmo_contacts_list", "arguments": { "limit": 20 } } } ``` *Result (generated from the schema)* ```json { "structuredContent": { "data": [ { "id": "id_8f2a1c", "name": "Example", "contactType": "person", "role": "client", "status": "active", "nif": "00000000T", "commercialName": "Example", "position": "", "contactNumber": "", "emails": [ { "id": "id_8f2a1c", "label": "Example", "email": "ana@example.com", "isPrimary": true } ], "billingEmail": "ana@example.com", "phoneNumbers": [ { "id": "id_8f2a1c", "label": "Example", "number": "", "countryCode": "ES", "isPrimary": true } ], "websites": [ { "id": "id_8f2a1c", "label": "Example", "url": "https://example.com" } ], "addresses": [ { "id": "id_8f2a1c", "label": "Example", "addressLine1": "", "addressLine2": "", "city": "", "province": "", "postcode": "", "country": "ES", "isMain": true } ], "folder": "", "discountPercentage": 1, "preferredLanguage": "es-ES", "currency": "EUR", "paymentMethod": { "type": "bank_transfer", "customValue": "" }, "paymentDays": [ 1 ], "expirationDays": 1, "subscribedToMarketing": true, "isAppUser": true, "customFields": { "key": "" }, "createdAt": "2026-09-01T08:00:00Z", "updatedAt": "2026-09-01T08:00:00Z" } ], "pagination": { "nextCursor": "eyJvIjo1MH0", "hasMore": true, "total": 1 }, "meta": { "rateLimit": { "limit": 120, "remaining": 119, "reset": 42 } } } } ``` ## Sample prompts *Prompt* ```text List my customers whose name starts with “Northwind”. ``` ## The same operation by REST This tool runs [`GET /api/v1/contacts`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/list-contacts). --- Canonical URL: https://docs.filmo.io/mcp/tools/contacts/filmo-contacts-list Last updated: 2026-10-25