주문하기
주문 하나는 목록 하나에 체커 하나를 실행합니다. 절차는 모든 체커에서 같습니다.
1. 체커 선택
GET /checkers는 계정에서 주문할 수 있는 체커를 고객님의 가격으로 나열합니다. 각 체커에는 whatsapp_status_detection 같은 id가 있으며, 전화번호, 이메일 또는 사용자 이름을 받습니다. 체커를 참고하세요.
curl "https://api.talismanleads.io/v1/checkers" \
-H "Authorization: Bearer tl_live_your_key_here"2. 목록 보내기
100,000건 이하이면서 4 MB 이하의 항목을 요청에 entries로 넣으세요. 더 큰 목록은 POST /uploads에 링크를 요청하고, PUT으로 그 링크에 파일을 보낸 다음, 해당 upload_id를 사용하세요. 링크는 2시간 동안 유효합니다. 이 링크로 API 키를 보내지 마세요.
- 파일은 한 줄에 항목 하나인
.txt이며, 최대 200 MB, 10,000,000건입니다. - 전화번호는
+14155550142처럼 국가 코드와 함께 작성하세요. - 한 파일의 전화번호는 한 국가의 번호여야 합니다(최소 90%). 섞인 목록은 국가별로 파일 하나씩 나누세요.
- 유효하지 않은 줄이 하나라도 있으면 목록 전체가 거부되며, 응답에 예시가 표시됩니다.
- 업로드된 파일은 24시간 동안 주문을 기다린 후 삭제됩니다.
- 사용하는 API 키 수와 관계없이 동시에 20개 파일 또는 100 MB까지 대기시킬 수 있고, 하루에 500회까지 업로드할 수 있습니다. 이 한도 미만일 때는 허용된 크기의 파일 하나를 추가로 올릴 수 있습니다.
링크 요청
curl -X POST "https://api.talismanleads.io/v1/uploads" \
-H "Authorization: Bearer tl_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"file_name":"list.txt","size_bytes":1048576}'링크로 파일 보내기
UPLOAD_URL="PASTE_upload_url_FROM_THE_ANSWER_ABOVE"
curl --upload-file list.txt "$UPLOAD_URL" \
-H "Content-Type: text/plain" \
-w "%{http_code}\n"3. 가격 확인
POST /estimates는 항목 수를 세고 가격을 계산하며, 요금을 청구하지 않습니다. 모든 파일은 최소 2,000건으로 청구되므로 billed_entries가 entries보다 많을 수 있습니다.
curl -X POST "https://api.talismanleads.io/v1/estimates" \
-H "Authorization: Bearer tl_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"checker":"whatsapp_status_detection","entries":["+14155550142","+12125550187"]}'4. 주문하기
POST /orders는 잔액에서 요금을 차감하고 작업을 대기열에 넣습니다. 재시도로 두 번 청구되지 않도록 Idempotency-Key를 보내세요. 안전한 재시도를 참고하세요. 가격을 확실히 하려면 expected_charge를 보내세요. 비용이 조금이라도 다르면 주문이 price_changed로 거부됩니다. 큰 목록은 읽는 데 시간이 걸리므로 응답을 최대 5분까지 기다리세요.
curl -X POST "https://api.talismanleads.io/v1/orders" \
-H "Authorization: Bearer tl_live_your_key_here" \
-H "Idempotency-Key: crm-export-2026-11-05" \
-H "Content-Type: application/json" \
-d '{"checker":"whatsapp_status_detection","entries":["+14155550142","+12125550187"]}'5. 상태 추적
GET /orders/{id}를 30초 이상의 간격으로 조회하세요. 큰 파일은 내부적으로 여러 파트로 나뉘지만, 주문에는 상태 하나와 합계 하나만 있습니다.
queued- 시작을 기다리는 중입니다.
processing- 실행 중입니다.
completed- 종료되었으며 모든 파트가 완료되었습니다.
partially_completed- 종료되었으며 일부 파트가 실패했습니다. 해당 파트는 환불됩니다. `refunded`에 돌아온 금액이 표시됩니다.
failed- 어떤 파트도 처리할 수 없었습니다. 요금은 환불됩니다. `refunded`에 돌아온 금액이 표시됩니다.
상태가 더 추가될 수 있으므로 모르는 상태는 아직 실행 중인 것으로 처리하세요.
curl "https://api.talismanleads.io/v1/orders/ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f" \
-H "Authorization: Bearer tl_live_your_key_here"6. 결과 받기
GET /orders/{id}/results는 파트별로 15분 동안 유효한 다운로드 링크를 제공합니다. 결과는 보관되므로 언제든 새 링크를 다시 요청할 수 있습니다. 파일은 보통 all.csv, 스프레드시트, 텍스트 목록이 들어 있는 zip이거나 단일 CSV입니다. 열이 추가될 수 있으므로 위치가 아닌 이름으로 읽으세요. 이 링크로 API 키를 보내지 마세요.
curl "https://api.talismanleads.io/v1/orders/ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f/results" \
-H "Authorization: Bearer tl_live_your_key_here"청구와 환불
charge는 주문 시점의 주문 비용이고, refunded는 그중 돌아온 금액입니다. 실패한 파트는 전액 환불되며, 제공업체의 집계가 적게 나온 파트는 해당 파트의 최소 청구액까지 차액이 환불됩니다. 둘 다 자동으로 처리됩니다.
약 하루 안에 같은 체커에서 같은 목록을 새 멱등 키로 보내면 새 주문으로 다시 청구되며, 새 검사 대신 이전 결과가 반환될 수 있습니다.
다른 곳에서 넣은 주문
웹사이트에서 넣은 주문도 목록에 표시됩니다. API 주문은 웹사이트의 내 작업에 API 배지와 함께 표시되며, Telegram에서 요청하지 않는 한 Telegram으로 아무것도 보내지 않습니다.