信頼のために構築TLS 暗号化GDPR 対応Google Cloud安全なお支払いセキュリティ概要
G2

G2で5段階中5.0の評価

G2でレビューを読む
The page-level analytics are the best part because they show real engagement instead of just basic opens.
Verified User in Computer Software
What I like most about the product is how easy it is to use, especially when it comes to listing all my links and embedding demos in one place for leads and prospects.
Jerome K.Founder
Responsiveness, configurability and development velocity.
Suman K.Co-Founder & CEO

APIリファレンス

HummingDeckは、統合パートナーや自動化プラットフォーム向けにREST APIを提供しています。各エンドポイントはBearer tokenで認証し、JSONレスポンスを返します。

ベースURLhttps://app.hummingdeck.com/api/v1
OpenAPI Spec

認証

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

メソッド

Bearer token

ヘッダー形式

Authorization: Bearer {access_token}

認証情報の種類

ワークスペースAPIトークン

Authorization: Bearer hd_api_...

REST APIへのアクセスは有料のBusinessプランに含まれています。Businessのトライアル中は、申請に応じてアクセスを付与します。その後、ワークスペースの所有者と管理者は、ワークスペース設定、連携、HummingDeck APIで名前付きのAPIキーを個別に作成できます。連携に必要な権限だけを選択してください。キーは作成時に一度だけ表示され、あとから取得できません。作成から1年で失効し、発行先のワークスペースに固定されるため、リクエスト側でワークスペースを選択したり変更したりすることはできません。

1つのワークスペースで有効にできるAPIキーは20個までです。キーを再発行すると、そのキーの以前のシークレットだけが直ちに無効になり、他のキーは引き続き使用できます。所有者と管理者は、個別のキーまたはすべてのキーをいつでも無効にできます。無効にしたシークレットは復元できません。

ワークスペースAPIキーが呼び出せるのは、選択された権限で許可された操作だけです。Webhookサブスクリプション用エンドポイントは利用できません。

Zapier OAuth

Authorization: Bearer {access_token}

ワークスペースがZapier連携を接続する際に、OAuth認証フローを通じて発行されます。アクセストークンは30日で失効します。有効期限90日のリフレッシュトークンを使うと、再認証なしで新しいアクセストークンを取得できます。

Webhookのサブスクリプションを作成・削除できるのは、この認証情報だけです。

権限

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

rooms:read

ルーム、タブ、項目、リンク、ラベルを表示します。

rooms:write

ルーム、タブ、項目、リンク、ラベルを作成・管理します。

plan:read

相互アクションプランのフェーズとタスクを表示します。

plan:write

相互アクションプランのフェーズとタスクを作成・管理します。

analytics:read

エンゲージメント分析、アクティビティ、取得メールを表示します。

crm:read

ワークスペースの会社と連絡先を検索します。

crm:write

会社、連絡先、リンクの対象者を作成・更新します。

documents:read

ドキュメントを検索し、メタデータを表示します。

documents:write

ドキュメントのアップロード、差し替え、名前変更、削除、共有リンクの管理、RoomsへのドキュメントやURLの追加。

エンドポイント行の権限ラベルは、ワークスペースAPIキーに適用されます。「必須」は常に必要、「追加で必須」は主な権限と併せて必要、「条件付き」はリクエストで関連するフィルターやフィールドを使う場合だけ必要です。GET /me に権限は不要です。Zapier OAuth には固定された連携アクセスが適用されます。

リクエストが401を返す場合

キーが不明または不正な形式である、失効または無効化されている、APIアクセスが無効なワークスペースに属している、あるいは発行者がそのワークスペースの所有者または管理者ではなくなった場合、リクエストは401を返します。

接続のテスト

トークンが有効であることを確認し、認証済みユーザーのプロフィールを確認します。

GET/me

現在のユーザーの名前、メールアドレス、チーム情報を返します。

APIキーの権限は不要

ドキュメント

ドキュメント(PDF、プレゼンテーション資料、提案書、その他のファイル)のアップロード、検索、管理を行います。

