Dokumentacja API
HummingDeck udostępnia REST API dla partnerów integracyjnych i platform automatyzacji. Punkty końcowe uwierzytelniają się tokenem Bearer i zwracają odpowiedzi JSON.
https://app.hummingdeck.com/api/v1Uwierzytelnianie
Każde żądanie do API przesyła token Bearer w nagłówku Authorization. Akceptowane są dwa rodzaje poświadczeń i działają one inaczej.
Metoda
Token Bearer
Format nagłówka
Authorization: Bearer {access_token}
Rodzaje poświadczeń
Token API przestrzeni roboczej
Authorization: Bearer hd_api_...
Wydawany przez właściciela przestrzeni roboczej w Ustawieniach przestrzeni, Integracje, HummingDeck API. W ramach zamkniętego pilotażu dostępny tylko dla wybranych przestrzeni. Token jest pokazywany jeden raz przy tworzeniu i później nie można go odzyskać. Wygasa rok po utworzeniu i jest na stałe powiązany z przestrzenią, dla której go wydano, więc żądanie nie może wybrać ani zmienić swojej przestrzeni roboczej.
Utworzenie tokenu, gdy jeden już istnieje, zastępuje go, a poprzedni natychmiast przestaje działać. Właściciel może wyłączyć token w dowolnym momencie. Dla tego tokenu jest to nieodwracalne: zamiast liczyć na przywrócenie, utwórz nowy.
Endpointy subskrypcji webhooków nie są dostępne dla tokenów API przestrzeni roboczej.
Zapier OAuth
Authorization: Bearer {access_token}
Wydawany przez proces autoryzacji OAuth, gdy przestrzeń robocza łączy integrację Zapier. Tokeny dostępu wygasają po 30 dniach. Użyj tokenu odświeżania, ważnego 90 dni, aby uzyskać nowy bez ponownej autoryzacji.
To jedyne poświadczenia, które mogą tworzyć i usuwać subskrypcje webhooków.
Kiedy żądanie zwraca 401
Żądanie jest odrzucane z kodem 401, gdy token jest nieznany lub nieprawidłowy, wygasł, został wyłączony, należy do przestrzeni roboczej z wyłączonym dostępem do API albo został wydany przez osobę, która nie jest już właścicielem tej przestrzeni.
Przetestuj połączenie
Sprawdź, czy Twój token jest ważny, i wyświetl profil uwierzytelnionego użytkownika.
/meZwraca imię i nazwisko, adres e-mail oraz informacje o zespole bieżącego użytkownika.Dokumenty
Przesyłaj, wyszukuj i zarządzaj dokumentami (plikami PDF, prezentacjami, propozycjami i innymi plikami).
/decksPrześlij nowy dokument. Wyślij jako multipart/form-data z polem file (PDF, PPTX, DOCX, XLSX, HTML) i polem title. Limit przesyłania przez API wynosi 30 MB./decks?title={query}Wyszukaj dokumenty według tytułu. Wyszukiwanie bez rozróżniania wielkości liter, zwraca do 20 wyników.Pola odpowiedzi
| Field | Type | Description |
|---|---|---|
| id | string | Identyfikator dokumentu |
| title | string | Tytuł dokumentu |
| fileType | string | Typ pliku (pdf, pptx, docx, html) |
| pageCount | number | Liczba stron |
| thumbnailUrl | string | URL miniatury |
| createdAt | string | Znacznik czasu ISO 8601 |
Pokoje
Pobieraj strukturę pokoju i twórz śledzone linki dla odbiorców. Funkcja jest dostępna tylko z tokenami API obszaru roboczego; dane uwierzytelniające OAuth Zapier są odrzucane.
/rooms/{roomId}Zwraca metadane, karty, elementy oraz liczbę aktywnych i wszystkich linków pokoju./rooms/{roomId}/linksTworzy przypisany otwarty link do aktywnego pokoju.Utwórz otwarty link do pokoju
Podaj co najmniej jedno z pól: recipientName, recipientEmail, contactId, companyId lub companyName. Imię i adres e-mail wyszukują lub tworzą kontakt, a pola firmy wyszukują lub tworzą firmę. Każda osoba mająca URL może otworzyć taki link.
{
"accessMode": "open",
"recipientName": "Ada Lovelace",
"recipientEmail": "ada@analytical.example",
"companyName": "Analytical Engines"
}Firmy i kontakty
Znajdź istniejące rekordy konta lub utwórz nowe z jednoznacznym dopasowaniem. Nazwy firm i adresy e-mail kontaktów są porównywane bez rozróżniania wielkości liter.
/companies?name={name}&domain={domain}Wyszukuje firmy według dokładnej nazwy i opcjonalnej domeny./companiesZnajduje firmę według nazwy bez rozróżniania wielkości liter lub ją tworzy. Jawna domena jedynie wzbogaca rekord./contacts?email={query}Wyszukuje kontakty według adresu e-mail i zwraca dopasowania wraz z powiązaną firmą./contactsZnajduje lub tworzy kontakt według adresu e-mail i opcjonalnie łączy go z firmą.Żądanie POST /companies
| Field | Type | Description | |
|---|---|---|---|
| name | string | wymagane | Nazwa firmy |
| domain | string | opcjonalne | Domena używana do wzbogacenia danych firmy. Nigdy nie służy do dopasowania istniejącej firmy |
Żądanie POST /contacts
| Field | Type | Description | |
|---|---|---|---|
| name | string | warunkowe | Pełne imię i nazwisko. Wymagane, jeśli brak firstName |
| firstName | string | warunkowe | Imię. Wymagane, jeśli brak name |
| lastName | string | opcjonalne | Nazwisko |
| string | wymagane | Adres e-mail używany do jednoznacznego dopasowania | |
| title | string | opcjonalne | Stanowisko |
| companyId | UUID | opcjonalne | Istniejąca firma w uwierzytelnionym obszarze roboczym |
| companyName | string | opcjonalne | Nazwa firmy do znalezienia lub utworzenia |
| companyDomain | string | opcjonalne | Opcjonalna domena do wzbogacenia danych używana z companyName. Nie jest kluczem dopasowania firmy |
Odpowiedź firmy
| Field | Type | Description |
|---|---|---|
| company.id | UUID | Identyfikator firmy |
| company.name | string | Nazwa firmy |
| company.domain | string | null | Znormalizowana domena firmy |
| created | boolean | true, jeśli żądanie POST utworzyło firmę |
Odpowiedź kontaktu
| Field | Type | Description |
|---|---|---|
| contact.id | UUID | Identyfikator kontaktu |
| contact.firstName | string | Imię |
| contact.lastName | string | Nazwisko |
| contact.email | string | Znormalizowany adres e-mail |
| contact.title | string | null | Stanowisko |
| contact.companyId | UUID | null | Identyfikator powiązanej firmy |
| contact.companyName | string | null | Nazwa powiązanej firmy |
| created | boolean | true, jeśli żądanie POST utworzyło kontakt |
| company | object | null | Ustalona firma, jeśli jest dostępna |
| companyCreated | boolean | true, jeśli to żądanie utworzyło firmę |
Webhooki
Subskrybuj zdarzenia w czasie rzeczywistym za pomocą REST Hooks. Gdy wystąpi zdarzenie, HummingDeck wysyła żądanie POST na zarejestrowany adres HTTPS z ładunkiem zdarzenia. Nieudane dostarczenia są ponawiane do 3 razy (po 1 s, 5 s i 30 s). Subskrypcje webhooków są zarządzane przez integrację Zapier i nie są dostępne dla tokenów API przestrzeni roboczej.
/hooksSubskrybuj zdarzenie. Wymaga docelowego adresu HTTPS i typu zdarzenia. Zwraca identyfikator subskrypcji./hooks/{id}Anuluj subskrypcję zdarzenia na podstawie identyfikatora subskrypcji.Typy zdarzeń
| Event | Description |
|---|---|
| view.created | Prawdziwa osoba obejrzała udostępniony dokument. Ruch botów (skanery bezpieczeństwa e-mail, crawlery) jest automatycznie filtrowany. |
| decision.made | Potencjalny klient odpowiedział na propozycję: zaakceptował, odrzucił lub poprosił o zmiany. |
| email_captured | Odwiedzający podał swój adres e-mail, aby uzyskać dostęp do treści z bramką. |
Przykładowe ładunki
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"
}
}Wyświetlenia i zdarzenia
Punkty końcowe pollingu do pobierania ostatnich danych zaangażowania. Zwracają te same dane, które webhooki dostarczają w czasie rzeczywistym. Używaj ich do uzupełniania danych, testowania lub jako rezerwę.
/viewsWyświetl 100 ostatnich wyświetleń dokumentów. Sesje botów są wykluczone./decisionsWyświetl ostatnie decyzje dotyczące propozycji (zaakceptowane, odrzucone, poproszone o zmiany)./emailsWyświetl ostatnie przechwycenia e-maili z treści z bramką.Obsługa błędów
Każdy błąd zwraca obiekt JSON z polem error opisującym, co poszło nie tak. Niektóre odpowiedzi zawierają też pole code do obsługi programistycznej, na przykład PLAN_LIMIT_REACHED, INVALID_FORMAT lub FILE_TOO_LARGE. Kody stanu HTTP są zgodne z przyjętymi konwencjami.
| Status | Meaning |
|---|---|
| 400 | Nieprawidłowe żądanie: brakujące lub nieprawidłowe parametry |
| 401 | Brak autoryzacji: nieprawidłowy lub wygasły Bearer token |
| 403 | Zabronione: osiągnięto limit planu albo ten rodzaj poświadczeń nie jest dozwolony w tym punkcie końcowym |
| 404 | Nie znaleziono: zasób nie istnieje lub nie należy do Twojego zespołu |
| 409 | Konflikt: podane identyfikatory kontaktu, adresu e-mail i firmy nie są zgodne |
| 500 | Błąd serwera: ponów żądanie |
Limity liczby żądań
Maksymalnie 50 aktywnych subskrypcji webhooków na zespół. Żądania API nie są ograniczone, ale nadmierne użycie może być ograniczane.
To API jest obecnie używane przez naszą integrację Zapier. W przyszłości mogą być obsługiwane dodatkowe platformy integracyjne.