Salt la conținutul principal
Endpoint-ul Creare Lead vă permite să adăugați programatic lead-uri noi în spațiul dvs. de lucru AgencyHandy din orice sistem extern — un formular web, un CRM, o platformă de automatizare marketing sau un script personalizat. Lead-urile create prin acest endpoint apar imediat în pipeline-ul dvs. de lead-uri, exact ca și cum ar fi fost adăugate manual.
Înainte de a utiliza acest endpoint, parcurgeți ghidul Noțiuni de bază pentru a obține cheia API și ID-ul companiei. De asemenea, trebuie să obțineți ID-ul rolului de client, care este necesar la crearea unui lead.

​
Cerințe preliminare

  • ✅ Cheie API generată din Configurare spațiu de lucru → Cheie API
  • ✅ ID companie recuperat din GET {{URL}}/accounts/companies
  • ✅ ID rol client recuperat (consultați Pasul 1 de mai jos)

​
Pasul 1: Obțineți ID-ul rolului de client

Înainte de a crea un lead, aveți nevoie de ID-ul rolului pentru rolul client din compania dvs.

​
Endpoint

GET {{URL}}/roles?type=company

​
Header-e

HeaderValoare
x-api-keyCheia dvs. API
companyidID-ul companiei dvs.

​
Exemplu de solicitare

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

​
Exemplu de răspuns

{
  "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"
    }
  ]
}
Găsiți intrarea unde roles[0].role.name === "client" și extrageți _id-ul exterior — adică roles[0]._id, nu roles[0].role._id. 
const clientRoleId = roles.find(r => r.role.name === "client")._id;
// e.g. "6525994184e9ddd798534535"
Utilizați roles[0]._id (ID-ul de mapare companie-rol), nu roles[0].role._id (ID-ul definiției rolului). Utilizarea ID-ului greșit face ca solicitarea de creare a lead-ului să eșueze.

​
Pasul 2: Creați un lead nou

​
Endpoint

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

​
Header-e

HeaderValoare
x-api-keyCheia dvs. API
companyidID-ul companiei dvs.
Content-Typeapplication/json

​
Corpul solicitării

Corpul solicitării este un array JSON — puteți crea unul sau mai multe lead-uri într-un singur apel.
​
firstName
string
obligatoriu
Prenumele lead-ului.
​
lastName
string
obligatoriu
Numele de familie al lead-ului.
​
email
string
obligatoriu
Adresa de e-mail a lead-ului. Trebuie să fie unică în spațiul dvs. de lucru.
​
role
string
obligatoriu
ID-ul rolului de client recuperat în Pasul 1 (adică roles[0]._id).
​
isConvertedClient
boolean
obligatoriu
Trebuie setat la false la crearea unui lead. Setați la true numai la conversia unui lead într-un client complet.
​
status
string
Statusul lead-ului în pipeline. Valori comune: New, Contacted, Qualified. Implicit New dacă este omis.
​
contactNo
string
Numărul de telefon al lead-ului.
​
source
string
Cum ați achiziționat acest lead. Exemple: website, referral, social.
​
positionInBoard
number
Poziția lead-ului (ordinea) în coloana panoului de pipeline. Implicit 1.

​
Exemplu de solicitare

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
    }
  ]'

​
Răspuns de succes

{
  "message": "Lead created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
​
message
string
Șir de confirmare: "Lead created successfully".
​
createdMembers
array
Array de obiecte lead create.
​
createdMembers[].\_id
string
ID-ul unic al lead-ului creat recent. Stocați-l dacă trebuie să faceți referire la lead în apeluri API ulterioare.
​
createdMembers[].name
string
Numele complet al lead-ului (firstName + lastName).
​
createdMembers[].status
string
Statusul pipeline-ului al lead-ului așa cum este stocat.
​
createdMembers[].role
string
Numele rolului atribuit membrului — va fi "client".
Puteți transmite mai multe obiecte lead în array pentru a crea mai multe lead-uri într-un singur apel API. Fiecare obiect trebuie să includă toate câmpurile obligatorii cu propria adresă de e-mail unică.