POST/decks

新しいドキュメントをアップロードします。fileフィールド(PDF、PPTX、DOCX、XLSX、XLS、HTML)とtitleフィールドを含むmultipart/form-dataとして送信します。API経由のアップロード上限は30MBです。アップロード後も処理は続き、レスポンスにはprocessingStatusが含まれます。

必須:documents:write
GET/decks/{deckId}

ドキュメントのメタデータと処理状況を取得

必須:documents:read
PATCH/decks/{deckId}

title(1~255文字)を含むJSONで資料名を変更します。資料ID、ファイル、共有リンクは維持されます。

必須:documents:write
DELETE/decks/{deckId}

資料を削除済みにし、すべての共有リンクを無効にします。元ファイルと過去の分析データは保持されます。有効な提案書がある場合は409 PROPOSAL_LOCKEDを返します。

必須:documents:write
GET/decks

新しい順に最大20件の資料を一覧表示します。任意のクエリパラメーター title を使うと、大文字と小文字を区別せずにタイトルの一部で絞り込めます。

必須:documents:read
GET/decks/search

queryで資料のタイトルを検索し、folderId(フォルダ未設定はroot)、fileType、createdAfter、createdBeforeで絞り込みます。sortはcreated_desc、created_asc、title_ascです。itemsとnextCursorを返します。limitは既定で20(1~100)。次のページでもフィルタと並び順を維持してください。

必須:documents:read
POST/decks/{deckId}/replace

同じ形式のローカルファイルで資料を差し替えます。documents:write 権限を持つワークスペース API キーが必要です。既存のリンク、タイトル、提供方法は維持されます。プレビュー可能なファイルは pending、ダウンロード専用ファイルは completed を返します。レスポンス項目は POST /decks と同じです。

必須:documents:write

GET /decks レスポンスフィールド

FieldTypeDescription
idstringドキュメントID
titlestringドキュメントタイトル
fileTypestringドキュメントのMIMEタイプ
pageCountinteger | nullページ数
thumbnailUrlstring | nullサムネイル画像のURL
processingStatusstringpending、processing、completed、failedのいずれか。処理中のドキュメントもルームに追加できます。ドキュメントへのリンクは、completedになってから送信してください。
processingErrorCodestring | null処理が失敗した場合の理由
createdAtstringISO 8601タイムスタンプ

POST /decks レスポンスフィールド

FieldTypeDescription
idstringドキュメントID
titlestringドキュメントタイトル
fileTypestringドキュメントのMIMEタイプ
processingStatusstringpending、processing、completed、failedのいずれか。処理中のドキュメントもルームに追加できます。ドキュメントへのリンクは、completedになってから送信してください。
processingErrorCodestring | null処理が失敗した場合の理由

共有リンク

追跡可能な資料リンクを作成・管理します。アクセス設定はpersonal/anonymousの帰属設定とは別です。個人用リンクでは同じリクエストで連絡先と会社を検索または作成できます。

POST/shares

アクセス、有効期限、ダウンロード、通知を設定して個人用または匿名リンクを作成します。accessの省略時はopenです。

必須:documents:write
条件付き:crm:write(Required for a non-anonymous share when the request supplies contactId, companyId, companyName, recipientEmail, or recipientName.)
GET/shares

単独の資料リンクを一覧表示し、documentIdまたは完全一致のslugで絞り込めます。itemsとnextCursorを返します。limitは既定で25(1~100)。ルームで作成したリンクにはルーム用のエンドポイントを使います。

必須:documents:read
GET/shares/{shareId}

単独の資料リンク、閲覧URL、有効なアクセス設定を取得します。受信者の識別情報と許可メールアドレスの取得にはcrm:readが必要です。

必須:documents:read
PATCH/shares/{shareId}

isActive、allowedEmails、verificationMethod、singleUseLink、expiresAt、allowDownload、notifyOnView、notifySlackを編集します。アクセス方式、資料、type、slugは固定です。isActive: falseで無効にします。

