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

Quando una richiesta restituisce 401

Una richiesta viene rifiutata con 401 quando il token è sconosciuto o malformato, è scaduto, è stato disattivato, appartiene a uno spazio di lavoro il cui accesso API è stato disattivato, oppure è stato emesso da qualcuno che non è più proprietario 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).

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

Recupera la struttura di una stanza e crea link tracciabili per il pubblico. Disponibile solo con token API dell’area di lavoro; le credenziali OAuth di Zapier vengono rifiutate.

Creare un link aperto per la stanza

Fornisci almeno uno dei campi recipientName, recipientEmail, contactId, companyId o companyName. Nome ed e-mail trovano o creano un contatto; i campi dell’azienda trovano o creano un’azienda. Chiunque disponga dell’URL può aprire un link aperto.

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

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. Alcune risposte includono anche un campo code per la gestione programmatica, come PLAN_LIMIT_REACHED, INVALID_FORMAT o FILE_TOO_LARGE. I codici di stato HTTP seguono le convenzioni consuete.

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.