API-referentie

Authenticatie

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

Soorten credentials

Machtigingen

Kies minstens één machtiging. Schrijfmachtigingen omvatten ook de bijbehorende leestoegang. Je kunt de machtigingen wijzigen wanneer je de sleutel vervangt.

De permissielabels bij endpoints gelden voor API-sleutels van de werkruimte. Vereiste permissies gelden altijd, extra vereiste permissies zijn samen nodig en voorwaardelijke permissies alleen wanneer het verzoek de bijbehorende filters of velden gebruikt. GET /me heeft geen permissie nodig. Zapier OAuth gebruikt de vaste integratietoegang.

Wanneer een aanvraag 401 teruggeeft

Een aanvraag retourneert 401 als de sleutel onbekend of ongeldig is, is verlopen, is uitgeschakeld, bij een werkruimte met uitgeschakelde API-toegang hoort, of is uitgegeven door iemand die geen eigenaar of beheerder van die werkruimte meer is.

Test uw verbinding

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

Documenten

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

GET /decks Antwoordvelden

POST /decks Antwoordvelden

Deellinks

Maak traceerbare documentlinks. Een persoonlijke link kan in dezelfde aanvraag het contact en bedrijf vinden of aanmaken.

Verzoeksvelden

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

Ruimtes

Maak Digital Sales Rooms met hun documenten en doelgroeplink in één aanroep, zoek ruimtes, wijzig hun instellingen, archiveer en herstel ze, en orden hun tabbladen en items. Alleen beschikbaar met API-tokens voor de werkruimte; Zapier OAuth-referenties worden geweigerd.

Een ruimte maken in één aanroep

Upload elk bestand met POST /decks en maak daarna de ruimte voor het bedrijf van de ontvanger, met een beperkte link voor de mensen die de ruimte mogen zien. Het bedrijf, de contactpersonen, de ruimte, de documenten en de link worden samen aangemaakt: als de aanroep wordt geweigerd, wordt er niets aangemaakt. Documenten kunnen al in de ruimte terwijl ze nog worden verwerkt. De items van de ruimte melden processingStatus, dus stuur de link pas zodra elk document completed meldt.

{
  "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 is open (iedereen met de URL), verify-any (bezoekers bevestigen hun e-mailadres met een eenmalige link) of verified-allowlist (alleen de adressen in allowedEmails en iedereen met een adres op de domeinen in allowedDomains). De API voegt uit zichzelf niemand toe aan een beperkte link, dus neem je eigen adres op als je de ruimte vooraf wilt bekijken. Een optie die je abonnement niet bevat geeft 403 FEATURE_NOT_AVAILABLE terug en een onbekend veld geeft 400, zodat een ruimte nooit opengaat voor een andere doelgroep dan je vroeg.

Tabbladen en items ordenen

Ga uit van de ruimte zoals die nu is: als je een ruimte opvraagt, krijg je de tabbladen en items in weergavevolgorde, en elk item meldt zijn tabblad en zijn positie daarin, geteld vanaf 0. Voeg tabbladen en items op een positie toe, verplaats items tussen tabbladen en stuur de volledige nieuwe volgorde van een tabblad. Een volgorde moet elk item van het tabblad precies één keer bevatten, dus vraag de ruimte opnieuw op als er intussen een andere wijziging was. Een tabblad kan weg zodra het geen items meer toont.

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

Ondersteunde embedaanbieders

Embeds accepteren een deel- of embedlink en normaliseren die naar de embedvorm van de aanbieder. Alles buiten deze lijst geeft 400 EMBED_PROVIDER_NOT_SUPPORTED.

Nog een doelgroeplink toevoegen

Elke ruimte heeft al een link uit POST /rooms; voeg er meer toe voor doelgroepen die een andere toewijzing of toegang nodig hebben. Geef minstens één van recipientName, recipientEmail, contactId, companyId of companyName op. accessMode accepteert dezelfde waarden open, verify-any of verified-allowlist als primaryLink, met dezelfde velden (requireEmail, allowedEmails, allowedDomains, label, expiresAt, allowDownloads). Een geweigerde aanroep, ook door een planlimiet, laat geen link, bedrijf of contact achter.

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

Een link bijwerken

Vier velden: isActive, expiresAt, allowedEmails, allowedDomains (de laatste twee alleen op verified-allowlist-links). accessMode en de slug veranderen nooit; maak in plaats daarvan een nieuwe link. Een link weer inschakelen controleert opnieuw de limiet voor actieve links van het abonnement.

{
  "isActive": false
}

Het actieplan opbouwen

Elke ruimte heeft precies één plan, dus het hangt onder de ruimte zonder eigen ID. De meeste taken horen bij een bedrijf en niet bij een persoon: stuur alleen een side en het plan leest dat als het bedrijf, precies wat je wilt als je niet weet wie aan de andere kant het werk doet. Voeg alleen een email toe als je de persoon kent. Een interne taak is nooit zichtbaar in de room en kan dus niet bij de ontvanger horen.

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

recipientCompletionEnabled op het plan bepaalt of wie de room opent de taken van de eigen kant mag afvinken. De standaard is true en het is de enige drempel: de API vraagt nooit om het adres van een ontvanger om een taak af te ronden. Wie wat heeft afgevinkt wordt vastgelegd met de zekerheid die de toegangsmodus van de room geeft.

Rooms labelen

Labels gelden voor de hele werkruimte: maak ze één keer en hergebruik ze. Geef labelIds mee bij POST /rooms om een room meteen te labelen, of bij PATCH /rooms/{roomId} om de hele set te vervangen; een lege array wist alle labels en het veld weglaten laat ze staan. Een room draagt er hooguit vijf, wat structureel is en geen instelling. Bij het lezen van een room worden de labels teruggegeven.

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

Zien wat er is gebeurd

Vraag /room-views op voor bezoeken in de hele werkruimte en lees daarna de analytics, activiteit en verzamelde adressen van één room. Geef de nextCursor van een pagina door als cursor om verder te gaan; een cursor die deze API niet heeft uitgegeven geeft 400 in plaats van opnieuw te beginnen, zodat een poller geen werk overdoet. Beperk het activiteitsvenster met since en blader er met cursor doorheen. /room-views is een venster en geen archief: zonder since krijg je de laatste 30 dagen en verzoeken van meer dan 90 dagen geleden worden geweigerd. Het gebruikte venster komt terug als since; stuur het mee met cursor om dezelfde set verder te doorlopen.

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.

POST /companies-aanvraag

POST /contacts-aanvraag

Bedrijfsantwoord

Contactantwoord

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.

Evenementtypen

Voorbeeldpayloads

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

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.

Foutafhandeling

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

Tarieflimieten

Handmatige werkruimtesleutels en Zapier OAuth-verbindingen hebben limieten per aanmeldgegeven: 600 leesverzoeken per 5 minuten, 120 schrijfverzoeken per minuut, 60 /room-views-verzoeken per minuut en 20 uploads per uur. Over alle aanmeldgegevens samen geldt per werkruimte een limiet van 1.200 leesverzoeken per 5 minuten, 240 schrijfverzoeken per minuut, 120 /room-views-verzoeken per minuut en 40 uploads per uur. Mislukte Bearer-authenticatie en ongeldige OAuth-clientauthenticatie zijn elk per client-IP beperkt tot 60 pogingen per 5 minuten. Maximaal 50 actieve webhookabonnementen per team.