必須:documents:write

リクエストフィールド

FieldTypeDescription
deckIdstring必須共有するドキュメントのID
recipientNamestring任意受信者の名前(個人リンク用)
recipientEmailstring任意受信者のメールアドレス(個人リンク用)
contactIdUUID任意認証済みワークスペースの既存の連絡先
companyIdUUID任意既存の会社。companyNameとは同時に使用できません
companyNamestring任意名前で検索または新規作成する会社
companyDomainstring任意companyNameが指定された場合に情報補完用として保存するドメイン。会社の選択には使用されません
typestring任意personalまたはanonymous。restricted、または受信者/会社情報がある場合の既定値はpersonal、それ以外はanonymousです。
accessstring任意open(既定)、ask(メール取得)、verify(任意の受信箱を確認)、restricted(許可された受信箱を確認)。メール取得とアクセス制限には対応するプランの機能が必要です。
allowedEmailsstring[]条件付きrestrictedで許可する完全一致のメールアドレス。1件以上、最大100件が必要です。ドメインのルールはルームにのみ適用されます。
verificationMethodstring任意verify/restrictedで使うcodeまたはlink。
singleUseLinkboolean任意確認が必要なアクセス方式で、メールのアクセスリンクを1回限りにするかどうか。コードは常に1回限りです。
expiresAtstring | null任意ISO 8601形式の有効期限。期限なしの場合はnull。
allowDownloadboolean任意閲覧者が資料をダウンロードできるかどうか。
notifyOnViewboolean任意閲覧通知をメールで送信するかどうか。
notifySlackboolean任意閲覧通知をSlackに送信するかどうか。

リンクとアカウント情報をまとめて作成

受信者と会社の情報を/sharesに直接送信します。HummingDeckは一致する情報を検索し、不足している場合は作成してリンクに関連付け、作成結果を返します。アカウント情報を作成しない場合は、typeにanonymousを明示してください。

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

レスポンスフィールド

FieldTypeDescription
idstring共有ID
slugstring共有スラッグ(URLで使用)
shareUrlstring完全な追跡可能URL
typestring"personal"または"anonymous"
recipientNamestring受信者名(個人リンクの場合)
recipientEmailstring受信者メールアドレス(個人リンクの場合)
contactobject | null個人リンクに関連付けられた連絡先
contactCreatedbooleanこのリクエストで連絡先を作成した場合はtrue
companyobject | null個人リンクに関連付けられた会社
companyCreatedbooleanこのリクエストで会社を作成した場合はtrue
createdAtstringISO 8601タイムスタンプ

ルーム

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

GET/rooms

ルームを新しい順に一覧表示します。search、status(active、archived、all)、companyIdで絞り込めます。1ページは25件(limitで最大100件)です。次のページを取得するには、そのページのnextCursorをcursorとして渡します。

必須:rooms:read
条件付き:crm:read(Required when the companyId filter is present.)
POST/rooms

ドキュメントと最初の対象者向けリンクを含むルームを1回の呼び出しで作成します。

必須:rooms:write
条件付き:documents:write(Required when documentIds contains one or more document IDs.)crm:write(Required when the request supplies contactId, recipientName, recipientEmail, companyId, companyName, or when either primaryLink.allowedEmails or primaryLink.allowedDomains is non-empty.)
POST/rooms/{roomId}/duplicate

会社や連絡先が未設定の新しいルームに複製します。name、includeDocuments、includeActionItems、includeBranding、mapDueDates(keepまたはclear)と新しいprimaryLinkの設定が必要です。元の対象者、会話、訪問履歴は引き継ぎません。

必須:rooms:write
条件付き:documents:write(Required when includeDocuments is true.)plan:write(Required when includeActionItems is true.)crm:write(Required when primaryLink.allowedEmails or allowedDomains is non-empty.)
GET/rooms/{roomId}

ルームの設定、表示順のタブと項目、リンク数を返します。

必須:rooms:read
PATCH/rooms/{roomId}

