Leads API
Legga i contatti commerciali e ne aggiorni lo stato dai Suoi sistemi con una chiave API con ambito limitato.
Questa pagina è stata tradotta dall'inglese. In caso di differenze, fa fede la versione inglese. Leggi in inglese
La Leads API consente al Suo CRM, al data warehouse o a uno strumento di automazione di leggere i Suoi contatti commerciali (lead) e di aggiornarne lo stato.
Crei le chiavi in Studio in Integrations → Leads API → New key. Ogni chiave ha:
- un nome;
- autorizzazioni:
leads:read(Read leads) e, facoltativamente,leads:write-status(Change lead status); - una scadenza di 30, 90, 180 giorni o 1 anno.
Le chiavi hanno la forma atl_lead_ seguita da 43 caratteri. Vengono mostrate una sola volta, archiviate solo come impronta, verificate a ogni richiesta e possono essere revocate in qualsiasi momento (Revoke key). Un ambiente del sito può avere fino a 20 chiavi attive. La creazione di una chiave può richiedere una seconda conferma sul Suo telefono.
URL di base e autenticazione
Sezione intitolata “URL di base e autenticazione”https://<delivery host>/v1/leads-api/environments/{environmentId}Authorization: Bearer atl_lead_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXLe risposte sono Cache-Control: private, no-store. Gli errori usano il formato application/problem+json della RFC 9457.
Elencare i contatti
Sezione intitolata “Elencare i contatti”GET /leads?since=2026-10-01T00:00:00Z&limit=50&cursor=…
| Parametro | Note |
|---|---|
since |
Solo i contatti aggiornati a partire da questo momento. ISO 8601 con fuso orario |
limit |
Da 1 a 200, predefinito 50 |
cursor |
Il nextCursor della risposta precedente |
I contatti arrivano dalla modifica meno recente. La risposta è { "leads": [ … ], "nextCursor": "…" | null }. Continui a scorrere le pagine finché nextCursor è null e memorizzi l’ultimo updatedAt per recuperare solo le modifiche la volta successiva.
L’elenco include contatti uniti, anonimizzati e di prova. Controlli mergedInto, anonymisedAt e isTest.
Ottenere un contatto
Sezione intitolata “Ottenere un contatto”GET /leads/{leadId}
| Campo | Note |
|---|---|
id, source |
La fonte è il modulo o il chatbot da cui proviene il contatto |
form |
{ key, name }, oppure null per i contatti del chatbot |
name, email, phone, company, message |
Vuoti dopo che la conservazione ha rimosso i dati personali |
details |
Eventuali altre risposte |
status |
new, contacted, qualified, won, lost o spam |
isTest |
Invii di prova da Studio |
version |
La rimandi quando cambia lo stato |
mergedInto, anonymisedAt |
Impostati quando il contatto è stato unito o anonimizzato |
createdAt, updatedAt |
Timestamp ISO 8601 |
Cambiare lo stato di un contatto
Sezione intitolata “Cambiare lo stato di un contatto”PATCH /leads/{leadId}/status con { "status": "qualified", "expectedVersion": 4 }. Richiede l’autorizzazione Change lead status. La modifica compare nella cronologia del contatto come effettuata dalla chiave.
Errori e limiti
Sezione intitolata “Errori e limiti”| Stato | Codice | Significato |
|---|---|---|
| 401 | CP_UNAUTHENTICATED |
Chiave mancante, errata, scaduta o revocata |
| 403 | CP_FORBIDDEN |
La chiave non ha l’autorizzazione per questa richiesta |
| 404 | CP_NOT_FOUND |
Nessun contatto di questo tipo in questo ambiente |
| 409 | CP_VERSION_CONFLICT |
Il contatto è cambiato dopo che lo ha letto. Lo rilegga |
| 422 | REQUEST_SCHEMA_INVALID |
Il corpo della richiesta o un parametro non è valido |
| 422 | CURSOR_INVALID |
Il cursore non ha potuto essere letto |
| 429 | RATE_LIMITED |
Più di 300 richieste al minuto. Attenda e riprovi |
Il limite di frequenza è applicato per singolo server API di Atlas, quindi consideri 300 richieste al minuto un massimo, non una garanzia.