Referencia de API

Autenticación

Cada petición a la API lleva un Bearer token en la cabecera Authorization. Se aceptan dos tipos de credencial, y se comportan de forma distinta.

Tipos de credencial

Cuando una petición devuelve 401

Una petición se rechaza con 401 cuando el token es desconocido o incorrecto, ha caducado, se ha desactivado, pertenece a un espacio de trabajo cuyo acceso a la API se ha desactivado, o lo emitió alguien que ya no es propietario de ese espacio.

Prueba tu conexión

Verifica que tu token es válido y consulta el perfil del usuario autenticado.

Documentos

Sube, busca y gestiona documentos (PDFs, presentaciones, propuestas y otros archivos).

Campos de respuesta

Enlaces de compartición

Crea enlaces rastreables para documentos. Un enlace personal puede resolver o crear su contacto y empresa en la misma solicitud.

Campos de la solicitud

Crea el enlace y los registros de cuenta a la vez

Envía los datos del destinatario y de la empresa directamente a /shares. HummingDeck busca registros coincidentes, crea los que faltan, los vincula al enlace e indica cuáles se han creado. Define type como anonymous para omitir la creación de cuentas.

{
  "deckId": "8f3d41de-2bb8-4d8e-80de-6cd2072ffab1",
  "recipientName": "Ada Lovelace",
  "recipientEmail": "ada@analytical.example",
  "companyName": "Analytical Engines",
  "companyDomain": "analytical.example"
}

Campos de respuesta

Salas

Consulta la estructura de una sala y crea enlaces de audiencia con seguimiento. Solo está disponible con tokens de API del espacio de trabajo; las credenciales OAuth de Zapier se rechazan.

Crear un enlace abierto para una sala

Indica al menos uno de estos campos: recipientName, recipientEmail, contactId, companyId o companyName. El nombre o correo busca o crea un contacto; los campos de empresa buscan o crean una empresa. Un enlace abierto permite acceder a cualquiera que tenga la URL.

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

Empresas y contactos

Busca registros de cuenta existentes o créalos con coincidencias deterministas. Los nombres de empresa y los correos de contacto no distinguen mayúsculas de minúsculas.

Solicitud POST /companies

Solicitud POST /contacts

Respuesta de empresa

Respuesta de contacto

Webhooks

Suscríbete a eventos en tiempo real mediante REST Hooks. Cuando ocurre un evento, HummingDeck envía una solicitud POST a tu URL HTTPS registrada con el payload del evento. Las entregas fallidas se reintentan hasta 3 veces (a intervalos de 1 s, 5 s y 30 s). Las suscripciones a webhooks las gestiona la integración de Zapier y no están disponibles para los tokens de API del espacio de trabajo.

Tipos de eventos

Ejemplos de payloads

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

Vistas y eventos

Endpoints de sondeo para recuperar datos de interacción recientes. Devuelven los mismos datos que entregan los webhooks en tiempo real. Úsalos para rellenar histórico, hacer pruebas o como alternativa.

Manejo de errores

Cada error devuelve un objeto JSON con un campo error que describe qué ha fallado. Algunas respuestas incluyen además un campo code para el tratamiento programático, como PLAN_LIMIT_REACHED, INVALID_FORMAT o FILE_TOO_LARGE. Los códigos de estado HTTP siguen las convenciones habituales.

Límites de velocidad

Máximo 50 suscripciones de webhook activas por equipo. Las solicitudes de API no tienen límite de velocidad, pero un uso excesivo puede ser limitado.