名前、ウェルカムメッセージ、担当者、会社、連絡先を変更します。

必須:rooms:write
条件付き:crm:write(Required when companyId or contactId is present, including null to detach the association.)
DELETE/rooms/{roomId}

ルーム、プラン、リンク、訪問履歴、会話を完全に削除します。confirmationNameに現在のルーム名を完全一致で指定してください。ライブラリの資料は保持されます。元に戻せる整理にはarchiveを使います。

必須:rooms:write
GET/rooms/{roomId}/appearance

保存済みのブランドカラー、フォント、ヘッダーのレイアウトを取得します。ヘッダー画像の有無と使用可能なフォントの一覧も返します。

必須:rooms:read
PATCH/rooms/{roomId}/appearance

ブランドカラー、見出し用フォント、本文用フォント、ヘッダーのレイアウトを変更します。色やフォントを既定値に戻すには null を指定します。

必須:rooms:write
PUT/rooms/{roomId}/header-image

ヘッダー画像をアップロードまたは差し替えます。10 MiB 以下、1200 × 400 ピクセル以上の JPEG、PNG、WebP に対応しています。

必須:rooms:write
DELETE/rooms/{roomId}/header-image

ヘッダー画像を削除します。

必須:rooms:write
POST/rooms/{roomId}/archive

ルームをアーカイブします。ルームのリンクは機能しなくなります。

必須:rooms:write
POST/rooms/{roomId}/restore

アーカイブされたルームを復元します。リンクは再び機能します。

必須:rooms:write
POST/rooms/{roomId}/tabs

タブを指定した位置または末尾に追加します。

必須:rooms:write
PATCH/rooms/{roomId}/tabs/{tabId}

タブの名前を変更します。

必須:rooms:write
PUT/rooms/{roomId}/tabs/order

すべてのタブを新しい順序に並べ替えます。

必須:rooms:write
DELETE/rooms/{roomId}/tabs/{tabId}

項目を表示していないタブを削除します。

必須:rooms:write
POST/rooms/{roomId}/items

タブにドキュメント、URL、埋め込み、セクション区切りを追加します。

必須:rooms:write
条件付き:documents:write(Required when type is document or url.)
PATCH/rooms/{roomId}/items/{itemId}

セクション名、埋め込みURL/設定、またはルーム内の資料名/表示を編集します。typeは既存の項目と一致させます。titleOverride: nullで資料名をリセットします。元の内容と項目の種類は維持されます。

必須:rooms:write
POST/rooms/{roomId}/items/{itemId}/move

項目を別のタブの末尾に移動します。

必須:rooms:write
PUT/rooms/{roomId}/items/order

1つのタブの項目を新しい順序に並べ替えます。

必須:rooms:write
DELETE/rooms/{roomId}/items/{itemId}

項目をルームから外します。ライブラリには残ります。

必須:rooms:write
GET/rooms/{roomId}/links

ルームのオーディエンス用リンクを新しい順に一覧表示します。制限付きリンクには有効な招待者も含まれます。

必須:rooms:read
POST/rooms/{roomId}/links

有効なルームに、対象者情報を関連付けた公開リンクを作成します。

必須:rooms:write
追加で必須:crm:write
PATCH/rooms/{roomId}/links/{linkId}

リンクの有効・無効を切り替え、有効期限を設定または解除し、アクセス許可リストを置き換えます。

必須:rooms:write
条件付き:crm:write(Required when allowedEmails or allowedDomains is present, including an empty array that clears the audience.)
GET/rooms/{roomId}/links/{linkId}/discussions

この対象者リンクのディスカッションを取得します。view=overviewはスレッドの要約、view=threadはanchorType、anchorId、cursorでページ分割したメッセージを返します。投稿者のメール取得にはcrm:readが必要です。

必須:rooms:read
PATCH/rooms/{roomId}/links/{linkId}/discussions/settings

