API per contatti, trattative e journey
Questi endpoint permettono al tuo codice, a Zapier o a n8n di agire sul tuo account: aggiungere contatti, aprire e spostare trattative, iscrivere contatti ai journey e leggere gli identificativi di cui queste chiamate hanno bisogno. Usano la stessa chiave API dell'API di invio.
Authorization: Bearer mia_live_...
Ogni famiglia di endpoint accetta 60 richieste al minuto per chiave. Oltre, ricevi 429. Gli errori arrivano come application/problem+json (RFC 9457: type, title, status, detail, error) con uno stato 4xx. Il contratto completo, con ogni forma di risposta, è nella specifica OpenAPI.
Contatti
Creare o aggiornare
POST /api/v1/contacts aggiunge un indirizzo a una lista di contatti, o lo aggiorna se c'è già:
{
"listId": "list_abc123",
"email": "[email protected]",
"fields": { "first_name": "Ada", "company": "Analytical Engines" }
}
Risponde 201 per un nuovo contatto e 200 per un aggiornamento, con il contatto salvato. Per inviarne fino a 500 in una volta, usa invece {"listId": "…", "contacts": [{"email": "…", "first_name": "…"}, …]}, che risponde con dei conteggi.
Ogni indirizzo viene verificato al salvataggio. L'API non registra mai una risposta sul consenso, quindi questi contatti ricevono gli invii come prima. Un singolo contatto che farebbe superare il limite di contatti del tuo piano riceve 409.
Cercare
GET /api/v1/[email protected] restituisce il contatto di quell'indirizzo in ogni lista, dal più recente. Aggiungi &listId= per cercare in una sola lista. Ogni ricerca viene registrata nel registro degli accessi ai dati personali del tuo account, come un contatto visualizzato nella dashboard.
Liste
GET /api/v1/lists restituisce id, name, fields e rowCount di ogni lista di contatti. Nessun dato dei contatti.
Trattative
Creare
POST /api/v1/deals:
{
"email": "[email protected]",
"title": "Annual plan",
"value": 1200,
"currency": "EUR"
}
Indica il contatto con email, oppure con listId più rowId. Con la sola email, la trattativa va sulla lista aggiornata più di recente che contiene l'indirizzo. Senza pipelineId e stageId, finisce nella prima fase aperta della tua pipeline predefinita. currency è USD per impostazione predefinita.
Invia un'intestazione Idempotency-Key (per esempio un numero d'ordine) per rendere sicuri i nuovi tentativi. Una ripetizione con la stessa chiave risponde 200 con "created": false invece di creare una seconda trattativa.
Aggiornare o spostare
PATCH /api/v1/deals/{id} accetta title, value, currency e stageId. Spostare in una fase vinta o persa chiude la trattativa. L'intero corpo viene verificato prima, quindi una fase sconosciuta non cambia nulla. Uno spostamento attiva l'attivatore di journey Cambio di fase di una trattativa e il webhook deal.stage_changed, come uno spostamento sulla bacheca.
Elencare
GET /api/v1/deals restituisce le tue trattative di tutte le pipeline, dalle spostate più di recente, nella stessa forma della risposta alla creazione. Filtra con pipelineId, stageId e status (open, won o lost). limit arriva a 500 (100 di default) e truncated dice se ne corrispondevano altre. Una trattativa riporta l'indirizzo del suo contatto, quindi ogni chiamata che restituisce trattative viene registrata nel registro degli accessi ai dati personali del tuo account.
Pipeline
GET /api/v1/pipelines restituisce le tue pipeline, quella predefinita per prima, ciascuna con le sue fasi (id, name, kind). Usalo per trovare lo stageId in cui spostare una trattativa.
Journey
GET /api/v1/journeys elenca i tuoi journey con identificativo, nome, attivatore e se sono attivi. ?trigger=api restituisce solo quelli a cui il tuo codice può iscrivere contatti.
POST /api/v1/journeys/{id}/trigger con {"email": "…", "listId": "…"} iscrive un contatto a un journey il cui attivatore è Chiamata API. Vedi journey.
Progetti email
GET /api/v1/projects restituisce id, name e purpose delle tue email dello studio, dalle modificate più di recente (fino a 200). Usa un id come projectId di un invio con modello. Senza il contenuto dell'email.
Eventi di esempio
GET /api/v1/events/sample?type=deal.stage_changed restituisce {"events": [ … ]} con una busta di webhook di esempio di quel tipo, oppure una per ogni tipo senza type. Gli strumenti di automazione lo usano per mostrarti i campi prima che arrivi un evento reale.
Webhook
GET, POST /api/v1/webhooks e DELETE /api/v1/webhooks/{id} gestiscono le iscrizioni agli eventi. Vedi webhook ed eventi.