Vai al contenuto principale
L’endpoint Crea Lead ti consente di aggiungere in modo programmatico nuovi lead al tuo workspace AgencyHandy da qualsiasi sistema esterno — un modulo web, un CRM, una piattaforma di marketing automation o uno script personalizzato. I lead creati tramite questo endpoint appaiono immediatamente nella tua pipeline di lead, come se fossero stati aggiunti manualmente.
Prima di utilizzare questo endpoint, completa la guida Getting Started per ottenere la tua chiave API e l’ID Azienda. Devi anche recuperare il tuo ID Ruolo Cliente, richiesto durante la creazione di un lead.

​
Prerequisiti

  • ✅ Chiave API generata da Configurazione Workspace → Chiave API
  • ✅ ID Azienda recuperato da GET {{URL}}/accounts/companies
  • ✅ ID Ruolo Cliente recuperato (vedi Passo 1 di seguito)

​
Passo 1: Ottieni l’ID Ruolo Cliente

Prima di creare un lead, hai bisogno dell’ID Ruolo per il ruolo client nella tua azienda.

​
Endpoint

GET {{URL}}/roles?type=company
HeaderValore
x-api-keyLa tua chiave API
companyidIl tuo ID Azienda

​
Richiesta di esempio

cURL
curl --request GET "https://api.agencyhandy.com/roles?type=company" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --header "companyid: <YOUR_COMPANY_ID>"

​
Risposta di esempio

{
  "roles": [
    {
      "_id": "6525994184e9ddd798534535",
      "role": {
        "_id": "6525994184e9ddd79853451e",
        "responsibility": "",
        "name": "client"
      },
      "company": "6525994184e9ddd79853450e",
      "createdAt": "2023-10-10T18:34:41.567Z",
      "updatedAt": "2024-10-01T07:28:48.340Z",
      "__v": 0,
      "type": "company"
    }
  ]
}
Trova la voce in cui roles[0].role.name === "client" ed estrai l’_id esterno — ovvero roles[0]._id, non roles[0].role._id. 
const clientRoleId = roles.find(r => r.role.name === "client")._id;
// e.g. "6525994184e9ddd798534535"
Usa roles[0]._id (l’ID di mappatura del ruolo aziendale), non roles[0].role._id (l’ID della definizione del ruolo). Usare l’ID sbagliato causa il fallimento della richiesta di creazione del lead.

​
Passo 2: Crea un nuovo lead

​
Endpoint

POST {{URL}}/members/bulk-lead

​
Header

HeaderValore
x-api-keyLa tua chiave API
companyidIl tuo ID Azienda
Content-Typeapplication/json

​
Corpo della richiesta

Il corpo della richiesta è un array JSON — puoi creare uno o più lead in una singola chiamata.
​
firstName
string
obbligatorio
Il nome del lead.
​
lastName
string
obbligatorio
Il cognome del lead.
​
email
string
obbligatorio
L’indirizzo email del lead. Deve essere univoco all’interno del tuo workspace.
​
role
string
obbligatorio
L’ID Ruolo Cliente recuperato nel Passo 1 (ovvero roles[0]._id).
​
isConvertedClient
boolean
obbligatorio
Deve essere impostato su false durante la creazione di un lead. Impostalo su true solo quando converti un lead in un cliente completo.
​
status
string
Lo stato della pipeline del lead. Valori comuni: New, Contacted, Qualified. Predefinito a New se omesso.
​
contactNo
string
Il numero di telefono del lead.
​
source
string
Come hai acquisito questo lead. Valori di esempio: website, referral, social.
​
positionInBoard
number
La posizione (ordine) del lead all’interno della colonna della pipeline. Predefinito a 1.

​
Richiesta di esempio

cURL
curl --request POST "https://api.agencyhandy.com/members/bulk-lead" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --header "companyid: <YOUR_COMPANY_ID>" \
  --header "Content-Type: application/json" \
  --data '[
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "role": "6525994184e9ddd798534535",
      "isConvertedClient": false,
      "status": "New",
      "contactNo": "1234567890",
      "source": "website",
      "positionInBoard": 1
    }
  ]'

​
Risposta di successo

{
  "message": "Lead created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
​
message
string
Stringa di conferma: "Lead created successfully".
​
createdMembers
array
Array degli oggetti lead creati.
​
createdMembers[].\_id
string
L’ID univoco del lead appena creato. Salvalo se hai bisogno di fare riferimento al lead nelle successive chiamate API.
​
createdMembers[].name
string
Il nome completo del lead (nome + cognome).
​
createdMembers[].status
string
Lo stato della pipeline del lead come memorizzato.
​
createdMembers[].role
string
Il nome del ruolo assegnato al membro — sarà "client".
Puoi passare più oggetti lead nell’array per creare diversi lead in una singola chiamata API. Ogni oggetto deve includere tutti i campi obbligatori con il proprio indirizzo email univoco.