Langsung ke konten utama
Endpoint Create Lead memungkinkan Anda menambahkan lead baru ke workspace AgencyHandy secara terprogram dari sistem eksternal mana pun — formulir web, CRM, platform otomasi pemasaran, atau skrip kustom. Lead yang dibuat melalui endpoint ini langsung muncul di pipeline lead Anda, sama seperti jika ditambahkan secara manual.
Sebelum menggunakan endpoint ini, selesaikan panduan Memulai untuk mendapatkan API key dan Company ID Anda. Anda juga perlu mengambil Client Role ID, yang diperlukan saat membuat lead.

​
Prasyarat

  • ✅ API key yang dibuat dari Workspace Config → API Key
  • ✅ Company ID yang diambil dari GET {{URL}}/accounts/companies
  • ✅ Client Role ID yang diambil (lihat Langkah 1 di bawah)

​
Langkah 1: Dapatkan Client Role ID

Sebelum membuat lead, Anda memerlukan Role ID untuk peran client di perusahaan Anda.

​
Endpoint

GET {{URL}}/roles?type=company
HeaderNilai
x-api-keyAPI key Anda
companyidCompany ID Anda

​
Contoh permintaan

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

​
Contoh respons

{
  "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"
    }
  ]
}
Temukan entri di mana roles[0].role.name === "client" dan ekstrak _id terluar — yaitu roles[0]._id, bukan roles[0].role._id. 
const clientRoleId = roles.find(r => r.role.name === "client")._id;
// e.g. "6525994184e9ddd798534535"
Gunakan roles[0]._id (ID pemetaan company-role), bukan roles[0].role._id (ID definisi peran). Menggunakan ID yang salah menyebabkan permintaan pembuatan lead gagal.

​
Langkah 2: Buat lead baru

​
Endpoint

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

​
Header

HeaderNilai
x-api-keyAPI key Anda
companyidCompany ID Anda
Content-Typeapplication/json

​
Isi permintaan

Isi permintaan adalah array JSON — Anda dapat membuat satu atau lebih lead dalam satu panggilan.
​
firstName
string
wajib
Nama depan lead.
​
lastName
string
wajib
Nama belakang lead.
​
email
string
wajib
Alamat email lead. Harus unik dalam workspace Anda.
​
role
string
wajib
Client Role ID yang diambil pada Langkah 1 (yaitu, roles[0]._id).
​
isConvertedClient
boolean
wajib
Harus diatur ke false saat membuat lead. Atur ke true hanya saat mengonversi lead menjadi klien penuh.
​
status
string
Status pipeline lead. Nilai umum: New, Contacted, Qualified. Default ke New jika dihilangkan.
​
contactNo
string
Nomor telepon lead.
​
source
string
Cara Anda mendapatkan lead ini. Contoh nilai: website, referral, social.
​
positionInBoard
number
Posisi (urutan) lead dalam kolom papan pipeline. Default ke 1.

​
Contoh permintaan

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

​
Respons sukses

{
  "message": "Lead created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
​
message
string
String konfirmasi: "Lead created successfully".
​
createdMembers
array
Array objek lead yang telah dibuat.
​
createdMembers[].\_id
string
ID unik dari lead yang baru dibuat. Simpan ini jika Anda perlu mereferensikan lead dalam panggilan API berikutnya.
​
createdMembers[].name
string
Nama lengkap lead (firstName + lastName).
​
createdMembers[].status
string
Status pipeline lead yang tersimpan.
​
createdMembers[].role
string
Nama peran yang ditetapkan ke anggota — akan menjadi "client".
Anda dapat meneruskan beberapa objek lead dalam array untuk membuat beberapa lead dalam satu panggilan API. Setiap objek harus menyertakan semua kolom yang diperlukan dengan alamat email uniknya sendiri.