API 레퍼런스

5분영업 REST API

5분영업 API를 사용하면 자체 CRM·내부 도구에서 리드 발굴, AI 메일 초안 생성, 캠페인 관리를 자동화할 수 있습니다. 모든 요청은 HTTPS이며 JSON 형식입니다.

현재 버전

v1.2

레이트 리밋

1,000 req/min

상태

Operational

Base URL · 버전

모든 API 호출은 다음 base URL을 사용합니다. 버전은 URL path에 명시합니다.

HTTPS

# Production
https://api.5min.kr/v1/

# Sandbox
https://sandbox-api.5min.kr/v1/

POST/v1/auth/token

액세스 토큰 발급

API 키와 시크릿으로 단기 액세스 토큰을 발급받습니다. 토큰 유효기간은 1시간입니다.

요청 파라미터

이름	설명
api_keystringrequired	대시보드 → 설정 → API에서 발급받은 키.
api_secretstringrequired	함께 발급받은 시크릿. 서버 사이드에서만 사용하세요.

cURL

curl -X POST https://api.5min.kr/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "pk_live_…",
    "api_secret": "sk_live_…"
  }'

Response · 200 OKapplication/json

{
  "access_token": "eyJhbGciOi…",
  "token_type": "Bearer",
  "expires_in": 3600
}

GET/v1/leads

리드 목록 조회

현재 워크스페이스에서 발굴된 리드를 페이지네이션으로 조회합니다. 기본 50개, 최대 200개.

쿼리 파라미터

이름	설명
campaign_idstring	특정 캠페인의 리드만 필터링.
statusenum	`new`, `contacted`, `replied`, `excluded`.
limitinteger	한 페이지 결과 수. 기본 50, 최대 200.
cursorstring	이전 응답의 `next_cursor`로 다음 페이지 요청.

cURL

curl https://api.5min.kr/v1/leads?status=new&limit=50 \
  -H 'Authorization: Bearer …'

Response · 200 OKapplication/json

{
  "data": [
    {
      "id": "lead_8f3k…",
      "name": "강남 미소치과",
      "industry": "medical",
      "region": "서울 강남구 역삼동",
      "email": "info@example.kr",
      "status": "new",
      "score": 92
    }
  ],
  "next_cursor": "eyJ…"
}

POST/v1/leads/search

리드 신규 발굴

키워드와 지역 조합으로 네이버 기반 발굴 엔진을 트리거합니다. 비동기 작업이며, 결과는 webhook 또는 GET /v1/leads 폴링으로 받습니다.

요청 본문

이름	설명
keywordstringrequired	업종 키워드. 예: `"치과"`, `"카페"`.
regionsarray<string>required	지역 배열. 예: `["강남구","서초구"]`.
max_resultsinteger	최대 결과 수. 기본 500, 플랜에 따라 상한이 적용됩니다.
campaign_idstring	결과를 자동으로 캠페인에 연결.

cURL

curl -X POST https://api.5min.kr/v1/leads/search \
  -H 'Authorization: Bearer …' \
  -H 'Content-Type: application/json' \
  -d '{
    "keyword": "치과",
    "regions": ["강남구", "서초구"],
    "max_results": 200,
    "campaign_id": "camp_a1b…"
  }'

GET/v1/campaigns

캠페인 목록

워크스페이스의 모든 캠페인을 조회합니다.

Response · 200 OK

{
  "data": [
    {
      "id": "camp_a1b…",
      "name": "강남 치과 1차",
      "status": "active",
      "leads_total": 247,
      "leads_contacted": 82,
      "reply_rate": 0.041,
      "created_at": "2026-05-12T09:00:00+09:00"
    }
  ]
}

POST/v1/campaigns

캠페인 생성

새 캠페인을 생성합니다. 기본 템플릿을 지정하면 이후 생성되는 메일 초안에 적용됩니다.

요청 본문

이름	설명
namestringrequired	캠페인 이름.
template_idstring	기본 적용할 콜드메일 템플릿 ID (예: `med-first-1`).
daily_send_limitinteger	하루 발송 권장 수. 기본 50, 최대 200.

POST/v1/emails/draft

AI 메일 초안 생성

리드 ID와 템플릿을 받아 업체별 개인화된 제목 3안 + 본문 1안을 생성합니다.

요청 본문

이름	설명
lead_idstringrequired	대상 리드의 ID.
template_idstring	사용할 템플릿. 미지정 시 캠페인 기본 템플릿.
toneenum	`formal` · `casual` · `concise`.

Response · 201 Created

{
  "id": "email_92x…",
  "lead_id": "lead_8f3k…",
  "subjects": [
    "강남 미소치과 환자 응대 효율을 30% 높여드릴 제안",
    "치과 전용 예약 응대 자동화 — 5분 자료",
    "[강남구] 치과 원장님께 — 응대 부담을 줄이는 제안"
  ],
  "body": "안녕하세요, 원장님…",
  "gmail_compose_url": "https://mail.google.com/mail/?…"
}

GET/v1/emails/{id}

메일 초안 조회

단일 메일 초안의 현재 상태와 본문을 조회합니다.

POST/v1/webhooks

웹훅 등록

리드 발굴 완료, 메일 발송 등 이벤트가 발생할 때 지정한 URL로 POST 알림을 받습니다.

지원 이벤트

이벤트	설명
`lead.created`	신규 리드가 발굴되었을 때.
`lead.replied`	리드가 메일에 답장했을 때 (Gmail 동기화 필요).
`email.sent`	광고주가 Gmail에서 발송 완료했을 때.
`watchlist.triggered`	Watchlist 트리거가 감지되었을 때.

Webhook payload 예시

{
  "event": "lead.created",
  "created_at": "2026-05-22T10:24:00+09:00",
  "data": {
    "lead_id": "lead_8f3k…",
    "campaign_id": "camp_a1b…"
  }
}

에러 코드

모든 에러는 HTTP 상태 코드 + 상세 본문으로 반환됩니다.

코드	의미
`400` bad_request	파라미터가 누락되었거나 형식이 잘못됨.
`401` unauthorized	토큰이 만료되었거나 잘못됨.
`403` forbidden	엔터프라이즈 외 플랜에서 API 호출.
`404` not_found	리소스를 찾을 수 없음.
`429` rate_limited	레이트 리밋 초과. `Retry-After` 헤더 참고.
`5xx` server_error	서버 측 오류. 재시도 권장.

레이트 리밋

엔터프라이즈 기본 한도는 분당 1,000 요청입니다. 응답 헤더에 잔여 호출 수가 포함됩니다.

Response headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 947
X-RateLimit-Reset: 1747900800

API 액세스가 필요하신가요?

엔터프라이즈 플랜에서만 활성화됩니다. 베타 미리보기 신청 가능.

API 접근 신청 가격 보기