API: creare lead e avviare chiamate

Con le API di Aptiva un tuo sistema può creare un lead (un contatto con almeno il numero di telefono) e far partire la chiamata dell'agente vocale AI verso quel contatto, poi leggere l'esito: come è andata, cosa si sono detti, quanto è durata. Sono due richieste HTTP: POST /leads/create, che restituisce l'id del lead, e POST /calls/start, che avvia la chiamata. È il flusso tipico di un form del sito o di un CRM che vuole richiamare chi ha appena lasciato i propri dati, mentre l'interesse è ancora caldo.

Questa guida spiega i due gruppi di endpoint con il loro comportamento reale, la cadenza automatica dei richiami (una funzione da conoscere per non stupirsi di un 204 senza chiamata immediata), i codici di errore, e chiude con l'esempio completo «form del sito → lead → chiamata → esito». Le convenzioni comuni (chiave, header X-API-Key, formato degli errori, paginazione) sono nella guida ai primi passi. Tutti i percorsi vanno aggiunti all'indirizzo base https://api.aptiva.cloud/external/api.

Creare un lead: upsert per telefono#

Un lead si crea con POST /leads/create e un body JSON in cui l'unico campo obbligatorio è phone. La risposta è 201 con l'identificativo del lead:

curl -sS -X POST "https://api.aptiva.cloud/external/api/leads/create" \
  -H "X-API-Key: $APTIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "<IL_TUO_NUMERO_DI_PROVA>",
    "name": "Mario",
    "lastName": "Rossi",
    "email": "mario.rossi@example.com",
    "leadCompanyName": "Rossi Srl",
    "additionalInfo": {
      "origine": "form preventivo",
      "prodotto": "impianto fotovoltaico 6 kW",
      "note": "preferisce essere richiamato al pomeriggio"
    },
    "leadMetadata": {
      "externalLeadId": "crm-88213"
    }
  }'

{ "id": 1285 }

La creazione è un upsert per telefono: la chiave di unicità è il numero normalizzato, all'interno della tua azienda. Se esiste già un lead con quel numero, non viene creato un duplicato: i campi che invii sovrascrivono quelli del lead esistente, i campi che non invii restano com'erano, e la risposta è comunque 201 con l'id del lead esistente. Il tuo codice non deve quindi distinguere fra «creato» e «aggiornato»: salva l'id e prosegui.

I campi del body:

Come viene validato e normalizzato il telefono#

Il numero di telefono viene accettato in qualunque scrittura leggibile (333 123 4567, +39 333 1234567, 0039 333 1234567, 333-1234567) e, se manca il prefisso internazionale, è considerato italiano. Viene poi verificato che sia un numero reale del piano di numerazione (non basta che siano cifre) e salvato nel formato internazionale E.164, per esempio +393331234567: è così che lo ritroverai in ogni risposta.

Un numero non valido fa fallire la richiesta con 422 e codice validation_error; nei details trovi phone_unparsable (non è interpretabile come numero) oppure phone_invalid (è scritto come un numero ma non esiste nel piano di numerazione, per esempio ha una cifra in più). Un buon form del sito valida il telefono prima di inviarlo, ma questo controllo è la rete di sicurezza che evita di far partire chiamate verso numeri inesistenti.

Se il numero è valido ma non si può chiamare, perché estero o a sovrapprezzo, la creazione di un lead nuovo o la modifica del telefono risponde 422 con phone_not_callable nei details: si chiamano solo fissi, cellulari, VoIP e numeri verdi italiani. Un lead che ha già quel numero, per esempio perché creato da una chiamata in entrata dall'estero, resta aggiornabile negli altri campi; avviare una chiamata verso di lui risponde invece 422 con CALL_DESTINATION_NOT_ALLOWED.

additionalInfo e leadMetadata: aggiornamento per fusione#

additionalInfo è un oggetto JSON libero in cui salvi il contesto del contatto: da dove arriva, cosa ha chiesto, note utili. L'agente vocale AI lo riceve come contesto quando chiama il lead (o quando il lead lo chiama), quindi è il modo per dirgli di cosa parlare («ha chiesto un preventivo per un impianto da 6 kW»); su richiesta possiamo limitare le chiavi che l'agente vede. Lo ritrovi nel dettaglio del lead e della chiamata.

Sia additionalInfo sia leadMetadata si aggiornano con la semantica del merge patch (JSON Merge Patch, RFC 7396):

• le chiavi che invii vengono aggiunte o sovrascritte;
• le chiavi che non invii restano;
• una chiave con valore null viene cancellata;
• gli oggetti annidati vengono fusi ricorsivamente con le stesse regole;
• inviare l'intero campo a null ("additionalInfo": null) svuota tutto.

