APIリファレンス

認証

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

認証情報の種類

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

トークンが未知または不正な形式である、失効している、無効化されている、APIアクセスがオフになったワークスペースに属している、あるいはそのワークスペースのオーナーではなくなった人が発行した場合、リクエストは401で拒否されます。

接続のテスト

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

ドキュメント

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

レスポンスフィールド

共有リンク

追跡可能なドキュメントリンクを作成します。個人リンクでは、同じリクエストで連絡先と会社を検索または作成できます。

リクエストフィールド

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

受信者と会社の情報を/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 認証情報は拒否されます。

公開ルームリンクを作成

recipientName、recipientEmail、contactId、companyId、companyName のうち少なくとも1つを指定してください。名前またはメールアドレスから連絡先を検索または作成し、会社フィールドから会社を検索または作成します。公開リンクはURLを知っている誰でも閲覧できます。

{
  "accessMode": "open",
  "recipientName": "Ada Lovelace",
  "recipientEmail": "ada@analytical.example",
  "companyName": "Analytical Engines"
}

会社と連絡先

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

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、INVALID_FORMAT、FILE_TOO_LARGE のようにプログラムで処理できる code フィールドも含まれます。HTTPステータスコードは一般的な慣例に従います。

レート制限

チームあたり最大50件のアクティブなwebhookサブスクリプション。APIリクエストにレート制限はありませんが、過度な使用はスロットリングされる場合があります。