API 참조
HummingDeck은 통합 파트너와 자동화 플랫폼을 위한 REST API를 제공합니다. 모든 엔드포인트는 OAuth 2.0 인증을 사용하며 JSON 응답을 반환합니다.
https://app.hummingdeck.com/api/v1인증
모든 API 요청은 Authorization 헤더에 유효한 OAuth 2.0 Bearer token이 필요합니다. 토큰은 OAuth 인증 흐름 중에 발급되며 30일 후 만료됩니다. 재인증 없이 새 액세스 토큰을 얻으려면 리프레시 토큰(90일 만료)을 사용하십시오.
방법
OAuth 2.0 (Bearer token)
헤더 형식
Authorization: Bearer {access_token}
연결 테스트
토큰이 유효한지 확인하고 인증된 사용자의 프로필을 확인합니다.
/me현재 사용자의 이름, 이메일, 팀 정보를 반환합니다.문서
문서(PDF, 슬라이드 덱, 제안서 및 기타 파일)를 업로드, 검색 및 관리합니다.
/decks새 문서를 업로드합니다. file 필드(PDF, PPTX, DOCX, HTML)와 title 필드를 포함한 multipart/form-data로 전송합니다./decks?title={query}제목으로 문서를 검색합니다. 대소문자를 구분하지 않으며, 최대 20개의 결과를 반환합니다.응답 필드
| Field | Type | Description |
|---|---|---|
| id | string | 문서 ID |
| title | string | 문서 제목 |
| fileType | string | 파일 유형(pdf, pptx, docx, html) |
| pageCount | number | 페이지 수 |
| thumbnailUrl | string | 썸네일 이미지 URL |
| createdAt | string | ISO 8601 타임스탬프 |
연락처
팀 주소록에서 연락처를 검색합니다.
/contacts?email={query}이메일 주소로 연락처를 검색합니다. 연관된 회사와 함께 일치하는 연락처를 반환합니다.응답 필드
| Field | Type | Description |
|---|---|---|
| id | string | 연락처 ID |
| firstName | string | 이름 |
| lastName | string | 성 |
| string | 이메일 주소 | |
| title | string | 직함 |
| leadName | string | 회사명 |
| createdAt | string | ISO 8601 타임스탬프 |
Webhook
REST Hooks를 통해 실시간 이벤트를 구독합니다. 이벤트가 발생하면 HummingDeck은 이벤트 페이로드와 함께 등록된 HTTPS URL로 POST 요청을 전송합니다. 배달 실패 시 최대 3회 재시도됩니다(1초, 5초, 30초 간격).
/hooks이벤트를 구독합니다. HTTPS 대상 URL과 이벤트 유형이 필요합니다. 구독 ID를 반환합니다./hooks/{id}구독 ID로 이벤트 구독을 취소합니다.이벤트 유형
| Event | Description |
|---|---|
| view.created | 실제 사람이 공유된 문서를 조회했습니다. 봇 트래픽(이메일 보안 스캐너, 크롤러)은 자동으로 필터링됩니다. |
| decision.made | 잠재 고객이 제안에 응답했습니다 — 수락, 거절 또는 변경 요청. |
| email_captured | 방문자가 게이트 콘텐츠에 접근하기 위해 이메일 주소를 입력했습니다. |
페이로드 예시
view.created
{
"event": "view.created",
"data": {
"id": "view_abc123",
"deck_id": "deck_xyz789",
"deck_title": "Q4 Enterprise Proposal",
"viewer_email": "sarah@acme.com",
"viewer_name": "Sarah Wood",
"viewer_company": "Acme Corp",
"location": "San Francisco, CA",
"device": "Desktop",
"browser": "Chrome",
"pages_viewed": 8,
"total_pages": 12,
"duration_seconds": 272,
"completion_percent": 67,
"created_at": "2026-03-29T14:32:00Z"
}
}decision.made
{
"event": "decision.made",
"data": {
"share_slug": "proposal-2024",
"decision": "accepted",
"deck_title": "Q4 Enterprise Proposal",
"viewer_email": "sarah@acme.com",
"viewer_name": "Sarah Wood",
"decision_note": "Approved pending final review",
"decided_at": "2026-03-29T15:30:00Z"
}
}email_captured
{
"event": "email_captured",
"data": {
"email": "prospect@company.com",
"share_slug": "proposal-2024",
"deck_title": "Q4 Enterprise Proposal",
"view_id": "view_xyz789",
"captured_at": "2026-03-29T14:35:00Z"
}
}조회수 및 이벤트
최근 참여 데이터를 검색하기 위한 폴링 엔드포인트입니다. webhook이 실시간으로 전달하는 동일한 데이터를 반환합니다 — 백필링, 테스트 또는 대안으로 사용하십시오.
/views가장 최근의 문서 조회 100건을 나열합니다. 봇 세션은 제외됩니다./decisions최근 제안 결정(수락, 거절, 변경 요청)을 나열합니다./emails게이트 콘텐츠에서의 최근 이메일 캡처를 나열합니다.오류 처리
모든 오류는 message 필드가 있는 JSON 객체를 반환합니다. HTTP 상태 코드는 표준 규칙을 따릅니다.
| Status | Meaning |
|---|---|
| 400 | 잘못된 요청 — 누락되거나 잘못된 파라미터 |
| 401 | 인증되지 않음 — 유효하지 않거나 만료된 Bearer token |
| 404 | 찾을 수 없음 — 리소스가 존재하지 않거나 팀 소유가 아님 |
| 500 | 서버 오류 — 요청을 재시도하십시오 |
속도 제한
팀당 최대 50개의 활성 webhook 구독. API 요청에는 속도 제한이 없지만 과도한 사용은 제한될 수 있습니다.
이 API는 현재 당사의 Zapier 통합에서 사용됩니다. 향후 추가 통합 플랫폼이 지원될 수 있습니다.