# Lead

## 1. Tạo mới Lead

<mark style="color:green;">`POST`</mark> `/{domain}/api/v1/lead`

Tạo mới Lead

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**

<table data-full-width="false"><thead><tr><th width="82">STT</th><th>Param</th><th width="113">Kiểu</th><th width="92">Độ dài</th><th>Ghi chú</th></tr></thead><tbody><tr><td>1*</td><td>lead</td><td>object</td><td><br></td><td>Đối tượng chứa thông tin lead</td></tr><tr><td>….</td><td>Các trường trong object lead<br></td><td><br></td><td><br></td><td><br></td></tr><tr><td>1</td><td>username</td><td>text</td><td>250</td><td>Họ tên khách hàng (Trong trường hợp số điện thoại hoặc email của khách đã tồn tại sẽ không sử dụng tham số này) </td></tr><tr><td>2</td><td>subject (*)</td><td>text</td><td>250</td><td>Tiêu đề</td></tr><tr><td>3</td><td>phone (*)</td><td>tel</td><td>50</td><td>Số điện thoại của khách hàng</td></tr><tr><td>4</td><td>email (*)</td><td>email</td><td>50</td><td>Email của khách hàng</td></tr><tr><td>5</td><td>service_id (**)</td><td>Int</td><td>10</td><td>Dịch vụ tiếp nhận Lead</td></tr><tr><td>6</td><td>group_id (**)</td><td>Int</td><td>10</td><td>ID bộ phận tiếp nhận</td></tr><tr><td>7</td><td>assignee_id (**)</td><td>Int</td><td>10</td><td>ID chuyên viên tiếp nhận</td></tr><tr><td>8</td><td>lead_status_id</td><td>Int</td><td>10 </td><td>ID trạng thái lead (Mặc định không điền sẽ lấy trạng thái đầu</td></tr><tr><td>9</td><td>estimated_closed_date</td><td>DateTime</td><td><br></td><td>Dự kiến hoàn thành (Định dạng YYYY-MM-DD HH:mm:ss) </td></tr><tr><td>10</td><td>lead_label</td><td>Array</td><td><br></td><td>Mảng ID label của lead Dạng [1,2,3]</td></tr><tr><td>11</td><td>custom_fields</td><td>Array</td><td><br></td><td>Mảng custom_fields tương tự tạo ticket</td></tr><tr><td>12</td><td>comment</td><td>Text</td><td>5000</td><td>Nội dung ghi chú</td></tr><tr><td>13</td><td>unqualify_reason</td><td>Int</td><td>10</td><td>ID của lý do không đạt (Chỉ áp dụng nếu lead_status_id ở trạng thái cuối)</td></tr></tbody></table>

Mẫu body JSON  tạo lead

```json
{
    "lead": {
        "phone": "0983980148",
        "service_id": 1244,
        "subject": "Test lead",
        "comment": "Helo world",
        "estimated_closed_date": "2024/03/21 23:59:59",
        "lead_status": 558,
        "lead_label_id": [
            10,
            11
        ],
        "ref_url": "https://gooogle.com?utm_content=TestREFERURL&utm_source=GANEW"
    }
}
```

**Kết quả phản hồi**\
Trong đối tượng lead trả về có chứa ID chính là Lead Id dùng để cập nhật hoặc thực thi các tác vụ khác liên quan

{% tabs %}
{% tab title="200" %}

```json
{
    "code": "ok",
    "lead": {
        "updated_at": "2024-03-21 15:11:06",
        "subject": "Test referer lead",
        "created_at": "2024-03-21 15:11:06",
        "id": 414856017,
        "requester_id": 63215969
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 2. Cập nhật Lead

<mark style="color:green;">`PUT`</mark> `/{domain}/api/v1/lead/{leadId}`

Cập nhật 1 lead với {leadId} là ID từ quá trình tạo mới hoặc quét dữ liệu đồng bộ từ trước

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**

| STT | Param                   | Type        | Length      | Description                                                                               |
| --- | ----------------------- | ----------- | ----------- | ----------------------------------------------------------------------------------------- |
| 1\* | lead                    | object      | <p><br></p> | Đối tượng chứa thông tin lead                                                             |
| ….  | <p><br></p>             | <p><br></p> | <p><br></p> | <p><br></p>                                                                               |
| 2   | subject                 | text        | 250         | Tiêu đề                                                                                   |
| 3   | assignee\_id            | Int         | 10          | ID chuyên viên tiếp nhận                                                                  |
| 4   | lead\_status\_id        | Int         | 10          | ID trạng thái lead (Mặc định không điền sẽ lấy trạng thái đầu                             |
| 5   | estimated\_closed\_date | DateTime    | <p><br></p> | Dự kiến hoàn thành (Định dạng YYYY-MM-DD HH:mm:ss)                                        |
| 6   | lead\_label             | Array       | <p><br></p> | Mảng ID label của lead Dạng \[1,2,3]                                                      |
| 7   | custom\_fields          | Array       | <p><br></p> | Mảng custom\_fields tương tự tạo ticket                                                   |
| 8   | comment (\*)            | OBJECT      | <p><br></p> | Object đối tượng comment                                                                  |
| 9   | comment.body            | Text        | 5000        | Nội dung comment                                                                          |
| 10  | comment.is\_public      | Int         | 1           | <p>Trạng thái comment<br>0: Ghi chú<br>1: Public (VD: Gửi email cho người yêu cầu …) </p> |
| 11  | comment.author\_id      | Int         | 10          | ID của người bình luận                                                                    |
| 12  | unqualify\_reason       | Int         | 10          | ID của lý do không đạt (Chỉ áp dụng nếu lead\_status\_id ở trạng thái cuối)               |

Mẫu ví dụ body Json cập nhật LeadID: 414856017

**PUT**: `/{domain}/api/v1/lead/414856017`

```json
{
    "lead": {
        "subject": "Tesst",
        "comment": {
            "body": "Cập nhật giá trị mua hành thành giao hàng",
            "is_public": 1,
            "author_id": 124734559
        },
        "lead_status_id": 1,
        "estimated_closed_date": "2024-04-11 00:00:00",
        "lead_label": [
            11,
            22
        ],
        "custom_fields": [
            {
                "id": "6068",
                "value": "106902"
            }
        ]
    }
}

```

**Kết quả phản hồi**

{% tabs %}
{% tab title="200" %}

```json
{
    "code": "ok",
    "lead": {
        "updated_at": "2024-03-21 15:11:06",
        "subject": "Test referer lead",
        "created_at": "2024-03-21 15:11:06",
        "id": 414856017,
        "requester_id": 63215969
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 3. Chi tiết Lead

<mark style="color:green;">`GET`</mark>`/{domain}/api/v1/lead/{leadId}`

\<Description of the endpoint>

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "lead": {
        "account_id": 8187,
        "id": 512534181,
        "lead_no": 16843,
        "requester_id": 207642682,
        "group_id": 12945,
        "ticket_source_end_status": null,
        "assignee_id": 124734559,
        "ticket_source": "Voice Out",
        "merge_status": null,
        "merge_to": null,
        "clone_from": null,
        "subject": "Cuộc gọi ra cho khách hàng  theo chiến dịch: Mơ Sample",
        "created_at": "2024-08-07 14:17:11",
        "updated_at": "2024-09-30 12:04:38",
        "duedate": null,
        "satisfaction": null,
        "satisfaction_content": null,
        "satisfaction_at": null,
        "satisfaction_send": null,
        "campaign_id": 78830,
        "campaign_action_id": -1,
        "campaign_status": 0,
        "automessage_id": null,
        "manualmessage_id": null,
        "incident_id": -1,
        "service_id": null,
        "qa_script_id": null,
        "qa_agent": null,
        "current_agent": null,
        "ticket_source_detail_id": 1154135,
        "convert_by": 124734559,
        "convert_at": "2024-08-07 14:24:12",
        "convert_type": 1,
        "unqualified_reasons": null,
        "last_lead_status_id": 25,
        "estimated_closed_date": null,
        "lead_status_id": 26,
        "comments": [
            {
                "ticket_comments_id": 1211536855,
                "ticket_id": 512534181,
                "comment": "aa",
                "commentator_id": 124734559,
                "username": "Admin1",
                "facebook": null,
                "facebook_name": null,
                "comment_source": null,
                "created_at": "2024-09-30 12:04:38",
                "attack_file_id": null,
                "file_name": null,
                "file_id": null,
                "download_connection_string": null,
                "call_id": null,
                "email_receive_id": null,
                "addition_details": null,
                "is_public": 0,
                "can_hide": null,
                "can_remove": null,
                "can_reply_privately": null,
                "facebook_comment_state": 0,
                "role_id": 1,
                "avatar": "https://3.bp.blogspot.com/-qCI9fu4I2SE/Y7UkNAM4jhI/AAAAAAAENjs/YWNtRIeDGjghZbiZmu9aduswuxvmuTYSACNcBGAsYHQ/photo.png?imgmax=3000"
            }  
        ],
        "custom_fields": [
            {
                "id": 5159,
                "label": "Kí tự 19",
                "type": "Text",
                "value": null
            },
            {
                "id": 9579,
                "label": "Phân loại ticket cha(2602)",
                "type": "Single drop-down list",
                "value": null
            }
        ],
        "tags": [],
        "ccs": [],
        "follows": [],
        "labels": [],
        "campaign": {
            "id": 78830,
            "campaign_name": "Mơ Sample",
            "status": 0
        },
        "campaign_action": null,
        "assignee": {
            "id": 124734559,
            "username": "Admin1",
            "email": "**@gmail.com",
            "phone_no": "***",
            "agent_id": "50024",
            "role_id": 1,
            "group_id": 12153,
            "group_name": "Default Group"
        },
        "requester": {
            "id": 207642682,
            "username": "cfsdcf",
            "email": null,
            "phone_no": null,
            "organization_id": null
        }
    }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 4. Danh sách lead

<mark style="color:green;">`GET`</mark> `/{domain}/api/v1/leads`

Lấy danh sách các leads

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Parameter**

| Param          | Ghi chú                                                                                              |
| -------------- | ---------------------------------------------------------------------------------------------------- |
| requester\_id  | ID Người yêu cầu                                                                                     |
| assignee\_id   | ID Chuyên viên                                                                                       |
| service\_id    | ID dịch vụ                                                                                           |
| page           | Trang số (mặc định 1)                                                                                |
| count          | Số bản ghi /trang (mặc định 50, max 500)                                                             |
| created\_since | <p>Ngày tạo từ (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p>                                        |
| created\_to    | <p>Ngày tạo tới (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p>                                       |
| updated\_since | <p>Ngày cập nhật từ (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p><p><br></p>                        |
| updated\_to    | <p>Ngày cập nhật tới (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p><p><br></p>                       |
| convert\_since | <p>Ngày chuyển đổi thành deal (từ lead) (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p><p><br></p>    |
| convert\_to    | <p>Ngày chuyển đổi thành deal tới (Kiểu Time TZ)<br>Vd: 2024-06-01T00:00:00Z</p><p><br></p>          |
| status\_ids    | <p>Trạng thái leads, chọn nhiều cách nhau bởi dấu phẩy<br>VD: 12 hoặc 12,34,56</p>                   |
| convert\_type  | <p>Trạng thái chuyển đổi từ lead sang deal</p><p>1: Chuyển thành Lead, 2: Chuyển thành Không đạt</p> |

**Mẫu dữ liệu phản hồi**

{% tabs %}
{% tab title="200" %}

```json
{
  "code": "ok",
  "numFound": 1,
  "leads": [
    {
      "id": 414857091,
      "lead_no": 273763,
      "requester_id": 63216680,
      "ticket_source_end_status": 1,
      "assignee_id": 1,
      "ticket_priority": "Normal",
      "ticket_source": "Voice Out",
      "is_overdue": null,
      "subject": "Cuộc gọi ra cho khách hàng loi.tranquang",
      "created_at": "2024-05-03T15:28:40Z",
      "updated_at": "2024-05-03T15:28:40Z",
      "duedate": null,
      "service_id": 2005289,
      "incident_id": null,
      "satisfaction": null,
      "satisfaction_at": null,
      "satisfaction_content": null,
      "campaign_id": null,
      "automessage_id": null,
      "source_detail_id": 127,
      "convert_by": null,
      "convert_at": null,
      "convert_type": null,
      "unqualified_reasons": null,
      "last_lead_status_id": null,
      "lead_status_id": 525,
      "estimated_closed_date": null
    }
  ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 5. Các thành phần khác của Lead

Các API bổ sung cho lead&#x20;

## 5.1 Danh sách trạng thái lead

<mark style="color:green;">`GET`</mark> `/{domain}/api/v1/lead/status`

Danh sách các trạng thái lead đã cấu hình trên hệ thống

Trong đó:

1. label: Tên trạng thái
2. id: ID trạng thái
3. status\_type: Kiểu trạng thái. 1: Đầu tiên, ,0 Giữa (đổi vị trí thoải mái-- index các loại), 2: Converted (index to nhất), 3: Unqualify

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Kết quả minh họa**&#x20;

{% tabs %}
{% tab title="200" %}

```json
{
  "code": "ok",
  "data": [
    {"id": 525, "label": "Tương tác mới"   , "status_type": 1},
    {"id": 557, "label": "Đang liên hệ"    , "status_type": 0},
    {"id": 558, "label": "Comming"         , "status_type": 0},
    {"id": 643, "label": "Trạng thái demo" , "status_type": 0},
    {"id": 527, "label": "Lead Converted1" , "status_type": 2},
    {"id": 528, "label": "Lead Unqualified", "status_type": 3}
  ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 5.2 Danh sách lý do không đạt Lead

<mark style="color:green;">`GET`</mark> `/{domain}/api/v1/lead/unqualified-reason`

Danh sách id các lý do không đạt đã được cấu hình cho lead

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "code": "ok",
  "data": [
    {
      "id": 176,
      "label": "No need"
    },
    {
      "id": 177,
      "label": "Not the decision maker"
    },
    {
      "id": 182,
      "label": "No budget"
    },
    {
      "id": 217,
      "label": "Lead unqualified"
    }
  ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 5.3 Danh sách lead labels

<mark style="color:green;">`GET`</mark> `/{domain}/lead/labels`

\<Description of the endpoint>

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "code": "ok",
  "data": [
    {
      "id": 17,
      "label": "5",
      "created_at": "2023-10-03 17:11:01",
      "updated_at": "2023-10-03 17:11:01"
    },
    {
      "id": 11,
      "label": "Cold",
      "created_at": "2023-10-02 11:13:17",
      "updated_at": "2023-10-02 11:13:17"
    },
    {
      "id": 22,
      "label": "Freezing@2",
      "created_at": "2023-10-25 14:22:14",
      "updated_at": "2023-10-25 14:22:14"
    }
  ]
}

```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.caresoft.vn/danh-muc/restful-api-cua-caresoft/lead.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.