Diseñado para generar confianzaCifrado TLSConforme al RGPDGoogle CloudPagos segurosVisión general de seguridad
G2

Valorado con 5,0 sobre 5 en G2

Leer las reseñas en G2
The page-level analytics are the best part because they show real engagement instead of just basic opens.
Verified User in Computer Software
What I like most about the product is how easy it is to use, especially when it comes to listing all my links and embedding demos in one place for leads and prospects.
Jerome K.Founder
Responsiveness, configurability and development velocity.
Suman K.Co-Founder & CEO

Referencia de API

HummingDeck expone una API REST para socios de integración y plataformas de automatización. Los endpoints se autentican con un Bearer token y devuelven respuestas JSON.

URL basehttps://app.hummingdeck.com/api/v1
OpenAPI Spec

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.

Método

Bearer token

Formato del encabezado

Authorization: Bearer {access_token}

Tipos de credencial

Token de API del espacio de trabajo

Authorization: Bearer hd_api_...

El acceso a la API REST está incluido en el plan Business de pago. Durante el período de prueba de Business, el acceso se concede previa solicitud. Después, los propietarios y administradores crean claves de API con nombres independientes en Configuración del espacio, Integraciones, HummingDeck API. Selecciona solo los permisos que necesita cada integración. La clave se muestra una sola vez al crearla y después no se puede recuperar. Caduca al año y permanece vinculada a su espacio de trabajo, por lo que una petición no puede elegir ni cambiar el espacio.

Un espacio de trabajo puede tener hasta 20 claves de API activas. Al reemplazar una clave, solo su secreto anterior deja de funcionar de inmediato; las demás claves siguen funcionando. Los propietarios y administradores pueden desactivar una clave o todas en cualquier momento. La revocación de ese secreto es permanente.

Una clave de API del espacio de trabajo solo puede ejecutar las operaciones permitidas por los permisos seleccionados. Los endpoints de suscripción a webhooks no están disponibles para estas claves.

Zapier OAuth

Authorization: Bearer {access_token}

Se emite mediante el flujo de autorización OAuth cuando un espacio de trabajo conecta la integración de Zapier. Los tokens de acceso caducan a los 30 días. Usa el token de actualización, que dura 90 días, para obtener uno nuevo sin volver a autorizar.

Es la única credencial que puede crear o eliminar suscripciones a webhooks.

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.

rooms:read

Ver salas, pestañas, elementos, enlaces y etiquetas.

rooms:write

Crear y gestionar salas, pestañas, elementos, enlaces y etiquetas.

plan:read

Ver fases y tareas del plan de acción mutuo.

plan:write

Crear y gestionar fases y tareas del plan de acción mutuo.

analytics:read

Ver análisis de interacción, actividad y correos capturados.

crm:read

Buscar empresas y contactos del espacio de trabajo.

crm:write

Crear o actualizar empresas, contactos y públicos de enlaces.

documents:read

Buscar documentos y consultar sus metadatos.

documents:write

Subir, reemplazar, renombrar y eliminar documentos; gestionar sus enlaces compartidos y añadir documentos o URL a Rooms.

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.

GET/me

Devuelve el nombre, el correo electrónico y la información del equipo del usuario actual.

No requiere permisos de clave de API

Documentos

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

POST/decks

Sube un nuevo documento. Envíalo como multipart/form-data con un campo file (PDF, PPTX, DOCX, XLSX, XLS, HTML) y un campo title. El límite de carga de la API es de 30 MB. El procesamiento continúa después de la carga; la respuesta incluye processingStatus.

Requerido:documents:write
GET/decks/{deckId}

Obtener los metadatos y el estado de procesamiento de un documento

Requerido:documents:read
PATCH/decks/{deckId}

Renombrar con un cuerpo JSON que contenga title (1–255 caracteres). Se conservan el ID del documento, el archivo y los enlaces.

Requerido:documents:write
DELETE/decks/{deckId}

Marcar el documento como eliminado y desactivar todos sus enlaces. Se conservan los archivos originales y las analíticas históricas. Una propuesta activa devuelve 409 PROPOSAL_LOCKED.

Requerido:documents:write
GET/decks

Lista hasta 20 documentos, primero los más recientes. Usa el parámetro de consulta opcional title para filtrar por una parte del título sin distinguir mayúsculas de minúsculas.

Requerido:documents:read
GET/decks/search