Un esempio: il lead ha additionalInfo uguale a {"origine": "form", "prodotto": "fotovoltaico", "note": "pomeriggio"}. Inviando, in una creazione o in un aggiornamento, {"prodotto": "fotovoltaico + accumulo", "note": null, "budget": "15000"}, il risultato è {"origine": "form", "prodotto": "fotovoltaico + accumulo", "budget": "15000"}: origine è rimasto, prodotto è cambiato, note è sparito, budget è stato aggiunto.

Aggiornare un lead: PATCH e semantica dei null#

Un lead esistente si aggiorna con PATCH /leads/update/ID e un body con solo i campi da cambiare. La risposta è 204 senza corpo.

curl -sS -X PATCH "https://api.aptiva.cloud/external/api/leads/update/1285" \
  -H "X-API-Key: $APTIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leadCompanyName": null,
    "additionalInfo": { "esito_commerciale": "preventivo inviato", "note": null }
  }'

Le regole per i valori:

Se cambi phone, il lead cambia numero. Non usare un numero già presente su un altro lead della tua azienda: il telefono è unico per azienda e in quel caso la richiesta oggi fallisce con un errore del server (500, internal_error), non con un errore descrittivo. Altri errori: 404 con not_found se il lead non esiste, 403 con forbidden se appartiene a un'altra azienda.

Leggere i lead: elenco e dettaglio#

L'elenco dei lead è GET /leads, paginato e ordinato con pageNumber, pageSize, orderBy e isAscending come descritto nella guida ai primi passi; il corpo è un array di lead in forma compatta e i metadati sono nell'header X-Pagination.

[
  {
    "id": 1285,
    "email": "mario.rossi@example.com",
    "name": "Mario",
    "lastName": "Rossi",
    "phone": "+393331234567",
    "leadCompanyName": "Rossi Srl"
  }
]

Il dettaglio è GET /leads/ID e aggiunge createdAt, additionalInfo e leadMetadata:

{
  "id": 1285,
  "email": "mario.rossi@example.com",
  "name": "Mario",
  "lastName": "Rossi",
  "phone": "+393331234567",
  "leadCompanyName": "Rossi Srl",
  "createdAt": "2026-09-11T09:32:10.482Z",
  "additionalInfo": {
    "origine": "form preventivo",
    "prodotto": "impianto fotovoltaico 6 kW",
    "note": "preferisce essere richiamato al pomeriggio"
  },
  "leadMetadata": {
    "external_lead_id": "crm-88213"
  }
}

Una particolarità di leadMetadata: in scrittura la chiave si chiama externalLeadId, in lettura torna in snake_case, external_lead_id. Vale anche per il lead incluso nel dettaglio di una chiamata.

Non esiste una ricerca per telefono nell'elenco: GET /leads accetta solo i parametri di paginazione. Se ti serve l'id di un lead a partire dal numero, puoi richiamare POST /leads/create con il solo phone: se il lead esiste ottieni il suo id senza modificarne i dati, ma se non esiste viene creato. Per non creare lead per sbaglio, la via più solida è salvare l'id nel tuo sistema al momento della creazione, accanto al contatto.

Avviare una chiamata: leadId, agentId e force#

Una chiamata in uscita si avvia con POST /calls/start e un body con tre campi:

curl -sS -X POST "https://api.aptiva.cloud/external/api/calls/start" \
  -H "X-API-Key: $APTIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "leadId": 1285, "agentId": 42, "force": false }'

La risposta è 204 senza corpo e significa «richiesta accettata»: la chiamata è stata messa in coda per l'esecuzione immediata, oppure programmata secondo la cadenza descritta nella sezione seguente. Il 204 non significa che il telefono sta già squillando: l'esito si legge poi con GET /calls.

Gli errori all'avvio#

Il credito non blocca l'avvio: se al momento della chiamata il credito è insufficiente, la chiamata viene registrata con outcome 550 (credito insufficiente) e non viene effettuata, né conta nella cadenza dei richiami. Conviene controllare periodicamente gli esiti e aggiungere crediti, o tenere attivo il rinnovo automatico, prima che accada (Prezzi).

La cadenza dei richiami: una funzione, non un limite#

La cadenza dei richiami è una funzione pensata per il telemarketing e per il richiamo dei contatti: limita a cinque i tentativi automatici verso la stessa persona e li distribuisce con tempi fatti apposta per trovarla, senza che tu debba scrivere alcuna logica di ripianificazione.

