Gebouwd op vertrouwenTLS-versleutelingAVG-klaarGoogle CloudVeilige betalingenBeveiligingsoverzicht

API-referentie

HummingDeck biedt een REST API voor integratiepartners en automatiseringsplatformen. Endpoints authenticeren met een Bearer token en geven JSON-antwoorden terug.

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

OpenAPI Spec

Authenticatie

Elke API-aanvraag stuurt een Bearer token mee in de Authorization-header. Er worden twee soorten credentials geaccepteerd, en ze gedragen zich verschillend.

Methode

Bearer token

Headerformaat

Authorization: Bearer {access_token}

Soorten credentials

Werkruimte-API-token

Authorization: Bearer hd_api_...

Uitgegeven door de eigenaar van de werkruimte via Werkruimte-instellingen, Integraties, HummingDeck API. Tijdens een besloten pilot alleen beschikbaar voor geselecteerde werkruimtes. Het token wordt bij het aanmaken één keer getoond en is daarna niet meer op te vragen. Het verloopt een jaar na aanmaak en is permanent gekoppeld aan de werkruimte waarvoor het is uitgegeven, dus een aanvraag kan haar werkruimte niet kiezen of overschrijven.

Een token aanmaken terwijl er al één is, vervangt het, en het vorige token werkt meteen niet meer. De eigenaar kan een token op elk moment uitschakelen. Voor dat token is dat definitief: maak een nieuw token aan in plaats van op herstel te rekenen.

Endpoints voor webhook-abonnementen zijn niet beschikbaar voor werkruimte-API-tokens.

Zapier OAuth

Authorization: Bearer {access_token}

Uitgegeven via de OAuth-autorisatiestroom wanneer een werkruimte de Zapier-integratie koppelt. Access tokens verlopen na 30 dagen. Gebruik het refresh token, dat 90 dagen geldig is, om een nieuw access token te krijgen zonder opnieuw te autoriseren.

Dit is de enige credential die webhook-abonnementen kan aanmaken of verwijderen.

Wanneer een aanvraag 401 teruggeeft

Een aanvraag wordt met 401 geweigerd als het token onbekend of ongeldig is, is verlopen, is uitgeschakeld, hoort bij een werkruimte waarvan API-toegang is uitgezet, of is uitgegeven door iemand die geen eigenaar meer is van die werkruimte.

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, XLSX, HTML) en een title-veld. De uploadlimiet via de API is 30 MB.

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 documentlinks. Een persoonlijke link kan in dezelfde aanvraag het contact en bedrijf vinden of aanmaken.

POST/sharesMaakt een persoonlijke of anonieme link. Persoonlijke links kunnen accountrecords automatisch vinden of aanmaken.

Verzoeksvelden

Field	Type		Description
deckId	string	verplicht	ID van het te delen document
recipientName	string	optioneel	Naam van de ontvanger voor een persoonlijke link
recipientEmail	string	optioneel	E-mailadres van de ontvanger voor een persoonlijke link
contactId	UUID	optioneel	Bestaand contact in de geauthenticeerde werkruimte
companyId	UUID	optioneel	Bestaand bedrijf. Kan niet samen met companyName worden gebruikt
companyName	string	optioneel	Bedrijf om op naam te vinden of aan te maken
companyDomain	string	optioneel	Domein dat voor verrijking wordt opgeslagen wanneer companyName is opgegeven. Het selecteert nooit een bedrijf
type	string	optioneel	Standaard personal met ontvanger- of accountvelden, anders anonymous

Maak de link en accountrecords tegelijk

Stuur gegevens van de ontvanger en het bedrijf rechtstreeks naar /shares. HummingDeck vindt overeenkomende records, maakt ontbrekende records aan, koppelt ze aan de link en meldt wat er is aangemaakt. Stel type expliciet in op anonymous om geen accountrecords aan te maken.

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

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)
contact	object \| null	Contact dat aan de persoonlijke link is gekoppeld
contactCreated	boolean	true als deze aanvraag het contact heeft aangemaakt
company	object \| null	Bedrijf dat aan de persoonlijke link is gekoppeld
companyCreated	boolean	true als deze aanvraag het bedrijf heeft aangemaakt
createdAt	string	ISO 8601-tijdstempel

Ruimtes

