Noté 5,0 sur 5 sur G2
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_...
L’accès à l’API REST est inclus dans l’offre Business payante. Pendant la période d’essai de Business, l’accès est accordé sur demande. Les propriétaires et les administrateurs créent ensuite des clés API nommées séparément dans Paramètres de l’espace, Intégrations, HummingDeck API. Choisissez uniquement les autorisations nécessaires à chaque intégration. Une clé s’affiche une seule fois à sa création et ne peut plus être récupérée. Elle expire après un an et reste liée à son espace de travail, qu’une requête ne peut ni choisir ni modifier.
Un espace de travail peut avoir jusqu’à 20 clés API actives. Remplacer une clé invalide immédiatement son ancien secret uniquement ; les autres clés continuent de fonctionner. Les propriétaires et les administrateurs peuvent désactiver une clé ou toutes les clés à tout moment. La révocation de ce secret est définitive.
Une clé API d’espace de travail ne peut appeler que les opérations autorisées par les autorisations choisies. Les endpoints d’abonnement aux webhooks ne sont pas disponibles pour ces clés.
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.
Autorisations
Choisissez au moins une autorisation. Les autorisations d’écriture incluent aussi l’accès en lecture correspondant. Vous pourrez les modifier en remplaçant la clé.
rooms:readConsulter les salles, onglets, éléments, liens et libellés.
rooms:writeCréer et gérer les salles, onglets, éléments, liens et libellés.
plan:readConsulter les phases et tâches du plan d’action mutuel.
plan:writeCréer et gérer les phases et tâches du plan d’action mutuel.
analytics:readConsulter les analyses d’engagement, l’activité et les e-mails recueillis.
crm:readRechercher les entreprises et contacts de l’espace de travail.
crm:writeCréer ou modifier des entreprises, des contacts et les audiences des liens.
documents:readRechercher des documents et consulter leurs métadonnées.
documents:writeImporter, remplacer, renommer et supprimer des documents ; gérer leurs liens de partage et ajouter des documents ou des URL aux Rooms.
Les libellés de permission sur les lignes des endpoints concernent les clés API de l’espace de travail. Les permissions requises s’appliquent toujours, les permissions supplémentaires sont nécessaires ensemble et les permissions conditionnelles uniquement lorsque la requête utilise les filtres ou champs associés. GET /me ne demande aucune permission. Zapier OAuth utilise son accès d’intégration fixe.
Quand une requête renvoie 401
Une requête renvoie 401 lorsque la clé est inconnue ou mal formée, a expiré, a été désactivée, appartient à un espace dont l’accès API a été coupé, ou a été émise par une personne qui n’est plus propriétaire ni administratrice 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.
Aucune permission de clé API requise
Documents
Téléchargez, recherchez et gérez des documents (PDFs, présentations, propositions et autres fichiers).
/decksTélécharger un nouveau document. Envoyez-le en multipart/form-data avec un champ file (PDF, PPTX, DOCX, XLSX, XLS, HTML) et un champ title. La limite d’envoi via l’API est de 30 Mo. Le traitement se poursuit après l’envoi ; la réponse inclut processingStatus.
documents:write/decks/{deckId}Obtenir les métadonnées et l’état de traitement d’un document
documents:read/decks/{deckId}Renommer avec un corps JSON contenant title (1–255 caractères). L’ID du document, le fichier et les liens restent identiques.
documents:write/decks/{deckId}Marquer le document comme supprimé et désactiver tous ses liens. Les fichiers source et l’historique analytique sont conservés. Une proposition active renvoie 409 PROPOSAL_LOCKED.
documents:write/decksRépertorie jusqu’à 20 documents, les plus récents en premier. Utilisez le paramètre de requête facultatif title pour filtrer sur une partie du titre sans tenir compte de la casse.
documents:read/decks/searchRechercher les titres avec query ; filtrer par folderId (root pour les fichiers sans dossier), fileType, createdAfter et createdBefore. sort : created_desc, created_asc ou title_asc. Renvoie items et nextCursor ; limit vaut 20 par défaut (1–100). Conserver les filtres et le tri entre les pages.
documents:read/decks/{deckId}/replaceRemplace un document par un fichier local du même type. Nécessite une clé API d’espace de travail avec documents:write. Les liens, le titre et le mode de diffusion restent inchangés. Les fichiers avec aperçu renvoient pending et ceux à télécharger uniquement completed. La réponse contient les mêmes champs que POST /decks.
documents:writeGET /decks Champs de réponse
| Field | Type | Description |
|---|---|---|
| id | string | Identifiant du document |
| title | string | Titre du document |
| fileType | string | Type MIME du document |
| pageCount | integer | null | Nombre de pages |
| thumbnailUrl | string | null | URL de l'image miniature |
| processingStatus | string | pending, processing, completed ou failed. Un document peut être ajouté à une salle pendant son traitement ; envoyez un lien vers ce document une fois qu’il indique completed. |
| processingErrorCode | string | null | Raison de l’échec du traitement, le cas échéant |
| createdAt | string | Horodatage ISO 8601 |
POST /decks Champs de réponse
| Field | Type | Description |
|---|---|---|
| id | string | Identifiant du document |
| title | string | Titre du document |
| fileType | string | Type MIME du document |
| processingStatus | string | pending, processing, completed ou failed. Un document peut être ajouté à une salle pendant son traitement ; envoyez un lien vers ce document une fois qu’il indique completed. |
| processingErrorCode | string | null | Raison de l’échec du traitement, le cas échéant |
Salles
Créez des Digital Sales Rooms avec leurs documents et leur lien d’audience en un seul appel, retrouvez vos salles, modifiez leurs paramètres, archivez-les et restaurez-les, et organisez leurs onglets et leurs éléments. Disponible uniquement avec les jetons d’API de l’espace de travail ; les identifiants OAuth Zapier sont refusés.
/roomsListe les salles, des plus récentes aux plus anciennes, avec les filtres search, status (active, archived ou all) et companyId. Chaque page contient 25 salles (jusqu’à 100 avec limit) ; passez le nextCursor d’une page comme cursor pour obtenir la suivante.
rooms:readcrm:read(Required when the companyId filter is present.)/roomsCrée une salle avec ses documents et son premier lien d’audience en un seul appel.
rooms:writedocuments:write(Required when documentIds contains one or more document IDs.)crm:write(Required when the request supplies contactId, recipientName, recipientEmail, companyId, companyName, or when either primaryLink.allowedEmails or primaryLink.allowedDomains is non-empty.)/rooms/{roomId}/duplicateCopier vers une nouvelle salle sans entreprise ni contact attribués. Fournir name, includeDocuments, includeActionItems, includeBranding, mapDueDates (keep ou clear) et une nouvelle politique primaryLink. Les audiences, conversations et visites d’origine ne sont pas copiées.
rooms:writedocuments:write(Required when includeDocuments is true.)plan:write(Required when includeActionItems is true.)crm:write(Required when primaryLink.allowedEmails or allowedDomains is non-empty.)/rooms/{roomId}Renvoie les paramètres de la salle, ses onglets et ses éléments dans l’ordre d’affichage, ainsi que le nombre de liens.
rooms:read/rooms/{roomId}Modifie le nom, le message d’accueil, l’interlocuteur, l’entreprise ou le contact.
rooms:writecrm:write(Required when companyId or contactId is present, including null to detach the association.)/rooms/{roomId}Supprimer définitivement la salle, le plan, les liens, l’historique des visites et les conversations. Envoyer confirmationName correspondant exactement au nom actuel. Les documents de la bibliothèque restent. Utiliser archive pour archiver la salle et pouvoir la restaurer.
rooms:write/rooms/{roomId}/appearanceRenvoie la couleur de marque, les polices et la disposition de l’en-tête enregistrées. Indique si une image d’en-tête est définie et liste les polices disponibles.
rooms:read/rooms/{roomId}/appearanceModifie la couleur de marque, la police des titres ou du corps du texte, ou la disposition de l’en-tête. La valeur null rétablit la couleur ou la police par défaut.
rooms:write/rooms/{roomId}/header-imageAjoute ou remplace l’image d’en-tête. Formats JPEG, PNG ou WebP, jusqu’à 10 Mio et au moins 1200 × 400 pixels.
rooms:write/rooms/{roomId}/header-imageSupprime l’image d’en-tête.
rooms:write/rooms/{roomId}/archiveArchive la salle. Ses liens cessent de fonctionner.
rooms:write/rooms/{roomId}/restoreRestaure une salle archivée. Ses liens fonctionnent à nouveau.
rooms:write/rooms/{roomId}/tabsAjoute un onglet, à une position donnée ou à la fin.
rooms:write/rooms/{roomId}/tabs/{tabId}Renomme un onglet.
rooms:write/rooms/{roomId}/tabs/orderRéorganise tous les onglets.
rooms:write/rooms/{roomId}/tabs/{tabId}Supprime un onglet qui n’affiche aucun élément.
rooms:write/rooms/{roomId}/itemsAjoute à un onglet un document, une URL, un contenu intégré ou un séparateur de section.
rooms:writedocuments:write(Required when type is document or url.)/rooms/{roomId}/items/{itemId}Modifier le libellé d’une section, l’URL/les paramètres d’un contenu intégré ou le titre/l’affichage local d’un document. type doit correspondre à l’élément ; titleOverride: null rétablit le titre. Le contenu source et le type restent fixes.
rooms:write/rooms/{roomId}/items/{itemId}/moveDéplace un élément à la fin d’un autre onglet.
rooms:write/rooms/{roomId}/items/orderRéorganise les éléments d’un onglet.
rooms:write/rooms/{roomId}/items/{itemId}Retire un élément de la salle. Il reste dans votre bibliothèque.
rooms:write/rooms/{roomId}/linksListe les liens d'audience de la salle, les plus récents d'abord, avec les invités actifs de chaque lien restreint.
rooms:read/rooms/{roomId}/linksCrée un lien ouvert attribué pour une salle active.
rooms:writecrm:write/rooms/{roomId}/links/{linkId}Active ou désactive un lien, définit ou efface son expiration, ou remplace sa liste d'accès.
rooms:writecrm:write(Required when allowedEmails or allowedDomains is present, including an empty array that clears the audience.)/rooms/{roomId}/links/{linkId}/discussionsLire les discussions de ce lien d’audience. view=overview résume les fils ; view=thread pagine les messages avec anchorType, anchorId et cursor. Les e-mails des auteurs nécessitent crm:read.
rooms:read/rooms/{roomId}/links/{linkId}/discussions/settingsActiver ou désactiver les discussions avec enabled. L’activation nécessite une salle/un lien actifs et la fonctionnalité de discussion. Pour Open ou Verify-any, confirmSharedAudience: true confirme que tous les utilisateurs du lien peuvent lire les échanges. L’historique est conservé.
rooms:write/rooms/{roomId}/action-planRenvoie le plan d'action de la salle : ses paramètres, ses phases, ses tâches (y compris internes), ses dépendances et sa progression.
plan:read/rooms/{roomId}/action-planModifie les paramètres du plan, y compris si les personnes qui ouvrent la salle peuvent cocher leurs propres tâches.
plan:write/rooms/{roomId}/action-plan/phasesAjoute un jalon. Sans color, les phases alternent turquoise, pêche et bleu dans l'ordre.
plan:write/rooms/{roomId}/action-plan/phases/{phaseId}Renomme une phase, la déplace, change sa date ou définit sa couleur. Envoyer color null rétablit la rotation.
plan:write/rooms/{roomId}/action-plan/phases/{phaseId}Supprime une phase. mode est obligatoire : delete_tasks ou move_to_unphased, pour qu'aucune tâche ne disparaisse par accident.
plan:write/rooms/{roomId}/action-plan/tasksAjoute une tâche. assignee vaut null, un side seul pour l'entreprise responsable, ou un side avec email pour une personne précise.
plan:write/rooms/{roomId}/action-plan/tasks/{taskId}Met à jour une tâche. Omettre assignee laisse la responsabilité inchangée ; envoyer null la supprime.
plan:write/rooms/{roomId}/action-plan/tasks/{taskId}Supprime une tâche. Ses sous-tâches partent avec elle.
plan:write/rooms/{roomId}/action-plan/tasks/{taskId}/statusTermine ou rouvre une tâche au nom de l'espace de travail. Une tâche derrière une dépendance inachevée renvoie 409 TASK_BLOCKED.
plan:write/rooms/{roomId}/action-plan/tasks/{taskId}/dependenciesRemplacer toute la liste dependsOnIds ; [] la vide. Les tâches doivent appartenir au plan. Les dépendances sur soi-même et les cycles sont refusés.
plan:write/rooms/{roomId}/action-plan/orderEnvoyer type=phases avec phaseIds ou type=tasks avec placements (id, phaseId, position). Inclure l’ensemble actuel complet, chaque élément une seule fois.
plan:write/action-plan-templatesLister les métadonnées des modèles de l’espace et des modèles publics avec pagination nextCursor. limit vaut 20 par défaut (1–100) ; les curseurs expirent après 15 minutes.
plan:read/rooms/{roomId}/action-plan/templatesEnregistrer ce plan comme modèle privé de l’espace. Envoyer title et éventuellement description ; la structure réutilisable et les décalages de dates relatifs sont conservés.
plan:write/rooms/{roomId}/action-plan/templates/applyEnvoyer templateId et mode=append|replace, avec targetDate facultatif (YYYY-MM-DD). replace supprime les phases/tâches actuelles ; les nouvelles tâches sont incomplètes.
plan:write/rooms/{roomId}/action-plan/calendarExporter une tâche ou phase datée avec type=task|phase et id. Renvoie du texte .ics dans du JSON pour l’importation dans un calendrier.
plan:read/rooms/{roomId}/analyticsVisites de la salle, visiteurs uniques, temps moyen, documents ouverts sur le total et achèvement moyen. Hors robots.
analytics:read/rooms/{roomId}/activityCe qui s'est passé dans la salle, le plus récent d'abord. Les entrées de discussion nomment l'auteur et ne contiennent jamais le message. Restreignez avec since.
analytics:read/rooms/{roomId}/captured-emailsAdresses recueillies par la salle. source vaut verify si la personne l'a confirmée avec un lien d'accès ou un code, et ask si elle l'a seulement saisie.
analytics:read/room-viewsEntrées dans les salles pour tout l'espace de travail, les plus récentes d'abord. Il n'existe pas d'autre source ; /views ne couvre que les vues de documents.
analytics:read/room-labelsListe les libellés de salle de l'espace de travail avec le nombre de salles qui utilisent chacun. C'est ici que vous trouvez les identifiants avant d'étiqueter une salle.
rooms:read/room-labelsCrée un libellé. Les noms sont uniques par espace de travail, sans tenir compte de la casse ; color est une valeur hexadécimale #RRGGBB.
rooms:write/room-labels/{labelId}Renomme un libellé, change sa couleur ou modifie sa description.
rooms:write/room-labels/{labelId}Supprime un libellé et ses affectations. Les salles qui le portaient ne changent pas ; la réponse indique combien l'ont perdu.
rooms:writeCréer une salle en un seul appel
Envoyez chaque fichier avec POST /decks, puis créez la salle pour l’entreprise du destinataire avec un lien restreint pour les personnes qui doivent la voir. L’entreprise, les contacts, la salle, les documents et le lien sont créés ensemble : si l’appel est refusé, rien n’est créé. Les documents peuvent entrer dans la salle pendant leur traitement. Les éléments de la salle indiquent processingStatus : envoyez donc le lien une fois que chaque document indique 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 vaut open (toute personne disposant de l’URL), verify-any (les visiteurs confirment leur adresse e-mail avec un lien d’accès ou un code) ou verified-allowlist (uniquement les adresses de allowedEmails et toute personne dont l’adresse appartient à un domaine de allowedDomains). L’API n’ajoute personne d’elle-même à un lien restreint : incluez votre propre adresse si vous voulez prévisualiser la salle. Une option que votre forfait n’inclut pas renvoie 403 FEATURE_NOT_AVAILABLE, et un champ inconnu renvoie 400 : une salle ne s’ouvre donc jamais à une autre audience que celle demandée.
Organiser les onglets et les éléments
Partez de l’état actuel de la salle : la lecture d’une salle renvoie ses onglets et ses éléments dans l’ordre d’affichage, et chaque élément indique son onglet et sa position dans celui-ci, à partir de 0. Ajoutez des onglets et des éléments à une position donnée, déplacez des éléments entre onglets et envoyez le nouvel ordre complet d’un onglet. Un ordre doit citer chaque élément de l’onglet exactement une fois : relisez donc la salle si une autre modification a eu lieu entre-temps. Un onglet peut être supprimé dès qu’il n’affiche plus aucun élément.
{
"type": "section",
"label": "Commercials",
"tabId": "{tabId}",
"position": 0
}Fournisseurs d'intégration pris en charge
Les intégrations acceptent un lien de partage ou un lien d'intégration et le normalisent vers la forme d'intégration du fournisseur. Tout ce qui sort de cette liste renvoie 400 EMBED_PROVIDER_NOT_SUPPORTED.
| Field | Type | Description |
|---|---|---|
| Vidéo | Loom, YouTube, Vimeo, Wistia, Vidyard, Fireflies | |
| Prise de rendez-vous | Calendly, Cal.com, SavvyCal, Google Calendar | |
| Formulaires | Typeform, Tally, Google Forms, Jotform, Fillout | |
| Design | Figma, Miro, Canva, Whimsical | |
| Documents et tableaux | Google Docs, Google Sheets, Notion, Coda, Airtable | |
| Présentations | Google Slides, Pitch, Gamma, Guideflow, Flipsnack, Prezi | |
| Audio | Spotify, SoundCloud |
Ajouter un autre lien d'audience
Chaque salle possède déjà un lien créé par POST /rooms ; ajoutez-en d'autres pour les audiences qui ont besoin d'une attribution ou d'un accès différents. Fournissez au moins l'un des champs recipientName, recipientEmail, contactId, companyId ou companyName. accessMode accepte les mêmes valeurs open, verify-any ou verified-allowlist que primaryLink, avec les mêmes champs (requireEmail, allowedEmails, allowedDomains, label, expiresAt, allowDownloads). Un appel refusé, y compris par une limite du forfait, ne laisse ni lien, ni entreprise, ni contact.
{
"companyName": "Analytical Engines",
"accessMode": "verified-allowlist",
"allowedEmails": [
{
"email": "cfo@analytical.example",
"name": "Sam Rivera"
}
]
}Modifier un lien
Quatre champs : isActive, expiresAt, allowedEmails, allowedDomains (les deux derniers uniquement sur les liens verified-allowlist). accessMode et le slug ne changent jamais ; créez plutôt un nouveau lien. Réactiver un lien revérifie la limite de liens actifs du forfait.
{
"isActive": false
}Construire le plan d'action
Chaque salle possède exactement un plan, qui se rattache donc à la salle sans identifiant propre. La plupart des tâches appartiennent à une entreprise plutôt qu'à une personne : envoyez un side seul et le plan le lit comme l'entreprise, ce qui convient quand vous ignorez qui fera le travail en face. N'ajoutez un email que si vous connaissez la personne. Une tâche interne n'apparaît jamais dans la salle et ne peut donc pas appartenir au destinataire.
{
"title": "Sign the NDA",
"assignee": {
"side": "buyer"
},
"dueDate": "2026-10-02"
}recipientCompletionEnabled sur le plan décide si les personnes qui ouvrent la salle peuvent cocher les tâches de leur côté. La valeur par défaut est true, et c'est la seule barrière : l'API ne demande jamais l'adresse d'un destinataire pour terminer une tâche. Qui a coché quoi est enregistré au niveau de certitude que permet le mode d'accès de la salle.
Étiqueter les salles
Les libellés valent pour tout l'espace de travail : créez-les une fois et réutilisez-les. Passez labelIds dans POST /rooms pour étiqueter une salle dès sa création, ou dans PATCH /rooms/{roomId} pour remplacer l'ensemble ; un tableau vide retire tous les libellés, et omettre le champ les laisse tels quels. Une salle en porte cinq au maximum, ce qui est structurel et non un réglage. La lecture d'une salle renvoie ses libellés.
{
"labelIds": [
"{labelId}"
]
}Savoir ce qui s'est passé
Interrogez /room-views pour les entrées de tout l'espace de travail, puis lisez les analyses, l'activité et les adresses recueillies d'une salle. Passez le nextCursor d'une page comme cursor pour continuer ; un curseur que cette API n'a pas émis renvoie 400 au lieu de repartir du début, de sorte qu'un scrutateur ne refait jamais le même travail. Utilisez since pour restreindre la période d’activité et cursor pour parcourir ses pages. /room-views est une fenêtre et non une archive : sans since vous obtenez les 30 derniers jours, et au-delà de 90 jours la requête est refusée. La fenêtre appliquée revient dans since ; renvoyez-la avec cursor pour continuer à parcourir le même ensemble.
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.
crm:read/companies/searchRechercher des noms d’entreprises et domaines avec query. Renvoie items et nextCursor ; limit vaut 20 par défaut (1–100). Conserver les filtres entre les pages.
crm:read/companiesRetrouve une entreprise par son nom sans tenir compte de la casse ou la crée. Un domaine explicite enrichit uniquement la fiche.
crm:write/contacts?email={query}Recherche des contacts par adresse e-mail et renvoie les correspondances avec leur entreprise associée.
crm:read/contacts/searchRechercher des noms, adresses e-mail et entreprises avec query ; filtrer éventuellement par companyId. Renvoie items et nextCursor ; limit vaut 20 par défaut (1–100). Conserver les filtres entre les pages.
crm:read/contactsRetrouve ou crée un contact par e-mail et l’associe facultativement à une entreprise.
crm:writeRequê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.
Zapier OAuth uniquement
/hooks/{id}Se désabonner d'un événement par identifiant d'abonnement.
Zapier OAuth uniquement
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
Consulter l’engagement récent sur les documents et les salles. /views, /decisions et /emails permettent l’interrogation périodique des événements ; les endpoints d’engagement, d’activité et de collecte d’e-mails offrent des lectures filtrées et paginées dans la période de conservation du forfait.
/viewsLister les 100 consultations de documents les plus récentes. Les sessions de bots sont exclues.
analytics:read/decisionsLister les décisions récentes sur les propositions (acceptées, refusées, modifications demandées).
analytics:read/emailsLister les captures d'e-mail récentes depuis du contenu protégé.
analytics:read/document-engagementFournir exactement un identifiant parmi documentId, shareId et shareSlug pour les métriques conservées et les visites paginées. includePages nécessite l’analyse par page. Conserver since et les filtres entre les pages.
analytics:read/activityLire les consultations de documents et entrées en salle avec type=all|documents|rooms et les filtres facultatifs documentId, shareId, roomId ou since. Renvoie items et nextCursor. Une entrée en salle ne prouve pas l’ouverture d’un document.
analytics:read/email-capturesview=people regroupe les e-mails enregistrés par audience et document/salle ; view=events liste les visites individuelles. Accepte type, documentId, shareId, roomId, since et cursor. Nécessite analytics:read et crm:read ; la collecte ne vaut pas consentement à un abonnement.
analytics:readcrm:readGestion des erreurs
Chaque erreur renvoie un objet JSON avec un champ error décrivant ce qui n’a pas fonctionné. La plupart des réponses contiennent aussi un champ code pour le traitement programmatique, par exemple PLAN_LIMIT_REACHED, FEATURE_NOT_AVAILABLE, ROOM_NOT_ACTIVE, TAB_NOT_EMPTY, 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 : l’identifiant ne possède pas un scope requis, une limite du forfait est atteinte, le forfait n’inclut pas une option nécessaire, 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 fournis ne correspondent pas, la salle est archivée, ou les onglets de la salle ne permettent pas la modification |
| 413 | Charge utile trop volumineuse : le corps de la requête ou le fichier dépasse la limite de cet endpoint |
| 429 | Trop de requêtes : la clé ou l’IP cliente a dépassé sa limite actuelle ; réessayez après le délai Retry-After |
| 500 | Erreur serveur : réessayez la requête |
Limites de débit
Les clés manuelles d’espace et les connexions OAuth Zapier sont limitées par identifiant : 600 lectures par 5 minutes, 120 écritures par minute, 60 requêtes /room-views par minute et 20 imports par heure. Pour l’ensemble des identifiants, chaque espace est limité à 1 200 lectures par 5 minutes, 240 écritures par minute, 120 requêtes /room-views par minute et 40 imports par heure. Les échecs d’authentification Bearer et les authentifications de client OAuth invalides sont chacun limités à 60 tentatives par 5 minutes et par IP cliente. Maximum 50 abonnements webhook actifs par équipe. /activity et /email-captures partagent le quota de /room-views. Les remplacements de documents partagent le quota d’imports. Une réponse 429 inclut Retry-After.
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.