La sequenza è sempre la stessa e dipende da quante chiamate il lead ha già ricevuto. Il ritardo si calcola dal momento in cui il richiamo viene programmato: la fine della chiamata precedente nella catena automatica, l'arrivo della richiesta per POST /calls/start.

Nella catena automatica, quindi, il quinto tentativo cade due giorni dopo il terzo: prima chiamata lunedì alle 10:00 senza risposta, seconda verso le 10:05, terza verso le 10:30, quarta martedì alle 13:00, quinta mercoledì alle 18:00.

Il conteggio si basa sulle chiamate già registrate per quel lead, comprese quelle in corso, escluse quelle con outcome 500 (fallita per errore tecnico) e 550 (credito insufficiente). Una chiamata fallita non consuma quindi un tentativo: il richiamo successivo viene programmato nello slot che sarebbe toccato a lei. Con un'eccezione: se il lead non ha altre chiamate valide (per esempio è fallita proprio la prima), il richiamo automatico non viene programmato; in quel caso tocca al tuo sistema riavviare la chiamata con POST /calls/start, che con conteggio zero parte subito.

I ritardi in minuti (5 e 25) rispettano la fascia dalle 9:00 alle 21:00 (ora italiana), con una regola calcolata sull'ora in cui il richiamo viene programmato, non sull'ora risultante: se sono già passate le 21:00, il richiamo va alle 9:00 del giorno dopo più il ritardo; se non sono ancora le 9:00, alle 9:00 dello stesso giorno più il ritardo; altrimenti parte dopo il ritardo, anche se l'ora risultante supera le 21:00 (una richiesta alle 20:50 con ritardo di 25 minuti viene programmata alle 21:15). Gli orari fissi delle 13:00 e delle 18:00 non hanno bisogno del controllo. La fascia non si applica alla prima chiamata a un lead né alle chiamate con force a true, che partono subito a qualunque ora. È voluto: un contatto che ha appena compilato un form è nel momento di massimo interesse, e va richiamato in quel momento. Se per il tuo caso d'uso preferisci non chiamare in certi orari, decidi tu quando avviare la chiamata.

La cadenza entra in gioco in tre modi:

1. In automatico, dopo una chiamata senza risposta. Se una chiamata in uscita finisce con outcome 101 (occupato), 102 (nessuna risposta), 103 (segreteria) o 500 (fallita), Aptiva programma da sola il tentativo successivo secondo la tabella. Nel dettaglio della chiamata il campo recallAt indica quando partirà. Non devi richiamare POST /calls/start: se lo fai, aggiungi un tentativo a quelli già programmati.
2. Quando avvii tu una chiamata con force a false (il valore predefinito) verso un lead già chiamato: la richiesta non parte subito ma viene programmata nello slot corrispondente al numero di chiamate già fatte. È il comportamento giusto per un CRM che «rimette in coda» un contatto senza preoccuparsi di quando chiamarlo.
3. Quando è la persona a chiedere di essere richiamata. Per le chiamate in uscita che finiscono con outcome 201, 300, 301 o 302, l'analisi post-chiamata può fissare recallAt a partire da ciò che la persona ha detto («richiamatemi domani alle 11»): la chiamata viene programmata a quell'ora, senza il controllo del conteggio né della fascia oraria. Se invece la persona ha chiesto di parlare con un umano (callAnalysis.humanCallbackRequest presente), non viene programmato alcun richiamo automatico: la palla passa a te.

Con force a true la chiamata viene messa in coda subito, qualunque sia lo storico del lead: è la scelta giusta quando è il contatto stesso ad aver chiesto di essere richiamato ora (un form appena inviato, un pulsante «richiamami»). Dal pannello di Aptiva la chiamata manuale è sempre forzata; via API la scelta è tua. Anche dopo una chiamata forzata senza risposta, i tentativi successivi vengono programmati in automatico.

Due punti da dichiarare con chiarezza. Primo: il limite dei cinque tentativi vale per la cadenza automatica e per POST /calls/start con force a false; non vale per force a true né per i richiami fissati dall'analisi post-chiamata. Secondo: oltre il quinto tentativo POST /calls/start con force a false risponde 204 senza generare nuove chiamate. Se il tuo sistema deve sapere se una chiamata è stata davvero creata, controlla poi GET /calls e non fidarti del solo stato HTTP. Per richiamare un contatto che ha già esaurito i tentativi, usa force a true.

Leggere le chiamate: esito, trascrizione, durate#

L'elenco delle chiamate è GET /calls, paginato come i lead; per vedere le più recenti per prime usa isAscending=false, e con orderBy puoi ordinarle anche per duration o outcome. Ogni elemento è in forma compatta:

