API Referansı

Kimlik Doğrulama

Her API isteği Authorization başlığında bir Bearer token taşır. İki tür kimlik bilgisi kabul edilir ve davranışları farklıdır.

Kimlik bilgisi türleri

İzinler

En az bir izin seçin. Yazma izinleri ilgili okuma erişimini de içerir. Anahtarı değiştirdiğinizde izinleri de değiştirebilirsiniz.

Uç nokta satırlarındaki izin etiketleri çalışma alanı API anahtarları için geçerlidir. Zorunlu izinler her zaman, ek izinler ana izinle birlikte, koşullu izinler ise yalnızca istek ilgili filtreleri veya alanları kullandığında gerekir. GET /me izin gerektirmez. Zapier OAuth sabit entegrasyon erişimini kullanır.

Bir istek 401 döndürdüğünde

Anahtar bilinmiyorsa veya hatalıysa, süresi dolmuşsa, devre dışı bırakılmışsa, API erişimi kapatılmış bir çalışma alanına aitse ya da anahtarı oluşturan kişi artık çalışma alanının sahibi veya yöneticisi değilse istek 401 döndürür.

Bağlantınızı test edin

Token'ınızın geçerli olduğunu doğrulayın ve kimliği doğrulanmış kullanıcının profilini görüntüleyin.

Belgeler

