API-referentie

HummingDeck biedt een REST API voor integratiepartners en automatiseringsplatformen. Alle endpoints gebruiken OAuth 2.0-authenticatie en retourneren JSON-antwoorden.

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

OpenAPI Spec

Authenticatie

Alle API-verzoeken vereisen een geldig OAuth 2.0 Bearer token in de Authorization-header. Tokens worden uitgegeven tijdens de OAuth-autorisatiestroom en verlopen na 30 dagen. Gebruik het vernieuwingstoken (verloopdatum 90 dagen) om een nieuw toegangstoken te verkrijgen zonder opnieuw te autoriseren.

Methode

OAuth 2.0 (Bearer token)

Headerformaat

Authorization: Bearer {access_token}

Test uw verbinding

Verifieer dat uw token geldig is en bekijk het profiel van de geauthenticeerde gebruiker.

GET/meRetourneert de naam, het e-mailadres en de teaminformatie van de huidige gebruiker.

Documenten

Upload, zoek en beheer documenten (PDF's, presentaties, voorstellen en andere bestanden).

POST/decksEen nieuw document uploaden. Verzend als multipart/form-data met een file-veld (PDF, PPTX, DOCX, HTML) en een title-veld.

GET/decks?title={query}Documenten zoeken op titel. Hoofdletterongevoelig, retourneert maximaal 20 overeenkomsten.

Antwoordvelden

Field	Type	Description
id	string	Document-ID
title	string	Documenttitel
fileType	string	Bestandstype (pdf, pptx, docx, html)
pageCount	number	Aantal pagina's
thumbnailUrl	string	URL van de miniatuurafbeelding
createdAt	string	ISO 8601-tijdstempel

Deellinks

Maak traceerbare links om documenten te delen met prospects. Elke link volgt betrokkenheid afzonderlijk.

POST/sharesEen deellink maken. Ondersteunt persoonlijke links (met naam en e-mail van ontvanger) en anonieme links.

Verzoeksvelden

Field	Type		Description
deckId	string	required	ID van het te delen document
recipientName	string	optional	Naam van de ontvanger (voor persoonlijke links)
recipientEmail	string	optional	E-mailadres van de ontvanger (voor persoonlijke links)
type	string	optional	"personal" of "anonymous" (standaard: anonymous)

Antwoordvelden

Field	Type	Description
id	string	Deel-ID
slug	string	Deel-slug (gebruikt in de URL)
shareUrl	string	Volledige traceerbare URL
type	string	"personal" of "anonymous"
recipientName	string	Naam van de ontvanger (bij persoonlijke links)
recipientEmail	string	E-mail van de ontvanger (bij persoonlijke links)
createdAt	string	ISO 8601-tijdstempel

Contacten

Zoek contacten in het adresboek van uw team.

GET/contacts?email={query}Contacten zoeken op e-mailadres. Retourneert overeenkomende contacten met hun bijbehorend bedrijf.

Antwoordvelden

Field	Type	Description
id	string	Contact-ID
firstName	string	Voornaam
lastName	string	Achternaam
email	string	E-mailadres
title	string	Functietitel
leadName	string	Bedrijfsnaam
createdAt	string	ISO 8601-tijdstempel

Webhooks

Abonneer op realtime-evenementen via REST Hooks. Wanneer een evenement plaatsvindt, stuurt HummingDeck een POST-verzoek naar uw geregistreerde HTTPS-URL met de evenementpayload. Mislukte leveringen worden tot 3 keer opnieuw geprobeerd (na 1 s, 5 s en 30 s).

POST/hooksAbonneren op een evenement. Vereist een HTTPS-doel-URL en een evenementtype. Retourneert een abonnements-ID.

DELETE/hooks/{id}Abonnement op een evenement opzeggen op basis van abonnements-ID.

Evenementtypen

Event	Description
view.created	Een echte persoon heeft een gedeeld document bekeken. Botverkeer (e-mailbeveiligingsscanners, crawlers) wordt automatisch gefilterd.
decision.made	Een prospect heeft gereageerd op een voorstel — geaccepteerd, afgewezen of wijzigingen aangevraagd.
email_captured	Een bezoeker heeft hun e-mailadres ingevoerd om toegang te krijgen tot beveiligde inhoud.

Voorbeeldpayloads

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

Weergaven en evenementen

Polling-endpoints voor het ophalen van recente betrokkenheidsgegevens. Deze retourneren dezelfde gegevens die webhooks in realtime leveren — gebruik ze voor backfilling, testen of als alternatief.

GET/viewsDe meest recente 100 documentweergaven weergeven. Botsessies zijn uitgesloten.

GET/decisionsRecente voorstelbeslissingen weergeven (geaccepteerd, afgewezen, wijzigingen aangevraagd).

GET/emailsRecente e-mailregistraties van beveiligde inhoud weergeven.

Foutafhandeling

Alle fouten retourneren een JSON-object met een message-veld. HTTP-statuscodes volgen standaardconventies.

Status	Meaning
400	Ongeldig verzoek — ontbrekende of ongeldige parameters
401	Niet geautoriseerd — ongeldig of verlopen Bearer token
404	Niet gevonden — resource bestaat niet of behoort niet tot uw team
500	Serverfout — probeer het verzoek opnieuw

Tarieflimieten

Maximaal 50 actieve webhookabonnementen per team. API-verzoeken worden niet beperkt, maar overmatig gebruik kan worden beperkt.

Deze API wordt momenteel gebruikt door onze Zapier-integratie. In de toekomst worden mogelijk aanvullende integratieplatformen ondersteund.