---
title: CRM anagrafiche
description: Lead, aziende, commenti e tag — crea e leggi le anagrafiche del tuo CRM Audin con l'API REST partner.
---

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](/docs/api-rest/autenticazione)). Lo schema completo di ogni
risorsa — tutti i campi e i parametri — resta sullo
[Swagger](https://api.audin.ai/docs/partners).

## 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 |

<Callout type="info">
  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](/docs/api-rest/outbound-webhooks).
</Callout>

### Creare un lead

<Tabs items={["curl", "JavaScript"]}>
<Tab value="curl">

```bash
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"
  }'
```

</Tab>
<Tab value="JavaScript">

```js
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();
```

</Tab>
</Tabs>

### Elencare i lead

`GET /leads` supporta paginazione (`page`, `pageSize` — max 100) e filtri via
query parameter:

<Tabs items={["curl", "JavaScript"]}>
<Tab value="curl">

```bash
curl "https://api.audin.ai/leads?page=1&pageSize=50" \
  -H "X-API-Key: $API_KEY"
```

</Tab>
<Tab value="JavaScript">

```js
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();
```

</Tab>
</Tabs>

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`.

<Tabs items={["curl", "JavaScript"]}>
<Tab value="curl">

```bash
# 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\"
  }"
```

</Tab>
<Tab value="JavaScript">

```js
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();
```

</Tab>
</Tabs>

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` |

<Tabs items={["curl", "JavaScript"]}>
<Tab value="curl">

```bash
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"
  }'
```

</Tab>
<Tab value="JavaScript">

```js
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();
```

</Tab>
</Tabs>

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à.

<Tabs items={["curl", "JavaScript"]}>
<Tab value="curl">

```bash
# 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>"}'
```

</Tab>
<Tab value="JavaScript">

```js
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 }),
});
```

</Tab>
</Tabs>

<Callout type="info">
  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](https://api.audin.ai/docs/partners). Verificali prima di consumarli.
</Callout>

## 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](/docs/api-rest/idempotency-e-rate-limit).

<Callout type="info">
  Schema completo (tutti i campi e parametri):
  [Swagger](https://api.audin.ai/docs/partners).
</Callout>

## Prossimo passo

<Cards>
  <Card href="/docs/api-rest/pipeline-e-deal" title="Pipeline & deal" description="Apri opportunità sui lead appena creati, con pipeline, stage e attività." />
  <Card href="/docs/api-rest/flussi" title="Flussi operativi" description="Esempio end-to-end: da azienda e lead all'apertura di una deal." />
</Cards>