Справочник API

Аутентификация

Каждый запрос к API передаёт Bearer-токен в заголовке Authorization. Принимаются два типа учётных данных, и ведут они себя по-разному.

Типы учётных данных

Разрешения

Выберите хотя бы одно разрешение. Разрешения на запись также включают соответствующий доступ на чтение. Разрешения можно изменить при замене ключа.

Метки разрешений в строках эндпоинтов относятся к API-ключам рабочего пространства. Обязательные разрешения нужны всегда, дополнительные — вместе с основным, а условные — только когда запрос использует связанные фильтры или поля. GET /me не требует разрешений. Zapier OAuth использует фиксированный доступ интеграции.

Когда запрос возвращает 401

Запрос возвращает 401, если ключ неизвестен или некорректен, истёк, был отключён, принадлежит рабочему пространству с выключенным доступом к API или был выпущен человеком, который больше не является владельцем или администратором этого пространства.

Проверить подключение

Убедитесь, что ваш токен действителен, и просмотрите профиль аутентифицированного пользователя.

Документы

Загружайте, ищите и управляйте документами (PDF-файлы, презентации, коммерческие предложения и другие файлы).

GET /decks Поля ответа

POST /decks Поля ответа

Ссылки для совместного доступа

Создавайте отслеживаемые ссылки на документы. Персональная ссылка может найти или создать контакт и компанию в том же запросе.

Поля запроса

Создайте ссылку и записи компании вместе

Передайте сведения о получателе и компании прямо в /shares. HummingDeck найдёт совпадающие записи, создаст недостающие, привяжет их к ссылке и сообщит, что было создано. Явно задайте type как anonymous, чтобы пропустить создание записей компании.

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

Поля ответа

Комнаты

Создавайте комнаты для сделок с документами и ссылкой для аудитории одним вызовом, находите комнаты, меняйте их настройки, архивируйте и восстанавливайте их, упорядочивайте вкладки и элементы. Доступно только с API-токенами рабочего пространства; учётные данные Zapier OAuth отклоняются.

Создание комнаты одним вызовом

Загрузите каждый файл через POST /decks, а затем создайте комнату для компании получателя с ограниченной ссылкой для тех, кто должен её видеть. Компания, контакты, комната, документы и ссылка создаются вместе: если вызов отклонён, не создаётся ничего. Документы можно добавить в комнату, пока они ещё обрабатываются. Элементы комнаты сообщают processingStatus, поэтому отправляйте ссылку, когда у каждого документа статус 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 (любой, у кого есть URL), verify-any (посетители подтверждают адрес электронной почты одноразовой ссылкой) или verified-allowlist (только адреса из allowedEmails и все, у кого адрес на доменах из allowedDomains). API само никого не добавляет к ограниченной ссылке, поэтому укажите свой адрес, если хотите заранее посмотреть комнату. Параметр, которого нет в вашем тарифе, возвращает 403 FEATURE_NOT_AVAILABLE, а неизвестное поле возвращает 400, поэтому комната никогда не откроется не той аудитории, которую вы указали.

Упорядочивание вкладок и элементов

Начните с текущего состояния комнаты: при чтении комнаты её вкладки и элементы возвращаются в порядке отображения, и каждый элемент сообщает свою вкладку и позицию в ней, считая с 0. Добавляйте вкладки и элементы в нужную позицию, перемещайте элементы между вкладками и отправляйте полный новый порядок вкладки. Порядок должен содержать каждый элемент вкладки ровно один раз, поэтому прочитайте комнату заново, если за это время произошло другое изменение. Вкладку можно удалить, когда в ней больше нет элементов.

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

Поддерживаемые источники встраивания

Встраивания принимают и ссылку для доступа, и ссылку для встраивания, приводя её к формату провайдера. Всё, чего нет в этом списке, возвращает 400 EMBED_PROVIDER_NOT_SUPPORTED.

Добавить ещё одну ссылку для аудитории

У каждой комнаты уже есть ссылка, созданная через POST /rooms; добавляйте новые для аудиторий, которым нужна другая атрибуция или другой доступ. Укажите хотя бы одно из полей recipientName, recipientEmail, contactId, companyId или companyName. accessMode принимает те же значения open, verify-any и verified-allowlist, что и primaryLink, с теми же полями (requireEmail, allowedEmails, allowedDomains, label, expiresAt, allowDownloads). Отклонённый вызов, в том числе из-за ограничения тарифа, не оставляет ни ссылки, ни компании, ни контакта.

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