enabledでディスカッションを有効または無効にします。有効化には有効なルーム/リンクとディスカッション機能が必要です。OpenまたはVerify-anyではconfirmSharedAudience: trueでリンクの利用者全員が会話を読めることを確認します。履歴は保持されます。

必須:rooms:write
GET/rooms/{roomId}/action-plan

ルームのアクションプランを返します。設定、フェーズ、タスク(社内限定を含む)、前提タスク、進捗が含まれます。

必須:plan:read
PATCH/rooms/{roomId}/action-plan

プランの設定を変更します。ルームを開いた人が自分のタスクを完了にできるかどうかも含みます。

必須:plan:write
POST/rooms/{roomId}/action-plan/phases

マイルストーンを追加します。colorを省略すると、フェーズは順にティール、ピーチ、ブルーになります。

必須:plan:write
PATCH/rooms/{roomId}/action-plan/phases/{phaseId}

フェーズの名前、位置、日付、色を変更します。colorにnullを送ると自動のローテーションに戻ります。

必須:plan:write
DELETE/rooms/{roomId}/action-plan/phases/{phaseId}

フェーズを削除します。modeは必須で、delete_tasksかmove_to_unphasedを指定します。タスクが意図せず消えることはありません。

必須:plan:write
POST/rooms/{roomId}/action-plan/tasks

タスクを追加します。assigneeはnull、担当する会社を表すsideのみ、または担当者を指すsideとemailのいずれかです。

必須:plan:write
PATCH/rooms/{roomId}/action-plan/tasks/{taskId}

タスクを更新します。assigneeを省略すると担当はそのまま、nullを送ると担当が外れます。

必須:plan:write
DELETE/rooms/{roomId}/action-plan/tasks/{taskId}

タスクを削除します。サブタスクも一緒に削除されます。

必須:plan:write
POST/rooms/{roomId}/action-plan/tasks/{taskId}/status

ワークスペースとしてタスクを完了または再開します。未完了の前提タスクがある場合は409 TASK_BLOCKEDを返します。

必須:plan:write
PUT/rooms/{roomId}/action-plan/tasks/{taskId}/dependencies

dependsOnIdsの全リストを置き換えます。[]で解除します。タスクは同じプラン内にある必要があります。自身への依存や循環は拒否されます。

必須:plan:write
PUT/rooms/{roomId}/action-plan/order

type=phasesとphaseIds、またはtype=tasksとplacements(id、phaseId、position)を送信します。現在の全項目をそれぞれ1回ずつ含めてください。

必須:plan:write
GET/action-plan-templates

ワークスペース内および公開テンプレートのメタデータをnextCursorでページ分割して取得します。limitは既定で20(1~100)。カーソルは15分で失効します。

必須:plan:read
POST/rooms/{roomId}/action-plan/templates

このプランをワークスペース専用テンプレートとして保存します。titleと任意のdescriptionを送信します。再利用できる構造と相対的な日付の差分は保持されます。

必須:plan:write
POST/rooms/{roomId}/action-plan/templates/apply

templateIdとmode=append|replace、任意のtargetDate(YYYY-MM-DD)を送信します。replaceは現在のフェーズ/タスクを削除します。新しいタスクは未完了で作成されます。

必須:plan:write
GET/rooms/{roomId}/action-plan/calendar

type=task|phaseとidで日付のあるタスクまたはフェーズをエクスポートします。カレンダーに取り込める.icsテキストをJSONで返します。

必須:plan:read
GET/rooms/{roomId}/analytics

ルームの訪問数、ユニーク閲覧者、平均滞在時間、開かれたドキュメント数と総数、平均完了率を返します。ボットは除外されます。

必須:analytics:read
GET/rooms/{roomId}/activity

ルームで起きたことを新しい順に返します。ディスカッションの項目は送信者を示すだけで、本文は含みません。sinceで範囲を絞れます。

必須:analytics:read
GET/rooms/{roomId}/captured-emails

ルームが集めたメールアドレスを返します。sourceは、訪問者がアクセスリンクまたはコードで確認したアドレスならverify、入力しただけならaskです。

