> For the complete documentation index, see [llms.txt](https://api-kit.prix.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-kit.prix.im/platform/search-customer.md).

# 고객 목록 조회 API

플랫폼 서비스에서 특정 비즈니스의 고객 목록을 조회할 수 있는 API를 제공합니다.

<br>

## `GET` kit-api/v1/customers

Method: GET\
Endpoint: kit-api/v1/customers

<br>

## Example

```
...kit-api/v1/customers?offset=0&limit=10
```

```
...kit-api/v1/customers?customKey=A5-k159402
```

<br>

## Request Query

| Key       | Description                 | Required |
| --------- | --------------------------- | -------- |
| limit     | 목록 개수 (default 10, max 100) | no       |
| offset    | 스킵할 목록 개수                   | no       |
| customKey | 검색할 custom key (단건 검색)      | no       |

<br>

## Response

```json
{
  "ok": true,
  "data": {
    "total": 2,
    "customers": [
      {
        "id": 1,
        "title": "김철수",
        "customKey": "A5-k159402",
        "ceo": "김대표",
        "registrationNumber": "789-30-01467",
        "address": "서울특별시 서초구 프릭스로 551",
        "industry": "정보통신업",
        "category": "응용 소프트웨어 개발 및 공급업",
        "managers": [
          {
            "name": "이담당자",
            "email": "customerManager@email.com",
            "position": "이담당자 직책",
            "note": "이담당자 메모",
            "contact": "이담당자 연락처",
            "roles": ["TAX_BILL", "SUB_TAX_BILL", "CONTRACT"] // 담당자 역할
          }
        ]
      },
      {
        "id": 2,
        "title": "김영희",
        "customKey": null
      }
    ]
  }
}
```

```json
{
  "ok": false, // api 실패
  "message": "error message", // Error가 존재하면 message(string)로 전달
  "errorCode": "ERROR_CODE"
}
```

<br>

## Error Codes

| Status Code | Error Code                     | Description           |
| ----------- | ------------------------------ | --------------------- |
| 400         | INVALID\_CUSTOMER\_CUSTOM\_KEY | 규칙을 벗어난 customKey인 경우 |
| 404         | NOT\_FOUND\_CUSTOMER           | 존재하지 않는 고객인 경우        |

<br>