Обновить ссылку

Четыре поля: isActive, expiresAt, allowedEmails, allowedDomains (последние два только у ссылок verified-allowlist). accessMode и слаг не меняются; создайте новую ссылку. Повторное включение ссылки заново проверяет лимит активных ссылок в тарифе.

{
  "isActive": false
}

Собрать план действий

У каждой комнаты ровно один план, поэтому он подключается к комнате без собственного идентификатора. Большинство задач принадлежит компании, а не человеку: отправьте один side, и план прочитает его как компанию. Именно это нужно, когда неизвестно, кто выполнит работу на другой стороне. Добавляйте email, только если знаете конкретного человека. Внутренняя задача никогда не видна в комнате, поэтому она не может принадлежать стороне получателя.

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

Поле recipientCompletionEnabled в плане решает, могут ли открывшие комнату отмечать задачи своей стороны. По умолчанию true, и это единственное условие: API никогда не требует адрес получателя, чтобы завершить задачу. Кто именно отметил задачу, записывается с той достоверностью, которую даёт режим доступа комнаты.

Помечать комнаты метками

Метки действуют во всём рабочем пространстве: создайте их один раз и используйте повторно. Передайте labelIds в POST /rooms, чтобы пометить комнату при создании, или в PATCH /rooms/{roomId}, чтобы заменить весь набор; пустой массив снимает все метки, а если поле не передано, они не меняются. Комната несёт не более пяти меток — это структурное ограничение, а не настройка. При чтении комнаты её метки возвращаются вместе с ней.

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

Узнать, что произошло

Запрашивайте /room-views, чтобы видеть входы по всему рабочему пространству, а затем читайте аналитику, активность и собранные адреса конкретной комнаты. Чтобы получить следующую страницу, передайте её nextCursor как cursor; курсор, который этот API не выдавал, возвращает 400 вместо перехода к началу, поэтому опрос не повторяет работу. Сужайте окно активности параметром since и переходите между страницами с помощью cursor. /room-views представляет временное окно, а не архив: без since возвращаются последние 30 дней, а запросы более чем за 90 дней отклоняются. Применённое окно возвращается в поле since; отправляйте его вместе с cursor, чтобы продолжать листать тот же набор.

Компании и контакты

Находите существующие записи или создавайте их по однозначным правилам сопоставления. Названия компаний и адреса электронной почты контактов сопоставляются без учёта регистра.

Запрос POST /companies

Запрос POST /contacts

Ответ с компанией

Ответ с контактом

Webhook

Подписывайтесь на события в реальном времени через REST Hooks. При возникновении события HummingDeck отправляет POST-запрос на зарегистрированный HTTPS-адрес с данными события. При сбое доставки выполняется до 3 повторных попыток (через 1 с, 5 с и 30 с). Подписки на вебхуки управляются интеграцией Zapier и недоступны для токенов API рабочего пространства.

Типы событий

Примеры данных

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

Просмотры и события

Эндпоинты для опроса последних данных о вовлечённости. Они возвращают те же данные, что webhook передаёт в реальном времени — используйте их для ретроспективного заполнения, тестирования или в качестве запасного варианта.

Обработка ошибок

Каждая ошибка возвращает JSON-объект с полем error, описывающим, что пошло не так. Большинство ответов также содержит поле code для программной обработки, например PLAN_LIMIT_REACHED, FEATURE_NOT_AVAILABLE, ROOM_NOT_ACTIVE, TAB_NOT_EMPTY, INVALID_FORMAT или FILE_TOO_LARGE. HTTP-коды статусов соответствуют общепринятым соглашениям.

Ограничения запросов

Для ручных ключей рабочего пространства и подключений Zapier OAuth действуют лимиты на учётные данные: 600 чтений за 5 минут, 120 операций записи в минуту, 60 запросов /room-views в минуту и 20 загрузок в час. Для всех учётных данных рабочего пространства вместе лимиты составляют 1 200 чтений за 5 минут, 240 операций записи в минуту, 120 запросов /room-views в минуту и 40 загрузок в час. Ошибки Bearer-аутентификации и недействительная аутентификация клиента OAuth отдельно ограничены 60 попытками за 5 минут для каждого IP клиента. Не более 50 активных webhook-подписок на команду.