Browse help topics
Agentic workflows and automation

API access and reference

See how API access works on Business, create named and scoped workspace API keys, review common automation use cases, and open the technical REST API reference.

Updated November 9, 2026

Examples use sample data. Available controls may vary by plan, role, and product version.

REST API access is included with a paid Business plan. Workspace owners and admins can create API keys as soon as the workspace pays for Business. During a Business trial, access is granted on request.

Product exampleBased on the live API key panel

HummingDeck API

Create separate API keys for each integration and grant only the access it needs.

CRM reporting

Active
analytics:readcrm:read
Created
September 2, 2026
Expires
September 2, 2027
Last used
Today

Room publishing

Active
rooms:readrooms:writedocuments:readdocuments:write
Created
August 18, 2026
Expires
August 18, 2027
Last used
Yesterday

API access is switched on per workspace. Owners and admins on Business request it from this section, and the panel above appears once access is granted.

Good API use cases

The API is a good fit when a real workflow needs to:

  • upload generated documents automatically;
  • replace a generated document while keeping its existing links;
  • find, rename, or delete documents as part of a repeatable workflow;
  • publish HTML output from an internal system;
  • create personalized Share Links from a CRM or sales workflow;
  • list Share Links and manage their access settings, expiry, downloads, and notifications;
  • create a Room with its documents and link, then arrange its tabs and sections;
  • find or create companies and contacts;
  • retrieve engagement events for an automation or integration.

Room workflows can also duplicate a Room, manage action-plan dependencies and templates, export dated tasks or phases as calendar files, and read or configure discussions for a specific audience link. Permanent Room deletion removes its links, visit history, and conversations while keeping library documents. Use archiving when you want to restore the Room later.

For a small number of manual uploads, the Document Library is simpler and safer than maintaining an API integration.

For occasional batches, Bulk-generate personalized document links from a CSV or connected Close Smart View. Use the API when link creation needs to run repeatedly inside another system.

Request access during a trial

On a Business trial, open Workspace → Integrations, select HummingDeck API, then choose Request API access on its page.

The request takes one click. Describing the workflow is optional, and it usually saves a round of email. Useful details:

  • the workflow you want to automate;
  • expected upload or request volume;
  • the file types involved;
  • whether you need companies, contacts, shares, Rooms, views, or events.

Workspace owners and admins can send the request. We reply by email when access is switched on. Paying for Business switches access on right away, without waiting for the review.

On plans below Business, the access controls stay visible and locked, and open your plan options instead.

Create workspace API keys

On a paid Business plan, or once access is switched on during a trial, a workspace owner or admin opens Workspace → Integrations → HummingDeck API. Creating or replacing a key requires a verified email address. Create a separate, clearly named key for each integration or workflow. A workspace can have up to 20 active API keys. A key name can contain 1 to 64 characters and must be unique among active keys, ignoring capitalization and surrounding spaces.

When you create or replace a key, grant only the permissions that integration needs. A write permission includes the matching read permission. The raw key is shown once, so store it in a secret manager. Do not paste it into browser code, an HTML upload, a public repository, a shared document, or a support ticket.

PermissionWhat it allows
rooms:readView Rooms, tabs, items, links, and labels.
rooms:writeCreate and manage Rooms, tabs, items, links, and labels.
plan:readView Mutual Action Plan phases and tasks.
plan:writeCreate and manage Mutual Action Plan phases and tasks.
analytics:readView engagement analytics, activity, and captured emails.
crm:readFind workspace companies and contacts.
crm:writeCreate or update companies, contacts, and link audiences.
documents:readFind documents and read their metadata.
documents:writeUpload, replace, rename, and delete documents; manage their Share Links and add documents or URLs to Rooms.

A key created before named permissions were introduced appears as Legacy API key and keeps all API permissions until you replace it or switch it off.

Every key is permanently bound to the workspace that created it. An API request cannot select another workspace or override this boundary.

Each key expires one year after it is created. Replacing a key switches off that key immediately and shows a new raw key without affecting the workspace's other keys. You can also switch off any key independently; a switched-off key cannot be restored.

The key list shows each key's status, permissions, creation and expiry dates, and most recent use. An expired or switched-off entry can prefill the name and permissions for a new key. Switch off all permanently disables every active key in the workspace at once.

A key also stops authenticating if the person who created it is no longer a workspace owner or admin. Create production keys from a stable owner or admin account, and replace them when responsibility for an integration changes.

Keys also stop working if a paid Business workspace stops paying. They are not deleted: they work again once the workspace pays for Business, until each key's one-year expiry.

Open the technical API reference

Use this Support article for access, credential, and workflow guidance. Use the canonical HummingDeck API reference for current endpoints, authentication, request and response schemas, errors, document uploads, Share Links, companies, contacts, Rooms, views, events, and webhooks.

Browser uploads accept files up to 100 MB. API document upload and replacement accept a file up to 30 MiB, with a 31 MiB limit for the full multipart request. HTML uploaded through the API must still meet the same static-content and asset requirements as a manual upload.

After uploading or replacing a previewable document, read its metadata to check the processing state before distributing its links. The document metadata read requires a workspace API key with documents:read and returns document details and processing status.

API replacement uses a manually issued workspace API key with documents:write. Zapier OAuth cannot replace a document. The file must have the same type as the current document, and the replacement keeps its Share Links and Room placements. Previewable files continue processing after the response; download-only files are ready when the response returns. A repeated request starts a new replacement. If a response is lost, inspect the current document or share view, or contact support before retrying. See Replace a document without changing its links for the sharing and recipient effects.

For API replacement, use a filename extension that matches the file type, such as .pdf, .pptx, or .docx. Missing or mismatched extensions return INVALID_FORMAT.