Přejít na hlavní obsah
Endpoint pro vytvoření leadu umožňuje programově přidávat nové leady do vašeho workspace AgencyHandy z libovolného externího systému — webového formuláře, CRM, platformy pro marketingovou automatizaci nebo vlastního skriptu. Leady vytvořené prostřednictvím tohoto endpointu se okamžitě zobrazí v pipeline leadů, jako by byly přidány ručně.
Před použitím tohoto endpointu dokončete průvodce Začínáme a získejte svůj API klíč a ID společnosti. Také potřebujete získat ID role klienta, které je vyžadováno při vytváření leadu.

​
Předpoklady

  • ✅ API klíč vygenerovaný z Konfigurace workspace → API klíč
  • ✅ ID společnosti získané z GET {{URL}}/accounts/companies
  • ✅ ID role klienta získáno (viz Krok 1 níže)

​
Krok 1: Získejte ID role klienta

Před vytvořením leadu potřebujete ID role pro roli client ve vaší společnosti.

​
Endpoint

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

​
Hlavičky

HlavičkaHodnota
x-api-keyVáš API klíč
companyidVaše ID společnosti

​
Ukázkový požadavek

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

​
Ukázková odpověď

{
  "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"
    }
  ]
}
Najděte záznam, kde roles[0].role.name === "client", a extrahujte vnější _id — to je roles[0]._id, nikoli roles[0].role._id. 
const clientRoleId = roles.find(r => r.role.name === "client")._id;
// e.g. "6525994184e9ddd798534535"
Použijte roles[0]._id (ID mapování role na společnost), nikoli roles[0].role._id (ID definice role). Použití nesprávného ID způsobí selhání požadavku na vytvoření leadu.

​
Krok 2: Vytvoření nového leadu

​
Endpoint

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

​
Hlavičky

HlavičkaHodnota
x-api-keyVáš API klíč
companyidVaše ID společnosti
Content-Typeapplication/json

​
Tělo požadavku

Tělo požadavku je JSON pole — v jednom volání můžete vytvořit jeden nebo více leadů.
​
firstName
string
povinné
Křestní jméno leadu.
​
lastName
string
povinné
Příjmení leadu.
​
email
string
povinné
E-mailová adresa leadu. Musí být jedinečná v rámci vašeho workspace.
​
role
string
povinné
ID role klienta získané v Kroku 1 (tj. roles[0]._id).
​
isConvertedClient
boolean
povinné
Při vytváření leadu musí být nastaveno na false. Nastavte na true pouze při převodu leadu na plnohodnotného klienta.
​
status
string
Stav leadu v pipeline. Běžné hodnoty: New, Contacted, Qualified. Výchozí hodnota je New, pokud není zadáno.
​
contactNo
string
Telefonní číslo leadu.
​
source
string
Způsob získání tohoto leadu. Příklady hodnot: website, referral, social.
​
positionInBoard
number
Pozice (pořadí) leadu ve sloupci pipeline. Výchozí hodnota je 1.

​
Ukázkový požadavek

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

​
Odpověď při úspěchu

{
  "message": "Lead created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
​
message
string
Potvrzovací řetězec: "Lead created successfully".
​
createdMembers
array
Pole vytvořených objektů leadů.
​
createdMembers[].\_id
string
Jedinečné ID nově vytvořeného leadu. Uložte jej, pokud potřebujete na lead odkazovat v následných voláních API.
​
createdMembers[].name
string
Celé jméno leadu (křestní jméno + příjmení).
​
createdMembers[].status
string
Stav leadu v pipeline tak, jak je uložen.
​
createdMembers[].role
string
Název role přiřazené členovi — bude "client".
V poli můžete předat více objektů leadů a vytvořit tak několik leadů v jednom volání API. Každý objekt musí obsahovat všechna povinná pole s vlastní jedinečnou e-mailovou adresou.