API Reference

HummingDeck exposes a REST API for integration partners and automation platforms. All endpoints use OAuth 2.0 authentication and return JSON responses.

Base URLhttps://app.hummingdeck.com/api/v1

OpenAPI Spec

Authentication

All API requests require a valid OAuth 2.0 Bearer token in the Authorization header. Tokens are issued during the OAuth authorization flow and expire after 30 days. Use the refresh token (90-day expiry) to obtain a new access token without re-authorizing.

Method

OAuth 2.0 (Bearer token)

Header format

Authorization: Bearer {access_token}

Test your connection

Verify your token is valid and see the authenticated user's profile.

GET/meReturns the current user's name, email, and team information.

Documents

Upload, search, and manage documents (PDFs, slide decks, proposals, and other files).

POST/decksUpload a new document. Send as multipart/form-data with a file field (PDF, PPTX, DOCX, HTML) and a title field.

GET/decks?title={query}Search documents by title. Case-insensitive, returns up to 20 matches.

Response fields

Field	Type	Description
id	string	Document ID
title	string	Document title
fileType	string	File type (pdf, pptx, docx, html)
pageCount	number	Number of pages
thumbnailUrl	string	Thumbnail image URL
createdAt	string	ISO 8601 timestamp

Share Links

Create trackable links for sharing documents with prospects. Each link tracks engagement separately.

POST/sharesCreate a share link. Supports personal links (with recipient name and email) and anonymous links.

Request fields

Field	Type		Description
deckId	string	required	ID of the document to share
recipientName	string	optional	Recipient's name (for personal links)
recipientEmail	string	optional	Recipient's email (for personal links)
type	string	optional	"personal" or "anonymous" (defaults to anonymous)

Response fields

Field	Type	Description
id	string	Share ID
slug	string	Share slug (used in the URL)
shareUrl	string	Full trackable URL
type	string	"personal" or "anonymous"
recipientName	string	Recipient name (if personal)
recipientEmail	string	Recipient email (if personal)
createdAt	string	ISO 8601 timestamp

Contacts

Search contacts in your team's address book.

GET/contacts?email={query}Search contacts by email address. Returns matching contacts with their associated company.

Response fields

Field	Type	Description
id	string	Contact ID
firstName	string	First name
lastName	string	Last name
email	string	Email address
title	string	Job title
leadName	string	Company name
createdAt	string	ISO 8601 timestamp

Webhooks

Subscribe to real-time events via REST Hooks. When an event occurs, HummingDeck sends a POST request to your registered HTTPS URL with the event payload. Failed deliveries are retried up to 3 times (at 1s, 5s, and 30s intervals).

POST/hooksSubscribe to an event. Requires a target HTTPS URL and an event type. Returns a subscription ID.

DELETE/hooks/{id}Unsubscribe from an event by subscription ID.

Event types

Event	Description
view.created	A real person viewed a shared document. Bot traffic (email security scanners, crawlers) is filtered automatically.
decision.made	A prospect responded to a proposal — accepted, declined, or requested changes.
email_captured	A viewer entered their email address to access gated content.

Example payloads

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 & Events

Polling endpoints for retrieving recent engagement data. These return the same data that webhooks deliver in real time — use them for backfilling, testing, or as a fallback.

GET/viewsList the most recent 100 document views. Bot sessions are excluded.

GET/decisionsList recent proposal decisions (accepted, declined, changes requested).

GET/emailsList recent email captures from gated content.

Error handling

All errors return a JSON object with a message field. HTTP status codes follow standard conventions.

Status	Meaning
400	Bad request — missing or invalid parameters
401	Unauthorized — invalid or expired Bearer token
404	Not found — resource does not exist or is not owned by your team
500	Server error — retry the request

Rate limits

Maximum 50 active webhook subscriptions per team. API requests are not rate-limited but excessive use may be throttled.

This API is currently used by our Zapier integration. Additional integration platforms may be supported in the future.