Buscar títulos con query; filtrar por folderId (root para archivos sin carpeta), fileType, createdAfter y createdBefore. sort: created_desc, created_asc o title_asc. Devuelve items y nextCursor; limit es 20 por defecto (1–100). Mantén los filtros y el orden al paginar.

Requerido:documents:read
POST/decks/{deckId}/replace

Sustituye un documento por un archivo local del mismo tipo. Requiere una clave de API del espacio de trabajo con documents:write. Se conservan los enlaces, el título y el modo de entrega. Los archivos con vista previa devuelven pending; los de solo descarga, completed. La respuesta tiene los mismos campos que POST /decks.

Requerido:documents:write

GET /decks Campos de respuesta

FieldTypeDescription
idstringID del documento
titlestringTítulo del documento
fileTypestringTipo MIME del documento
pageCountinteger | nullNúmero de páginas
thumbnailUrlstring | nullURL de la imagen en miniatura
processingStatusstringpending, processing, completed o failed. Un documento puede añadirse a una sala mientras se procesa; envía un enlace a él cuando indique completed.
processingErrorCodestring | nullMotivo por el que falló el procesamiento, si falló
createdAtstringMarca de tiempo ISO 8601

POST /decks Campos de respuesta

FieldTypeDescription
idstringID del documento
titlestringTítulo del documento
fileTypestringTipo MIME del documento
processingStatusstringpending, processing, completed o failed. Un documento puede añadirse a una sala mientras se procesa; envía un enlace a él cuando indique completed.
processingErrorCodestring | nullMotivo por el que falló el procesamiento, si falló

Enlaces de compartición

Crear y gestionar enlaces de documentos con seguimiento. Los ajustes de acceso son independientes de la atribución personal/anonymous; los enlaces personales pueden buscar o crear el contacto y la empresa en la misma petición.

POST/shares

Crear un enlace personal o anónimo con ajustes de acceso, caducidad, descarga y notificaciones. Si se omite access, se usa open.

Requerido:documents:write
Condicional:crm:write(Required for a non-anonymous share when the request supplies contactId, companyId, companyName, recipientEmail, or recipientName.)
GET/shares

Listar enlaces independientes, con filtro opcional por documentId o slug exacto. Devuelve items y nextCursor; limit es 25 por defecto (1–100). Para enlaces de salas, usa los endpoints de enlaces de sala.

Requerido:documents:read
GET/shares/{shareId}

Consultar un enlace independiente, su URL de visualización y sus ajustes de acceso efectivos. Las identidades y direcciones permitidas requieren crm:read.

Requerido:documents:read
PATCH/shares/{shareId}

Editar isActive, allowedEmails, verificationMethod, singleUseLink, expiresAt, allowDownload, notifyOnView o notifySlack. Se conservan el modo de acceso, el documento, type y slug. isActive: false desactiva el enlace.

Requerido:documents:write

Campos de la solicitud

FieldTypeDescription
deckIdstringobligatorioID del documento a compartir
recipientNamestringopcionalNombre del destinatario (para enlaces personales)
recipientEmailstringopcionalCorreo electrónico del destinatario (para enlaces personales)
contactIdUUIDopcionalContacto existente en el espacio de trabajo autenticado
companyIdUUIDopcionalEmpresa existente. No se puede combinar con companyName
companyNamestringopcionalEmpresa que se buscará por nombre o se creará
companyDomainstringopcionalDominio guardado para completar datos cuando se proporciona companyName. Nunca selecciona una empresa
typestringopcionalpersonal o anonymous. Por defecto personal con acceso restricted o datos de destinatario/cuenta; en los demás casos, anonymous.
accessstringopcionalopen (por defecto), ask (recoger correo), verify (verificar cualquier buzón) o restricted (verificar un buzón permitido). La captura de correo y el acceso restringido requieren las funciones correspondientes del plan.
allowedEmailsstring[]condicionalDirecciones exactas para restricted; se requiere una lista no vacía de hasta 100 direcciones. Las reglas de dominio solo se aplican a las salas.
verificationMethodstringopcionalcode o link para verify/restricted.
singleUseLinkbooleanopcionalSi el enlace de acceso enviado por correo es de un solo uso en los modos verificados. Los códigos siempre son de un solo uso.
expiresAtstring | nullopcionalFecha y hora de caducidad ISO 8601, o null sin caducidad.
allowDownloadbooleanopcionalSi los visitantes pueden descargar el documento.
notifyOnViewbooleanopcionalSi se envían notificaciones de visualización por correo.
notifySlackbooleanopcionalSi se envían notificaciones de visualización a Slack.

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