[
  {
    "id": 9876,
    "lead": {
      "id": 1285,
      "email": "mario.rossi@example.com",
      "name": "Mario",
      "lastName": "Rossi",
      "phone": "+393331234567",
      "leadCompanyName": "Rossi Srl"
    },
    "createdAt": "2026-09-11T09:32:41.115Z",
    "outcome": 200,
    "duration": 184,
    "direction": 1,
    "callInfo": null,
    "voicebotConfig": { "id": 42, "name": "Richiamo preventivi", "direction": 1 }
  }
]

Il dettaglio GET /calls/ID aggiunge il lead completo (con additionalInfo), la trascrizione, l'analisi e le durate:

{
  "id": 9876,
  "lead": { "id": 1285, "phone": "+393331234567", "name": "Mario", "lastName": "Rossi", "email": "mario.rossi@example.com", "leadCompanyName": "Rossi Srl", "createdAt": "2026-09-11T09:32:10.482Z", "additionalInfo": { "origine": "form preventivo" }, "leadMetadata": { "external_lead_id": "crm-88213" } },
  "createdAt": "2026-09-11T09:32:41.115Z",
  "outcome": 200,
  "duration": 184,
  "direction": 1,
  "voicebotConfig": { "id": 42, "name": "Richiamo preventivi", "direction": 1 },
  "transcriptionItems": [
    { "timestamp": "2026-09-11T09:32:45.002Z", "role": "assistant", "content": "Buongiorno, sono l'assistente di Rossi Energia, la chiamo per il preventivo richiesto sul nostro sito...", "aiInterrupted": false },
    { "timestamp": "2026-09-11T09:32:52.410Z", "role": "user", "content": "Sì, buongiorno, volevo capire i tempi di installazione.", "aiInterrupted": false }
  ],
  "callAnalysis": {
    "recap": "Il cliente conferma l'interesse per l'impianto da 6 kW e chiede i tempi di installazione; concordato che un tecnico lo richiami entro venerdì per fissare il sopralluogo.",
    "humanCallbackRequest": {
      "target": "specific_person",
      "targetLabel": "tecnico commerciale",
      "preferredTimeText": "entro venerdì, pomeriggio",
      "reason": "fissare il sopralluogo"
    }
  },
  "recallAt": null,
  "callInfo": null,
  "durationWithAiSec": null,
  "sipBridgeDurationSec": null
}

I campi da conoscere:

• outcome: codice numerico dell'esito (tabella sotto). È null finché la chiamata non è conclusa.
• direction: 0 chiamata in entrata, 1 chiamata in uscita.
• transcriptionItems: la conversazione turno per turno, con role (assistant è l'agente, user è la persona), content e aiInterrupted (true se la persona ha interrotto l'agente mentre parlava).
• callAnalysis.recap: il riepilogo della chiamata scritto dall'agente; callAnalysis.humanCallbackRequest: presente se la persona ha chiesto di essere richiamata da un umano, con target (operator o specific_person), targetLabel, preferredTimeText e reason.
• recallAt: data e ora del prossimo tentativo programmato, dopo una chiamata senza risposta (cadenza dei richiami) o quando la persona ha chiesto di essere richiamata (analisi post-chiamata); null negli altri casi. Attenzione al formato: è espresso in UTC senza indicazione del fuso, a differenza di createdAt che termina con Z. Un valore come 2026-09-12T11:00:00 va letto come le 11:00 UTC, cioè le 13:00 ora italiana con l'ora estiva: prima di interpretarlo, trattalo come UTC (per esempio aggiungendo Z).
• durationWithAiSec e sipBridgeDurationSec: valorizzati solo se c'è stato un trasferimento di chiamata a una persona che ha risposto; il primo sono i secondi con l'agente AI prima del passaggio, il secondo i secondi della conversazione dopo. Senza trasferimento sono entrambi null. duration è la durata complessiva in secondi.
• callInfo: informazioni tecniche aggiuntive, non strutturate; può essere null.

Non c'è la registrazione audio nelle API: si ascolta dal pannello.

I codici di outcome#

Per un cruscotto o un CRM, la lettura più utile è per famiglia: 1xx riprova (o lascia fare alla cadenza dei richiami), 2xx lavora sul recap, 3xx guarda humanCallbackRequest e recallAt, 5xx controlla il credito o scrivici.

Esempio completo: dal form del sito all'esito della chiamata#

