> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agencyhandy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AgencyHandy API：以程式方式建立新的潛在客戶

> 使用 AgencyHandy API，透過向 bulk-lead 端點傳送帶有必填欄位的 POST 請求，以程式方式建立新的潛在客戶。

建立潛在客戶端點讓您能夠從任何外部系統（網頁表單、CRM、行銷自動化平台或自訂腳本）以程式方式將新的潛在客戶新增至您的 AgencyHandy 工作區。透過此端點建立的潛在客戶將立即出現在您的潛在客戶管道中，就像手動新增一樣。

<Note>
  使用此端點前，請先完成[入門指南](/zh-Hant/api/getting-started)以取得您的 API 金鑰和公司 ID。您還需要取得**客戶角色 ID**，這在建立潛在客戶時為必要項目。
</Note>

## 前置條件

* ✅ 從 **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   |

### 範例請求

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

### 範例回應

```json theme={null}
{
  "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`。

```javascript theme={null}
const clientRoleId = roles.find(r => r.role.name === "client")._id;
// e.g. "6525994184e9ddd798534535"
```

<Warning>
  請使用 `roles[0]._id`（公司-角色對應 ID），**而非** `roles[0].role._id`（角色定義 ID）。使用錯誤的 ID 會導致潛在客戶建立請求失敗。
</Warning>

***

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

### 端點

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

### 標頭

| 標頭             | 值                  |
| -------------- | ------------------ |
| `x-api-key`    | 您的 API 金鑰          |
| `companyid`    | 您的公司 ID            |
| `Content-Type` | `application/json` |

### 請求主體

請求主體為 **JSON 陣列** — 您可以在單次呼叫中建立一個或多個潛在客戶。

<ParamField body="firstName" type="string" required>
  潛在客戶的名字。
</ParamField>

<ParamField body="lastName" type="string" required>
  潛在客戶的姓氏。
</ParamField>

<ParamField body="email" type="string" required>
  潛在客戶的電子郵件地址。在您的工作區內必須是唯一的。
</ParamField>

<ParamField body="role" type="string" required>
  步驟 1 中取得的客戶角色 ID（即 `roles[0]._id`）。
</ParamField>

<ParamField body="isConvertedClient" type="boolean" required>
  建立潛在客戶時必須設定為 `false`。僅在將潛在客戶轉換為正式客戶時設定為 `true`。
</ParamField>

<ParamField body="status" type="string">
  潛在客戶的管道狀態。常用值：`New`、`Contacted`、`Qualified`。若省略則預設為 `New`。
</ParamField>

<ParamField body="contactNo" type="string">
  潛在客戶的電話號碼。
</ParamField>

<ParamField body="source" type="string">
  您獲取此潛在客戶的管道。範例值：`website`、`referral`、`social`。
</ParamField>

<ParamField body="positionInBoard" type="number">
  潛在客戶在管道看板欄位中的位置（順序）。預設為 `1`。
</ParamField>

### 範例請求

```bash cURL theme={null}
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
    }
  ]'
```

### 成功回應

```json theme={null}
{
  "message": "Lead created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
```

<ResponseField name="message" type="string">
  確認字串：`"Lead created successfully"`。
</ResponseField>

<ResponseField name="createdMembers" type="array">
  已建立的潛在客戶物件陣列。
</ResponseField>

<ResponseField name="createdMembers[].\_id" type="string">
  新建立潛在客戶的唯一 ID。若您需要在後續 API 呼叫中引用此潛在客戶，請儲存此 ID。
</ResponseField>

<ResponseField name="createdMembers[].name" type="string">
  潛在客戶的全名（firstName + lastName）。
</ResponseField>

<ResponseField name="createdMembers[].status" type="string">
  已儲存的潛在客戶管道狀態。
</ResponseField>

<ResponseField name="createdMembers[].role" type="string">
  指派給成員的角色名稱 — 將為 `"client"`。
</ResponseField>

<Tip>
  您可以在陣列中傳遞多個潛在客戶物件，以在單次 API 呼叫中建立多個潛在客戶。每個物件必須包含所有必填欄位，並使用各自唯一的電子郵件地址。
</Tip>