Referência da API

Autenticação

Cada pedido à API leva um Bearer token no cabeçalho Authorization. São aceites dois tipos de credencial, e comportam-se de forma diferente.

Tipos de credencial

Permissões

Escolha pelo menos uma permissão. As permissões de escrita também incluem o acesso de leitura correspondente. Pode alterar as permissões quando substituir a chave.

Os rótulos de permissão nas linhas dos endpoints aplicam-se às chaves de API do espaço de trabalho. As permissões obrigatórias aplicam-se sempre, as adicionais são necessárias em conjunto e as condicionais apenas quando o pedido usa os filtros ou campos relacionados. GET /me não requer permissão. O Zapier OAuth usa o acesso fixo da integração.

Quando um pedido devolve 401

Um pedido devolve 401 quando a chave é desconhecida ou inválida, expirou, foi desativada, pertence a um espaço com o acesso à API desativado ou foi emitida por alguém que já não é proprietário nem administrador desse espaço.

Teste sua conexão

Verifique se seu token é válido e consulte o perfil do usuário autenticado.

Documentos

Envie, pesquise e gerencie documentos (PDFs, apresentações, propostas e outros arquivos).

GET /decks Campos da resposta

POST /decks Campos da resposta

Links de compartilhamento

Crie links rastreáveis para documentos. Um link pessoal pode localizar ou criar seu contato e sua empresa na mesma requisição.

Campos da requisição

Crie o link e os registros da conta juntos

Envie os dados do destinatário e da empresa diretamente para /shares. O HummingDeck localiza registros correspondentes, cria os que faltam, associa-os ao link e informa o que foi criado. Defina type explicitamente como anonymous para não criar registros da conta.

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

Campos da resposta

Salas

Crie salas de negociação com seus documentos e o link de público em uma única chamada, encontre salas, altere as configurações, arquive e restaure salas, e organize suas abas e itens. Disponível apenas com tokens de API do espaço de trabalho; as credenciais OAuth do Zapier são rejeitadas.

Criar uma sala em uma única chamada

Envie cada arquivo com POST /decks e depois crie a sala para a empresa do destinatário com um link restrito para as pessoas que devem vê-la. A empresa, os contatos, a sala, os documentos e o link são criados juntos: se a chamada for recusada, nada é criado. Os documentos podem entrar na sala enquanto ainda estão sendo processados. Os itens da sala informam processingStatus, então envie o link quando todos os documentos estiverem como 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 é open (qualquer pessoa com a URL), verify-any (os visitantes confirmam o e-mail com um link de uso único) ou verified-allowlist (somente os endereços em allowedEmails e qualquer pessoa dos domínios em allowedDomains). A API não adiciona ninguém a um link restrito por conta própria, então inclua o seu endereço se quiser visualizar a sala antes. Uma opção que o seu plano não inclui retorna 403 FEATURE_NOT_AVAILABLE, e um campo desconhecido retorna 400, para que uma sala nunca se abra para um público diferente do que você pediu.

Organizar abas e itens

Parta da sala como ela está agora: ao ler uma sala, você recebe as abas e os itens na ordem de exibição, e cada item informa sua aba e sua posição nela, contando a partir de 0. Adicione abas e itens em uma posição, mova itens entre abas e envie a nova ordem completa de uma aba. Uma ordem precisa listar cada item da aba exatamente uma vez, então leia a sala de novo se outra alteração tiver acontecido nesse meio-tempo. Uma aba pode ser removida quando não mostra mais nenhum item.

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

Provedores de incorporação suportados

Os embeds aceitam um link de compartilhamento ou de incorporação e o normalizam para a forma de incorporação do provedor. Qualquer coisa fora desta lista retorna 400 EMBED_PROVIDER_NOT_SUPPORTED.

Adicionar outro link de público

Cada sala já tem um link criado por POST /rooms; adicione mais para públicos que precisam de outra atribuição ou outro acesso. Informe pelo menos um entre recipientName, recipientEmail, contactId, companyId ou companyName. accessMode aceita os mesmos valores open, verify-any ou verified-allowlist de primaryLink, com os mesmos campos (requireEmail, allowedEmails, allowedDomains, label, expiresAt, allowDownloads). Uma chamada recusada, inclusive por limite do plano, não deixa nenhum link, empresa ou contato.

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

