--- title: "Edit an anagrafica" method: PATCH path: "/api/v1/rest/anagrafiche/parties/{id}" tags: ["Contacts"] --- # Edit an anagrafica `PATCH /api/v1/rest/anagrafiche/parties/{id}` ## Request - Base URL: `https://api.custodo.ai` - URL: `https://api.custodo.ai/api/v1/rest/anagrafiche/parties/{id}` - Auth: HTTP bearer Changes fields on an existing anagrafica. Only the fields you pass are touched, and `null` CLEARS one — so omitting a field is not the same as emptying it. `roles` and `tags` are REPLACED whole, never merged: read the record first (anagrafiche_get_party) and pass everything it should end up with — a customer that also became a supplier is `["cliente", "fornitore"]`, not `["fornitore"]`. `custom` is merged key by key, like the record’s own fields. A role outside the caller’s own role list is refused. It cannot move an address (anagrafiche_set_address) and cannot delete the record (anagrafiche_delete_party). ## Path parameters - `id` string, uuid, required ## Headers - `X-Tenant-Id` string, uuid ## Request body - object - `kind` 'company' | 'person': `company` for an organisation, `person` for an individual or a ditta individuale. - `name` string: What people call them — «Rossi». This is the name every list shows. - `roles` string[]: What the anagrafica IS to the organisation — a SET, because a supplier that is also a customer holds both. Built-in keys: cliente, potenziale_cliente, ex_cliente, fornitore, agente, dipendente, collaboratore, consulente; the organisation’s own come from anagrafiche_list_roles. At most 20. Each member may be limited to some roles by an administrator; a set none of whose roles the caller may write (`access.write` on anagrafiche_list_roles) is refused. - `lifecycle` 'lead' | 'prospect' | 'customer' | 'former': DEPRECATED — send `roles` instead. The CRM’s old «Relazione», still accepted from callers written before it became roles: `lead` and `prospect` mean the role potenziale_cliente, `customer` means cliente, `former` means ex_cliente. Ignored whenever `roles` is also given. - `legal_name` string, nullable: The ragione sociale an invoice must carry — «Rossi S.r.l. Unipersonale» — when it differs from `name`. - `first_name` string, nullable: Only on a `person`. - `last_name` string, nullable: Only on a `person`. - `job_title` string, nullable: Their job — «Amministratore delegato». Only on a `person`. - `parent_id` string, uuid, nullable: The company this person works for, or the holding above this company. Another anagrafica’s id, from anagrafiche_search_parties or anagrafiche_create_party. A party can never be its own ancestor. - `vat_number` string, nullable: Partita IVA. Paste it as you have it: «IT 123.456.789-03» is stored as «12345678903». An Italian one is checked against its check digit; a foreign one is only shape-checked. - `tax_code` string, nullable: Codice fiscale: 16 characters for a person, the 11-digit partita IVA for a company. Checked. - `sdi_code` string, nullable: Codice destinatario for electronic invoicing: 7 characters for a private recipient, 6 for a PA. «0000000» legitimately means «no electronic channel». - `pec` string, nullable: The certified mailbox. A PEC is not an ordinary address — never put one in `email`. - `email` string, nullable: Ordinary email. What the duplicate probe matches on, and what files mail from this address under the anagrafica. - `phone` string, nullable: Landline, as it is dialled. - `mobile` string, nullable: Mobile number. - `whatsapp` string, nullable: The number they chat on WhatsApp, with the country code — «+39 333 123 4567». Its own field, never inferred from `mobile`: stored normalised, and what the WhatsApp module writes to. - `website` string, nullable: Their site: an http(s) address or a bare host, never another scheme. - `industry` string, nullable: Free text — «studio commercialista», «edilizia». There is no closed list. - `owner_user_id` string, uuid, nullable: Whose account it is. A colleague’s `user_id` from custodo_list_members, your own from custodo_whoami, or the `owner_user_id` a `detailed` anagrafiche_get_party returns. - `agent_user_id` string, uuid, nullable: The agente di riferimento who brought the account. A colleague’s `user_id` from custodo_list_members, or your own from custodo_whoami. Recorded only — this product computes no commission. - `source` string, nullable: Where they came from — «passaparola», «fiera», «sito». Free text. - `tags` string[]: Free labels, at most 20. REPLACES the whole list, so pass the tags the record should end up with. - `consent_basis` 'contract' | 'consent' | 'legitimate_interest' | 'legal_obligation', nullable: The GDPR Article 6 basis for holding their data. Never invent one — leave it out when nobody has recorded it. - `consent_at` string, date-time, nullable: When that basis was established, ISO-8601 with a timezone. - `consent_source` string, nullable: How it was obtained — «contratto firmato», «modulo sul sito». - `marketing_opt_out` boolean: true when they have asked not to be contacted commercially. - `notes` string, nullable: Free notes on the record, written by people and read by people. - `custom` object: The organisation’s own fields, FIELD KEY → value. The keys, types, options and which roles each field is for are `partyFields` in custodo_get_module_settings (module `anagrafiche`). A value is text, a number, a date as YYYY-MM-DD, true/false, or one of a choice field’s options exactly. Only the keys you pass change and `null` clears one. A key no field declares, or a field limited to roles the record does not hold, is refused; a required field the record’s roles want must be given. ## Response `200` Done. `data` is the tool’s own answer. - RestResult - `ok` true, required - `data` unknown, required ## Other responses - `400`: The arguments did not validate: `error.message` names the field, what it expects and what arrived. - `401`: No API key, or one that is malformed, unknown, revoked or expired. - `403`: The call never ran: the module is off for this organisation, the credential lacks the permission or the module, the tier does not cover it, or the tool is destructive and the key was not minted for that. - `404`: Nothing with that id in this organisation. - `409`: The record is in a state that does not allow it — under legal hold, already sent, already closed. `error.code` says which. - `422`: The tool ran and refused, in a sentence of its own (`TOOL_REFUSED`): the message says what to change. Retrying the same call will not help. - `429`: The API key has spent its minute, or its day. Every request a key makes counts. See `Retry-After`. --- [API](https://skmtc.dev/custodo/apis/custodo-integrazioni.md) · [All operations](https://skmtc.dev/custodo/apis/custodo-integrazioni/llms.txt) · [OpenAPI document](https://skmtc.dev/custodo/apis/custodo-integrazioni/revisions/16d336d3ec2a?raw)