FieldTypeDescription
idstringID del enlace de compartición
slugstringSlug del enlace (usado en la URL)
shareUrlstringURL rastreable completa
typestring"personal" o "anonymous"
recipientNamestringNombre del destinatario (si es personal)
recipientEmailstringCorreo del destinatario (si es personal)
contactobject | nullContacto resuelto y vinculado al enlace
contactCreatedbooleanIndica si esta solicitud ha creado el contacto
companyobject | nullEmpresa resuelta y vinculada al enlace
companyCreatedbooleanIndica si esta solicitud ha creado la empresa
createdAtstringMarca de tiempo ISO 8601

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.

GET/rooms

Lista las salas, de la más reciente a la más antigua. Filtra con search, status (active, archived o all) y companyId. Cada página contiene 25 salas (hasta 100 con limit); pasa el nextCursor de una página como cursor para obtener la siguiente.

Requerido:rooms:read
Condicional:crm:read(Required when the companyId filter is present.)
POST/rooms

Crea una sala con sus documentos y su primer enlace de audiencia en una sola llamada.

Requerido:rooms:write
Condicional:documents: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.)
POST/rooms/{roomId}/duplicate

Copiar a una sala nueva sin empresa ni contacto asignados. Indicar name, includeDocuments, includeActionItems, includeBranding, mapDueDates (keep o clear) y una nueva política primaryLink. No se copian las audiencias, conversaciones ni visitas originales.

Requerido:rooms:write
Condicional:documents:write(Required when includeDocuments is true.)plan:write(Required when includeActionItems is true.)crm:write(Required when primaryLink.allowedEmails or allowedDomains is non-empty.)
GET/rooms/{roomId}

Devuelve la configuración de la sala, sus pestañas y elementos en el orden de visualización, y el número de enlaces.

Requerido:rooms:read
PATCH/rooms/{roomId}

Cambia el nombre, el mensaje de bienvenida, la persona de contacto, la empresa o el contacto.

Requerido:rooms:write
Condicional:crm:write(Required when companyId or contactId is present, including null to detach the association.)
DELETE/rooms/{roomId}

Eliminar permanentemente la sala, el plan, los enlaces, el historial de visitas y las conversaciones. Enviar confirmationName con el nombre actual exacto. Se conservan los documentos de la biblioteca. Usa archive para una limpieza reversible.

Requerido:rooms:write
GET/rooms/{roomId}/appearance

Consulta el color de marca, las fuentes y el diseño de la cabecera guardados. Indica si hay una imagen de cabecera y enumera las fuentes disponibles.

Requerido:rooms:read
PATCH/rooms/{roomId}/appearance

Cambia el color de marca, la fuente de los títulos o del texto, o el diseño de la cabecera. Usa null para restablecer el color o una fuente.

Requerido:rooms:write
PUT/rooms/{roomId}/header-image

Sube o sustituye la imagen de cabecera. Admite JPEG, PNG y WebP de hasta 10 MiB y al menos 1200 × 400 píxeles.

Requerido:rooms:write
DELETE/rooms/{roomId}/header-image

Elimina la imagen de cabecera.

Requerido:rooms:write
POST/rooms/{roomId}/archive

Archiva la sala. Sus enlaces dejan de funcionar.

Requerido:rooms:write
POST/rooms/{roomId}/restore

Restaura una sala archivada. Sus enlaces vuelven a funcionar.

Requerido:rooms:write
POST/rooms/{roomId}/tabs

Añade una pestaña, en una posición concreta o al final.

Requerido:rooms:write
PATCH/rooms/{roomId}/tabs/{tabId}

Cambia el nombre de una pestaña.

Requerido:rooms:write
PUT/rooms/{roomId}/tabs/order

Cambia el orden de todas las pestañas.

Requerido:rooms:write
DELETE/rooms/{roomId}/tabs/{tabId}

Elimina una pestaña que no muestra elementos.

Requerido:rooms:write
POST/rooms/{roomId}/items

Añade a una pestaña un documento, una URL, un contenido incrustado o un separador de sección.

Requerido:rooms:write
Condicional:documents:write(Required when type is document or url.)
PATCH/rooms/{roomId}/items/{itemId}

