APIリファレンス

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

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

認証

すべてのAPIリクエストには、AuthorizationヘッダーにOAuth 2.0の有効なBearer tokenが必要です。トークンはOAuth認証フロー中に発行され、30日後に失効します。再認証なしで新しいアクセストークンを取得するには、リフレッシュトークン（有効期限90日）を使用してください。

メソッド

OAuth 2.0 (Bearer token)

ヘッダー形式

Authorization: Bearer {access_token}

接続のテスト

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

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

ドキュメント

ドキュメント（PDF、スライドデッキ、提案書、その他のファイル）のアップロード、検索、管理を行います。

POST/decks新しいドキュメントをアップロードします。fileフィールド（PDF、PPTX、DOCX、HTML）とtitleフィールドを含むmultipart/form-dataとして送信します。
GET/decks?title={query}タイトルでドキュメントを検索します。大文字小文字を区別せず、最大20件の結果を返します。

レスポンスフィールド

FieldTypeDescription
idstringドキュメントID
titlestringドキュメントタイトル
fileTypestringファイルタイプ（pdf、pptx、docx、html）
pageCountnumberページ数
thumbnailUrlstringサムネイル画像のURL
createdAtstringISO 8601タイムスタンプ

共有リンク

見込み客とドキュメントを共有するための追跡可能なリンクを作成します。各リンクはエンゲージメントを個別に追跡します。

POST/shares共有リンクを作成します。個人リンク（受信者の名前とメールアドレス付き）と匿名リンクをサポートします。

リクエストフィールド

FieldTypeDescription
deckIdstringrequired共有するドキュメントのID
recipientNamestringoptional受信者の名前（個人リンク用）
recipientEmailstringoptional受信者のメールアドレス（個人リンク用）
typestringoptional"personal"または"anonymous"（デフォルト：anonymous）

レスポンスフィールド

FieldTypeDescription
idstring共有ID
slugstring共有スラッグ（URLで使用）
shareUrlstring完全な追跡可能URL
typestring"personal"または"anonymous"
recipientNamestring受信者名（個人リンクの場合）
recipientEmailstring受信者メールアドレス（個人リンクの場合）
createdAtstringISO 8601タイムスタンプ

連絡先

チームのアドレス帳で連絡先を検索します。

GET/contacts?email={query}メールアドレスで連絡先を検索します。関連する会社とともに一致する連絡先を返します。

レスポンスフィールド

FieldTypeDescription
idstring連絡先ID
firstNamestring名
lastNamestring姓
emailstringメールアドレス
titlestring役職
leadNamestring会社名
createdAtstringISO 8601タイムスタンプ

Webhook

REST Hooksを介してリアルタイムイベントにサブスクライブします。イベントが発生すると、HummingDeckはイベントペイロードとともに登録済みのHTTPS URLにPOSTリクエストを送信します。配信が失敗した場合は最大3回まで再試行されます（1秒、5秒、30秒の間隔）。

POST/hooksイベントにサブスクライブします。HTTPS宛先URLとイベントタイプが必要です。サブスクリプションIDを返します。
DELETE/hooks/{id}サブスクリプションIDによってイベントのサブスクリプションを解除します。

イベントタイプ

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

ビューとイベント

最近のエンゲージメントデータを取得するためのポーリングエンドポイントです。これらはwebhookがリアルタイムで配信するのと同じデータを返します — バックフィル、テスト、またはフォールバックとして使用してください。

GET/views最新のドキュメント閲覧100件をリストします。ボットセッションは除外されます。
GET/decisions最近の提案決定（承認、拒否、変更要求）をリストします。
GET/emailsゲートコンテンツからの最近のメールキャプチャをリストします。

エラー処理

すべてのエラーはmessageフィールドを持つJSONオブジェクトを返します。HTTPステータスコードは標準的な規則に従います。

StatusMeaning
400リクエスト不正 — パラメータが欠落しているか無効です
401未認証 — Bearer tokenが無効または期限切れです
404見つかりません — リソースが存在しないか、チームに属していません
500サーバーエラー — リクエストを再試行してください

レート制限

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

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