API-Referenz
HummingDeck stellt eine REST API für Integrationspartner und Automatisierungsplattformen bereit. Endpunkte authentifizieren sich mit einem Bearer-Token und geben JSON-Antworten zurück.
https://app.hummingdeck.com/api/v1Authentifizierung
Jede API-Anfrage sendet ein Bearer-Token im Authorization-Header. Es werden zwei Arten von Anmeldedaten akzeptiert, und sie verhalten sich unterschiedlich.
Methode
Bearer-Token
Header-Format
Authorization: Bearer {access_token}
Arten von Anmeldedaten
Workspace-API-Token
Authorization: Bearer hd_api_...
Wird vom Workspace-Inhaber unter Workspace-Einstellungen, Integrationen, HummingDeck API ausgestellt. Während eines privaten Pilotprogramms nur für ausgewählte Workspaces verfügbar. Das Token wird bei der Erstellung einmal angezeigt und lässt sich danach nicht mehr abrufen. Es läuft ein Jahr nach der Erstellung ab und ist dauerhaft an den Workspace gebunden, für den es ausgestellt wurde. Eine Anfrage kann ihren Workspace daher weder auswählen noch überschreiben.
Ein neues Token zu erstellen, während bereits eines existiert, ersetzt es, und das vorherige Token funktioniert sofort nicht mehr. Der Inhaber kann ein Token jederzeit deaktivieren. Für dieses Token ist das endgültig: Erstellen Sie ein neues, statt auf eine Wiederherstellung zu warten.
Endpunkte für Webhook-Abonnements stehen Workspace-API-Tokens nicht zur Verfügung.
Zapier OAuth
Authorization: Bearer {access_token}
Wird über den OAuth-Autorisierungsflow ausgestellt, wenn ein Workspace die Zapier-Integration verbindet. Zugriffstokens laufen nach 30 Tagen ab. Verwenden Sie das Refresh-Token, das 90 Tage gültig ist, um ohne erneute Autorisierung ein neues Zugriffstoken zu erhalten.
Dies sind die einzigen Anmeldedaten, die Webhook-Abonnements erstellen oder löschen können.
Wenn eine Anfrage 401 zurückgibt
Eine Anfrage wird mit 401 abgelehnt, wenn das Token unbekannt oder fehlerhaft ist, abgelaufen ist, deaktiviert wurde, zu einem Workspace gehört, dessen API-Zugriff deaktiviert wurde, oder von jemandem ausgestellt wurde, der nicht mehr Inhaber dieses Workspace ist.
Verbindung testen
Überprüfen Sie die Gültigkeit Ihres Tokens und sehen Sie das Profil des authentifizierten Benutzers.
/meGibt Name, E-Mail und Teaminformationen des aktuellen Benutzers zurück.Dokumente
Dokumente hochladen, suchen und verwalten (PDFs, Präsentationen, Angebote und andere Dateien).
/decksEin neues Dokument hochladen. Als multipart/form-data mit einem file-Feld (PDF, PPTX, DOCX, XLSX, HTML) und einem title-Feld senden. Das Upload-Limit der API beträgt 30 MB./decks?title={query}Dokumente nach Titel suchen. Groß-/Kleinschreibung wird nicht beachtet, gibt bis zu 20 Treffer zurück.Antwortfelder
| Field | Type | Description |
|---|---|---|
| id | string | Dokument-ID |
| title | string | Dokumenttitel |
| fileType | string | Dateityp (pdf, pptx, docx, html) |
| pageCount | number | Anzahl der Seiten |
| thumbnailUrl | string | URL des Vorschaubildes |
| createdAt | string | ISO 8601-Zeitstempel |
Räume
Rufe die Raumstruktur ab und erstelle nachverfolgbare Zielgruppenlinks für Räume. Nur mit Workspace-API-Token verfügbar; Zapier-OAuth-Anmeldedaten werden abgelehnt.
/rooms/{roomId}Gibt Raummetadaten, Tabs, Inhalte sowie die Anzahl aktiver und aller Links zurück./rooms/{roomId}/linksErstellt einen zugeordneten offenen Link für einen aktiven Raum.Offenen Raumlink erstellen
Gib mindestens eines dieser Felder an: recipientName, recipientEmail, contactId, companyId oder companyName. Name und E-Mail suchen oder erstellen einen Kontakt; Unternehmensfelder suchen oder erstellen ein Unternehmen. Ein offener Link erlaubt allen Personen mit der URL den Zugriff.
{
"accessMode": "open",
"recipientName": "Ada Lovelace",
"recipientEmail": "ada@analytical.example",
"companyName": "Analytical Engines"
}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.
/companies?name={name}&domain={domain}Bis zu 10 Unternehmen nach exaktem Namen, Domain oder beidem finden./companiesEin Unternehmen anhand des Namens ohne Beachtung der Groß- und Kleinschreibung finden oder anlegen. Eine explizite Domain ergänzt nur den Datensatz. created kennzeichnet das Ergebnis./contacts?email={query}Kontakte nach E-Mail-Adresse suchen. Gibt passende Kontakte mit ihrem zugehörigen Unternehmen zurück./contactsEinen Kontakt nach E-Mail finden oder anlegen, optional mit einem vorhandenen oder neuen Unternehmen.Anfrage POST /companies
| Field | Type | Description | |
|---|---|---|---|
| name | string | erforderlich | Unternehmensname |
| domain | string | optional | Unternehmensdomain zur Ergänzung. Sie wird nie zum Abgleich mit einem bestehenden Unternehmen verwendet |
Anfrage POST /contacts
| Field | Type | Description | |
|---|---|---|---|
| name | string | bedingt | Vollständiger Name. Dieses Feld oder firstName und lastName verwenden |
| firstName | string | bedingt | Vorname, wenn name nicht angegeben ist |
| lastName | string | optional | Nachname bei Verwendung von firstName |
| string | erforderlich | E-Mail für die Suche ohne Beachtung der Groß- und Kleinschreibung | |
| title | string | optional | Berufsbezeichnung |
| companyId | UUID | optional | Vorhandenes Unternehmen im authentifizierten Arbeitsbereich |
| companyName | string | optional | Unternehmen, das ohne companyId gefunden oder angelegt wird |
| companyDomain | string | optional | Optionale Ergänzungsdomain für companyName. Kein Abgleichsschlüssel für Unternehmen |
Unternehmensantwort
| Field | Type | Description |
|---|---|---|
| company.id | UUID | Unternehmens-ID |
| company.name | string | Unternehmensname |
| company.domain | string | null | Normalisierte Unternehmensdomain |
| created | boolean | Ob diese Anfrage das Unternehmen angelegt hat |
Kontaktantwort
| Field | Type | Description |
|---|---|---|
| contact.id | UUID | Kontakt-ID |
| contact.firstName | string | Vorname |
| contact.lastName | string | Nachname |
| contact.email | string | E-Mail-Adresse |
| contact.title | string | null | Berufsbezeichnung |
| contact.companyId | UUID | null | ID des zugehörigen Unternehmens |
| contact.companyName | string | null | Name des zugehörigen Unternehmens |
| created | boolean | Ob diese Anfrage den Kontakt angelegt hat |
| company | object | null | Aufgelöstes Unternehmen, falls vorhanden |
| companyCreated | boolean | Ob diese Anfrage das Unternehmen angelegt hat |
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.
/hooksEin Ereignis abonnieren. Erfordert eine HTTPS-Ziel-URL und einen Ereignistyp. Gibt eine Abonnement-ID zurück./hooks/{id}Ein Ereignis anhand der Abonnement-ID abbestellen.Ereignistypen
| Event | Description |
|---|---|
| view.created | Eine echte Person hat ein freigegebenes Dokument aufgerufen. Bot-Verkehr (E-Mail-Sicherheitsscanner, Crawler) wird automatisch gefiltert. |
| decision.made | Ein Interessent hat auf ein Angebot reagiert: angenommen, abgelehnt oder Änderungen angefordert. |
| email_captured | Ein Besucher hat seine E-Mail-Adresse eingegeben, um auf gesperrte Inhalte zuzugreifen. |
Beispiel-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"
}
}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.
/viewsDie letzten 100 Dokumentaufrufe auflisten. Bot-Sitzungen sind ausgeschlossen./decisionsAktuelle Angebotsentscheidungen auflisten (angenommen, abgelehnt, Änderungen angefordert)./emailsAktuelle E-Mail-Erfassungen aus gesperrten Inhalten auflisten.Fehlerbehandlung
Jeder Fehler gibt ein JSON-Objekt mit einem error-Feld zurück, das beschreibt, was schiefgelaufen ist. Manche Antworten enthalten zusätzlich ein code-Feld für die programmatische Behandlung, etwa PLAN_LIMIT_REACHED, INVALID_FORMAT oder FILE_TOO_LARGE. Die HTTP-Statuscodes folgen den üblichen Konventionen.
| Status | Meaning |
|---|---|
| 400 | Ungültige Anfrage: fehlende oder ungültige Parameter |
| 401 | Nicht autorisiert: ungültiges oder abgelaufenes Bearer-Token |
| 403 | Verboten: Plangrenze erreicht, oder dieser Anmeldedatentyp ist an diesem Endpunkt nicht zulässig |
| 404 | Nicht gefunden: Ressource existiert nicht oder gehört nicht Ihrem Team |
| 409 | Konflikt: Kontakt-, E-Mail- und Unternehmenskennungen stimmen nicht überein |
| 500 | Serverfehler: Anfrage erneut senden |
Rate-Limits
Maximal 50 aktive Webhook-Abonnements pro Team. API-Anfragen unterliegen keinem Rate-Limit, übermäßige Nutzung kann jedoch gedrosselt werden.
Diese API wird derzeit von unserer Zapier-Integration verwendet. Weitere Integrationsplattformen können in Zukunft unterstützt werden.