API 참조
HummingDeck은 통합 파트너와 자동화 플랫폼을 위한 REST API를 제공합니다. 엔드포인트는 Bearer 토큰으로 인증하며 JSON 응답을 반환합니다.
https://app.hummingdeck.com/api/v1인증
모든 API 요청은 Authorization 헤더에 Bearer 토큰을 담아 보냅니다. 두 가지 자격 증명을 지원하며, 동작 방식이 서로 다릅니다.
방법
Bearer 토큰
헤더 형식
Authorization: Bearer {access_token}
자격 증명 종류
워크스페이스 API 토큰
Authorization: Bearer hd_api_...
워크스페이스 소유자가 워크스페이스 설정, 연동, HummingDeck API에서 발급합니다. 비공개 파일럿 기간에는 선정된 워크스페이스만 사용할 수 있습니다. 토큰은 생성 시 한 번만 표시되며 이후에는 다시 확인할 수 없습니다. 생성 후 1년이 지나면 만료되고, 발급된 워크스페이스에 영구적으로 묶이므로 요청이 워크스페이스를 선택하거나 변경할 수 없습니다.
토큰이 이미 있는 상태에서 새로 만들면 기존 토큰을 대체하며, 이전 토큰은 즉시 작동을 멈춥니다. 소유자는 언제든 토큰을 사용 중지할 수 있습니다. 해당 토큰에 대해서는 되돌릴 수 없으므로 복구 대신 새 토큰을 생성하세요.
웹훅 구독 엔드포인트는 워크스페이스 API 토큰으로 사용할 수 없습니다.
Zapier OAuth
Authorization: Bearer {access_token}
워크스페이스가 Zapier 연동을 연결할 때 OAuth 인증 절차를 통해 발급됩니다. 액세스 토큰은 30일 후 만료됩니다. 90일간 유효한 리프레시 토큰을 사용하면 다시 인증하지 않고 새 액세스 토큰을 받을 수 있습니다.
웹훅 구독을 생성하거나 삭제할 수 있는 유일한 자격 증명입니다.
요청이 401을 반환하는 경우
토큰을 알 수 없거나 형식이 잘못된 경우, 만료된 경우, 사용 중지된 경우, API 액세스가 꺼진 워크스페이스에 속한 경우, 또는 더 이상 해당 워크스페이스의 소유자가 아닌 사람이 발급한 경우 요청은 401로 거부됩니다.
연결 테스트
토큰이 유효한지 확인하고 인증된 사용자의 프로필을 확인합니다.
/me현재 사용자의 이름, 이메일, 팀 정보를 반환합니다.문서
문서(PDF, 슬라이드 덱, 제안서 및 기타 파일)를 업로드, 검색 및 관리합니다.
/decks새 문서를 업로드합니다. file 필드(PDF, PPTX, DOCX, XLSX, HTML)와 title 필드를 포함한 multipart/form-data로 전송합니다. API 업로드 한도는 30MB입니다./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 타임스탬프 |
룸
룸 구조를 조회하고 추적 가능한 룸 대상 링크를 만듭니다. 워크스페이스 API 토큰으로만 사용할 수 있으며 Zapier OAuth 자격 증명은 거부됩니다.
/rooms/{roomId}룸 메타데이터, 탭, 콘텐츠 항목, 활성 및 전체 링크 수를 반환합니다./rooms/{roomId}/links활성 룸에 귀속 정보가 있는 공개 링크를 만듭니다.공개 룸 링크 만들기
recipientName, recipientEmail, contactId, companyId, companyName 중 하나 이상을 입력하세요. 이름과 이메일은 연락처를 찾거나 만들고, 회사 필드는 회사를 찾거나 만듭니다. 공개 링크는 URL을 아는 누구나 룸을 볼 수 있습니다.
{
"accessMode": "open",
"recipientName": "Ada Lovelace",
"recipientEmail": "ada@analytical.example",
"companyName": "Analytical Engines"
}회사 및 연락처
기존 계정 레코드를 결정적으로 찾아 사용하거나 새로 만듭니다. 회사 이름과 연락처 이메일은 대소문자를 구분하지 않고 일치시킵니다.
/companies?name={name}&domain={domain}정확한 이름과 선택적 도메인으로 회사를 검색합니다./companies대소문자를 구분하지 않는 이름으로 회사를 찾거나 만듭니다. 명시적 도메인은 레코드 정보만 보완합니다./contacts?email={query}이메일 주소로 연락처를 검색합니다. 연관된 회사와 함께 일치하는 연락처를 반환합니다./contacts연락처를 이메일로 찾거나 만들고 선택적으로 회사에 연결합니다.POST /companies 요청
| Field | Type | Description | |
|---|---|---|---|
| name | string | 필수 | 회사 이름 |
| domain | string | 선택 | 회사 정보 보완에 사용할 도메인. 기존 회사 일치에는 사용하지 않음 |
POST /contacts 요청
| Field | Type | Description | |
|---|---|---|---|
| name | string | 조건부 | 전체 이름. firstName이 없으면 필수 |
| firstName | string | 조건부 | 이름. name이 없으면 필수 |
| lastName | string | 선택 | 성 |
| string | 필수 | 고유하게 일치시킬 이메일 주소 | |
| title | string | 선택 | 직함 |
| companyId | UUID | 선택 | 인증된 워크스페이스의 기존 회사 |
| companyName | string | 선택 | 찾거나 만들 회사 이름 |
| companyDomain | string | 선택 | companyName과 함께 사용할 선택적 정보 보완 도메인. 회사 일치 키가 아님 |
회사 응답
| Field | Type | Description |
|---|---|---|
| company.id | UUID | 회사 ID |
| company.name | string | 회사 이름 |
| company.domain | string | null | 정규화된 회사 도메인 |
| created | boolean | POST 요청에서 회사를 만든 경우 true |
연락처 응답
| Field | Type | Description |
|---|---|---|
| contact.id | UUID | 연락처 ID |
| contact.firstName | string | 이름 |
| contact.lastName | string | 성 |
| contact.email | string | 정규화된 이메일 주소 |
| contact.title | string | null | 직함 |
| contact.companyId | UUID | null | 연결된 회사 ID |
| contact.companyName | string | null | 연결된 회사 이름 |
| created | boolean | POST 요청에서 연락처를 만든 경우 true |
| company | object | null | 확인된 회사(있는 경우) |
| companyCreated | boolean | 이 요청에서 회사를 만든 경우 true |
Webhook
REST Hooks를 통해 실시간 이벤트를 구독합니다. 이벤트가 발생하면 HummingDeck은 이벤트 페이로드와 함께 등록된 HTTPS URL로 POST 요청을 전송합니다. 배달 실패 시 최대 3회 재시도됩니다(1초, 5초, 30초 간격). 웹훅 구독은 Zapier 연동으로 관리되며 워크스페이스 API 토큰으로는 사용할 수 없습니다.
/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게이트 콘텐츠에서의 최근 이메일 캡처를 나열합니다.오류 처리
모든 오류는 무엇이 잘못되었는지 설명하는 error 필드가 담긴 JSON 객체를 반환합니다. 일부 응답에는 PLAN_LIMIT_REACHED, INVALID_FORMAT, FILE_TOO_LARGE처럼 프로그래밍 방식으로 처리할 수 있는 code 필드도 포함됩니다. HTTP 상태 코드는 표준 규칙을 따릅니다.
| Status | Meaning |
|---|---|
| 400 | 잘못된 요청: 누락되거나 잘못된 파라미터 |
| 401 | 인증되지 않음: 유효하지 않거나 만료된 Bearer token |
| 403 | 금지됨: 요금제 한도에 도달했거나 이 엔드포인트에서 허용되지 않는 자격 증명 유형입니다 |
| 404 | 찾을 수 없음: 리소스가 존재하지 않거나 팀 소유가 아님 |
| 409 | 충돌: 제공된 연락처, 이메일, 회사 식별자가 서로 일치하지 않습니다 |
| 500 | 서버 오류: 요청을 재시도하십시오 |
속도 제한
팀당 최대 50개의 활성 webhook 구독. API 요청에는 속도 제한이 없지만 과도한 사용은 제한될 수 있습니다.
이 API는 현재 당사의 Zapier 통합에서 사용됩니다. 향후 추가 통합 플랫폼이 지원될 수 있습니다.