Editar una etiqueta de sección, la URL/ajustes de un contenido incrustado o el título/presentación local de un documento. type debe coincidir con el elemento; titleOverride: null restablece el título. Se conservan el contenido original y el tipo.

Requerido:rooms:write
POST/rooms/{roomId}/items/{itemId}/move

Mueve un elemento al final de otra pestaña.

Requerido:rooms:write
PUT/rooms/{roomId}/items/order

Cambia el orden de los elementos de una pestaña.

Requerido:rooms:write
DELETE/rooms/{roomId}/items/{itemId}

Saca un elemento de la sala. Sigue en tu biblioteca.

Requerido:rooms:write
GET/rooms/{roomId}/links

Lista los enlaces de audiencia de la sala, los más recientes primero, con los invitados activos de cada enlace restringido.

Requerido:rooms:read
POST/rooms/{roomId}/links

Crea un enlace abierto con atribución para una sala activa.

Requerido:rooms:write
También requerido:crm:write
PATCH/rooms/{roomId}/links/{linkId}

Activa o desactiva un enlace, define o borra su caducidad, o reemplaza su lista de acceso.

Requerido:rooms:write
Condicional:crm:write(Required when allowedEmails or allowedDomains is present, including an empty array that clears the audience.)
GET/rooms/{roomId}/links/{linkId}/discussions

Consultar conversaciones de este enlace de audiencia. view=overview resume hilos; view=thread pagina mensajes con anchorType, anchorId y cursor. Los correos de los autores requieren crm:read.

Requerido:rooms:read
PATCH/rooms/{roomId}/links/{linkId}/discussions/settings

Activar o desactivar las conversaciones con enabled. Activarlas requiere una sala/enlace activos y la función de conversaciones. En Open o Verify-any, confirmSharedAudience: true confirma que todos los usuarios del enlace pueden leerlas. Se conserva el historial.

Requerido:rooms:write
GET/rooms/{roomId}/action-plan

Devuelve el plan de acción de la sala: sus ajustes, fases, tareas (incluidas las internas), dependencias y progreso.

Requerido:plan:read
PATCH/rooms/{roomId}/action-plan

Cambia los ajustes del plan, incluido si quienes abren la sala pueden marcar sus propias tareas.

Requerido:plan:write
POST/rooms/{roomId}/action-plan/phases

Añade un hito. Si omites color, las fases alternan turquesa, melocotón y azul por orden.

Requerido:plan:write
PATCH/rooms/{roomId}/action-plan/phases/{phaseId}

Renombra una fase, la mueve, cambia su fecha o define su color. Enviar color null restaura la rotación.

Requerido:plan:write
DELETE/rooms/{roomId}/action-plan/phases/{phaseId}

Elimina una fase. mode es obligatorio: delete_tasks o move_to_unphased, para que ninguna tarea desaparezca por accidente.

Requerido:plan:write
POST/rooms/{roomId}/action-plan/tasks

Añade una tarea. assignee es null, un side solo para la empresa responsable, o un side con email para una persona concreta.

Requerido:plan:write
PATCH/rooms/{roomId}/action-plan/tasks/{taskId}

Actualiza una tarea. Si omites assignee, la responsabilidad no cambia; enviar null la borra.

Requerido:plan:write
DELETE/rooms/{roomId}/action-plan/tasks/{taskId}

Elimina una tarea. Sus subtareas se van con ella.

Requerido:plan:write
POST/rooms/{roomId}/action-plan/tasks/{taskId}/status

Completa o reabre una tarea en nombre del espacio de trabajo. Una tarea con una dependencia sin terminar devuelve 409 TASK_BLOCKED.

Requerido:plan:write
PUT/rooms/{roomId}/action-plan/tasks/{taskId}/dependencies

Reemplazar la lista completa dependsOnIds; [] la vacía. Las tareas deben pertenecer al plan. Se rechazan las dependencias propias y los ciclos.

Requerido:plan:write
PUT/rooms/{roomId}/action-plan/order

Enviar type=phases con phaseIds o type=tasks con placements (id, phaseId, position). Incluir el conjunto actual completo exactamente una vez.

Requerido:plan:write
GET/action-plan-templates

Listar metadatos de plantillas del espacio y públicas con paginación nextCursor. limit es 20 por defecto (1–100); los cursores caducan a los 15 minutos.

Requerido:plan:read
POST/rooms/{roomId}/action-plan/templates

