跳轉到主要內容
建立潛在客戶端點讓您能夠從任何外部系統（網頁表單、CRM、行銷自動化平台或自訂腳本）以程式方式將新的潛在客戶新增至您的 AgencyHandy 工作區。透過此端點建立的潛在客戶將立即出現在您的潛在客戶管道中，就像手動新增一樣。
使用此端點前，請先完成入門指南以取得您的 API 金鑰和公司 ID。您還需要取得客戶角色 ID，這在建立潛在客戶時為必要項目。

​
前置條件

  • ✅ 從 Workspace Config → API Key 產生的 API 金鑰
  • ✅ 從 GET {{URL}}/accounts/companies 取得的公司 ID
  • ✅ 已取得客戶角色 ID（請參閱下方步驟 1）

​
步驟 1：取得客戶角色 ID

建立潛在客戶之前，您需要公司中 client 角色的角色 ID。

​
端點

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

​
標頭

標頭值
x-api-key您的 API 金鑰
companyid您的公司 ID

​
範例請求

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

​
範例回應

{
  "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"
    }
  ]
}
找到 roles[0].role.name === "client" 的條目，並提取外層 _id — 即 roles[0]._id，而非 roles[0].role._id。 
const clientRoleId = roles.find(r => r.role.name === "client")._id;
// e.g. "6525994184e9ddd798534535"
請使用 roles[0]._id（公司-角色對應 ID），而非 roles[0].role._id（角色定義 ID）。使用錯誤的 ID 會導致潛在客戶建立請求失敗。

​
步驟 2：建立新的潛在客戶

​
端點

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

​
標頭

標頭值
x-api-key您的 API 金鑰
companyid您的公司 ID
Content-Typeapplication/json

​
請求主體

請求主體為 JSON 陣列 — 您可以在單次呼叫中建立一個或多個潛在客戶。
​
firstName
string
必填
潛在客戶的名字。
​
lastName
string
必填
潛在客戶的姓氏。
​
email
string
必填
潛在客戶的電子郵件地址。在您的工作區內必須是唯一的。
​
role
string
必填
步驟 1 中取得的客戶角色 ID（即 roles[0]._id）。
​
isConvertedClient
boolean
必填
建立潛在客戶時必須設定為 false。僅在將潛在客戶轉換為正式客戶時設定為 true。
​
status
string
潛在客戶的管道狀態。常用值：New、Contacted、Qualified。若省略則預設為 New。
​
contactNo
string
潛在客戶的電話號碼。
​
source
string
您獲取此潛在客戶的管道。範例值：website、referral、social。
​
positionInBoard
number
潛在客戶在管道看板欄位中的位置（順序）。預設為 1。

​
範例請求

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

​
成功回應

{
  "message": "Lead created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
​
message
string
確認字串："Lead created successfully"。
​
createdMembers
array
已建立的潛在客戶物件陣列。
​
createdMembers[].\_id
string
新建立潛在客戶的唯一 ID。若您需要在後續 API 呼叫中引用此潛在客戶，請儲存此 ID。
​
createdMembers[].name
string
潛在客戶的全名（firstName + lastName）。
​
createdMembers[].status
string
已儲存的潛在客戶管道狀態。
​
createdMembers[].role
string
指派給成員的角色名稱 — 將為 "client"。
您可以在陣列中傳遞多個潛在客戶物件，以在單次 API 呼叫中建立多個潛在客戶。每個物件必須包含所有必填欄位，並使用各自唯一的電子郵件地址。