Référence API
HummingDeck expose une API REST pour les partenaires d'intégration et les plateformes d'automatisation. Tous les endpoints utilisent l'authentification OAuth 2.0 et renvoient des réponses JSON.
https://app.hummingdeck.com/api/v1Authentification
Toutes les requêtes API nécessitent un Bearer token OAuth 2.0 valide dans l'en-tête Authorization. Les tokens sont émis lors du flux d'autorisation OAuth et expirent après 30 jours. Utilisez le token de rafraîchissement (expiration 90 jours) pour obtenir un nouveau token d'accès sans avoir à réautoriser.
Méthode
OAuth 2.0 (Bearer token)
Format de l'en-tête
Authorization: Bearer {access_token}
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, HTML) et un champ title./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 |
Contacts
Recherchez des contacts dans le carnet d'adresses de votre équipe.
/contacts?email={query}Rechercher des contacts par adresse e-mail. Renvoie les contacts correspondants avec leur entreprise associée.Champs de réponse
| Field | Type | Description |
|---|---|---|
| id | string | Identifiant du contact |
| firstName | string | Prénom |
| lastName | string | Nom de famille |
| string | Adresse e-mail | |
| title | string | Intitulé du poste |
| leadName | string | Nom de l'entreprise |
| createdAt | string | Horodatage ISO 8601 |
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).
/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
Toutes les erreurs renvoient un objet JSON avec un champ message. Les codes de statut HTTP suivent les conventions standard.
| Status | Meaning |
|---|---|
| 400 | Requête incorrecte — paramètres manquants ou invalides |
| 401 | Non autorisé — Bearer token invalide ou expiré |
| 404 | Introuvable — la ressource n'existe pas ou n'appartient pas à votre équipe |
| 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.