리드 생성 엔드포인트를 사용하면 외부 시스템 — 웹 양식, CRM, 마케팅 자동화 플랫폼, 또는 맞춤 스크립트 — 에서 AgencyHandy 워크스페이스에 프로그래밍 방식으로 새 리드를 추가할 수 있습니다. 이 엔드포인트를 통해 생성된 리드는 수동으로 추가한 것처럼 즉시 리드 파이프라인에 나타납니다.
이 엔드포인트를 사용하기 전에 시작하기 가이드를 완료하여 API 키와 회사 ID를 얻으세요. 리드를 생성할 때 필요한 클라이언트 역할 ID도 가져와야 합니다. 사전 요구 사항
- ✅ 워크스페이스 설정 → API 키에서 생성된 API 키
- ✅
GET {{URL}}/accounts/companies에서 조회한 회사 ID
- ✅ 클라이언트 역할 ID 조회 (아래 1단계 참조)
1단계: 클라이언트 역할 ID 가져오기
리드를 생성하기 전에 회사의 client 역할에 대한 역할 ID가 필요합니다.
엔드포인트
GET {{URL}}/roles?type=company
| 헤더 | 값 |
|---|
x-api-key | API 키 |
companyid | 회사 ID |
요청 예시
curl --request GET "https://api.agencyhandy.com/roles?type=company" \
--header "x-api-key: <YOUR_API_KEY>" \
--header "companyid: <YOUR_COMPANY_ID>"
응답 예시
{
"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가 아님)를 추출합니다.
const clientRoleId = roles.find(r => r.role.name === "client")._id;
// e.g. "6525994184e9ddd798534535"
roles[0]._id (회사-역할 매핑 ID)를 사용하세요, roles[0].role._id (역할 정의 ID)가 아닙니다. 잘못된 ID를 사용하면 리드 생성 요청이 실패합니다.
2단계: 새 리드 생성
엔드포인트
POST {{URL}}/members/bulk-lead
| 헤더 | 값 |
|---|
x-api-key | API 키 |
companyid | 회사 ID |
Content-Type | application/json |
요청 본문
요청 본문은 JSON 배열입니다 — 단일 호출로 하나 이상의 리드를 생성할 수 있습니다.
리드의 이메일 주소입니다. 워크스페이스 내에서 고유해야 합니다.
1단계에서 조회한 클라이언트 역할 ID (즉, roles[0]._id)입니다.
리드를 생성할 때는 false로 설정해야 합니다. 리드를 전체 클라이언트로 전환할 때만 true로 설정합니다.
리드의 파이프라인 상태입니다. 일반적인 값: New, Contacted, Qualified. 생략 시 기본값은 New입니다.
이 리드를 획득한 경로입니다. 예시 값: website, referral, social.
파이프라인 보드 열 내에서 리드의 위치(순서)입니다. 기본값은 1입니다.
요청 예시
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
}
]'
성공 응답
{
"message": "Lead created successfully",
"createdMembers": [
{
"_id": "NEW_MEMBER_ID",
"name": "John Doe",
"status": "New",
"role": "client"
}
]
}
확인 문자열: "Lead created successfully".
새로 생성된 리드의 고유 ID입니다. 이후 API 호출에서 리드를 참조해야 하는 경우 저장하세요.
구성원에게 배정된 역할 이름 — "client"가 됩니다.
배열에 여러 리드 객체를 전달하여 단일 API 호출로 여러 리드를 생성할 수 있습니다. 각 객체에는 고유한 이메일 주소와 함께 필수 필드가 모두 포함되어야 합니다.
