APIリファレンス

認証

すべてのAPIリクエストは、AuthorizationヘッダーにBearer tokenを付けて送信します。2種類の認証情報に対応しており、それぞれ挙動が異なります。

認証情報の種類

権限

権限を1つ以上選択してください。書き込み権限には対応する読み取り権限も含まれます。キーを再発行するときに権限を変更できます。

エンドポイント行の権限ラベルは、ワークスペース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"
}

レスポンスフィールド

ルーム

ドキュメントと対象者向けリンクを備えたデジタルセールスルームを1回の呼び出しで作成し、ルームの検索、設定の変更、アーカイブと復元、タブと項目の整理を行います。ワークスペース API トークンでのみ利用でき、Zapier OAuth 認証情報は拒否されます。

1回の呼び出しでルームを作成

各ファイルを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から数える）を示します。タブや項目を指定した位置に追加し、項目をタブ間で移動し、タブの新しい順序を全体として送信します。順序にはタブ内のすべての項目を1回ずつ含める必要があるため、途中で別の変更が入った場合はルームを読み込み直してください。タブは、項目を表示しなくなれば削除できます。

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

対応している埋め込み提供元

埋め込みは共有リンクと埋め込みリンクのどちらも受け付け、提供元の埋め込み形式に正規化します。この一覧にないものは 400 EMBED_PROVIDER_NOT_SUPPORTED を返します。

別のオーディエンス用リンクを追加

どのルームにも POST /rooms で作られたリンクが1つあります。帰属や権限を分けたい相手には、さらにリンクを追加してください。recipientName、recipientEmail、contactId、companyId、companyName のうち少なくとも1つを指定します。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"
    }
  ]
}

リンクを更新

対象は4つのフィールドです。isActive、expiresAt、allowedEmails、allowedDomains（後者2つは verified-allowlist のリンクのみ）。accessMode とスラッグは変更できないため、新しいリンクを作成してください。リンクを再度有効にすると、プランのアクティブリンク数の上限が再確認されます。

{
  "isActive": false
}

アクションプランを組み立てる

どのルームにもプランはちょうど1つなので、プラン専用のIDはなくルームの下に置かれます。多くのタスクは個人ではなく会社に属します。sideだけを送ればプランはそれを会社として扱います。相手側の誰が作業するか分からないときは、これが適切です。担当者が分かっている場合にだけemailを追加してください。社内限定のタスクはルームに表示されないため、受信者側に割り当てることはできません。

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

プランのrecipientCompletionEnabledが、ルームを開いた人が自分の側のタスクを完了にできるかどうかを決めます。既定値はtrueで、これが唯一の条件です。タスクを完了するために受信者のアドレスをAPIが求めることはありません。誰が完了にしたかは、ルームのアクセスモードに応じた確度で記録されます。

ルームにラベルを付ける

ラベルはワークスペース全体で共有されるので、一度作れば使い回せます。作成と同時にルームへ付けるにはPOST /roomsでlabelIdsを渡し、まとめて入れ替えるにはPATCH /rooms/{roomId}で渡します。空の配列はすべてのラベルを外し、フィールドを省略すると変更されません。1つのルームが持てるのは最大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秒の間隔）。 Webhookのサブスクリプションは 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回、書き込みは1分あたり120回、/room-viewsは1分あたり60回、アップロードは1時間あたり20回です。すべての認証情報を合わせたワークスペース単位では、読み取りは5分あたり1,200回、書き込みは1分あたり240回、/room-viewsは1分あたり120回、アップロードは1時間あたり40回です。Bearer認証の失敗と無効なOAuthクライアント認証は、それぞれクライアントIPごとに5分あたり60回までです。チームあたりアクティブなwebhookサブスクリプションは最大50件です。