Référence API
HummingDeck expose une API REST pour les partenaires d'intégration et les plateformes d'automatisation. Les endpoints s'authentifient avec un Bearer token et renvoient des réponses JSON.
https://app.hummingdeck.com/api/v1Authentification
Chaque requête API transporte un Bearer token dans l'en-tête Authorization. Deux types d'identifiants sont acceptés, et leur comportement diffère.
Méthode
Bearer token
Format de l'en-tête
Authorization: Bearer {access_token}
Types d'identifiants
Token d'API de l'espace de travail
Authorization: Bearer hd_api_...
Émis par le propriétaire de l'espace de travail depuis Paramètres de l'espace, Intégrations, HummingDeck API. Réservé à certains espaces de travail pendant un pilote privé. Le token s'affiche une seule fois à sa création et ne peut plus être récupéré ensuite. Il expire un an après sa création et reste lié de façon permanente à l'espace pour lequel il a été émis : une requête ne peut donc ni choisir ni modifier son espace de travail.
Créer un token alors qu'il en existe déjà un le remplace, et le précédent cesse aussitôt de fonctionner. Le propriétaire peut désactiver un token à tout moment. C'est définitif pour ce token : créez-en un nouveau plutôt que d'espérer le restaurer.
Les endpoints d'abonnement aux webhooks ne sont pas accessibles aux tokens d'API d'espace de travail.
Zapier OAuth
Authorization: Bearer {access_token}
Émis via le flux d'autorisation OAuth lorsqu'un espace de travail connecte l'intégration Zapier. Les tokens d'accès expirent après 30 jours. Utilisez le token de rafraîchissement, valable 90 jours, pour en obtenir un nouveau sans réautoriser.
Ce sont les seuls identifiants pouvant créer ou supprimer des abonnements aux webhooks.
Quand une requête renvoie 401
Une requête est rejetée avec un code 401 lorsque le token est inconnu ou mal formé, a expiré, a été désactivé, appartient à un espace de travail dont l'accès API a été coupé, ou a été émis par une personne qui n'est plus propriétaire de cet espace.
Tester votre connexion
Vérifiez que votre token est valide et consultez le profil de l'utilisateur authentifié.
/meRenvoie le nom, l'e-mail et les informations d'équipe de l'utilisateur actuel.Documents
Téléchargez, recherchez et gérez des documents (PDFs, présentations, propositions et autres fichiers).
/decksTélécharger un nouveau document. Envoyez en multipart/form-data avec un champ file (PDF, PPTX, DOCX, XLSX, HTML) et un champ title. La limite d’envoi via l’API est de 30 Mo./decks?title={query}Rechercher des documents par titre. Insensible à la casse, renvoie jusqu'à 20 résultats.Champs de réponse
| Field | Type | Description |
|---|---|---|
| id | string | Identifiant du document |
| title | string | Titre du document |
| fileType | string | Type de fichier (pdf, pptx, docx, html) |
| pageCount | number | Nombre de pages |
| thumbnailUrl | string | URL de l'image miniature |
| createdAt | string | Horodatage ISO 8601 |
Salles
Consultez la structure d’une salle et créez des liens d’audience avec suivi. Disponible uniquement avec les jetons d’API de l’espace de travail ; les identifiants OAuth Zapier sont refusés.
/rooms/{roomId}Renvoie les métadonnées, les onglets, les éléments et le nombre de liens actifs et total./rooms/{roomId}/linksCrée un lien ouvert attribué pour une salle active.Créer un lien ouvert vers une salle
Renseignez au moins l’un des champs suivants : recipientName, recipientEmail, contactId, companyId ou companyName. Le nom ou l’adresse e-mail recherche ou crée un contact ; les champs d’entreprise recherchent ou créent une entreprise. Toute personne disposant de l’URL peut ouvrir un lien ouvert.
{
"accessMode": "open",
"recipientName": "Ada Lovelace",
"recipientEmail": "ada@analytical.example",
"companyName": "Analytical Engines"
}Entreprises et contacts
Retrouvez des fiches de compte existantes ou créez-les avec une correspondance déterministe. Les noms d’entreprise et les e-mails des contacts sont comparés sans tenir compte de la casse.
/companies?name={name}&domain={domain}Recherche des entreprises par nom exact et, facultativement, par domaine./companiesRetrouve une entreprise par son nom sans tenir compte de la casse ou la crée. Un domaine explicite enrichit uniquement la fiche./contacts?email={query}Recherche des contacts par adresse e-mail et renvoie les correspondances avec leur entreprise associée./contactsRetrouve ou crée un contact par e-mail et l’associe facultativement à une entreprise.Requête POST /companies
| Field | Type | Description | |
|---|---|---|---|
| name | string | requis | Nom de l’entreprise |
| domain | string | facultatif | Domaine utilisé pour enrichir l’entreprise. Il ne sert jamais à retrouver une entreprise existante |
Requête POST /contacts
| Field | Type | Description | |
|---|---|---|---|
| name | string | conditionnel | Nom complet. Requis si firstName est absent |
| firstName | string | conditionnel | Prénom. Requis si name est absent |
| lastName | string | facultatif | Nom de famille |
| string | requis | Adresse e-mail utilisée pour une correspondance unique | |
| title | string | facultatif | Intitulé du poste |
| companyId | UUID | facultatif | Entreprise existante dans l’espace de travail authentifié |
| companyName | string | facultatif | Nom de l’entreprise à retrouver ou à créer |
| companyDomain | string | facultatif | Domaine d’enrichissement facultatif utilisé avec companyName. Ce n’est pas une clé de correspondance |
Réponse de l’entreprise
| Field | Type | Description |
|---|---|---|
| company.id | UUID | Identifiant de l’entreprise |
| company.name | string | Nom de l’entreprise |
| company.domain | string | null | Domaine normalisé de l’entreprise |
| created | boolean | true si la requête POST a créé l’entreprise |
Réponse du contact
| Field | Type | Description |
|---|---|---|
| contact.id | UUID | Identifiant du contact |
| contact.firstName | string | Prénom |
| contact.lastName | string | Nom de famille |
| contact.email | string | Adresse e-mail normalisée |
| contact.title | string | null | Intitulé du poste |
| contact.companyId | UUID | null | Identifiant de l’entreprise associée |
| contact.companyName | string | null | Nom de l’entreprise associée |
| created | boolean | true si la requête POST a créé le contact |
| company | object | null | Entreprise résolue, si disponible |
| companyCreated | boolean | true si cette requête a créé l’entreprise |
Webhooks
Abonnez-vous aux événements en temps réel via REST Hooks. Lorsqu'un événement se produit, HummingDeck envoie une requête POST à votre URL HTTPS enregistrée avec le payload de l'événement. Les livraisons échouées sont relancées jusqu'à 3 fois (à intervalles de 1 s, 5 s et 30 s). Les abonnements aux webhooks sont gérés par l'intégration Zapier et ne sont pas accessibles aux tokens d'API d'espace de travail.
/hooksS'abonner à un événement. Nécessite une URL HTTPS cible et un type d'événement. Renvoie un identifiant d'abonnement./hooks/{id}Se désabonner d'un événement par identifiant d'abonnement.Types d'événements
| Event | Description |
|---|---|
| view.created | Une vraie personne a consulté un document partagé. Le trafic de bots (scanners de sécurité e-mail, robots d'indexation) est filtré automatiquement. |
| decision.made | Un prospect a répondu à une proposition : acceptée, refusée ou avec des modifications demandées. |
| email_captured | Un visiteur a saisi son adresse e-mail pour accéder à du contenu protégé. |
Exemples de payloads
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"
}
}Vues et événements
Endpoints d'interrogation pour récupérer les données d'engagement récentes. Ils renvoient les mêmes données que les webhooks livrent en temps réel. Utilisez-les pour le remplissage, les tests ou en tant que solution de secours.
/viewsLister les 100 consultations de documents les plus récentes. Les sessions de bots sont exclues./decisionsLister les décisions récentes sur les propositions (acceptées, refusées, modifications demandées)./emailsLister les captures d'e-mail récentes depuis du contenu protégé.Gestion des erreurs
Chaque erreur renvoie un objet JSON avec un champ error décrivant ce qui n'a pas fonctionné. Certaines réponses contiennent aussi un champ code pour le traitement programmatique, par exemple PLAN_LIMIT_REACHED, INVALID_FORMAT ou FILE_TOO_LARGE. Les codes de statut HTTP suivent les conventions habituelles.
| Status | Meaning |
|---|---|
| 400 | Requête incorrecte : paramètres manquants ou invalides |
| 401 | Non autorisé : Bearer token invalide ou expiré |
| 403 | Interdit : limite du forfait atteinte, ou ce type d'identifiant n'est pas autorisé sur cet endpoint |
| 404 | Introuvable : la ressource n'existe pas ou n'appartient pas à votre équipe |
| 409 | Conflit : les identifiants du contact, de l’e-mail et de l’entreprise ne correspondent pas |
| 500 | Erreur serveur : réessayez la requête |
Limites de débit
Maximum 50 abonnements webhook actifs par équipe. Les requêtes API ne sont pas limitées en débit, mais un usage excessif peut être bridé.
Cette API est actuellement utilisée par notre intégration Zapier. Des plateformes d'intégration supplémentaires pourront être prises en charge à l'avenir.