API Reference

Authentication

Every API request carries a Bearer token in the Authorization header. Two kinds of credential are accepted, and they behave differently.

Credential types

Permissions

Choose at least one permission. Write permissions also include matching read access. You can change permissions when you replace the key.

Permission labels on endpoint rows apply to workspace API keys. Required permissions always apply, also-required permissions are needed together, and conditional permissions apply only when the request uses the related filters or fields. GET /me needs no permission. Zapier OAuth uses its fixed integration access.

When a request returns 401

A request returns 401 when the key is unknown or malformed, has expired, has been switched off, belongs to a workspace whose API access was turned off, or was issued by someone who is no longer an owner or admin of that workspace.

Test your connection

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

Documents

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

GET /decks Response fields

POST /decks Response fields

Share Links

Create trackable document links. A personal link can resolve or create its contact and company in the same request.

Request fields

Create the link and account records together

Send recipient and company details directly to /shares. HummingDeck finds matching records, creates any that are missing, attaches them to the link, and reports what was created. Set type to anonymous explicitly to skip account creation.

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

Response fields

Rooms

Create deal rooms with their documents and audience link in one call, find rooms, change their settings, archive and restore them, and arrange their tabs and items. Available only to workspace API tokens; Zapier OAuth credentials are rejected.

Create a room in one call

Upload each file with POST /decks, then create the room for the recipient's company with a Restricted link for the people who should see it. The company, contacts, room, documents, and link are created together: if the call is refused, none of them is. Documents can go into the room while they are still processing. The room's items report processingStatus, so send the link once every document reads 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 is open (anyone with the URL), verify-any (visitors confirm their email address with a one-time link), or verified-allowlist (only the addresses in allowedEmails and anyone at the domains in allowedDomains). The API adds nobody to a Restricted link on its own, so include your own address if you want to preview the room. An option your plan does not include returns 403 FEATURE_NOT_AVAILABLE, and an unknown field returns 400, so a room never opens to a different audience than the one you asked for.

Arrange tabs and items

Start from the room as it is now: reading a room returns its tabs and items in display order, and each item reports its tab and its position in it, counting from 0. Add tabs and items at a position, move items between tabs, and send a tab's complete new order. An order must list every item in the tab exactly once, so read the room again if another change landed in between. A tab can be removed once it shows no items.

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

Supported embed providers

Embeds accept a share link or an embed link and normalize it to the provider's embed form. Anything outside this set returns 400 EMBED_PROVIDER_NOT_SUPPORTED.

Add another audience link

Every room already has one link from POST /rooms; add more for audiences that need different attribution or access. Provide at least one of recipientName, recipientEmail, contactId, companyId, or companyName. accessMode takes the same open, verify-any, or verified-allowlist values as primaryLink, with the same fields (requireEmail, allowedEmails, allowedDomains, label, expiresAt, allowDownloads). A refused call, including a plan gate, leaves no link, company, or contact behind.

{
  "companyName": "Analytical Engines",
  "accessMode": "verified-allowlist",
  "allowedEmails": [
    {
      "email": "cfo@analytical.example",
      "name": "Sam Rivera"
    }
  ]
}

Update a link

Four fields: isActive, expiresAt, allowedEmails, allowedDomains (the last two on verified-allowlist links only). accessMode and the slug never change; create a new link instead. Turning a link back on rechecks the plan's active-link limit.

{
  "isActive": false
}

Build the action plan

Every room owns exactly one plan, so it mounts under the room without an ID of its own. Most tasks belong to a company rather than a person: send a side on its own and the plan reads it as the company, which is what you want when you do not know who on the other side will do the work. Add an email only when you know the individual. An internal task is never shown in the room, so it cannot belong to the recipient side.

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

recipientCompletionEnabled on the plan decides whether the people who open the room may tick their own side's tasks off. It defaults to true, and it is the only gate: the API never asks a caller to supply a recipient's address in order to complete a task. Who ticked each one is recorded at whatever confidence the room's access mode gives.

Tag rooms with labels

Labels are workspace-wide, so create them once and reuse them. Pass labelIds on POST /rooms to tag a room as you create it, or on PATCH /rooms/{roomId} to replace the whole set; an empty array clears every label, and omitting the field leaves them alone. A room carries at most five, which is structural rather than a setting. Reading a room returns its labels.

{
  "labelIds": [
    "{labelId}"
  ]
}

Learn what happened

Poll /room-views for entries across the workspace, then read one room's analytics, activity, and captured addresses. Pass a page's nextCursor as cursor to continue; a cursor this API did not issue returns 400 rather than restarting from the top, so a poller never repeats work. Use since to narrow the activity window and cursor to page through it. /room-views is a window rather than an archive: without since you get the last 30 days, and more than 90 days back is refused. The window used comes back as since; send it alongside cursor to keep paging one set.

Companies & Contacts

Find existing account records or create them with deterministic matching. Company names and contact emails are matched case-insensitively.

POST /companies request

POST /contacts request

Company response

Contact response

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). Webhook subscriptions are managed by the Zapier integration and are not available to workspace API tokens.

Event types

Example payloads

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

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.

Error handling

Every error returns a JSON object with an error field describing what went wrong. Most responses also include a code field for programmatic handling, such as PLAN_LIMIT_REACHED, FEATURE_NOT_AVAILABLE, ROOM_NOT_ACTIVE, TAB_NOT_EMPTY, INVALID_FORMAT, or FILE_TOO_LARGE. HTTP status codes follow standard conventions.

Rate limits

Manual workspace keys and Zapier OAuth connections are limited per credential: 600 reads per 5 minutes, 120 writes per minute, 60 /room-views requests per minute, and 20 uploads per hour. Across all credentials, each workspace is limited to 1,200 reads per 5 minutes, 240 writes per minute, 120 /room-views requests per minute, and 40 uploads per hour. Failed bearer authentication and invalid OAuth client authentication are each limited per client IP to 60 attempts per 5 minutes. Maximum 50 active webhook subscriptions per team.