API 참조

인증

모든 API 요청은 Authorization 헤더에 Bearer 토큰을 담아 보냅니다. 두 가지 자격 증명을 지원하며, 동작 방식이 서로 다릅니다.

자격 증명 종류

권한

권한을 하나 이상 선택하세요. 쓰기 권한에는 해당 읽기 권한도 포함됩니다. 키를 교체할 때 권한을 변경할 수 있습니다.

엔드포인트 행의 권한 표시는 워크스페이스 API 키에 적용됩니다. 필수 권한은 항상 필요하고, 추가 필수 권한은 함께 필요하며, 조건부 권한은 요청에서 관련 필터나 필드를 사용할 때만 필요합니다. GET /me에는 권한이 필요하지 않습니다. Zapier OAuth에는 고정된 연동 접근 권한이 적용됩니다.

요청이 401을 반환하는 경우

키를 알 수 없거나 형식이 잘못된 경우, 만료되었거나 비활성화된 경우, API 액세스가 꺼진 워크스페이스에 속한 경우, 또는 발급자가 더 이상 해당 워크스페이스의 소유자나 관리자가 아닌 경우 요청은 401을 반환합니다.

연결 테스트

토큰이 유효한지 확인하고 인증된 사용자의 프로필을 확인합니다.

문서

문서(PDF, 슬라이드 덱, 제안서 및 기타 파일)를 업로드, 검색 및 관리합니다.

GET /decks 응답 필드

POST /decks 응답 필드

공유 링크

추적 가능한 문서 링크를 만듭니다. 개인 링크는 같은 요청에서 연락처와 회사를 찾거나 만들 수 있습니다.

요청 필드

링크와 계정 레코드를 함께 만들기

수신자와 회사 정보를 /shares로 직접 전송합니다. HummingDeck이 일치하는 레코드를 찾고, 없는 레코드를 만든 뒤 링크에 연결하고 무엇이 생성되었는지 알려 줍니다. 계정 생성을 건너뛰려면 type을 anonymous로 명시하세요.

{
  "deckId": "8f3d41de-2bb8-4d8e-80de-6cd2072ffab1",
  "recipientName": "Ada Lovelace",
  "recipientEmail": "ada@analytical.example",
  "companyName": "Analytical Engines",
  "companyDomain": "analytical.example"
}

응답 필드

룸

문서와 대상 링크를 갖춘 딜룸을 한 번의 호출로 만들고, 룸을 찾고, 설정을 변경하고, 보관 및 복원하고, 탭과 항목을 정리합니다. 워크스페이스 API 토큰으로만 사용할 수 있으며 Zapier OAuth 자격 증명은 거부됩니다.

한 번의 호출로 룸 만들기

각 파일을 POST /decks로 업로드한 다음, 수신자 회사를 위한 룸을 봐야 할 사람만 열 수 있는 제한된 링크와 함께 만드세요. 회사, 연락처, 룸, 문서, 링크가 함께 만들어지므로 호출이 거부되면 아무것도 만들어지지 않습니다. 문서는 처리 중에도 룸에 추가할 수 있습니다. 룸의 항목은 processingStatus를 알려 주므로 모든 문서가 completed가 된 뒤에 링크를 보내세요.

{
  "name": "Acme renewal",
  "companyName": "Acme Inc",
  "recipientName": "Pat Buyer",
  "recipientEmail": "pat@acme.example",
  "documentIds": [
    "{documentId}",
    "{documentId}"
  ],
  "primaryLink": {
    "accessMode": "verified-allowlist",
    "allowedEmails": [
      "pat@acme.example",
      {
        "email": "cfo@acme.example",
        "name": "Sam Rivera"
      }
    ],
    "allowedDomains": [
      "acme.example"
    ]
  }
}

accessMode는 open(URL을 아는 누구나), verify-any(방문자가 일회용 링크로 이메일 주소를 확인), verified-allowlist(allowedEmails의 주소와 allowedDomains 도메인의 주소를 가진 사람만) 중 하나입니다. API는 제한된 링크에 누구도 자동으로 추가하지 않으므로, 룸을 미리 보려면 본인 주소도 넣으세요. 요금제에 없는 옵션은 403 FEATURE_NOT_AVAILABLE을, 알 수 없는 필드는 400을 반환하므로 룸이 요청한 것과 다른 대상에게 열리는 일은 없습니다.

탭과 항목 정리하기

룸의 현재 상태에서 시작하세요. 룸을 읽으면 탭과 항목이 표시 순서대로 반환되고, 각 항목은 속한 탭과 그 안에서의 위치(0부터 셈)를 알려 줍니다. 탭과 항목을 원하는 위치에 추가하고, 항목을 탭 사이로 옮기고, 탭의 새 순서를 전체로 보내세요. 순서에는 탭의 모든 항목이 정확히 한 번씩 들어가야 하므로, 그 사이에 다른 변경이 있었다면 룸을 다시 읽으세요. 탭은 항목이 하나도 표시되지 않을 때 삭제할 수 있습니다.

{
  "type": "section",
  "label": "Commercials",
  "tabId": "{tabId}",
  "position": 0
}

지원되는 임베드 제공업체

임베드는 공유 링크와 임베드 링크를 모두 받아 제공업체의 임베드 형식으로 정규화합니다. 이 목록에 없는 것은 400 EMBED_PROVIDER_NOT_SUPPORTED를 반환합니다.

다른 대상용 링크 추가

