Riferimento API

Autenticazione

Ogni richiesta API porta un Bearer token nell'header Authorization. Sono accettati due tipi di credenziale, che si comportano in modo diverso.

Tipi di credenziale

Autorizzazioni

Scegli almeno un’autorizzazione. Le autorizzazioni di scrittura includono anche il corrispondente accesso in lettura. Puoi modificarle quando sostituisci la chiave.

Le etichette dei permessi nelle righe degli endpoint si applicano alle chiavi API dello spazio di lavoro. I permessi richiesti valgono sempre, quelli aggiuntivi servono insieme e quelli condizionali solo quando la richiesta usa i relativi filtri o campi. GET /me non richiede permessi. Zapier OAuth usa il proprio accesso di integrazione fisso.

Quando una richiesta restituisce 401

Una richiesta restituisce 401 se la chiave è sconosciuta o malformata, è scaduta, è stata disattivata, appartiene a uno spazio di lavoro con accesso API disattivato oppure è stata emessa da una persona che non è più proprietaria o amministratrice di quello spazio.

Testa la connessione

Verifica che il tuo token sia valido e consulta il profilo dell'utente autenticato.

Documenti

Carica, cerca e gestisci documenti (PDF, presentazioni, proposte e altri file).

GET /decks Campi della risposta

POST /decks Campi della risposta

Link di condivisione

Crea link tracciabili ai documenti. Un link personale può trovare o creare il contatto e l’azienda nella stessa richiesta.

Campi della richiesta

Crea insieme il link e i record dell’account

Invia i dati del destinatario e dell’azienda direttamente a /shares. HummingDeck trova i record corrispondenti, crea quelli mancanti, li collega al link e indica cosa è stato creato. Imposta esplicitamente type su anonymous per evitare la creazione dei record dell’account.

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

Campi della risposta

Stanze

Crea Deal Room con i relativi documenti e il link per il pubblico in una sola chiamata, trova le stanze, modificane le impostazioni, archiviale e ripristinale, e organizzane schede ed elementi. Disponibile solo con token API dell’area di lavoro; le credenziali OAuth di Zapier vengono rifiutate.

Creare una stanza con una sola chiamata

Carica ogni file con POST /decks, poi crea la stanza per l’azienda del destinatario con un link riservato alle persone che devono vederla. Azienda, contatti, stanza, documenti e link vengono creati insieme: se la chiamata viene rifiutata, non viene creato nulla. I documenti possono entrare nella stanza anche mentre sono ancora in elaborazione. Gli elementi della stanza riportano processingStatus, quindi invia il link quando ogni documento risulta completed.

