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

Permisos

Elige al menos un permiso. Los permisos de escritura también incluyen el acceso de lectura correspondiente. Puedes cambiar los permisos cuando reemplaces la clave.

Las etiquetas de permisos en las filas de endpoints se aplican a las claves de API del espacio de trabajo. Los permisos requeridos se aplican siempre, los adicionales se necesitan a la vez y los condicionales solo cuando la solicitud usa los filtros o campos relacionados. GET /me no necesita permisos. Zapier OAuth usa su acceso fijo de integración.

Cuando una petición devuelve 401

Una petición devuelve 401 si la clave es desconocida o incorrecta, ha caducado, se ha desactivado, pertenece a un espacio de trabajo cuyo acceso a la API se desactivó o fue emitida por alguien que ya no es propietario ni administrador 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).

GET /decks Campos de respuesta

POST /decks 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

Crea salas de negociación con sus documentos y su enlace de audiencia en una sola llamada, busca salas, cambia su configuración, archívalas y restáuralas, y organiza sus pestañas y elementos. Solo está disponible con tokens de API del espacio de trabajo; las credenciales OAuth de Zapier se rechazan.

Crear una sala en una sola llamada

Sube cada archivo con POST /decks y luego crea la sala para la empresa del destinatario con un enlace restringido para las personas que deben verla. La empresa, los contactos, la sala, los documentos y el enlace se crean a la vez: si se rechaza la llamada, no se crea nada. Los documentos pueden añadirse a la sala mientras se siguen procesando. Los elementos de la sala indican processingStatus, así que envía el enlace cuando todos los documentos indiquen 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 es open (cualquiera con la URL), verify-any (los visitantes confirman su correo con un enlace de un solo uso) o verified-allowlist (solo las direcciones de allowedEmails y cualquier persona de los dominios de allowedDomains). La API no añade a nadie por su cuenta a un enlace restringido, así que incluye tu propia dirección si quieres ver la sala antes. Una opción que tu plan no incluye devuelve 403 FEATURE_NOT_AVAILABLE, y un campo desconocido devuelve 400, de modo que una sala nunca se abre a una audiencia distinta de la que pediste.

Organizar pestañas y elementos

Parte del estado actual de la sala: al leer una sala se obtienen sus pestañas y elementos en el orden de visualización, y cada elemento indica su pestaña y su posición en ella, empezando por 0. Añade pestañas y elementos en una posición, mueve elementos entre pestañas y envía el nuevo orden completo de una pestaña. Un orden debe incluir cada elemento de la pestaña exactamente una vez, así que vuelve a leer la sala si mientras tanto se produjo otro cambio. Una pestaña se puede eliminar cuando ya no muestra elementos.

{
  "type": "section",
  "label": "Commercials",
  "tabId": "{tabId}",
  "position": 0
}

Proveedores de inserción admitidos

Los embeds aceptan un enlace para compartir o un enlace de inserción y lo normalizan a la forma de inserción del proveedor. Cualquier cosa fuera de este conjunto devuelve 400 EMBED_PROVIDER_NOT_SUPPORTED.

Añadir otro enlace de audiencia

Cada sala ya tiene un enlace creado por POST /rooms; añade más para audiencias que necesiten otra atribución u otro acceso. Indica al menos uno de recipientName, recipientEmail, contactId, companyId o companyName. accessMode admite los mismos valores open, verify-any o verified-allowlist que primaryLink, con los mismos campos (requireEmail, allowedEmails, allowedDomains, label, expiresAt, allowDownloads). Una llamada rechazada, incluso por un límite del plan, no deja ningún enlace, empresa ni contacto.

{
  "companyName": "Analytical Engines",
  "accessMode": "verified-allowlist",
  "allowedEmails": [
    {
      "email": "cfo@analytical.example",
      "name": "Sam Rivera"
    }
  ]
}

Actualizar un enlace

Cuatro campos: isActive, expiresAt, allowedEmails y allowedDomains (los dos últimos solo en enlaces verified-allowlist). accessMode y el slug nunca cambian; crea un enlace nuevo en su lugar. Reactivar un enlace vuelve a comprobar el límite de enlaces activos del plan.

{
  "isActive": false
}

Construir el plan de acción

Cada sala tiene exactamente un plan, así que cuelga de la sala sin identificador propio. La mayoría de las tareas pertenecen a una empresa y no a una persona: si envías solo un side, el plan lo interpreta como la empresa, que es lo que quieres cuando no sabes quién hará el trabajo al otro lado. Añade un email solo cuando conozcas a la persona. Una tarea interna nunca se ve en la sala, así que no puede pertenecer al destinatario.

{
  "title": "Sign the NDA",
  "assignee": {
    "side": "buyer"
  },
  "dueDate": "2026-10-02"
}

recipientCompletionEnabled en el plan decide si quienes abren la sala pueden marcar las tareas de su lado. Por defecto es true y es la única barrera: la API nunca pide la dirección de un destinatario para completar una tarea. Quién marcó cada una se registra con la certeza que dé el modo de acceso de la sala.

Etiquetar salas

Las etiquetas son de todo el espacio de trabajo: créalas una vez y reutilízalas. Envía labelIds en POST /rooms para etiquetar una sala al crearla, o en PATCH /rooms/{roomId} para reemplazar el conjunto completo; un array vacío quita todas las etiquetas y omitir el campo las deja intactas. Una sala lleva como máximo cinco, algo estructural y no una preferencia. Al leer una sala se devuelven sus etiquetas.

{
  "labelIds": [
    "{labelId}"
  ]
}

Saber qué ocurrió

Consulta /room-views para ver las entradas de todo el espacio de trabajo y luego lee las analíticas, la actividad y las direcciones capturadas de una sala. Pasa el nextCursor de una página como cursor para continuar; un cursor que esta API no emitió devuelve 400 en lugar de empezar de nuevo, así un consultor periódico no repite trabajo. Usa since para acotar el periodo de actividad y cursor para recorrer sus páginas. /room-views es una ventana, no un archivo histórico: sin since obtienes los últimos 30 días, y más de 90 días atrás se rechaza. La ventana aplicada vuelve como since; envíala junto a cursor para seguir paginando el mismo conjunto.

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. La mayoría de las respuestas incluyen además un campo code para el tratamiento programático, como PLAN_LIMIT_REACHED, FEATURE_NOT_AVAILABLE, ROOM_NOT_ACTIVE, TAB_NOT_EMPTY, INVALID_FORMAT o FILE_TOO_LARGE. Los códigos de estado HTTP siguen las convenciones habituales.

Límites de velocidad

Las claves manuales del espacio y las conexiones OAuth de Zapier tienen límites por credencial: 600 lecturas cada 5 minutos, 120 escrituras por minuto, 60 solicitudes a /room-views por minuto y 20 subidas por hora. En el conjunto de todas las credenciales, cada espacio admite 1.200 lecturas cada 5 minutos, 240 escrituras por minuto, 120 solicitudes a /room-views por minuto y 40 subidas por hora. Los fallos de autenticación Bearer y la autenticación no válida del cliente OAuth se limitan por separado a 60 intentos cada 5 minutos por IP cliente. Máximo 50 suscripciones de webhook activas por equipo.