API Reference / Contatti

Contatti

I contatti sono le persone: referenti che possono essere collegati a un account. Stessa CRUD completa degli account, con in più il legame verso l'azienda.

Prima di iniziare

Envelope, errori, paginazione e advanced_filters sono comuni: vedi Introduzione alle API. Ogni richiesta richiede Authorization: Bearer <accessToken>.

01L'oggetto Contatto

Ogni contatto restituito dall'API ha questa forma. Le date sono stringhe ISO 8601 in UTC; i campi non leggibili dal tuo ruolo vengono omessi dalla risposta.

Attributo	Tipo	Descrizione
id	integer	Identificativo univoco del contatto.
account_id	integer \| null	Account collegato (lookup verso Account).
first_name	string	Nome del referente.
last_name	string \| null	Cognome.
email	string \| null	Email del contatto.
phone	string \| null	Telefono.
job_title	string \| null	Ruolo/mansione.
owner_user_id	integer \| null	Utente proprietario del record.
assigned_user_id	integer \| null	Utente assegnatario.
created_by	integer \| null	Utente che ha creato il record.
updated_by	integer \| null	Ultimo utente che l'ha modificato.
is_deleted	boolean	`true` se in cestino (soft delete).
created_at	string	Data/ora di creazione (ISO 8601).
updated_at	string	Data/ora ultima modifica (ISO 8601).

json · l'oggetto Contatto

{
  "id": 341,
  "account_id": 128,
  "first_name": "Giulia",
  "last_name": "Bianchi",
  "email": "g.bianchi@acme.it",
  "phone": "+39 02 7654321",
  "job_title": "Responsabile acquisti",
  "owner_user_id": 7,
  "assigned_user_id": 7,
  "created_by": 7,
  "updated_by": 7,
  "is_deleted": false,
  "created_at": "2026-07-07T15:24:00.000Z",
  "updated_at": "2026-07-07T15:24:00.000Z"
}

02Endpoint

Metodo	Path	Azione	Cosa fa
GET	/api/contacts	read	Elenco paginato e filtrabile.
GET	/api/contacts/:id	read	Un singolo contatto.
GET	/api/contacts/:id/history	read	Storico modifiche del record.
GET	/api/contacts/lookup	read	Opzioni per i campi lookup (id + etichetta).
POST	/api/contacts	create	Crea un contatto.
PATCH	/api/contacts/:id	update	Modifica parziale.
PATCH	/api/contacts/bulk	update	Aggiornamento massivo.
DELETE	/api/contacts/:id	delete	Soft delete.
POST	/api/contacts/:id/restore	update	Ripristina un record eliminato.
GET	/api/contacts/export.csv · .xlsx	export	Esporta l'elenco filtrato.
POST	/api/contacts/import/preview · /execute	create	Import CSV.

03Elencare i contatti

GET /api/contacts bearer richiesto

Restituisce i contatti visibili all'utente (secondo lo scope del ruolo), paginati.

Parametri query

Parametro	Tipo		Descrizione
limit	integer	opzionale	Righe per pagina. Default 50, max 200.
offset	integer	opzionale	Righe da saltare (default 0).
sort_by	string	opzionale	Colonna di ordinamento (es. `last_name`, `created_at`).
sort_dir	string	opzionale	`asc` o `desc`.
advanced_filters	string (JSON)	opzionale	Array di condizioni: vedi Filtri avanzati.

Richiesta

curl "https://crm.tuodominio.it/api/contacts?limit=2&sort_by=created_at&sort_dir=desc" \
  -H "Authorization: Bearer <accessToken>"

