Contacts

Update a contact

Partially updates a contact (send only the fields to change).

Tool

filmo_contacts_update

Destructivecontacts:write

contacts:write
120/min
Server annotation: Destructive
Server annotation: Idempotent
Requires human confirmation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_contacts_update",
    "arguments": {
      "contactId": "cont_8f2a1c"
    }
  }
}

{
  "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",
      "relatedContacts": [
        {
          "id": "id_8f2a1c",
          "name": "Example",
          "commercialName": "Example",
          "contactType": "person",
          "role": "client",
          "status": "active",
          "relationRole": "<relationRole>"
        }
      ]
    },
    "meta": {
      "idempotencyKey": "<the key you sent, or the one the server generated>",
      "rateLimit": {
        "limit": 120,
        "remaining": 119,
        "reset": 42
      }
    }
  }
}

generated from the schema

Requires human confirmation

Put this tool on your client's “ask before running” list. The annotations are hints that the server declares, not guarantees: do not decide the approval from destructiveHint alone.

The arrays of emails, phones and addresses replace the existing list entirely. Returns the updated contact in detail.

Arguments

contactIdstringRequired

Contact identifier.

Limits: min length 1

namestring

Contact name (person or company).

Limits: min length 1, max length 200

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 clears it ("" is normalized to null too).

Limits: max length 20

commercialNamestring | null

Trade name; null clears it.

Limits: max length 200

positionstring | null

Job title or position; null clears it.

Limits: max length 200

emailsobject[]

List of email addresses that REPLACES the existing list entirely (max 20). Internal ids are generated by the server.

Limits: max 20 items

Show child attributes

emails.emailstring<email>Required

Email address; the format is validated.

Limits: max length 200

emails.labelstring

Descriptive label of the email (e.g. "Personal", "Billing").

Limits: max length 100

emails.isPrimaryboolean

Marks this email as the primary one for the contact.

phoneNumbersobject[]

List of phone numbers that REPLACES the existing list entirely (max 20). Internal ids are generated by the server.

Limits: max 20 items

Show child attributes

phoneNumbers.numberstringRequired

Phone number.

Limits: min length 1, max length 50

phoneNumbers.labelstring

Descriptive label of the phone number (e.g. "Mobile", "Office").

Limits: max length 100

phoneNumbers.countryCodestring

International country calling code (e.g. "+34").

Limits: max length 10

phoneNumbers.isPrimaryboolean

Marks this phone number as the primary one for the contact.

websitesobject[]

List of websites that REPLACES the existing list entirely (max 20). Internal ids are generated by the server.

Limits: max 20 items

Show child attributes

websites.urlstring<uri>Required

Website URL; the format is validated.

Limits: max length 300

websites.labelstring

Descriptive label of the website (e.g. "Corporate website", "LinkedIn").

Limits: max length 100

addressesobject[]

List of addresses that REPLACES the existing list entirely (max 20). Send the id of each existing address you want to keep; addresses without id are created with a new one. An id that is not an address of this contact responds 400. Leaving out an address that an order uses as its billing or shipping address responds 409 address_in_use and nothing is changed.

Limits: max 20 items

Show child attributes

addresses.idstring

Identifier of an existing address to keep it; omit it to add a new one.

Limits: min length 1

addresses.labelstring

Descriptive label of the address (e.g. "Billing", "Shipping").

Limits: max length 100

addresses.addressLine1stringRequired

First line of the address (street and number). Required.

Limits: min length 1, max length 300

addresses.addressLine2string

Second line of the address (floor, door, etc.).

Limits: max length 300

addresses.citystring

City of the address.

Limits: max length 200

addresses.provincestring

Province or region of the address.

Limits: max length 200

addresses.postcodestring

Postcode of the address.

Limits: max length 20

addresses.countrystring

Country of the address (code or short name).

Limits: max length 10

addresses.isMainboolean

Marks this address as the main one for the contact.

folderstring | null

Folder or organizational grouping; null clears it.

Limits: max length 200

contactNumberstring | null

Contact number (internal reference); null clears it.

Limits: max length 50

discountPercentagenumber | null

General discount percentage of the contact (0-100); null clears it.

Limits: min 0, max 100

subscribedToMarketingboolean

Whether the contact is subscribed to marketing communications.

idempotencyKeystring

Idempotency key chosen by the client (a UUID is recommended). Repeating the same key with the same arguments within 24 h returns the stored response without executing again; with different arguments it responds 422. It is the safe way to retry after a network failure.

Limits: min length 1, max length 255

ifMatchstring

Optimistic locking: the meta.etag you got from the detail read of this resource (or "*"). If the resource changed since, the call fails with 412 precondition_failed before writing anything; read it again and retry. Omit it to write unconditionally.

Limits: min length 1

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.

relatedContactsobject[]

Contacts related to this contact (e.g. people of a company).

Show child attributes

relatedContacts.idstring

Unique identifier of the related contact.

relatedContacts.namestring

Name of the related contact.

relatedContacts.commercialNamestring | null

Trade name of the related contact; null if not recorded.

relatedContacts.contactTypestring

Type of the related contact: person or company.

Available options: person, company

relatedContacts.rolestring

Role of the related contact.

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

relatedContacts.statusstring

Status of the related contact: active, inactive or archived.

Available options: active, inactive, archived

relatedContacts.relationRolestring | null

Role of the relationship between the two contacts (e.g. "employee of"); null if not recorded.

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

The same operation by REST

This tool runs PATCH /api/v1/contacts/{contactId}.

Contacts
Update a contact
Partially updates a contact (send only the fields to change).
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

The same operation by REST

Related pages

Update a contact

Safe writes

Errors