본문으로 건너뛰기
TalismanLeadsDocs
홈API 키 받기

API 레퍼런스

기본 주소는 https://api.talismanleads.io/v1입니다. 업로드 및 다운로드 링크를 제외하고 요청과 응답은 JSON입니다. OpenAPI 파일로도 제공됩니다.

잔액

GET/account

잔액과 현재 적용 중인 제한.

필요한 API 키: 읽기 전용 또는 주문 가능

요청 예시

curl "https://api.talismanleads.io/v1/account" \
  -H "Authorization: Bearer tl_live_your_key_here"

응답 예시 (200)

{
  "balance": "100.00",
  "currency": "USD",
  "key": {
    "id": "11111111-1111-4111-8111-111111111111",
    "scopes": [
      "read",
      "orders"
    ]
  },
  "limits": {
    "reads_per_minute": 60,
    "result_downloads_per_minute": 30,
    "uploads_per_minute": 10,
    "estimates_per_minute": 10,
    "orders_per_minute": 10,
    "open_task_parts": 20
  }
}

체커 나열

GET/checkers

이 계정에서 지금 주문할 수 있는 체커와 그 가격. 일시 중지되었거나 차단된 체커는 나열되지 않습니다.

필요한 API 키: 읽기 전용 또는 주문 가능

요청 예시

curl "https://api.talismanleads.io/v1/checkers" \
  -H "Authorization: Bearer tl_live_your_key_here"

응답 예시 (200)

{
  "checkers": [
    {
      "id": "whatsapp_status_detection",
      "name": "WhatsApp Status Detection",
      "input": "phone",
      "price": {
        "amount": "3.00",
        "per_entries": 10000,
        "currency": "USD"
      },
      "minimum_entries": 0,
      "minimum_billed_entries": 2000,
      "calling_code": null
    }
  ]
}

큰 목록 업로드

POST/uploads

파일을 저장소로 바로 보내는 링크입니다. PUT과 제공된 헤더로 보내세요. 링크는 2시간 동안 유효합니다.

필요한 API 키: 주문 가능

본문

size_bytesinteger · 필수
파일 크기(바이트).
file_namestring · 선택
목록의 이름. .txt로 끝납니다.

요청 예시

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}'

응답 예시 (201)

{
  "upload_id": "upl_2b7d9f10-6c3e-4a1f-8d2b-9e8f7a6b5c4d",
  "upload_url": "https://storage.example.com/upload/sign/list.txt?token=...",
  "method": "PUT",
  "headers": {
    "Content-Type": "text/plain"
  },
  "expires_at": "2026-11-05T11:00:00.000Z"
}

주문 비용 확인

POST/estimates

항목 수를 세고, 가격을 계산하고, 목록의 문제를 보고합니다. 요금을 청구하지 않습니다. 응답을 최대 5분까지 기다리세요.

필요한 API 키: 주문 가능

본문

checkerstring · 필수
GET /checkers에서 받은 체커의 id.
entriesstring[] · 선택
목록. 항목당 문자열 하나이며, 100,000건 이하이면서 4 MB 이하입니다. 이것 또는 upload_id를 보내세요.
upload_idstring · 선택
POST /uploads에서 받은 upload_id. 이것 또는 entries를 보내세요.
countrystring · 선택
번호의 국가를 밝히고 싶을 때 쓰는 두 글자 국가 코드.
file_namestring · 선택
목록의 이름. .txt로 끝납니다.

요청 예시

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"]}'

응답 예시 (200)

{
  "checker": "whatsapp_status_detection",
  "entries": 2,
  "billed_entries": 2000,
  "charge": "0.60",
  "currency": "USD",
  "parts": 1,
  "country": {
    "code": "US",
    "share": 1
  }
}

주문하기

POST/orders

잔액에서 요금을 차감하고 작업을 대기열에 넣습니다. 새 주문에는 201을, 반복에는 200과 Idempotent-Replay: true를 응답합니다. 같은 순간의 반복도 201을 응답할 수 있으므로 주문은 id로 구분하세요. 응답을 최대 5분까지 기다리세요.

필요한 API 키: 주문 가능

헤더

Idempotency-Keystring · 필수
공백 없는 200자 이하의 ASCII 문자열. 7일 동안 같은 멱등 키는 같은 주문을 뜻합니다.

본문

