CRM anagrafiche
Lead, aziende, commenti e tag — crea e leggi le anagrafiche del tuo CRM Audin con l'API REST partner.
Versione Markdown di questa pagina
Scarica o copia il contenuto di questa pagina in formato .md — utile per fornirlo a un agente AI che integra questa specifica feature.
Il gruppo CRM anagrafiche copre le entità di base del CRM: i contatti (lead), le aziende a cui sono associati, i commenti che annoti su di loro e i tag con cui li classifichi. È il punto di partenza per sincronizzare un gestionale esterno con Audin.
Le risorse
| Path | Descrizione |
|---|---|
/leads | Contatti / prospect — anagrafica delle persone |
/companies | Anagrafica delle aziende |
/comments | Commenti e note su lead/azienda |
/tags | Tag per classificare lead e deal |
Tutte le rotte richiedono l'header X-API-Key (vedi
Autenticazione). Lo schema completo di ogni
risorsa — tutti i campi e i parametri — resta sullo
Swagger.
Lead
Un lead è un contatto del CRM. I campi chiave alla creazione:
| Campo | Tipo | Obbligatorio | Note |
|---|---|---|---|
fullName | string | sì | Nome completo del contatto |
email | string | no | |
phoneNumber | string | no | Formato E.164 consigliato (es. +393331234567) |
companyId | string | no | Id di una company esistente per associare il lead |
role | string | no | Ruolo/posizione del contatto in azienda |
leadStatus | enum | no | NEW, CONTACTED, QUALIFIED, PROPOSAL, NEGOTIATION, WON, LOST, ON_HOLD |
I lead sincronizzati da un'integrazione (es. HubSpot) popolano anche un
set di campi nativi dedicati, in sola lettura per chi consuma l'API
(valorizzati dalla sincronizzazione, altrimenti null):
| Campo | Tipo | Note |
|---|---|---|
firstName, lastName | string | Nome e cognome separati |
jobTitle | string | Mansione / ruolo |
mobilePhone | string | Cellulare (in aggiunta a phoneNumber) |
companyName | string | Ragione sociale associata |
website | string | Sito web |
lifecycleStage | string | Fase del ciclo di vita dal sistema di origine |
address, city, state, zip, country | string | Indirizzo postale |
Per i record sincronizzati, le proprietà personalizzate dell'account e
le altre proprietà native non mappate sono conservate senza perdita sotto
customParams.hubspot: customParams.hubspot.custom (le tue custom
property) e customParams.hubspot.native (le altre native). Vedi anche gli
outbound webhook.
Creare un lead
curl -X POST https://api.audin.ai/leads \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fullName": "Mario Rossi",
"email": "mario@acme.example.com",
"phoneNumber": "+393331234567"
}'const res = await fetch("https://api.audin.ai/leads", {
method: "POST",
headers: {
"X-API-Key": process.env.AUDIN_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
fullName: "Mario Rossi",
email: "mario@acme.example.com",
phoneNumber: "+393331234567",
}),
});
const lead = await res.json();Elencare i lead
GET /leads supporta paginazione (page, pageSize — max 100) e filtri via
query parameter:
curl "https://api.audin.ai/leads?page=1&pageSize=50" \
-H "X-API-Key: $API_KEY"const params = new URLSearchParams({ page: "1", pageSize: "50" });
const res = await fetch(`https://api.audin.ai/leads?${params}`, {
headers: { "X-API-Key": process.env.AUDIN_API_KEY },
});
const leads = await res.json();Operazioni disponibili: GET /leads (lista), POST /leads (crea),
GET /leads/{id}, PUT /leads/{id}, DELETE /leads/{id}.
Aziende
Un'azienda (company) rappresenta l'organizzazione a cui un lead
appartiene. Campi chiave alla creazione:
| Campo | Tipo | Obbligatorio | Note |
|---|---|---|---|
name | string | sì | Ragione sociale |
domain | string | sì | Dominio dell'azienda (es. acme.example.com) |
sector | string | no | Settore |
website, address, city, country, description | string | no |
Come per i lead, le aziende sincronizzate da un'integrazione (es. HubSpot)
popolano un set di campi nativi dedicati, in sola lettura (altrimenti
null):
| Campo | Tipo | Note |
|---|---|---|
phone | string | Telefono dell'azienda |
numberOfEmployees | number | Numero di dipendenti |
annualRevenue | number | Fatturato annuo |
state, zip | string | Provincia/regione e CAP |
lifecycleStage | string | Fase del ciclo di vita dal sistema di origine |
companyType | string | Tipologia di azienda |
Le proprietà personalizzate e le altre native non mappate sono conservate
sotto metadata.hubspot (custom e native), con la stessa convenzione
descritta per i lead.
Creare un'azienda e associarvi un lead
L'ordine tipico per popolare il CRM è: crea prima l'azienda, poi il lead
passando l'id ritornato come companyId.
# 1. Crea l'azienda
COMPANY_ID=$(curl -sX POST https://api.audin.ai/companies \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Acme Srl","domain":"acme.example.com"}' \
| jq -r '.id')
# 2. Crea il lead associato
curl -X POST https://api.audin.ai/leads \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"fullName\": \"Mario Rossi\",
\"email\": \"mario@acme.example.com\",
\"companyId\": \"$COMPANY_ID\"
}"const headers = {
"X-API-Key": process.env.AUDIN_API_KEY,
"Content-Type": "application/json",
};
// 1. Crea l'azienda
const companyRes = await fetch("https://api.audin.ai/companies", {
method: "POST",
headers,
body: JSON.stringify({ name: "Acme Srl", domain: "acme.example.com" }),
});
const company = await companyRes.json();
// 2. Crea il lead associato
const leadRes = await fetch("https://api.audin.ai/leads", {
method: "POST",
headers,
body: JSON.stringify({
fullName: "Mario Rossi",
email: "mario@acme.example.com",
companyId: company.id,
}),
});
const lead = await leadRes.json();Operazioni disponibili: GET /companies, POST /companies,
GET /companies/{id}, PUT /companies/{id}, DELETE /companies/{id}. Le
relazioni lead↔azienda si gestiscono anche via POST /leads/{id}/companies.
Commenti
I commenti sono note e annotazioni associate a un lead. Si creano con
POST /comments/create:
| Campo | Tipo | Obbligatorio | Note |
|---|---|---|---|
content | string | sì | Testo del commento |
userId | string | sì | Id del lead a cui il commento si riferisce |
type | enum | no | NOTE, CALL_SUMMARY, MEETING, EMAIL, TASK |
curl -X POST https://api.audin.ai/comments/create \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"userId": "<lead-id>",
"content": "Richiamare la prossima settimana",
"type": "NOTE"
}'const res = await fetch("https://api.audin.ai/comments/create", {
method: "POST",
headers: {
"X-API-Key": process.env.AUDIN_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
userId: leadId,
content: "Richiamare la prossima settimana",
type: "NOTE",
}),
});
const comment = await res.json();Aggiorna o elimina con PUT /comments/{id} / DELETE /comments/{id}.
Tag
I tag classificano lead e deal. Crea un tag con name e color, poi
assegnalo a un'entità.
# Crea il tag
curl -X POST https://api.audin.ai/tags \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"VIP","color":"#e11d48"}'
# Assegnalo a un'entità (es. un lead)
curl -X POST https://api.audin.ai/tags/assign \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"tagId":"<tag-id>","entityType":"LEAD","entityId":"<lead-id>"}'const headers = {
"X-API-Key": process.env.AUDIN_API_KEY,
"Content-Type": "application/json",
};
const tagRes = await fetch("https://api.audin.ai/tags", {
method: "POST",
headers,
body: JSON.stringify({ name: "VIP", color: "#e11d48" }),
});
const tag = await tagRes.json();
await fetch("https://api.audin.ai/tags/assign", {
method: "POST",
headers,
body: JSON.stringify({ tagId: tag.id, entityType: "LEAD", entityId: leadId }),
});La forma esatta del body di assegnazione (campi e valori ammessi di
entityType) e gli endpoint di assegnazione bulk (/tags/assign/bulk,
/tags/unassign) sono descritti sullo
Swagger. Verificali prima di consumarli.
Rendere ripetibili le creazioni
Tutte le rotte POST di questo gruppo accettano l'header Idempotency-Key: usalo
per evitare di creare duplicati sui retry. Vedi
Idempotency & rate limit.
Schema completo (tutti i campi e parametri): Swagger.