API-Referenz

Authentifizierung

Jede API-Anfrage sendet ein Bearer-Token im Authorization-Header. Es werden zwei Arten von Anmeldedaten akzeptiert, und sie verhalten sich unterschiedlich.

Arten von Anmeldedaten

Berechtigungen

Wähle mindestens eine Berechtigung aus. Schreibberechtigungen enthalten auch den entsprechenden Lesezugriff. Beim Ersetzen des Schlüssels kannst du die Berechtigungen ändern.

Die Berechtigungsangaben in den Endpunktzeilen gelten für Workspace-API-Schlüssel. Erforderliche Berechtigungen gelten immer, zusätzlich erforderliche werden gemeinsam benötigt und bedingte nur dann, wenn die Anfrage die zugehörigen Filter oder Felder verwendet. GET /me benötigt keine Berechtigung. Zapier OAuth verwendet seinen festgelegten Integrationszugriff.

Wenn eine Anfrage 401 zurückgibt

Eine Anfrage gibt 401 zurück, wenn der Schlüssel unbekannt oder fehlerhaft ist, abgelaufen oder deaktiviert wurde, zu einem Arbeitsbereich mit deaktiviertem API-Zugriff gehört oder von einer Person ausgestellt wurde, die nicht mehr Inhaber oder Administrator dieses Arbeitsbereichs ist.

Verbindung testen

Überprüfen Sie die Gültigkeit Ihres Tokens und sehen Sie das Profil des authentifizierten Benutzers.

Dokumente

Dokumente hochladen, suchen und verwalten (PDFs, Präsentationen, Angebote und andere Dateien).

GET /decks Antwortfelder

POST /decks Antwortfelder

Freigabelinks

Verfolgbare Dokumentlinks erstellen. Ein persönlicher Link kann Kontakt und Unternehmen in derselben Anfrage auflösen oder anlegen.

Anforderungsfelder

Link und Kontodatensätze gemeinsam anlegen

Empfänger- und Unternehmensdaten direkt an /shares senden. HummingDeck findet passende Datensätze, legt fehlende an, verknüpft sie mit dem Link und meldet, was erstellt wurde. type ausdrücklich auf anonymous setzen, um keine Kontodatensätze anzulegen.

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

Antwortfelder

Räume

Erstelle digitale Verkaufsräume samt Dokumenten und Zielgruppenlink mit einem einzigen Aufruf, finde Räume, ändere ihre Einstellungen, archiviere sie und stelle sie wieder her und ordne ihre Tabs und Elemente an. Nur mit Workspace-API-Token verfügbar; Zapier-OAuth-Anmeldedaten werden abgelehnt.

Einen Raum mit einem Aufruf erstellen

Lade jede Datei mit POST /decks hoch und erstelle dann den Raum für das Unternehmen der Empfänger mit einem eingeschränkten Link für die Personen, die ihn sehen sollen. Unternehmen, Kontakte, Raum, Dokumente und Link werden gemeinsam angelegt: Wird der Aufruf abgelehnt, wird nichts davon angelegt. Dokumente können schon während der Verarbeitung in den Raum. Die Elemente des Raums melden processingStatus; verschicke den Link also erst, wenn jedes Dokument completed meldet.

