Przejdź do głównej treści
Punkt końcowy tworzenia leada umożliwia programowe dodawanie nowych leadów do przestrzeni roboczej AgencyHandy z dowolnego zewnętrznego systemu — formularza internetowego, systemu CRM, platformy automatyzacji marketingu lub niestandardowego skryptu. Leady utworzone za pomocą tego punktu końcowego pojawiają się natychmiast w Twoim lejku sprzedażowym, tak jakby zostały dodane ręcznie.
Przed użyciem tego punktu końcowego ukończ przewodnik Pierwsze kroki, aby uzyskać klucz API i identyfikator firmy. Potrzebujesz również pobrać swój identyfikator roli klienta, który jest wymagany przy tworzeniu leada.

​
Wymagania wstępne

  • ✅ Klucz API wygenerowany z Konfiguracja przestrzeni roboczej → Klucz API
  • ✅ Identyfikator firmy pobrany z GET {{URL}}/accounts/companies
  • ✅ Identyfikator roli klienta pobrany (patrz Krok 1 poniżej)

​
Krok 1: Pobierz identyfikator roli klienta

Przed utworzeniem leada potrzebujesz identyfikatora roli client w swojej firmie.

​
Punkt końcowy

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

​
Nagłówki

NagłówekWartość
x-api-keyTwój klucz API
companyidTwój identyfikator firmy

​
Przykładowe żądanie

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

​
Przykładowa odpowiedź

{
  "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"
    }
  ]
}
Znajdź wpis, gdzie roles[0].role.name === "client" i wyodrębnij zewnętrzny _id — to jest roles[0]._id, nie roles[0].role._id. 
const clientRoleId = roles.find(r => r.role.name === "client")._id;
// e.g. "6525994184e9ddd798534535"
Użyj roles[0]._id (identyfikatora mapowania roli firmowej), nie roles[0].role._id (identyfikatora definicji roli). Użycie nieprawidłowego identyfikatora spowoduje niepowodzenie żądania utworzenia leada.

​
Krok 2: Utwórz nowego leada

​
Punkt końcowy

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

​
Nagłówki

NagłówekWartość
x-api-keyTwój klucz API
companyidTwój identyfikator firmy
Content-Typeapplication/json

​
Ciało żądania

Ciało żądania jest tablicą JSON — możesz utworzyć jednego lub więcej leadów w jednym wywołaniu.
​
firstName
string
wymagane
Imię leada.
​
lastName
string
wymagane
Nazwisko leada.
​
email
string
wymagane
Adres e-mail leada. Musi być unikalny w obrębie Twojej przestrzeni roboczej.
​
role
string
wymagane
Identyfikator roli klienta pobrany w Kroku 1 (tj. roles[0]._id).
​
isConvertedClient
boolean
wymagane
Musi być ustawione na false przy tworzeniu leada. Ustaw na true tylko przy konwersji leada na pełnego klienta.
​
status
string
Status leada w lejku sprzedażowym. Typowe wartości: New, Contacted, Qualified. Domyślnie New, jeśli pominięte.
​
contactNo
string
Numer telefonu leada.
​
source
string
Sposób pozyskania tego leada. Przykładowe wartości: website, referral, social.
​
positionInBoard
number
Pozycja leada (kolejność) w kolumnie tablicy lejka. Domyślnie 1.

​
Przykładowe żądanie

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

​
Odpowiedź sukcesu

{
  "message": "Lead created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
​
message
string
Ciąg potwierdzający: "Lead created successfully".
​
createdMembers
array
Tablica utworzonych obiektów leadów.
​
createdMembers[].\_id
string
Unikalny identyfikator nowo utworzonego leada. Zapisz go, jeśli chcesz odwoływać się do leada w kolejnych wywołaniach API.
​
createdMembers[].name
string
Pełne imię i nazwisko leada (imię + nazwisko).
​
createdMembers[].status
string
Status leada w lejku sprzedażowym, tak jak został zapisany.
​
createdMembers[].role
string
Nazwa roli przypisanej do członka — będzie to "client".
Możesz przekazać wiele obiektów leadów w tablicy, aby utworzyć kilku leadów w jednym wywołaniu API. Każdy obiekt musi zawierać wszystkie wymagane pola z własnym unikalnym adresem e-mail.