Haal de ruimtestructuur op en maak traceerbare links voor een doelgroep. Alleen beschikbaar met API-tokens voor de werkruimte; Zapier OAuth-referenties worden geweigerd.

GET/rooms/{roomId}Geeft metadata, tabbladen, inhoud en het aantal actieve en totale links van de ruimte terug.

POST/rooms/{roomId}/linksMaakt een toegeschreven open link voor een actieve ruimte.

Een open ruimtelink maken

Vul minstens één van deze velden in: recipientName, recipientEmail, contactId, companyId of companyName. Naam en e-mail zoeken of maken een contactpersoon; bedrijfsvelden zoeken of maken een bedrijf. Iedereen met de URL kan een open link bekijken.

{
  "accessMode": "open",
  "recipientName": "Ada Lovelace",
  "recipientEmail": "ada@analytical.example",
  "companyName": "Analytical Engines"
}

Bedrijven en contacten

Vind bestaande accountrecords of maak ze aan met eenduidige matching. Bedrijfsnamen en e-mailadressen van contacten worden zonder onderscheid tussen hoofdletters en kleine letters vergeleken.

GET/companies?name={name}&domain={domain}Zoekt bedrijven op exacte naam en een optioneel domein.

POST/companiesVindt een bedrijf hoofdletterongevoelig op naam of maakt het aan. Een expliciet domein verrijkt alleen het record.

GET/contacts?email={query}Zoekt contacten op e-mailadres en retourneert overeenkomsten met het bijbehorende bedrijf.

POST/contactsVindt of maakt een contact op e-mailadres en koppelt dit optioneel aan een bedrijf.

POST /companies-aanvraag

Field	Type		Description
name	string	verplicht	Bedrijfsnaam
domain	string	optioneel	Domein voor bedrijfsverrijking. Het wordt nooit gebruikt om een bestaand bedrijf te vinden

POST /contacts-aanvraag

Field	Type		Description
name	string	voorwaardelijk	Volledige naam. Verplicht als firstName ontbreekt
firstName	string	voorwaardelijk	Voornaam. Verplicht als name ontbreekt
lastName	string	optioneel	Achternaam
email	string	verplicht	E-mailadres voor eenduidige matching
title	string	optioneel	Functietitel
companyId	UUID	optioneel	Bestaand bedrijf in de geauthenticeerde werkruimte
companyName	string	optioneel	Naam van het bedrijf om te vinden of aan te maken
companyDomain	string	optioneel	Optioneel verrijkingsdomein voor gebruik met companyName. Geen matchingsleutel voor bedrijven

Bedrijfsantwoord

Field	Type	Description
company.id	UUID	Bedrijfs-ID
company.name	string	Bedrijfsnaam
company.domain	string \| null	Genormaliseerd bedrijfsdomein
created	boolean	true als de POST-aanvraag het bedrijf heeft aangemaakt

Contactantwoord

Field	Type	Description
contact.id	UUID	Contact-ID
contact.firstName	string	Voornaam
contact.lastName	string	Achternaam
contact.email	string	Genormaliseerd e-mailadres
contact.title	string \| null	Functietitel
contact.companyId	UUID \| null	ID van het gekoppelde bedrijf
contact.companyName	string \| null	Naam van het gekoppelde bedrijf
created	boolean	true als de POST-aanvraag het contact heeft aangemaakt
company	object \| null	Gevonden bedrijf, indien beschikbaar
companyCreated	boolean	true als deze aanvraag het bedrijf heeft aangemaakt

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). Webhook-abonnementen worden beheerd door de Zapier-integratie en zijn niet beschikbaar voor werkruimte-API-tokens.

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

Elke fout geeft een JSON-object terug met een error-veld dat beschrijft wat er misging. Sommige antwoorden bevatten ook een code-veld voor programmatische afhandeling, zoals PLAN_LIMIT_REACHED, INVALID_FORMAT of FILE_TOO_LARGE. HTTP-statuscodes volgen de gebruikelijke conventies.

Status	Meaning
400	Ongeldig verzoek: ontbrekende of ongeldige parameters
401	Niet geautoriseerd: ongeldig of verlopen Bearer token
403	Verboden: limiet van het abonnement bereikt, of dit type credential is niet toegestaan op dit endpoint
404	Niet gevonden: resource bestaat niet of behoort niet tot uw team
409	Conflict: de opgegeven contact-, e-mail- en bedrijfs-ID's komen niet overeen
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.