Leads API

범위가 제한된 API 키로 자체 시스템에서 리드를 읽고 상태를 업데이트하세요.

이 페이지는 영어에서 번역되었습니다. 내용이 다를 경우 영어 버전이 우선합니다. 영어로 읽기

Leads API를 사용하면 CRM, 데이터 웨어하우스, 자동화 도구가 리드를 읽고 상태를 업데이트할 수 있습니다.

키

Studio의 Integrations → Leads API → New key에서 키를 만듭니다. 각 키에는 다음이 있습니다.

이름
권한: leads:read(Read leads) 및 선택적으로 leads:write-status(Change lead status)
30일, 90일, 180일 또는 1년의 만료 기간

키는 atl_lead_ 뒤에 43자가 붙는 형태입니다. 한 번만 표시되고, 지문으로만 저장되며, 모든 요청에서 확인되고, 언제든 해지할 수 있습니다(Revoke key). 사이트 환경당 활성 키는 최대 20개입니다. 키를 만들 때 휴대폰에서 두 번째 확인이 필요할 수 있습니다.

기본 URL과 인증

https://<delivery host>/v1/leads-api/environments/{environmentId}
Authorization: Bearer atl_lead_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

응답은 Cache-Control: private, no-store입니다. 오류는 RFC 9457 application/problem+json 형식을 사용합니다.

리드 목록

GET /leads?since=2026-10-01T00:00:00Z&limit=50&cursor=…

매개변수	비고
`since`	이 시각 이후(해당 시각 포함)에 업데이트된 리드만. 시간대가 포함된 ISO 8601
`limit`	1~200, 기본값 50
`cursor`	이전 응답의 `nextCursor`

리드는 변경이 가장 오래된 순서로 반환됩니다. 응답은 { "leads": [ … ], "nextCursor": "…" | null }입니다. nextCursor가 null이 될 때까지 페이지를 넘기고, 마지막 updatedAt을 저장해 두었다가 다음에는 변경 사항만 가져오세요.

목록에는 병합된 리드, 익명화된 리드, 테스트 리드가 포함됩니다. mergedInto, anonymisedAt, isTest를 확인하세요.

리드 하나 가져오기

GET /leads/{leadId}

필드	비고
`id`, `source`	source는 리드가 들어온 폼 또는 챗봇입니다
`form`	`{ key, name }`, 챗봇 리드는 `null`
`name`, `email`, `phone`, `company`, `message`	보존 정책이 개인정보를 제거한 뒤에는 비어 있습니다
`details`	그 밖의 답변
`status`	`new`, `contacted`, `qualified`, `won`, `lost`, `spam`
`isTest`	Studio 테스트 제출
`version`	상태를 변경할 때 다시 보내세요
`mergedInto`, `anonymisedAt`	리드가 병합되거나 익명화되었을 때 설정됩니다
`createdAt`, `updatedAt`	ISO 8601 타임스탬프

리드 상태 변경

PATCH /leads/{leadId}/status에 { "status": "qualified", "expectedVersion": 4 }를 보냅니다. Change lead status 권한이 필요합니다. 변경은 리드 기록에 해당 키가 수행한 것으로 표시됩니다.

오류와 제한

상태	코드	의미
401	`CP_UNAUTHENTICATED`	키가 없거나, 잘못되었거나, 만료되었거나, 해지되었습니다
403	`CP_FORBIDDEN`	키에 이 요청에 필요한 권한이 없습니다
404	`CP_NOT_FOUND`	이 환경에 해당 리드가 없습니다
409	`CP_VERSION_CONFLICT`	읽은 이후 리드가 변경되었습니다. 다시 읽으세요
422	`REQUEST_SCHEMA_INVALID`	요청 본문 또는 매개변수가 올바르지 않습니다
422	`CURSOR_INVALID`	커서를 읽을 수 없습니다
429	`RATE_LIMITED`	분당 300건을 초과했습니다. 기다린 뒤 다시 시도하세요

속도 제한은 Atlas API 서버별로 적용되므로 분당 300건은 보장 수치가 아니라 상한으로 생각하세요.