API-Referenz

HummingDeck stellt eine REST API für Integrationspartner und Automatisierungsplattformen bereit. Alle Endpunkte verwenden OAuth 2.0-Authentifizierung und geben JSON-Antworten zurück.

Basis-URLhttps://app.hummingdeck.com/api/v1

OpenAPI Spec

Authentifizierung

Alle API-Anfragen erfordern ein gültiges OAuth 2.0 Bearer-Token im Authorization-Header. Tokens werden während des OAuth-Autorisierungsflows ausgestellt und laufen nach 30 Tagen ab. Verwenden Sie das Refresh-Token (90 Tage Gültigkeit), um ohne erneute Autorisierung ein neues Zugriffstoken zu erhalten.

Methode

OAuth 2.0 (Bearer token)

Header-Format

Authorization: Bearer {access_token}

Verbindung testen

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

GET/meGibt Name, E-Mail und Teaminformationen des aktuellen Benutzers zurück.

Dokumente

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

POST/decksEin neues Dokument hochladen. Als multipart/form-data mit einem file-Feld (PDF, PPTX, DOCX, HTML) und einem title-Feld senden.

GET/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

Freigabelinks

Verfolgbare Links erstellen, um Dokumente mit Interessenten zu teilen. Jeder Link verfolgt das Engagement separat.

POST/sharesEinen Freigabelink erstellen. Unterstützt persönliche Links (mit Name und E-Mail des Empfängers) und anonyme Links.

Anforderungsfelder

Field	Type		Description
deckId	string	required	ID des zu teilenden Dokuments
recipientName	string	optional	Name des Empfängers (für persönliche Links)
recipientEmail	string	optional	E-Mail des Empfängers (für persönliche Links)
type	string	optional	"personal" oder "anonymous" (Standard: anonymous)

Antwortfelder

Field	Type	Description
id	string	Freigabe-ID
slug	string	Freigabe-Slug (wird in der URL verwendet)
shareUrl	string	Vollständige verfolgbare URL
type	string	"personal" oder "anonymous"
recipientName	string	Name des Empfängers (bei persönlichen Links)
recipientEmail	string	E-Mail des Empfängers (bei persönlichen Links)
createdAt	string	ISO 8601-Zeitstempel

Kontakte

Kontakte im Adressbuch Ihres Teams suchen.

GET/contacts?email={query}Kontakte nach E-Mail-Adresse suchen. Gibt passende Kontakte mit ihrem zugehörigen Unternehmen zurück.

Antwortfelder

Field	Type	Description
id	string	Kontakt-ID
firstName	string	Vorname
lastName	string	Nachname
email	string	E-Mail-Adresse
title	string	Berufsbezeichnung
leadName	string	Unternehmensname
createdAt	string	ISO 8601-Zeitstempel

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).

POST/hooksEin Ereignis abonnieren. Erfordert eine HTTPS-Ziel-URL und einen Ereignistyp. Gibt eine Abonnement-ID zurück.

DELETE/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.

GET/viewsDie letzten 100 Dokumentaufrufe auflisten. Bot-Sitzungen sind ausgeschlossen.

GET/decisionsAktuelle Angebotsentscheidungen auflisten (angenommen, abgelehnt, Änderungen angefordert).

GET/emailsAktuelle E-Mail-Erfassungen aus gesperrten Inhalten auflisten.

Fehlerbehandlung

Alle Fehler geben ein JSON-Objekt mit einem message-Feld zurück. HTTP-Statuscodes folgen den Standardkonventionen.

Status	Meaning
400	Ungültige Anfrage — fehlende oder ungültige Parameter
401	Nicht autorisiert — ungültiges oder abgelaufenes Bearer-Token
404	Nicht gefunden — Ressource existiert nicht oder gehört nicht Ihrem Team
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.