Lo scenario: un visitatore compila il form «richiedi un preventivo» sul tuo sito e vuoi che l'agente lo chiami entro pochi secondi, poi vuoi vedere nel tuo CRM com'è andata. Tutto avviene sul tuo server, mai nel browser (la chiave API non deve uscire dal server).

Passo 1: il form invia i dati al tuo server. Il tuo backend riceve nome, telefono, email e la richiesta.

Passo 2: il server crea il lead. Salvi la richiesta in additionalInfo, così l'agente sa di cosa parlare, e il tuo id in leadMetadata.externalLeadId.

curl -sS -X POST "https://api.aptiva.cloud/external/api/leads/create" \
  -H "X-API-Key: $APTIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "<IL_TUO_NUMERO_DI_PROVA>",
    "name": "Mario",
    "lastName": "Rossi",
    "email": "mario.rossi@example.com",
    "additionalInfo": {
      "origine": "form preventivo sito",
      "richiesta": "impianto fotovoltaico 6 kW con accumulo, casa indipendente a Bergamo",
      "inviato_il": "2026-09-11T09:32:00+02:00"
    },
    "leadMetadata": { "externalLeadId": "crm-88213" }
  }'

Risposta: 201 con {"id": 1285}. Salva 1285 accanto al contatto nel tuo CRM.

Passo 3: il server avvia la chiamata, forzandola. È il contatto stesso ad aver chiesto di essere contattato ora, quindi force a true: parte subito anche se in passato lo avevi già chiamato.

curl -sS -X POST "https://api.aptiva.cloud/external/api/calls/start" \
  -H "X-API-Key: $APTIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "leadId": 1285, "agentId": 42, "force": true }'

Risposta: 204. Se ricevi 422 con OUTBOUND_CONFIG_REQUIRED, l'agente 42 non è un agente per chiamate in uscita: nel pannello controlla la direzione dell'agente.

Sull'orario: la chiamata parte subito a qualunque ora, anche se il form arriva di sera. È il comportamento pensato per il telemarketing: chi ha appena lasciato i suoi dati è nel momento di massimo interesse, e richiamarlo in pochi secondi fa la differenza. Se per la tua attività preferisci non chiamare in certi orari, avvia la chiamata dal tuo sistema all'orario che scegli: force a false non la rimanda, perché la prima chiamata a un lead nuovo parte comunque subito.

Passo 4: il server legge l'esito. Qualche minuto dopo (o con un controllo periodico ogni minuto), leggi le chiamate più recenti e prendi quelle del tuo lead:

curl -sS "https://api.aptiva.cloud/external/api/calls?pageNumber=0&pageSize=50&isAscending=false" \
  -H "X-API-Key: $APTIVA_API_KEY"

Nell'array cerca gli elementi con lead.id uguale a 1285; il primo è la chiamata più recente. Se non trovi ancora nulla, la chiamata è in coda o programmata: il record viene creato nel momento in cui viene eseguita. Finché outcome è null la chiamata è in corso. Quando ha un valore, chiedi il dettaglio:

curl -sS "https://api.aptiva.cloud/external/api/calls/9876" \
  -H "X-API-Key: $APTIVA_API_KEY"

Passo 5: aggiorna il tuo CRM. Con outcome 200 o 201 salva callAnalysis.recap come nota e, se humanCallbackRequest è presente, crea un'attività per la persona indicata con preferredTimeText. Con 101, 102 o 103 non fare niente: la cadenza dei richiami ha già programmato il tentativo successivo, e recallAt ti dice quando (in UTC); segna nel CRM «richiamo automatico previsto» e ricontrolla dopo quell'ora. Con 301 guarda recallAt: se è valorizzato, il richiamo all'ora chiesta dalla persona è già programmato.

In tutto sono due richieste per far partire la chiamata e una o due per leggere l'esito. Per confrontare i tempi di risposta reali con quelli del tuo team, createdAt della chiamata meno inviato_il del form ti dà i secondi trascorsi fra la richiesta e la chiamata.

Prossimi passi#

1. Prova il flusso con il tuo numero: crea il lead, avvia la chiamata con force a true e leggi il dettaglio con la trascrizione. Se non hai ancora la chiave, la guida ai primi passi spiega dove trovarla.
2. Se l'agente deve poter passare la chiamata a una persona, configura il trasferimento con API: configurare il trasferimento di chiamata, e leggi come funziona in Trasferimento assistito: l'agente AI passa la chiamata.
3. Per volumi importanti (importazioni di migliaia di contatti, campagne) o per esigenze che le API non coprono ancora, scrivici dalla pagina Contatti: troviamo insieme la soluzione. I costi delle chiamate sono nella pagina Prezzi.