Contacts

List contacts

Returns the contacts (customers and suppliers) visible to the key, cursor-paginated.

Tool

filmo_contacts_list

Readcontacts:read

contacts:read
120/min
Server annotation: Read-only
Server annotation: Idempotent

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_contacts_list",
    "arguments": {
      "limit": 20
    }
  }
}

{
  "structuredContent": {
    "data": [
      {
        "id": "id_8f2a1c",
        "name": "Example",
        "contactType": "person",
        "role": "client",
        "status": "active",
        "nif": "00000000T",
        "commercialName": "Example",
        "position": "<position>",
        "contactNumber": "<contactNumber>",
        "emails": [
          {
            "id": "id_8f2a1c",
            "label": "Example",
            "email": "ana@example.com",
            "isPrimary": true
          }
        ],
        "billingEmail": "ana@example.com",
        "phoneNumbers": [
          {
            "id": "id_8f2a1c",
            "label": "Example",
            "number": "<number>",
            "countryCode": "ES",
            "isPrimary": true
          }
        ],
        "websites": [
          {
            "id": "id_8f2a1c",
            "label": "Example",
            "url": "https://example.com"
          }
        ],
        "addresses": [
          {
            "id": "id_8f2a1c",
            "label": "Example",
            "addressLine1": "<addressLine1>",
            "addressLine2": "<addressLine2>",
            "city": "<city>",
            "province": "<province>",
            "postcode": "<postcode>",
            "country": "ES",
            "isMain": true
          }
        ],
        "folder": "<folder>",
        "discountPercentage": 1,
        "preferredLanguage": "es-ES",
        "currency": "EUR",
        "paymentMethod": {
          "type": "bank_transfer",
          "customValue": "<customValue>"
        },
        "paymentDays": [
          1
        ],
        "expirationDays": 1,
        "subscribedToMarketing": true,
        "isAppUser": true,
        "customFields": {
          "key": "<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
      }
    }
  }
}

generated from the schema

Tenancy inherited from the parent account: a billing account also sees the contacts of its parent account.

Arguments

limitintegerdefault:50

Page size (1-500). Defaults to 50.

Limits: min 1, max 500

cursorstring

Opaque cursor of the page to return. Pass the value of pagination.nextCursor from the previous response; treat it as opaque.

Limits: max length 200

sortstring

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.

Limits: max length 200

typestring

Filter by contact type: person (individual) or company (business).

Available options: person, company

rolestring

Filter by contact role: client, provider, lead, debtor, creditor, student, teacher or unspecified.

Available options: client, provider, lead, debtor, creditor, student, teacher, unspecified

emailstring

Filter by email: matches against the email addresses of the contact.

Limits: max length 200

phonestring

Filter by phone: matches against the phone numbers of the contact.

Limits: max length 200

isAppUserboolean

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.

includeTotalbooleandefault:false

Set it to true to include pagination.total, the number of results that match the filters across all pages. Off by default.

dateFiltersobject

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.

Show child attributes

dateFilters.createdobject

Show child attributes

dateFilters.created.gtestring

From this day or instant, inclusive.

dateFilters.created.ltestring

Up to this day or instant, inclusive.

dateFilters.created.gtstring

Strictly after; a bare day means after the end of that day.

dateFilters.created.ltstring

Strictly before; a bare day means before the start of that day.

dateFilters.created.onstring

Exactly that day; an instant means the whole business day that contains it.

dateFilters.updatedobject

Show child attributes

dateFilters.updated.gtestring

From this day or instant, inclusive.

dateFilters.updated.ltestring

Up to this day or instant, inclusive.

dateFilters.updated.gtstring

Strictly after; a bare day means after the end of that day.

dateFilters.updated.ltstring

Strictly before; a bare day means before the start of that day.

dateFilters.updated.onstring

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.

Show the attributes of data

idstring

Unique identifier of the contact.

namestring

Contact name (person or company).

contactTypestring

Contact type: person (individual) or company (business).

Available options: person, company

rolestring

Contact role: client, provider, lead, debtor, creditor, student, teacher or unspecified.

Available options: client, provider, lead, debtor, creditor, student, teacher, unspecified

statusstring

Contact status: active (operational), inactive (deactivated) or archived (closed, kept for historical records).

Available options: active, inactive, archived

nifstring | null

NIF/CIF or tax identification number; null if not recorded.

commercialNamestring | null

Trade name; null if it matches the name or is not recorded.

positionstring | null

Job title or position of the contact person; null if not recorded.

contactNumberstring | null

Contact number assigned by the account (internal reference); null if not recorded.

emailsobject[]

List of email addresses of the contact.

Show child attributes

emails.idstring

Internal identifier of the email within the contact.

emails.labelstring | null

Descriptive label of the email; null if it has none.

emails.emailstring

Email address.

emails.isPrimaryboolean

Whether this is the primary email of the contact.

billingEmailstring | null

Dedicated billing email; null means the primary email is used.

phoneNumbersobject[]

List of phone numbers of the contact.

Show child attributes

phoneNumbers.idstring

Internal identifier of the phone number within the contact.

phoneNumbers.labelstring | null

Descriptive label of the phone number; null if it has none.

phoneNumbers.numberstring

Phone number.

phoneNumbers.countryCodestring | null

International country calling code (e.g. "+34"); null if not recorded.

phoneNumbers.isPrimaryboolean

Whether this is the primary phone number of the contact.

websitesobject[]

List of websites of the contact.

Show child attributes

websites.idstring

Internal identifier of the website within the contact.

websites.labelstring | null

Descriptive label of the website; null if it has none.

websites.urlstring

Website URL.

addressesobject[]

List of addresses of the contact.

Show child attributes

addresses.idstring

Internal identifier of the address within the contact.

addresses.labelstring | null

Descriptive label of the address; null if it has none.

addresses.addressLine1string | null

First line of the address; null if not recorded.

addresses.addressLine2string | null

Second line of the address; null if not recorded.

addresses.citystring | null

City; null if not recorded.

addresses.provincestring | null

Province or region; null if not recorded.

addresses.postcodestring | null

Postcode; null if not recorded.

addresses.countrystring | null

Country; null if not recorded.

addresses.isMainboolean

Whether this is the main address of the contact.

folderstring | null

Folder or organizational grouping; null if the contact is not classified.

discountPercentagenumber | null

General discount percentage of the contact (0-100); null if no discount is configured.

preferredLanguagestring | null

Preferred language of the contact; null if not recorded.

currencystring | null

Default currency of the contact as an ISO 4217 code; null if not recorded.

paymentMethodobject | null

Preferred payment method of the contact; null if not configured.

Show child attributes

paymentMethod.typestring

Payment method type: bank_transfer, card, cash, sepa_direct_debit or other.

Available options: bank_transfer, card, cash, other, sepa_direct_debit

paymentMethod.customValuestring | null

Free-text detail when the type is "other" (for example a method recorded before it was configured); null otherwise.

paymentDaysinteger[] | null

Days of the month on which the contact makes payments; null if not configured.

expirationDaysinteger | null

Default due days for the invoices of the contact; null if not configured.

subscribedToMarketingboolean

Whether the contact is subscribed to marketing communications.

isAppUserboolean

Whether the contact has access to the app.

customFieldsobject<string, any>

Custom field values by custom field identifier; the definitions are in /api/v1/custom-fields.

createdAtstring<date-time>

Creation date in ISO 8601 with offset.

updatedAtstring<date-time>

Last update date in ISO 8601 with offset.

An error is a result with isError: true and the problem in content[0].text; there is no structuredContent. See Errors.

Sample prompts

List my customers whose name starts with “Northwind”.

The same operation by REST

This tool runs GET /api/v1/contacts.

Contacts
List contacts
Returns the contacts (customers and suppliers) visible to the key, cursor-paginated.
Guides
Safe writes
An assistant that can write can also write the wrong thing. Decide which tools need a person, retry without duplicating, and know what a write sets in motion.
Guides
Errors
A tool error is a result with isError: true and the problem in the first text block. Branch on its code.

Was this page helpful?

Result

Arguments

Result

Sample prompts

The same operation by REST

Related pages

List contacts

Safe writes

Errors