{
  "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 ist open (jeder mit der URL), verify-any (Besucher bestätigen ihre E-Mail-Adresse über einen Einmal-Link) oder verified-allowlist (nur die Adressen in allowedEmails und alle mit einer Adresse bei den Domains in allowedDomains). Die API fügt einem eingeschränkten Link niemanden von sich aus hinzu; nimm also deine eigene Adresse auf, wenn du den Raum vorab ansehen möchtest. Eine Option, die dein Tarif nicht enthält, liefert 403 FEATURE_NOT_AVAILABLE, und ein unbekanntes Feld liefert 400. So öffnet sich ein Raum nie für eine andere Zielgruppe als die angefragte.

Tabs und Elemente anordnen

Geh vom aktuellen Stand des Raums aus: Beim Abrufen eines Raums kommen seine Tabs und Elemente in Anzeigereihenfolge zurück, und jedes Element meldet seinen Tab und seine Position darin, gezählt ab 0. Füge Tabs und Elemente an einer Position hinzu, verschiebe Elemente zwischen Tabs und sende die vollständige neue Reihenfolge eines Tabs. Eine Reihenfolge muss jedes Element des Tabs genau einmal enthalten; ruf den Raum also erneut ab, wenn zwischendurch eine andere Änderung erfolgt ist. Ein Tab lässt sich entfernen, sobald er keine Elemente mehr anzeigt.

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

Unterstützte Embed-Anbieter

Embeds akzeptieren einen Freigabe- oder Einbettungslink und normalisieren ihn auf die Embed-Form des Anbieters. Alles außerhalb dieser Liste liefert 400 EMBED_PROVIDER_NOT_SUPPORTED.

Weiteren Zielgruppen-Link hinzufügen

Jeder Raum hat bereits einen Link aus POST /rooms; weitere kommen für Zielgruppen hinzu, die eine andere Zuordnung oder einen anderen Zugriff brauchen. Gib mindestens eines von recipientName, recipientEmail, contactId, companyId oder companyName an. accessMode nimmt dieselben Werte open, verify-any oder verified-allowlist wie primaryLink, mit denselben Feldern (requireEmail, allowedEmails, allowedDomains, label, expiresAt, allowDownloads). Ein abgelehnter Aufruf, auch an einer Plangrenze, hinterlässt weder Link noch Unternehmen oder Kontakt.

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

Einen Link ändern

Vier Felder: isActive, expiresAt, allowedEmails, allowedDomains (die beiden letzten nur bei verified-allowlist-Links). accessMode und der Slug ändern sich nie; lege stattdessen einen neuen Link an. Wer einen Link wieder aktiviert, löst eine erneute Prüfung des Limits für aktive Links im Plan aus.

{
  "isActive": false
}

Den Aktionsplan aufbauen

Jeder Raum hat genau einen Plan, daher hängt er ohne eigene ID am Raum. Die meisten Aufgaben gehören einem Unternehmen und nicht einer Person: Wird nur eine Seite gesendet, liest der Plan sie als das Unternehmen. Genau das willst du, wenn du nicht weißt, wer die Arbeit auf der Gegenseite erledigt. Eine E-Mail kommt nur dazu, wenn die Person bekannt ist. Eine interne Aufgabe erscheint nie im Raum und kann deshalb nicht der Empfängerseite gehören.

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

recipientCompletionEnabled im Plan entscheidet, ob die Personen im Raum die Aufgaben ihrer Seite abhaken dürfen. Der Standard ist true, und es ist die einzige Schranke: Die API verlangt nie die Adresse einer empfangenden Person, um eine Aufgabe abzuschließen. Wer abgehakt hat, wird mit der Sicherheit festgehalten, die der Zugriffsmodus des Raums hergibt.

Räume mit Labels kennzeichnen

Labels gelten workspaceweit: einmal anlegen, überall wiederverwenden. Übergib labelIds bei POST /rooms, um einen Raum direkt beim Anlegen zu kennzeichnen, oder bei PATCH /rooms/{roomId}, um den gesamten Satz zu ersetzen; ein leeres Array entfernt alle Labels, und wenn das Feld fehlt, bleiben sie unverändert. Ein Raum trägt höchstens fünf, was strukturell festgelegt und keine Einstellung ist. Beim Lesen eines Raums werden seine Labels mitgeliefert.

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

Erfahren, was passiert ist

Frage /room-views nach Zutritten im gesamten Workspace ab und lies dann Analytics, Aktivität und gesammelte Adressen eines Raums. Übergib den nextCursor einer Seite als cursor, um fortzufahren; ein Cursor, den diese API nicht ausgegeben hat, liefert 400 statt neu zu beginnen, damit ein Poller keine Arbeit wiederholt. Grenzen Sie das Aktivitätsfenster mit since ein und blättern Sie mit cursor durch die Ergebnisse. /room-views ist ein Zeitfenster und kein Archiv: ohne since bekommst du die letzten 30 Tage, mehr als 90 Tage zurück wird abgelehnt. Das verwendete Fenster kommt als since zurück; sende es zusammen mit cursor, um dieselbe Menge weiterzublättern.

Unternehmen und Kontakte

Vorhandene Kontodatensätze mit eindeutiger Zuordnung finden oder anlegen. Unternehmensnamen und Kontakt-E-Mails werden ohne Beachtung der Groß- und Kleinschreibung verglichen.

Anfrage POST /companies

Anfrage POST /contacts

Unternehmensantwort

Kontaktantwort

Webhooks

Echtzeit-Ereignisse über REST Hooks abonnieren. Wenn ein Ereignis eintritt, sendet HummingDeck eine POST-Anfrage an Ihre registrierte HTTPS-URL mit dem Ereignis-Payload. Fehlgeschlagene Zustellungen werden bis zu 3 Mal wiederholt (nach 1 s, 5 s und 30 s). Webhook-Abonnements werden von der Zapier-Integration verwaltet und stehen Workspace-API-Tokens nicht zur Verfügung.

Ereignistypen

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

Aufrufe & Ereignisse

Polling-Endpunkte zum Abrufen aktueller Engagement-Daten. Diese geben dieselben Daten zurück, die Webhooks in Echtzeit liefern. Nutzen Sie sie zum Nachfüllen, Testen oder als Fallback.

Fehlerbehandlung

Jeder Fehler gibt ein JSON-Objekt mit einem error-Feld zurück, das beschreibt, was schiefgelaufen ist. Die meisten Antworten enthalten zusätzlich ein code-Feld für die programmatische Behandlung, etwa PLAN_LIMIT_REACHED, FEATURE_NOT_AVAILABLE, ROOM_NOT_ACTIVE, TAB_NOT_EMPTY, INVALID_FORMAT oder FILE_TOO_LARGE. Die HTTP-Statuscodes folgen den üblichen Konventionen.

Rate-Limits

Manuelle Workspace-Schlüssel und Zapier-OAuth-Verbindungen werden pro Schlüssel beziehungsweise Verbindung begrenzt: 600 Lesezugriffe in 5 Minuten, 120 Schreibzugriffe pro Minute, 60 Aufrufe von /room-views pro Minute und 20 Uploads pro Stunde. Workspace-weit gelten über alle Zugangsdaten hinweg 1.200 Lesezugriffe in 5 Minuten, 240 Schreibzugriffe pro Minute, 120 Aufrufe von /room-views pro Minute und 40 Uploads pro Stunde. Fehlgeschlagene Bearer-Authentifizierungen und ungültige OAuth-Client-Authentifizierungen sind jeweils pro Client-IP auf 60 Versuche in 5 Minuten begrenzt. Maximal 50 aktive Webhook-Abonnements pro Team.