> For the complete documentation index, see [llms.txt](https://en.help.firstline.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://en.help.firstline.cc/developer/api/contact.md).

# Customer

## List

Retrieve the customer list via a GET request, and filter, sort, and paginate according to the following query parameters.

```javascript
GET https://{API_HOST}/api/v1/contact
```

Based on the following **Query Parameters** filter by parameters.

```javascript
curl -X GET
    -H "Content-Type: application/json"
    https://{API_HOST}/api/v1/contact
```

### Query Parameters

<table><thead><tr><th>Name</th><th>Type</th><th width="95.75390625">Required</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>page</td><td>integer</td><td>No</td><td>Current page number (starting from 1)</td><td>page=2</td></tr><tr><td>search</td><td>string</td><td>No</td><td>Name keyword search</td><td>search=John</td></tr><tr><td>created_at__start</td><td>string (datetime)</td><td>No</td><td>Created time (from)</td><td>created_at__start=2023-01-01</td></tr><tr><td>created_at__end</td><td>string (datetime)</td><td>No</td><td>Created time (to)</td><td>created_at__end=2023-12-31</td></tr><tr><td>birth_months</td><td>array&#x3C;integer></td><td>No</td><td>Birth months (1–12)</td><td>birth_months=1,2</td></tr><tr><td>membership_no</td><td>string</td><td>No</td><td>Membership number</td><td>membership_no=123456</td></tr><tr><td>sponsor_id</td><td>string</td><td>No</td><td>Owner ID</td><td>sponsor_id=999</td></tr><tr><td>company_ids</td><td>array&#x3C;integer></td><td>No</td><td>Company ID</td><td>company_ids=1,2,3</td></tr><tr><td>tag_ids</td><td>array&#x3C;integer></td><td>No</td><td>Tag ID list</td><td>tag_ids=101,102</td></tr><tr><td>identity_no</td><td>string</td><td>No</td><td>ID card number</td><td>identity_no=A123456789</td></tr><tr><td>phone_number</td><td>string</td><td>No</td><td>Phone number</td><td>phone_number=0912345678</td></tr><tr><td>age__start</td><td>integer</td><td>No</td><td>Age (from)</td><td>age__start=20</td></tr><tr><td>age__end</td><td>integer</td><td>No</td><td>Age (to)</td><td>age__end=40</td></tr><tr><td>has_duplicate_number</td><td>boolean (0/1)</td><td>No</td><td>Whether there is a duplicate number</td><td>has_duplicate_number=1</td></tr><tr><td>has_number</td><td>boolean (0/1)</td><td>No</td><td>Whether there is a phone number</td><td>has_number=1</td></tr><tr><td>has_fb_optin</td><td>boolean (0/1)</td><td>No</td><td>Whether there is FB authorization</td><td>has_fb_optin=1</td></tr><tr><td>has_valid_fb_optin</td><td>boolean (0/1)</td><td>No</td><td>Whether there is valid FB authorization</td><td>has_valid_fb_optin=1</td></tr><tr><td>has_disturb</td><td>boolean (0/1)</td><td>No</td><td>Whether there is do-not-disturb data</td><td>has_disturb=1</td></tr></tbody></table>

### Response

| PROPERTY | TYPE             | DESCRIPTION         |
| -------- | ---------------- | ------------------- |
| data     | Array of objects | Customer data array |
| meta     | Object           | Pagination info     |

## Retrieve

```javascript
GET https://{API_HOST}/api/v1/contact/{contact}
```

### URL Parameters

| PARAMETER   | REQUIRED | DEFAULT | TYPE   | DESCRIPTION |
| ----------- | -------- | ------- | ------ | ----------- |
| **contact** | True     | NULL    | Number | Customer ID |

```javascript
curl -X get
    -H "Content-Type: application/json"
    https://{API_HOST}/api/v1/contact/1
```

### Response

Please refer to[Customer](https://help.firstline.cc/developer/api/hui-ying-wu-jian-ge-shi#ke-hu-contact)response format.

| PROPERTY | TYPE   | DESCRIPTION                                                                               |
| -------- | ------ | ----------------------------------------------------------------------------------------- |
| **data** | Object | [Customer](https://help.firstline.cc/developer/api/hui-ying-wu-jian-ge-shi#ke-hu-contact) |

```javascript

{
    "data": {
        "id": 1,
        "name": "Angelita D'Amore",
        "first_name": "Angelita",
        "last_name": "D'Amore",
        "membership_no": "8771639",
        "identity_no": "418099",
        "gender": 0,
        "birth_at": "1985-08-27",
        "profile_id": 1,
        "profile": {
            "id": 1,
            "phones": []
        },
        "email_contacts": [],
        "cz_cols": [
            {
                "id": 1,
                "value": "19999",
                "category_id": 1
            },
            {
                "id": 4,
                "value": "51",
                "category_id": 1
            },
            {
                "id": 5,
                "value": null,
                "category_id": 1
            }
        ]
    }
}
```

## Create

```javascript
POST https://{API_HOST}/api/v1/contact
```

Please put the added fields in **JSON Request Body** do not append them to the URL Query String.

```javascript
curl -X POST "https://{API_HOST}/api/v1/contact" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"abc","last_name":"cde"}'
```

### JSON Request Body

| PARAMETER          | REQUIRED | DEFAULT | TYPE   | DESCRIPTION                                                              |
| ------------------ | -------- | ------- | ------ | ------------------------------------------------------------------------ |
| **membership\_no** | false    | NULL    | String | Membership number                                                        |
| **identity\_no**   | false    | NULL    | String | ID card                                                                  |
| **gender**         | false    | NULL    | Number | <p>Gender<br>0: Female<br>1: Male</p>                                    |
| **first\_name**    | true     | NULL    | String | Last name                                                                |
| **last name**      | false    | NULL    | String | First name                                                               |
| **birth\_at**      | false    | NULL    | Date   | Date of birth                                                            |
| **cz\_cols**       | false    | NULL    | Array  | Custom fields, see the parameter types below **CzCol** Table description |
| **company\_ids**   | false    | NULL    | Array  | Company system ID number                                                 |

### Response

Please refer to[Customer](https://help.firstline.cc/developer/api/hui-ying-wu-jian-ge-shi#ke-hu-contact)Response format

```javascript

{
    "data": {
        "id": 2,
        "name": "abc cde",
        "first_name": "abc",
        "last_name": "cde",
        "membership_no": null,
        "identity_no": null,
        "gender": null,
        "birth_at": null,
        "profile_id": 1,
        "profile": {
            "id": 1,
            "phones": []
        },
        "cz_cols": [
            {
                "id": 4,
                "value": "123456"
            },
            {
                "id": 7,
                "value": "apple"
            }
        ]}
}
```

## Update

```javascript
PUT https://{API_HOST}/api/v1/contact/{id}
```

### URL Parameters

| PARAMETER | DESCRIPTION |
| --------- | ----------- |
| **id**    | Customer ID |

```javascript
curl -X PUT "https://{API_HOST}/api/v1/contact/2" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"First","last_name":"Line"}'
```

### JSON Request Body

| PARAMETER          | REQUIRED | DEFAULT | TYPE   | DESCRIPTION                                                              |
| ------------------ | -------- | ------- | ------ | ------------------------------------------------------------------------ |
| **membership\_no** | false    | NULL    | String | Membership number                                                        |
| **identity\_no**   | false    | NULL    | String | ID card                                                                  |
| **gender**         | false    | NULL    | Number | <p>Gender<br>0: Female<br>1: Male</p>                                    |
| **first\_name**    | false    | NULL    | String | Last name                                                                |
| **last name**      | false    | NULL    | String | First name                                                               |
| **birth\_at**      | false    | NULL    | Date   | Date of birth                                                            |
| **cz\_cols**       | false    | NULL    | Array  | Custom fields, see the parameter types below **CzCol** Table description |
| **tag\_ids**       | false    | NULL    | Array  | Customer tags, pass in customer tag IDs                                  |
| **company\_ids**   | false    | NULL    | Array  | Company system ID number                                                 |

### Response

Please refer to[Customer](https://help.firstline.cc/developer/api/hui-ying-wu-jian-ge-shi#ke-hu-contact)Response format

```json

{
    "data": {
        "id": 2,
        "name": "First Line",
        "first_name": "First",
        "last_name": "Line",
        "membership_no": null,
        "identity_no": null,
        "gender": null,
        "birth_at": null,
        "profile_id": 1,
        "profile": {
            "id": 1,
            "phones": []
        },
        "cz_cols": [
            {
                "id": 4,
                "value": "123456"
            },
            {
                "id": 7,
                "value": "apple"
            },
            {
                "id": 18,
                "value":  ["A", "B", "C"]
            }
        ],
        "tag_id": [4, 6]
    }
}
```

## Delete

```
DELETE https://{API_HOST}/api/v1/contact/{id}
```

### URL Parameters

| PARAMETER | DESCRIPTION                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------ |
| **id**    | [Customer](https://help.firstline.cc/developer/api/hui-ying-wu-jian-ge-shi#ke-hu-contact)System ID #ID |

```javascript
curl -X DELETE
    -H "Content-Type: application/json"
    https://{API_HOST}/api/v1/contact/2
```