Guardar este plan como plantilla privada del espacio. Enviar title y, opcionalmente, description; se conservan la estructura reutilizable y los intervalos de fechas relativos.

Requerido:plan:write
POST/rooms/{roomId}/action-plan/templates/apply

Enviar templateId y mode=append|replace, con targetDate opcional (YYYY-MM-DD). replace elimina las fases/tareas actuales; las nuevas comienzan sin completar.

Requerido:plan:write
GET/rooms/{roomId}/action-plan/calendar

Exportar una tarea o fase con fecha mediante type=task|phase e id. Devuelve texto .ics en JSON para importarlo al calendario.

Requerido:plan:read
GET/rooms/{roomId}/analytics

Visitas a la sala, espectadores únicos, tiempo medio, documentos abiertos del total y finalización media. Sin bots.

Requerido:analytics:read
GET/rooms/{roomId}/activity

Lo que ocurrió en la sala, lo más reciente primero. Las entradas de conversación nombran a quien escribió y nunca incluyen el mensaje. Acota con since.

Requerido:analytics:read
GET/rooms/{roomId}/captured-emails

Direcciones que recogió la sala. source es verify si la persona la confirmó con un enlace de acceso o un código, y ask si solo la escribió.

Requerido:analytics:read
GET/room-views

Entradas a salas en todo el espacio de trabajo, las más recientes primero. No hay otra fuente para saber que alguien entró; /views solo cubre vistas de documentos.

Requerido:analytics:read
GET/room-labels

Lista las etiquetas de sala del espacio de trabajo con cuántas salas usa cada una. Aquí encuentras los IDs antes de etiquetar una sala.

Requerido:rooms:read
POST/room-labels

Crea una etiqueta. Los nombres son únicos por espacio de trabajo, sin distinguir mayúsculas; color es un valor hexadecimal #RRGGBB.

Requerido:rooms:write
PATCH/room-labels/{labelId}

Renombra una etiqueta, cambia su color o edita su descripción.

Requerido:rooms:write
DELETE/room-labels/{labelId}

Elimina una etiqueta y sus asignaciones. Las salas que la llevaban no cambian; la respuesta indica cuántas la perdieron.

Requerido:rooms:write

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 dirección de correo con un enlace de acceso o un código) 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.

FieldTypeDescription
VídeoLoom, YouTube, Vimeo, Wistia, Vidyard, Fireflies
AgendamientoCalendly, Cal.com, SavvyCal, Google Calendar
FormulariosTypeform, Tally, Google Forms, Jotform, Fillout
DiseñoFigma, Miro, Canva, Whimsical
Documentos y tablasGoogle Docs, Google Sheets, Notion, Coda, Airtable
PresentacionesGoogle Slides, Pitch, Gamma, Guideflow, Flipsnack, Prezi
AudioSpotify, SoundCloud

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.

GET/companies?name={name}&domain={domain}

Busca hasta 10 empresas por nombre exacto, dominio o ambos.

Requerido:crm:read
GET/companies/search

Buscar nombres de empresas y dominios con query. Devuelve items y nextCursor; limit es 20 por defecto (1–100). Mantén los filtros al paginar.

Requerido:crm:read
POST/companies

Busca una empresa por nombre sin distinguir mayúsculas de minúsculas o la crea. Un dominio explícito solo completa el registro. El campo created identifica el resultado.

Requerido:crm:write
GET/contacts?email={query}

Busca contactos por dirección de correo electrónico. Devuelve contactos coincidentes con su empresa asociada.

Requerido:crm:read
GET/contacts/search

Buscar nombres, correos y empresas con query; filtrar opcionalmente por companyId. Devuelve items y nextCursor; limit es 20 por defecto (1–100). Mantén los filtros al paginar.

Requerido:crm:read
POST/contacts

Busca un contacto por correo o lo crea, con una empresa existente o nueva opcional.

Requerido:crm:write

Solicitud POST /companies

FieldTypeDescription
namestringobligatorioNombre de la empresa
domainstringopcionalDominio de la empresa para completar datos. Nunca se usa para buscar una empresa existente

Solicitud POST /contacts