모든 룸에는 POST /rooms로 만든 링크가 이미 하나 있습니다. 귀속이나 접근 권한을 다르게 하려면 링크를 더 추가하세요. recipientName, recipientEmail, contactId, companyId, companyName 중 최소 하나를 지정합니다. accessMode는 primaryLink와 같은 open, verify-any, verified-allowlist 값을 받고 필드도 동일합니다(requireEmail, allowedEmails, allowedDomains, label, expiresAt, allowDownloads). 요금제 한도를 포함해 거부된 호출은 링크도, 회사도, 연락처도 남기지 않습니다.

{
  "companyName": "Analytical Engines",
  "accessMode": "verified-allowlist",
  "allowedEmails": [
    {
      "email": "cfo@analytical.example",
      "name": "Sam Rivera"
    }
  ]
}

링크 업데이트

네 개의 필드를 바꿀 수 있습니다. isActive, expiresAt, allowedEmails, allowedDomains(뒤의 두 개는 verified-allowlist 링크에만 해당). accessMode와 슬러그는 바뀌지 않으므로 새 링크를 만드세요. 링크를 다시 켜면 요금제의 활성 링크 한도를 다시 확인합니다.

{
  "isActive": false
}

실행 계획 만들기

모든 룸에는 계획이 정확히 하나 있으므로 별도 ID 없이 룸 아래에 붙습니다. 대부분의 작업은 개인이 아니라 회사에 속합니다. side만 보내면 계획은 이를 회사로 읽으며, 상대 쪽에서 누가 일할지 모를 때 이것이 적절합니다. 담당자를 아는 경우에만 email을 추가하세요. 내부 전용 작업은 룸에 표시되지 않으므로 수신자 쪽에 배정할 수 없습니다.

{
  "title": "Sign the NDA",
  "assignee": {
    "side": "buyer"
  },
  "dueDate": "2026-10-02"
}

계획의 recipientCompletionEnabled가 룸을 여는 사람이 자기 쪽 작업을 완료 처리할 수 있는지 결정합니다. 기본값은 true이며 이것이 유일한 조건입니다. 작업을 완료하기 위해 API가 수신자의 주소를 요구하는 일은 없습니다. 누가 완료했는지는 룸의 접근 방식이 제공하는 확실성만큼 기록됩니다.

룸에 라벨 붙이기

라벨은 워크스페이스 전체에서 공유되므로 한 번 만들어 재사용합니다. 룸을 만들면서 라벨을 붙이려면 POST /rooms에 labelIds를 전달하고, 전체 세트를 교체하려면 PATCH /rooms/{roomId}에 전달하세요. 빈 배열은 모든 라벨을 제거하고, 필드를 생략하면 그대로 유지됩니다. 한 룸은 최대 5개를 가지며, 이는 설정이 아니라 구조적 제한입니다. 룸을 읽으면 라벨도 함께 반환됩니다.

{
  "labelIds": [
    "{labelId}"
  ]
}

무슨 일이 있었는지 확인하기

/room-views를 조회해 워크스페이스 전체의 입장 기록을 확인한 다음, 개별 룸의 분석, 활동 및 수집된 주소를 읽습니다. 계속하려면 페이지의 nextCursor를 cursor로 전달하세요. 이 API가 발급하지 않은 커서는 처음부터 다시 시작하지 않고 400을 반환하므로 폴링 작업이 중복되지 않습니다. since로 활동 기간을 좁히고 cursor로 페이지를 이어서 가져옵니다. /room-views는 아카이브가 아니라 기간입니다. since를 생략하면 최근 30일이 반환되며, 90일보다 오래된 요청은 거부됩니다. 적용된 기간은 since로 반환되므로 cursor와 함께 보내면 같은 범위를 계속 조회할 수 있습니다.

회사 및 연락처

기존 계정 레코드를 결정적으로 찾아 사용하거나 새로 만듭니다. 회사 이름과 연락처 이메일은 대소문자를 구분하지 않고 일치시킵니다.

POST /companies 요청

POST /contacts 요청

회사 응답

연락처 응답

Webhook

REST Hooks를 통해 실시간 이벤트를 구독합니다. 이벤트가 발생하면 HummingDeck은 이벤트 페이로드와 함께 등록된 HTTPS URL로 POST 요청을 전송합니다. 배달 실패 시 최대 3회 재시도됩니다(1초, 5초, 30초 간격). 웹훅 구독은 Zapier 연동으로 관리되며 워크스페이스 API 토큰으로는 사용할 수 없습니다.

이벤트 유형

페이로드 예시

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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이 실시간으로 전달하는 동일한 데이터를 반환합니다. 백필링, 테스트 또는 대안으로 사용하십시오.

오류 처리

모든 오류는 무엇이 잘못되었는지 설명하는 error 필드가 담긴 JSON 객체를 반환합니다. 대부분의 응답에는 PLAN_LIMIT_REACHED, FEATURE_NOT_AVAILABLE, ROOM_NOT_ACTIVE, TAB_NOT_EMPTY, INVALID_FORMAT, FILE_TOO_LARGE처럼 프로그래밍 방식으로 처리할 수 있는 code 필드도 포함됩니다. HTTP 상태 코드는 표준 규칙을 따릅니다.

속도 제한

수동 워크스페이스 키와 Zapier OAuth 연결에는 자격 증명별 제한이 적용됩니다. 읽기는 5분당 600회, 쓰기는 분당 120회, /room-views는 분당 60회, 업로드는 시간당 20회입니다. 모든 자격 증명을 합친 워크스페이스별 제한은 읽기 5분당 1,200회, 쓰기 분당 240회, /room-views 분당 120회, 업로드 시간당 40회입니다. Bearer 인증 실패와 유효하지 않은 OAuth 클라이언트 인증은 각각 클라이언트 IP별로 5분당 60회로 제한됩니다. 팀당 활성 webhook 구독은 최대 50개입니다.