Contacts

Create an anagrafica

Adds a company or a person to the register — the roles it holds (a customer, a supplier, both…), the fiscal block (partita IVA, codice fiscale, codice destinatario, PEC), the contact details, the owner and the GDPR basis. A partita IVA is NOT unique here (branches of one group share one, and so do a person and their ditta individuale), so nothing is refused as a duplicate: call anagrafiche_find_duplicates first and show the user what came back. Addresses are separate — add them with anagrafiche_set_address afterwards. A role outside the caller’s own role list (see access on anagrafiche_list_roles) is refused. It appears in the register immediately, so confirm the details with the user first.

post/api/v1/rest/anagrafiche/parties

Request

  • Base URL: https://api.custodo.ai
  • URL: https://api.custodo.ai/api/v1/rest/anagrafiche/parties
  • Auth: HTTP bearer

Headers

X-Tenant-Idstring uuid

The organisation to act in. An API key is bound to exactly one, so this is optional for a key and must match the one it was minted for.

Request body

kind'company' | 'person'

company for an organisation, person for an individual or a ditta individuale.

namestring required

What people call them — «Rossi». This is the name every list shows.

rolesstring[]

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_namestring

The ragione sociale an invoice must carry — «Rossi S.r.l. Unipersonale» — when it differs from name.

first_namestring

Only on a person.

last_namestring

Only on a person.

job_titlestring

Their job — «Amministratore delegato». Only on a person.

parent_idstring uuid

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_numberstring

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_codestring

Codice fiscale: 16 characters for a person, the 11-digit partita IVA for a company. Checked.

sdi_codestring

Codice destinatario for electronic invoicing: 7 characters for a private recipient, 6 for a PA. «0000000» legitimately means «no electronic channel».

pecstring

The certified mailbox. A PEC is not an ordinary address — never put one in email.

emailstring

Ordinary email. What the duplicate probe matches on, and what files mail from this address under the anagrafica.

phonestring

Landline, as it is dialled.

mobilestring

Mobile number.

whatsappstring

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.

websitestring

Their site: an http(s) address or a bare host, never another scheme.

industrystring

Free text — «studio commercialista», «edilizia». There is no closed list.

owner_user_idstring uuid

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_idstring uuid

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.

sourcestring

Where they came from — «passaparola», «fiera», «sito». Free text.

tagsstring[]

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'

The GDPR Article 6 basis for holding their data. Never invent one — leave it out when nobody has recorded it.

consent_atstring date-time

When that basis was established, ISO-8601 with a timezone.

consent_sourcestring

How it was obtained — «contratto firmato», «modulo sul sito».

marketing_opt_outboolean

true when they have asked not to be contacted commercially.

notesstring

Free notes on the record, written by people and read by people.

customobject

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

Done. data is the tool’s own answer.

oktrue required
dataunknown required

Changes

No recorded changes to this operation across all 1 revision of this API.