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 {"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.

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.

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.