FieldTypeDescription
namestringcondicionalNombre completo. Usa este campo o firstName y lastName
firstNamestringcondicionalNombre cuando no se proporciona name
lastNamestringopcionalApellido cuando se usa firstName
emailstringobligatorioCorreo usado para buscar sin distinguir mayúsculas de minúsculas
titlestringopcionalCargo
companyIdUUIDopcionalEmpresa existente en el espacio de trabajo autenticado
companyNamestringopcionalEmpresa que se buscará o creará si no se proporciona companyId
companyDomainstringopcionalDominio opcional para completar datos con companyName. No se usa como criterio de búsqueda

Respuesta de empresa

FieldTypeDescription
company.idUUIDID de la empresa
company.namestringNombre de la empresa
company.domainstring | nullDominio normalizado de la empresa
createdbooleanIndica si esta solicitud ha creado la empresa

Respuesta de contacto

FieldTypeDescription
contact.idUUIDID del contacto
contact.firstNamestringNombre
contact.lastNamestringApellido
contact.emailstringDirección de correo electrónico
contact.titlestring | nullCargo
contact.companyIdUUID | nullID de la empresa asociada
contact.companyNamestring | nullNombre de la empresa asociada
createdbooleanIndica si esta solicitud ha creado el contacto
companyobject | nullEmpresa resuelta, si está disponible
companyCreatedbooleanIndica si esta solicitud ha creado la empresa

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.

POST/hooks

Suscribirse a un evento. Requiere una URL HTTPS de destino y un tipo de evento. Devuelve un ID de suscripción.

Solo Zapier OAuth

DELETE/hooks/{id}

Cancelar la suscripción a un evento por ID de suscripción.

Solo Zapier OAuth

Tipos de eventos

EventDescription
view.createdUna persona real vio un documento compartido. El tráfico de bots (escáneres de seguridad de correo electrónico, rastreadores) se filtra automáticamente.
decision.madeUn prospecto respondió a una propuesta: aceptada, rechazada o con cambios solicitados.
email_capturedUn visitante introdujo su dirección de correo electrónico para acceder a contenido protegido.

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

Vistas y eventos

Consultar la actividad reciente en documentos y salas. /views, /decisions y /emails permiten consultar eventos periódicamente; los endpoints de interacción, actividad y captura de correos ofrecen consultas filtradas y paginadas dentro del período de retención del plan.

GET/views

Listar las 100 visualizaciones de documentos más recientes. Las sesiones de bots están excluidas.

Requerido:analytics:read
GET/decisions

Listar las decisiones recientes sobre propuestas (aceptadas, rechazadas, cambios solicitados).

Requerido:analytics:read
GET/emails

Listar las capturas de correo electrónico recientes de contenido protegido.

Requerido:analytics:read
GET/document-engagement

Indicar exactamente uno de documentId, shareId o shareSlug para obtener métricas conservadas y visitas paginadas. includePages requiere analíticas por página. Mantén since y los filtros al paginar.

Requerido:analytics:read
GET/activity

Consultar vistas de documentos y entradas a salas con type=all|documents|rooms y filtros opcionales documentId, shareId, roomId o since. Devuelve items y nextCursor. Entrar en una sala no demuestra que se haya abierto un documento.

Requerido:analytics:read
GET/email-captures

view=people agrupa correos registrados por audiencia y documento/sala; view=events lista visitas individuales. Admite type, documentId, shareId, roomId, since y cursor. Requiere analytics:read y crm:read; la captura no supone consentimiento de suscripción.

Requerido:analytics:read
También requerido:crm:read

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.

StatusMeaning
400Solicitud incorrecta: parámetros faltantes o inválidos
401No autorizado: Bearer token inválido o expirado
403Prohibido: la credencial no tiene un scope necesario, se ha alcanzado un límite del plan, el plan no incluye una opción necesaria, o este tipo de credencial no está permitido en este endpoint
404No encontrado: el recurso no existe o no pertenece a tu equipo
409Conflicto: los identificadores proporcionados no coinciden, la sala está archivada, o las pestañas de la sala no permiten el cambio
413Carga demasiado grande: el cuerpo de la solicitud o el archivo supera el límite de este endpoint
429Demasiadas solicitudes: la clave o la IP cliente superó su límite actual; reinténtalo tras el plazo indicado en Retry-After
500Error del servidor: reintenta la solicitud

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. /activity y /email-captures comparten el cupo de /room-views. Los reemplazos de documentos comparten el cupo de subidas. Una respuesta 429 incluye Retry-After.

Esta API es utilizada actualmente por nuestra integración con Zapier. Es posible que en el futuro se admitan plataformas de integración adicionales.