Atualizar um link

Quatro campos: isActive, expiresAt, allowedEmails e allowedDomains (os dois últimos apenas em links verified-allowlist). accessMode e o slug nunca mudam; crie um link novo. Reativar um link verifica de novo o limite de links ativos do plano.

{
  "isActive": false
}

Montar o plano de ação

Cada sala tem exatamente um plano, por isso ele fica sob a sala sem identificador próprio. A maioria das tarefas pertence a uma empresa e não a uma pessoa: envie apenas um side e o plano o lê como a empresa, que é o que você quer quando não sabe quem fará o trabalho do outro lado. Acrescente um email só quando souber quem é a pessoa. Uma tarefa interna nunca aparece na sala, então não pode pertencer ao destinatário.

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

recipientCompletionEnabled no plano decide se quem abre a sala pode marcar as tarefas do próprio lado. O padrão é true e é a única barreira: a API nunca pede o endereço de um destinatário para concluir uma tarefa. Quem marcou cada uma fica registrado com a certeza que o modo de acesso da sala permite.

Etiquetar salas

As etiquetas valem para todo o espaço de trabalho: crie uma vez e reutilize. Envie labelIds em POST /rooms para etiquetar uma sala já na criação, ou em PATCH /rooms/{roomId} para substituir o conjunto inteiro; um array vazio remove todas as etiquetas e omitir o campo as mantém. Uma sala carrega no máximo cinco, o que é estrutural e não uma configuração. Ler uma sala retorna suas etiquetas.

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

Saber o que aconteceu

Consulte /room-views para ver as entradas em todo o espaço de trabalho e depois leia a analítica, a atividade e os endereços recolhidos de uma sala. Passe o nextCursor de uma página como cursor para continuar; um cursor que esta API não emitiu devolve 400 em vez de recomeçar, para que a consulta não repita trabalho. Use since para restringir a janela de atividade e cursor para percorrer as páginas. /room-views é uma janela, não um arquivo: sem since recebe os últimos 30 dias, e pedidos com mais de 90 dias são recusados. A janela aplicada volta como since; envie-a com cursor para continuar a percorrer o mesmo conjunto.

Empresas e contatos

Localize registros de conta existentes ou crie novos com correspondência determinística. Nomes de empresas e e-mails de contatos são comparados sem diferenciar maiúsculas de minúsculas.

Requisição POST /companies

Requisição POST /contacts

Resposta da empresa

Resposta do contato

Webhooks

Assine eventos em tempo real por meio de REST Hooks. Quando um evento ocorre, o HummingDeck envia uma requisição POST para sua URL HTTPS registrada com o payload do evento. As entregas com falha são repetidas até 3 vezes (com intervalos de 1 s, 5 s e 30 s). As subscrições de webhooks são geridas pela integração Zapier e não estão disponíveis para tokens de API do espaço de trabalho.

Tipos de eventos

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

Visualizações e eventos

Endpoints de polling para recuperar dados de engajamento recentes. Eles retornam os mesmos dados que os webhooks entregam em tempo real. Use-os para preenchimento retroativo, testes ou como alternativa.

Tratamento de erros

Cada erro retorna um objeto JSON com um campo error que descreve o que deu errado. A maioria das respostas também inclui um campo code para tratamento programático, como PLAN_LIMIT_REACHED, FEATURE_NOT_AVAILABLE, ROOM_NOT_ACTIVE, TAB_NOT_EMPTY, INVALID_FORMAT ou FILE_TOO_LARGE. Os códigos de status HTTP seguem as convenções habituais.

Limites de taxa

As chaves manuais do espaço e as ligações OAuth Zapier têm limites por credencial: 600 leituras a cada 5 minutos, 120 escritas por minuto, 60 pedidos a /room-views por minuto e 20 carregamentos por hora. No conjunto de todas as credenciais, cada espaço está limitado a 1 200 leituras a cada 5 minutos, 240 escritas por minuto, 120 pedidos a /room-views por minuto e 40 carregamentos por hora. As falhas de autenticação Bearer e as autenticações inválidas de cliente OAuth estão separadamente limitadas a 60 tentativas a cada 5 minutos por IP cliente. Máximo de 50 assinaturas de webhook ativas por equipa.