checkerstring · 필수
GET /checkers에서 받은 체커의 id.
entriesstring[] · 선택
목록. 항목당 문자열 하나이며, 100,000건 이하이면서 4 MB 이하입니다. 이것 또는 upload_id를 보내세요.
upload_idstring · 선택
POST /uploads에서 받은 upload_id. 이것 또는 entries를 보내세요.
countrystring · 선택
번호의 국가를 밝히고 싶을 때 쓰는 두 글자 국가 코드.
file_namestring · 선택
목록의 이름. .txt로 끝납니다.
expected_chargestring · 선택
달러 단위 가격(예: "18.00"). 비용이 조금이라도 다르면 주문이 price_changed로 거부됩니다.

요청 예시

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"]}'

응답 예시 (201)

{
  "id": "ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f",
  "checker": "whatsapp_status_detection",
  "status": "queued",
  "entries": 2,
  "charge": "0.60",
  "refunded": "0.00",
  "currency": "USD",
  "parts": {
    "total": 1,
    "completed": 0,
    "failed": 0
  },
  "results": null,
  "error": null,
  "source": "api",
  "created_at": "2026-11-05T09:00:00.000Z",
  "completed_at": null
}

주문 나열

GET/orders

최신순입니다. 다음 페이지는 next_cursor를 cursor로 다시 전달하세요.

필요한 API 키: 읽기 전용 또는 주문 가능

쿼리 매개변수

limitinteger · 선택
반환할 개수(1~100). 기본값은 20입니다.
cursorstring · 선택
이전 페이지의 next_cursor.

요청 예시

curl "https://api.talismanleads.io/v1/orders?limit=20" \
  -H "Authorization: Bearer tl_live_your_key_here"

응답 예시 (200)

{
  "orders": [
    {
      "id": "ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f",
      "checker": "whatsapp_status_detection",
      "status": "completed",
      "entries": 2,
      "charge": "0.60",
      "refunded": "0.00",
      "currency": "USD",
      "parts": {
        "total": 1,
        "completed": 1,
        "failed": 0
      },
      "results": {
        "registered": 1,
        "not_registered": 1
      },
      "error": null,
      "source": "api",
      "created_at": "2026-11-05T09:00:00.000Z",
      "completed_at": "2026-11-05T09:02:10.000Z"
    }
  ],
  "next_cursor": null
}

주문 하나

GET/orders/{id}

상태, 항목, 청구액, 환불, 파트, 집계. 파트가 끝나기 전까지 results는 null이며, 체커가 보고하지 않는 집계는 null입니다.

필요한 API 키: 읽기 전용 또는 주문 가능

경로 매개변수

idstring · 필수
주문의 id.

요청 예시

curl "https://api.talismanleads.io/v1/orders/ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f" \
  -H "Authorization: Bearer tl_live_your_key_here"

응답 예시 (200)

{
  "id": "ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f",
  "checker": "whatsapp_status_detection",
  "status": "completed",
  "entries": 2,
  "charge": "0.60",
  "refunded": "0.00",
  "currency": "USD",
  "parts": {
    "total": 1,
    "completed": 1,
    "failed": 0
  },
  "results": {
    "registered": 1,
    "not_registered": 1
  },
  "error": null,
  "source": "api",
  "created_at": "2026-11-05T09:00:00.000Z",
  "completed_at": "2026-11-05T09:02:10.000Z"
}

결과 파일

GET/orders/{id}/results

파트별로 15분 동안 유효한 다운로드 링크. 실행 중인 파트에는 링크가 없습니다. 완료된 파트에 링크가 없으면 고객 지원팀에 문의하세요.

필요한 API 키: 읽기 전용 또는 주문 가능

경로 매개변수

idstring · 필수
주문의 id.

요청 예시

curl "https://api.talismanleads.io/v1/orders/ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f/results" \
  -H "Authorization: Bearer tl_live_your_key_here"

응답 예시 (200)

{
  "order_id": "ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f",
  "status": "completed",
  "parts": [
    {
      "part": 1,
      "status": "completed",
      "file_name": "result.csv",
      "url": "https://storage.example.com/sign/result.csv?token=...",
      "expires_at": "2026-11-05T09:17:10.000Z"
    }
  ]
}

오류

이전

체커

다음

이 페이지의 내용

잔액체커 나열큰 목록 업로드주문 비용 확인주문하기주문 나열주문 하나결과 파일