必須:analytics:read
GET/room-views

ワークスペース全体のルーム入室を新しい順に返します。入室を知る手段はほかになく、/viewsはドキュメントの閲覧のみを対象とします。

必須:analytics:read
GET/room-labels

ワークスペースのルームラベルを、それぞれを使っているルーム数とともに一覧表示します。ルームにラベルを付ける前に、ここでIDを確認します。

必須:rooms:read
POST/room-labels

ラベルを作成します。名前は大文字小文字を区別せずワークスペース内で一意です。colorは#RRGGBB形式の16進数です。

必須:rooms:write
PATCH/room-labels/{labelId}

ラベルの名前、色、説明を変更します。

必須:rooms:write
DELETE/room-labels/{labelId}

ラベルと、その割り当てを削除します。付いていたルーム自体はそのままで、レスポンスには何件から外れたかが含まれます。

必須:rooms:write

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 を返します。

FieldTypeDescription
動画Loom, YouTube, Vimeo, Wistia, Vidyard, Fireflies
日程調整Calendly, Cal.com, SavvyCal, Google Calendar
フォームTypeform, Tally, Google Forms, Jotform, Fillout
デザインFigma, Miro, Canva, Whimsical
ドキュメントと表Google Docs, Google Sheets, Notion, Coda, Airtable
プレゼンテーションGoogle Slides, Pitch, Gamma, Guideflow, Flipsnack, Prezi
音声Spotify, SoundCloud

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

どのルームにも 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 と一緒に送れば同じ範囲を続けて取得できます。

会社と連絡先

既存のアカウント情報を一貫した条件で検索するか、新規作成します。会社名と連絡先メールアドレスは大文字と小文字を区別せず照合されます。

GET/companies?name={name}&domain={domain}

完全一致する名前と任意のドメインで会社を検索します。

必須:crm:read
GET/companies/search

queryで会社名とドメインを検索します。itemsとnextCursorを返します。limitは既定で20(1~100)。次のページでもフィルタを維持してください。

必須:crm:read
POST/companies

大文字と小文字を区別せず名前で会社を検索または作成します。明示したドメインはレコードの情報補完にのみ使用されます。

必須:crm:write
GET/contacts?email={query}

メールアドレスで連絡先を検索します。関連する会社とともに一致する連絡先を返します。

必須:crm:read
GET/contacts/search

queryで名前、メールアドレス、会社を検索し、companyIdで絞り込めます。itemsとnextCursorを返します。limitは既定で20(1~100)。次のページでもフィルタを維持してください。

必須:crm:read
POST/contacts

メールアドレスで連絡先を検索または作成し、必要に応じて会社に関連付けます。

必須:crm:write

POST /companiesのリクエスト

FieldTypeDescription
namestring必須会社名
domainstring任意会社情報の補完に使用するドメイン。既存会社の照合には使用されません

POST /contactsのリクエスト

FieldTypeDescription
namestring条件付き氏名。firstNameがない場合は必須
firstNamestring条件付き名。nameがない場合は必須
lastNamestring任意姓
emailstring必須一意の照合に使用するメールアドレス
titlestring任意役職
companyIdUUID任意認証済みワークスペースの既存の会社
companyNamestring任意検索または作成する会社名
companyDomainstring任意companyNameとともに使用する任意の情報補完ドメイン。会社の照合キーではありません

会社のレスポンス

FieldTypeDescription
company.idUUID会社ID
company.namestring会社名
company.domainstring | null正規化された会社ドメイン
createdbooleanPOSTリクエストで会社を作成した場合はtrue

連絡先のレスポンス

FieldTypeDescription
contact.idUUID連絡先ID
contact.firstNamestring名
contact.lastNamestring姓
contact.emailstring正規化されたメールアドレス
contact.titlestring | null役職
contact.companyIdUUID | null関連付けられた会社ID
contact.companyNamestring | null関連付けられた会社名
createdbooleanPOSTリクエストで連絡先を作成した場合はtrue
companyobject | null解決された会社(存在する場合)
companyCreatedbooleanこのリクエストで会社を作成した場合はtrue

