> ## 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: 프로그래밍 방식으로 새 클라이언트 생성

> 이름, 이메일, 연락처 정보와 함께 bulk-client 엔드포인트에 게시하여 AgencyHandy 워크스페이스에 프로그래밍 방식으로 새 클라이언트를 추가하세요.

클라이언트 생성 엔드포인트를 사용하면 외부 시스템에서 AgencyHandy 워크스페이스에 직접 클라이언트를 추가할 수 있습니다. 리드와 달리 클라이언트는 주문, 인보이스, 프로젝트에 배정될 수 있는 완전히 온보딩된 연락처입니다. 이 엔드포인트를 사용하여 CRM, 온보딩 양식, 또는 기타 데이터 소스에서 새 클라이언트를 동기화하세요.

<Note>
  이 엔드포인트를 사용하기 전에 [시작하기](/ko/api/getting-started) 가이드를 완료하여 API 키와 회사 ID를 얻으세요. 리드 생성 엔드포인트와 달리, 클라이언트 생성에는 별도의 역할 ID 조회 단계가 **필요하지 않습니다**.
</Note>

## 사전 요구 사항

* ✅ **워크스페이스 설정 → API 키**에서 생성된 API 키
* ✅ `GET {{URL}}/accounts/companies`에서 조회한 회사 ID

***

## 엔드포인트

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

## 헤더

| 헤더             | 값                  |
| -------------- | ------------------ |
| `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="isConvertedClient" type="boolean" required>
  완전히 새로운 클라이언트의 경우 `false`로 설정합니다. 기존 리드를 클라이언트로 전환할 때는 `true`로 설정합니다.
</ParamField>

<ParamField body="status" type="string">
  클라이언트의 상태입니다. 일반적인 값: `New`, `Active`. 생략 시 기본값은 `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-client" \
  --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",
      "isConvertedClient": false,
      "status": "New",
      "contactNo": "1234567890",
      "source": "website",
      "positionInBoard": 1
    }
  ]'
```

## 성공 응답

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

<ResponseField name="message" type="string">
  성공 시 확인 문자열입니다.
</ResponseField>

<ResponseField name="createdMembers" type="array">
  생성된 클라이언트 객체의 배열입니다.
</ResponseField>

<ResponseField name="createdMembers[].\_id" type="string">
  새로 생성된 클라이언트의 고유 ID입니다. API를 통해 주문이나 인보이스에 클라이언트를 배정할 때 이 ID를 사용합니다.
</ResponseField>

<ResponseField name="createdMembers[].name" type="string">
  클라이언트의 전체 이름 (이름 + 성)입니다.
</ResponseField>

<ResponseField name="createdMembers[].status" type="string">
  저장된 클라이언트의 상태입니다.
</ResponseField>

<ResponseField name="createdMembers[].role" type="string">
  구성원에게 배정된 역할 — `"client"`가 됩니다.
</ResponseField>

<Note>
  이 엔드포인트의 `companyId` 헤더는 `Id`에서 대문자 **I**를 사용합니다 — `companyId` — 일부 다른 엔드포인트에서 사용하는 `companyid` (모두 소문자)와 다릅니다. 인증 오류를 방지하려면 위에 표시된 정확한 대소문자를 사용하세요.
</Note>

<Tip>
  배열에 여러 클라이언트 객체를 전달하여 단일 API 호출로 클라이언트를 일괄 생성할 수 있습니다. 각 객체에는 고유한 `email` 주소가 있어야 합니다. 중복된 이메일은 해당 항목에 대한 유효성 검사 오류를 발생시킵니다.
</Tip>