Belgeleri (PDF'ler, slayt destesi, teklifler ve diğer dosyalar) yükleyin, arayın ve yönetin.

GET /decks Yanıt alanları

POST /decks Yanıt alanları

Paylaşım Bağlantıları

İzlenebilir belge bağlantıları oluşturun. Kişisel bir bağlantı, kişiyi ve şirketi aynı istekte bulabilir veya oluşturabilir.

İstek alanları

Bağlantıyı ve hesap kayıtlarını birlikte oluşturun

Alıcı ve şirket bilgilerini doğrudan /shares isteğine ekleyin. HummingDeck eşleşen kayıtları bulur, eksik olanları oluşturur, bağlantıya bağlar ve nelerin oluşturulduğunu bildirir. Hesap oluşturmayı atlamak için type alanını açıkça anonymous yapın.

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

Yanıt alanları

Odalar

Oda yapısını alın ve izlenebilir hedef kitle bağlantıları oluşturun. Yalnızca çalışma alanı API belirteçleriyle kullanılabilir; Zapier OAuth kimlik bilgileri reddedilir.

Tek çağrıda oda oluşturun

Her dosyayı POST /decks ile yükleyin, ardından odayı alıcı tarafın şirketi için, görmesi gereken kişilere açık kısıtlı bir bağlantıyla oluşturun. Şirket, kişiler, oda, belgeler ve bağlantı birlikte oluşturulur: çağrı reddedilirse hiçbiri oluşturulmaz. Belgeler işlenmeye devam ederken odaya eklenebilir. Odanın öğeleri processingStatus bildirdiğinden, bağlantıyı her belge completed okuduğunda gönderin.

{
  "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 değeri open (URL'ye sahip herkes), verify-any (ziyaretçiler e-posta adreslerini tek kullanımlık bağlantıyla doğrular) veya verified-allowlist (yalnızca allowedEmails içindeki adresler ve allowedDomains alan adlarındaki herkes) olabilir. API kısıtlı bir bağlantıya kendiliğinden kimseyi eklemez; odayı önizlemek isterseniz kendi adresinizi de ekleyin. Planınızda bulunmayan bir seçenek 403 FEATURE_NOT_AVAILABLE, bilinmeyen bir alan ise 400 döndürür; böylece bir oda istediğinizden farklı bir kitleye açılmaz.

Sekmeleri ve öğeleri düzenleyin

Odanın şu anki hâlinden başlayın: bir odayı okumak sekmelerini ve öğelerini görüntüleme sırasıyla döndürür ve her öğe hangi sekmede olduğunu ve o sekmedeki sırasını 0'dan sayarak bildirir. Sekmeleri ve öğeleri belirli bir sıraya ekleyin, öğeleri sekmeler arasında taşıyın ve bir sekmenin yeni sırasının tamamını gönderin. Sıralama, sekmedeki her öğeyi tam olarak bir kez listelemelidir; arada başka bir değişiklik olduysa odayı yeniden okuyun. Hiç öğe göstermeyen bir sekme kaldırılabilir.

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

Desteklenen gömme sağlayıcıları

Gömmeler hem paylaşım bağlantısını hem de gömme bağlantısını kabul eder ve sağlayıcının gömme biçimine normalleştirir. Bu listenin dışındaki her şey 400 EMBED_PROVIDER_NOT_SUPPORTED döndürür.

Başka bir hedef kitle bağlantısı ekleyin

Her odanın POST /rooms ile oluşturulmuş bir bağlantısı zaten vardır; farklı atıf veya erişim gerektiren hedef kitleler için yenilerini ekleyin. recipientName, recipientEmail, contactId, companyId veya companyName alanlarından en az birini verin. accessMode, primaryLink ile aynı open, verify-any ve verified-allowlist değerlerini ve aynı alanları alır (requireEmail, allowedEmails, allowedDomains, label, expiresAt, allowDownloads). Plan sınırı dahil, reddedilen bir çağrı geride bağlantı, şirket veya kişi bırakmaz.

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

Bir bağlantıyı güncelleyin

Dört alan: isActive, expiresAt, allowedEmails, allowedDomains (son ikisi yalnızca verified-allowlist bağlantılarında). accessMode ve slug hiç değişmez; bunun yerine yeni bir bağlantı oluşturun. Bir bağlantıyı yeniden açmak, plandaki etkin bağlantı sınırını yeniden denetler.

{
  "isActive": false
}

Eylem planını oluşturun

Her odanın tam olarak bir planı vardır, bu yüzden plan kendi kimliği olmadan odanın altında yer alır. Görevlerin çoğu bir kişiye değil bir şirkete aittir: yalnızca side gönderin, plan bunu şirket olarak okur. Karşı tarafta işi kimin yapacağını bilmediğinizde istediğiniz budur. E-posta adresini yalnızca kişiyi biliyorsanız ekleyin. Dahili bir görev odada hiç görünmez, bu yüzden alıcı tarafına ait olamaz.

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

Plandaki recipientCompletionEnabled, odayı açanların kendi taraflarındaki görevleri işaretleyip işaretleyemeyeceğine karar verir. Varsayılanı true'dur ve tek koşul budur: API bir görevi tamamlamak için alıcının adresini hiçbir zaman istemez. Her görevi kimin işaretlediği, odanın erişim moduna göre sağlanan kesinlikle kaydedilir.

Odaları etiketleyin

Etiketler çalışma alanının tamamında geçerlidir: bir kez oluşturun, tekrar tekrar kullanın. Bir odayı oluştururken etiketlemek için POST /rooms içinde, tüm kümeyi değiştirmek için PATCH /rooms/{roomId} içinde labelIds gönderin; boş bir dizi tüm etiketleri kaldırır, alanı hiç göndermemek ise onları olduğu gibi bırakır. Bir oda en fazla beş etiket taşır; bu bir ayar değil, yapısal bir sınırdır. Bir odayı okumak etiketlerini de döndürür.

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

Ne olduğunu öğrenin

Çalışma alanındaki tüm girişleri görmek için /room-views uç noktasını yoklayın, ardından tek bir odanın analitiğini, etkinliğini ve toplanan adreslerini okuyun. Devam etmek için sayfanın nextCursor değerini cursor olarak gönderin; bu API'nin vermediği bir imleç baştan başlamak yerine 400 döndürür, böylece yoklama aynı işi tekrarlamaz. Etkinlik aralığını since ile daraltın ve sayfalar arasında cursor ile ilerleyin. /room-views bir arşiv değil, zaman penceresidir: since göndermezseniz son 30 günü alırsınız ve 90 günden eski istekler reddedilir. Uygulanan pencere since olarak döner; aynı kümeyi sayfalamaya devam etmek için cursor ile birlikte gönderin.

Şirketler ve Kişiler

Mevcut hesap kayıtlarını bulun veya kesin eşleştirme kurallarıyla oluşturun. Şirket adları ve kişi e-posta adresleri büyük ve küçük harfe duyarlı olmadan eşleştirilir.

POST /companies isteği

POST /contacts isteği

Şirket yanıtı

Kişi yanıtı

Webhook'lar

REST Hooks aracılığıyla gerçek zamanlı olaylara abone olun. Bir olay gerçekleştiğinde, HummingDeck kayıtlı HTTPS URL'nize olay yüküyle birlikte bir POST isteği gönderir. Başarısız teslimler 3 defaya kadar yeniden denenir (1 s, 5 s ve 30 s aralıklarla). Webhook abonelikleri Zapier entegrasyonu tarafından yönetilir ve çalışma alanı API token'ları için kullanılamaz.

Olay türleri

Örnek yükler

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

Görüntülemeler ve Olaylar

Son etkileşim verilerini almak için yoklama uç noktaları. Bunlar, webhook'ların gerçek zamanlı olarak ilettiği aynı verileri döndürür. Geri doldurma, test veya yedek olarak kullanın.

Hata işleme

Her hata, neyin yanlış gittiğini açıklayan bir error alanı içeren JSON nesnesi döndürür. Çoğu yanıt ayrıca PLAN_LIMIT_REACHED, FEATURE_NOT_AVAILABLE, ROOM_NOT_ACTIVE, TAB_NOT_EMPTY, INVALID_FORMAT veya FILE_TOO_LARGE gibi programatik işleme yönelik bir code alanı içerir. HTTP durum kodları standart kurallara uyar.

Hız sınırları

Manuel çalışma alanı anahtarlarına ve Zapier OAuth bağlantılarına kimlik bilgisi başına sınır uygulanır: 5 dakikada 600 okuma, dakikada 120 yazma, dakikada 60 /room-views isteği ve saatte 20 yükleme. Tüm kimlik bilgileri birlikte değerlendirildiğinde çalışma alanı başına sınır; 5 dakikada 1.200 okuma, dakikada 240 yazma, dakikada 120 /room-views isteği ve saatte 40 yüklemedir. Başarısız Bearer kimlik doğrulaması ve geçersiz OAuth istemci kimlik doğrulaması ayrı ayrı istemci IP’si başına 5 dakikada 60 denemeyle sınırlıdır. Ekip başına en fazla 50 etkin webhook aboneliği olabilir.