Riferimento API

HummingDeck espone un'API REST per i partner di integrazione e le piattaforme di automazione. Tutti gli endpoint utilizzano l'autenticazione OAuth 2.0 e restituiscono risposte JSON.

URL basehttps://app.hummingdeck.com/api/v1

OpenAPI Spec

Autenticazione

Tutte le richieste API richiedono un Bearer token OAuth 2.0 valido nell'intestazione Authorization. I token vengono emessi durante il flusso di autorizzazione OAuth e scadono dopo 30 giorni. Usa il token di aggiornamento (scadenza 90 giorni) per ottenere un nuovo token di accesso senza dover riautorizzare.

Metodo

OAuth 2.0 (Bearer token)

Formato dell'intestazione

Authorization: Bearer {access_token}

Testa la connessione

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

GET/meRestituisce nome, e-mail e informazioni sul team dell'utente corrente.

Documenti

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

POST/decksCaricare un nuovo documento. Invia come multipart/form-data con un campo file (PDF, PPTX, DOCX, HTML) e un campo title.

GET/decks?title={query}Cerca documenti per titolo. Non distingue maiuscole e minuscole; restituisce fino a 20 risultati.

Campi della risposta

Field	Type	Description
id	string	ID del documento
title	string	Titolo del documento
fileType	string	Tipo di file (pdf, pptx, docx, html)
pageCount	number	Numero di pagine
thumbnailUrl	string	URL dell'immagine in miniatura
createdAt	string	Timestamp ISO 8601

Link di condivisione

Crea link tracciabili per condividere documenti con i prospect. Ogni link traccia il coinvolgimento separatamente.

POST/sharesCreare un link di condivisione. Supporta link personali (con nome e e-mail del destinatario) e link anonimi.

Campi della richiesta

Field	Type		Description
deckId	string	required	ID del documento da condividere
recipientName	string	optional	Nome del destinatario (per i link personali)
recipientEmail	string	optional	E-mail del destinatario (per i link personali)
type	string	optional	"personal" o "anonymous" (predefinito: anonymous)

Campi della risposta

Field	Type	Description
id	string	ID del link di condivisione
slug	string	Slug del link (usato nell'URL)
shareUrl	string	URL tracciabile completo
type	string	"personal" o "anonymous"
recipientName	string	Nome del destinatario (se personale)
recipientEmail	string	E-mail del destinatario (se personale)
createdAt	string	Timestamp ISO 8601

Contatti

Cerca contatti nella rubrica del tuo team.

GET/contacts?email={query}Cerca contatti per indirizzo e-mail. Restituisce i contatti corrispondenti con la relativa azienda associata.

Campi della risposta

Field	Type	Description
id	string	ID del contatto
firstName	string	Nome
lastName	string	Cognome
email	string	Indirizzo e-mail
title	string	Titolo professionale
leadName	string	Nome dell'azienda
createdAt	string	Timestamp ISO 8601

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

POST/hooksIscriversi a un evento. Richiede un URL HTTPS di destinazione e un tipo di evento. Restituisce un ID abbonamento.

DELETE/hooks/{id}Annullare l'iscrizione a un evento tramite ID abbonamento.

Tipi di eventi

Event	Description
view.created	Una persona reale ha visualizzato un documento condiviso. Il traffico bot (scanner di sicurezza e-mail, crawler) viene filtrato automaticamente.
decision.made	Un prospect ha risposto a una proposta — accettata, rifiutata o con modifiche richieste.
email_captured	Un visitatore ha inserito il proprio indirizzo e-mail per accedere a contenuti protetti.

Esempi di payload

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

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.

GET/viewsElencare le 100 visualizzazioni di documenti più recenti. Le sessioni bot sono escluse.

GET/decisionsElencare le decisioni recenti sulle proposte (accettate, rifiutate, modifiche richieste).

GET/emailsElencare le recenti acquisizioni di e-mail da contenuti protetti.

Gestione degli errori

Tutti gli errori restituiscono un oggetto JSON con un campo message. I codici di stato HTTP seguono le convenzioni standard.

Status	Meaning
400	Richiesta non valida — parametri mancanti o non validi
401	Non autorizzato — Bearer token non valido o scaduto
404	Non trovato — la risorsa non esiste o non appartiene al tuo team
500	Errore del server — riprova la richiesta

Limiti di frequenza

Massimo 50 abbonamenti webhook attivi per team. Le richieste API non sono soggette a limiti di frequenza, ma un uso eccessivo potrebbe essere rallentato.

Questa API è attualmente utilizzata dalla nostra integrazione Zapier. Ulteriori piattaforme di integrazione potrebbero essere supportate in futuro.