{
  "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 può essere open (chiunque abbia l’URL), verify-any (i visitatori confermano il proprio indirizzo e-mail con un link monouso) o verified-allowlist (solo gli indirizzi in allowedEmails e chiunque abbia un indirizzo nei domini in allowedDomains). L’API non aggiunge nessuno di sua iniziativa a un link riservato, quindi includi il tuo indirizzo se vuoi vedere l’anteprima della stanza. Un’opzione non inclusa nel tuo piano restituisce 403 FEATURE_NOT_AVAILABLE e un campo sconosciuto restituisce 400, così una stanza non si apre mai a un pubblico diverso da quello richiesto.

Organizzare schede ed elementi

Parti dallo stato attuale della stanza: leggendo una stanza ottieni schede ed elementi nell’ordine di visualizzazione, e ogni elemento riporta la sua scheda e la sua posizione al suo interno, contando da 0. Aggiungi schede ed elementi in una posizione, sposta elementi tra le schede e invia il nuovo ordine completo di una scheda. Un ordine deve elencare ogni elemento della scheda esattamente una volta, quindi rileggi la stanza se nel frattempo è intervenuta un’altra modifica. Una scheda si può rimuovere quando non mostra più elementi.

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

Fornitori di embed supportati

Gli embed accettano un link di condivisione o di incorporamento e lo normalizzano alla forma di incorporamento del fornitore. Qualsiasi cosa fuori da questo elenco restituisce 400 EMBED_PROVIDER_NOT_SUPPORTED.

Aggiungere un altro link per il pubblico

Ogni stanza ha già un link creato da POST /rooms; aggiungine altri per i destinatari che richiedono un'attribuzione o un accesso diverso. Indica almeno uno tra recipientName, recipientEmail, contactId, companyId o companyName. accessMode accetta gli stessi valori open, verify-any o verified-allowlist di primaryLink, con gli stessi campi (requireEmail, allowedEmails, allowedDomains, label, expiresAt, allowDownloads). Una chiamata rifiutata, anche per un limite del piano, non lascia alcun link, azienda o contatto.

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

Aggiornare un link

Quattro campi: isActive, expiresAt, allowedEmails, allowedDomains (gli ultimi due solo sui link verified-allowlist). accessMode e lo slug non cambiano mai; crea invece un nuovo link. Riattivare un link fa ricontrollare il limite di link attivi del piano.

{
  "isActive": false
}

Costruire il piano d'azione

Ogni room ha esattamente un piano, quindi si aggancia alla room senza un identificatore proprio. La maggior parte delle attività appartiene a un'azienda e non a una persona: se invii solo un side, il piano lo legge come l'azienda, che è ciò che serve quando non sai chi farà il lavoro dall'altra parte. Aggiungi un'email solo quando conosci la persona. Un'attività interna non compare mai nella room, quindi non può appartenere al destinatario.

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

recipientCompletionEnabled sul piano decide se chi apre la room può spuntare le attività del proprio lato. Il valore predefinito è true ed è l'unico vincolo: l'API non chiede mai l'indirizzo di un destinatario per completare un'attività. Chi ha spuntato cosa viene registrato con la certezza consentita dalla modalità di accesso della room.

Etichettare le room

Le etichette valgono per tutto lo spazio di lavoro: creale una volta e riusale. Passa labelIds in POST /rooms per etichettare una room al momento della creazione, oppure in PATCH /rooms/{roomId} per sostituire l'intero insieme; un array vuoto rimuove tutte le etichette e omettere il campo le lascia invariate. Una room ne porta al massimo cinque, per struttura e non per impostazione. Leggendo una room vengono restituite le sue etichette.

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

Sapere che cosa è successo

Interroga /room-views per vedere gli ingressi in tutto lo spazio di lavoro, quindi leggi analytics, attività e indirizzi raccolti di una singola room. Per continuare, passa il nextCursor di una pagina come cursor; un cursore non emesso da questa API restituisce 400 invece di ripartire dall'inizio, così chi interroga non ripete il lavoro. Usa since per restringere l'intervallo dell'attività e cursor per scorrerne le pagine. /room-views è una finestra, non un archivio: senza since ottieni gli ultimi 30 giorni, mentre le richieste oltre 90 giorni indietro vengono rifiutate. La finestra applicata torna come since; inviala insieme a cursor per continuare a sfogliare lo stesso insieme.

Aziende e contatti

Trova i record dell’account esistenti o creane di nuovi con una corrispondenza deterministica. I nomi delle aziende e le e-mail dei contatti vengono confrontati senza distinzione tra maiuscole e minuscole.

Richiesta POST /companies

Richiesta POST /contacts

Risposta dell’azienda

Risposta del contatto

Webhook

Iscriviti agli eventi in tempo reale tramite REST Hooks. Quando si verifica un evento, HummingDeck invia una richiesta POST all'URL HTTPS registrato con il payload dell'evento. Le consegne fallite vengono ritentate fino a 3 volte (a intervalli di 1 s, 5 s e 30 s). Le sottoscrizioni ai webhook sono gestite dall'integrazione Zapier e non sono disponibili per i token API dello spazio di lavoro.

Tipi di eventi

Esempi di payload

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

Visualizzazioni ed eventi

Endpoint di polling per recuperare i dati di coinvolgimento recenti. Restituiscono gli stessi dati che i webhook consegnano in tempo reale. Usali per il backfilling, i test o come alternativa.

Gestione degli errori

Ogni errore restituisce un oggetto JSON con un campo error che descrive cosa non ha funzionato. La maggior parte delle risposte include anche un campo code per la gestione programmatica, come PLAN_LIMIT_REACHED, FEATURE_NOT_AVAILABLE, ROOM_NOT_ACTIVE, TAB_NOT_EMPTY, INVALID_FORMAT o FILE_TOO_LARGE. I codici di stato HTTP seguono le convenzioni consuete.

Limiti di frequenza

Le chiavi manuali dello spazio e le connessioni OAuth Zapier hanno limiti per credenziale: 600 letture ogni 5 minuti, 120 scritture al minuto, 60 richieste a /room-views al minuto e 20 caricamenti all’ora. Considerando tutte le credenziali, ogni spazio è limitato a 1.200 letture ogni 5 minuti, 240 scritture al minuto, 120 richieste a /room-views al minuto e 40 caricamenti all’ora. Le autenticazioni Bearer non riuscite e le autenticazioni client OAuth non valide sono limitate separatamente a 60 tentativi ogni 5 minuti per IP client. Massimo 50 abbonamenti webhook attivi per team.