const res = await fetch("https://crm.tuodominio.it/api/contacts?limit=2&sort_by=created_at&sort_dir=desc", {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const { data } = await res.json();

Risposta · 200

json

{
  "success": true,
  "data": {
    "items": [ { "id": 341, "first_name": "Giulia", "account_id": 128, … }, { "id": 340, … } ],
    "pagination": { "limit": 2, "offset": 0, "count": 2, "sortBy": "created_at", "sortDir": "desc" }
  }
}

04Recuperare un contatto

GET /api/contacts/:id bearer richiesto

Parametri path

Parametro	Tipo	Descrizione
id	integer	Id del contatto.

Esiti

Stato	Corpo
200	`{ success: true, data: { …contatto } }`
404	`NOT_FOUND`: inesistente o fuori dal tuo scope.

05Creare un contatto

POST /api/contacts bearer richiesto

Parametri body

Campo	Tipo		Note
first_name	string	richiesto	Nome. 1–120 caratteri.
last_name	string	opzionale	Cognome. Max 120.
email	string	opzionale	Email, validata.
phone	string	opzionale	Max 40 caratteri.
job_title	string	opzionale	Ruolo/mansione. Max 120.
account_id	integer	opzionale	Account a cui collegare il contatto (lookup verso Account).
owner_user_id	integer	opzionale	Proprietario. Assegnabile solo a sé o a un sottoposto nella gerarchia dei ruoli (admin: chiunque). Vedi Utenti e team.
assigned_user_id	integer	opzionale	Utente assegnatario.

Richiesta

curl -X POST https://crm.tuodominio.it/api/contacts \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Giulia", "last_name": "Bianchi", "account_id": 128, "job_title": "Responsabile acquisti" }'

const res = await fetch("https://crm.tuodominio.it/api/contacts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ first_name: "Giulia", last_name: "Bianchi", account_id: 128, job_title: "Responsabile acquisti" }),
});
const { data } = await res.json();

Risposta · 201

json

{ "success": true, "data": { "id": 341, "first_name": "Giulia", "account_id": 128, "is_deleted": false, … } }

Esiti

Stato	Codice	Quando
201	·	Contatto creato; nel corpo l'oggetto completo.
422	`VALIDATION_ERROR`	`first_name` mancante, campo fuori misura, o `account_id` inesistente/fuori scope.
403	`FORBIDDEN`	Campo non scrivibile dal ruolo (nei `details` l'elenco dei campi negati).

Nota · collegamento all'account

Se passi un account_id inesistente o fuori dal tuo scope, la richiesta fallisce in validazione (422). Le liste restituiscono il nome dell'account già risolto accanto all'id, così non devi fare una seconda chiamata per mostrarlo.

06Aggiornare un contatto

PATCH/api/contacts/:idbearer richiesto

Modifica parziale: invia solo i campi da cambiare (gli stessi del body di creazione, tutti opzionali). Risponde 200 con l'oggetto aggiornato, 404 se fuori scope, 422 in validazione.

curl

curl -X PATCH https://crm.tuodominio.it/api/contacts/341 \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "job_title": "Direttore acquisti" }'

07Eliminare e ripristinare

DELETE/api/contacts/:idbearer richiesto

Soft delete: il record viene marcato eliminato (is_deleted: true), non cancellato. Risponde 200 { deleted: true, id }.

POST/api/contacts/:id/restorebearer richiesto

Ripristina un contatto eliminato (richiede il permesso update). Risponde 200 con l'oggetto ripristinato.

08Aggiornamento massivo

PATCH/api/contacts/bulkbearer richiesto

Applica gli stessi valori a una lista di record. Gli id fuori dal tuo scope vengono saltati; la risposta riporta quanti record sono stati effettivamente aggiornati.

Body

json

{ "ids": [341, 340, 339], "changes": { "account_id": 128 } }

Risposta · 200

json

{ "success": true, "data": { "requested": 3, "updated": 2 } }

09Import ed export

Export: GET /export.csv o /export.xlsx rispettano gli stessi filtri della lista (advanced_filters, ordinamento). Richiedono il permesso export.
Import: POST /import/preview restituisce un'anteprima con la mappatura colonne e gli errori riga per riga; POST /import/execute applica. L'import richiede scope all e rispetta i permessi di scrittura per campo.

← PrecedenteAccount Successiva →Lead