Webhook

REST Hooksを介してリアルタイムイベントにサブスクライブします。イベントが発生すると、HummingDeckはイベントペイロードとともに登録済みのHTTPS URLにPOSTリクエストを送信します。配信が失敗した場合は最大3回まで再試行されます(1秒、5秒、30秒の間隔)。 Webhookのサブスクリプションは Zapier 連携で管理され、ワークスペースAPIトークンでは利用できません。

POST/hooks

イベントにサブスクライブします。HTTPS宛先URLとイベントタイプが必要です。サブスクリプションIDを返します。

Zapier OAuthのみ

DELETE/hooks/{id}

サブスクリプションIDによってイベントのサブスクリプションを解除します。

Zapier OAuthのみ

イベントタイプ

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

ビューとイベント

資料とルームの最近のエンゲージメントを取得します。/views、/decisions、/emailsはイベントの定期取得に対応します。エンゲージメント、アクティビティ、取得メールのエンドポイントでは、プランの保持期間内で絞り込みとページ分割を利用できます。

GET/views

最新のドキュメント閲覧100件をリストします。ボットセッションは除外されます。

必須:analytics:read
GET/decisions

最近の提案決定(承認、拒否、変更要求)をリストします。

必須:analytics:read
GET/emails

ゲートコンテンツからの最近のメールキャプチャをリストします。

必須:analytics:read
GET/document-engagement

documentId、shareId、shareSlugのいずれか1つを指定して、保持期間内の指標とページ分割された訪問履歴を取得します。includePagesにはページ別分析が必要です。次のページでもsinceとフィルタを維持してください。

必須:analytics:read
GET/activity

type=all|documents|roomsと任意のdocumentId、shareId、roomId、sinceで資料の閲覧とルームへの訪問を取得します。itemsとnextCursorを返します。ルームへの訪問は資料が開かれた証拠にはなりません。

必須:analytics:read
GET/email-captures

view=peopleは記録されたメールを対象者と資料/ルーム別にまとめ、view=eventsは個々の訪問を返します。type、documentId、shareId、roomId、since、cursorに対応します。analytics:readとcrm:readが必要です。メールの取得は購読への同意を意味しません。

必須:analytics:read
追加で必須:crm:read

エラー処理

すべてのエラーは、何が問題だったかを示す error フィールドを含むJSONオブジェクトを返します。ほとんどのレスポンスには、PLAN_LIMIT_REACHED、FEATURE_NOT_AVAILABLE、ROOM_NOT_ACTIVE、TAB_NOT_EMPTY、INVALID_FORMAT、FILE_TOO_LARGE のようにプログラムで処理できる code フィールドも含まれます。HTTPステータスコードは一般的な慣例に従います。

StatusMeaning
400リクエスト不正:パラメータが欠落しているか無効です
401未認証:Bearer tokenが無効または期限切れです
403禁止:認証情報に必要なscopeがない、プランの上限に達している、必要なオプションがプランにない、またはこの認証情報の種類ではこのエンドポイントを利用できません
404見つかりません:リソースが存在しないか、チームに属していません
409競合:指定した識別子が一致しない、ルームがアーカイブされている、またはルームのタブの状態によりこの変更ができません
413ペイロードが大きすぎます:リクエスト本文またはアップロードファイルがこのエンドポイントの上限を超えています
429リクエストが多すぎます:キーまたはクライアントIPが現在の上限を超えました。Retry-Afterの時間後に再試行してください
500サーバーエラー:リクエストを再試行してください

レート制限

手動のワークスペースキーと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件です。 /activityと/email-capturesは/room-viewsと同じ呼び出し枠を使用します。資料の差し替えはアップロード枠を使用します。429レスポンスにはRetry-Afterが含まれます。

このAPIは現在、当社のZapier統合で使用されています。将来的には追加の統合プラットフォームがサポートされる可能性があります。