Naar hoofdinhoud gaan
Met het eindpunt Lead aanmaken kunt u programmatisch nieuwe leads toevoegen aan uw AgencyHandy-werkruimte vanuit elk extern systeem — een webformulier, een CRM, een marketingautomatiseringsplatform of een aangepast script. Leads die via dit eindpunt worden aangemaakt, verschijnen onmiddellijk in uw lead-pipeline, alsof ze handmatig zijn toegevoegd.
Voltooi voordat u dit eindpunt gebruikt de gids Aan de Slag om uw API-sleutel en Bedrijfs-ID te verkrijgen. U heeft ook uw Klantrol-ID nodig, die vereist is bij het aanmaken van een lead.

​
Vereisten

  • ✅ API-sleutel gegenereerd vanuit Werkruimteconfiguratie → API-sleutel
  • ✅ Bedrijfs-ID opgehaald via GET {{URL}}/accounts/companies
  • ✅ Klantrol-ID opgehaald (zie Stap 1 hieronder)

​
Stap 1: Haal de Klantrol-ID op

Voordat u een lead aanmaakt, heeft u de Rol-ID nodig voor de client-rol in uw bedrijf.

​
Eindpunt

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

​
Headers

HeaderWaarde
x-api-keyUw API-sleutel
companyidUw Bedrijfs-ID

​
Voorbeeldverzoek

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

​
Voorbeeldantwoord

{
  "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"
    }
  ]
}
Zoek het item waar roles[0].role.name === "client" en extraheer de buitenste _id — dat is roles[0]._id, niet roles[0].role._id. 
const clientRoleId = roles.find(r => r.role.name === "client")._id;
// bijv. "6525994184e9ddd798534535"
Gebruik roles[0]._id (het bedrijfsrol-koppeling-ID), niet roles[0].role._id (het roldefinitie-ID). Het gebruik van het verkeerde ID zorgt ervoor dat het verzoek voor het aanmaken van de lead mislukt.

​
Stap 2: Maak een nieuwe lead aan

​
Eindpunt

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

​
Headers

HeaderWaarde
x-api-keyUw API-sleutel
companyidUw Bedrijfs-ID
Content-Typeapplication/json

​
Verzoekbody

De verzoekbody is een JSON-array — u kunt één of meer leads aanmaken in één aanroep.
​
firstName
string
vereist
De voornaam van de lead.
​
lastName
string
vereist
De achternaam van de lead.
​
email
string
vereist
Het e-mailadres van de lead. Moet uniek zijn binnen uw werkruimte.
​
role
string
vereist
De Klantrol-ID opgehaald in Stap 1 (d.w.z. roles[0]._id).
​
isConvertedClient
boolean
vereist
Moet worden ingesteld op false bij het aanmaken van een lead. Stel in op true alleen bij het converteren van een lead naar een volwaardige klant.
​
status
string
De pipelinestatus van de lead. Veelgebruikte waarden: New, Contacted, Qualified. Standaard New indien weggelaten.
​
contactNo
string
Het telefoonnummer van de lead.
​
source
string
Hoe u deze lead heeft verkregen. Voorbeeldwaarden: website, referral, social.
​
positionInBoard
number
De positie (volgorde) van de lead binnen de pipelinebordkolom. Standaard 1.

​
Voorbeeldverzoek

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

​
Succesantwoord

{
  "message": "Lead created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
​
message
string
Bevestigingsreeks: "Lead created successfully".
​
createdMembers
array
Array van aangemaakte lead-objecten.
​
createdMembers[].\_id
string
Het unieke ID van de nieuw aangemaakte lead. Bewaar dit als u naar de lead wilt verwijzen in volgende API-aanroepen.
​
createdMembers[].name
string
De volledige naam van de lead (voornaam + achternaam).
​
createdMembers[].status
string
De pipelinestatus van de lead zoals opgeslagen.
​
createdMembers[].role
string
De rolnaam die aan het lid is toegewezen — wordt "client".
U kunt meerdere lead-objecten in de array doorgeven om meerdere leads aan te maken in één API-aanroep. Elk object moet alle vereiste velden bevatten met een eigen uniek e-mailadres.