Batch E-Signature API: How to Send Hundreds of Documents at Scale (2026)

import crypto from "crypto";

export interface BatchContractItem {
  id: string; // Database internal ID
  recipientName: string;
  recipientEmail: string;
  markdownContent: string;
  metadata?: Record<string, any>;
}

export interface BatchDispatchResult {
  successful: Array<{ id: string; documentId: string; signingUrl: string }>;
  failed: Array<{ id: string; error: string }>;
}

export async function executeBatchSigning(
  contracts: BatchContractItem[],
  concurrencyLimit: number = 15,
  delayBetweenChunksMs: number = 750
): Promise<BatchDispatchResult> {
  const successful: BatchDispatchResult["successful"] = [];
  const failed: BatchDispatchResult["failed"] = [];

  const apiKey = process.env.SIGNBEE_API_KEY!;
  const endpoint = "https://signb.ee/api/v1/send";

  // Chunk array into manageable concurrency blocks
  for (let i = 0; i < contracts.length; i += concurrencyLimit) {
    const chunk = contracts.slice(i, i + concurrencyLimit);

    const chunkPromises = chunk.map(async (contract) => {
      // Deterministic idempotency key: prevents double dispatches on retries
      const idempotencyKey = crypto
        .createHash("sha256")
        .update(`${contract.id}-${contract.recipientEmail}`)
        .digest("hex");

      const response = await fetch(endpoint, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${apiKey}`,
          "Idempotency-Key": idempotencyKey,
        },
        body: JSON.stringify({
          markdown: contract.markdownContent,
          recipient_name: contract.recipientName,
          recipient_email: contract.recipientEmail,
          metadata: {
            ...contract.metadata,
            batch_id: "batch_2026_q3_renewals",
            internal_contract_id: contract.id,
          },
        }),
      });

      if (!response.ok) {
        const errorText = await response.text();
        throw new Error(`HTTP ${response.status}: ${errorText}`);
      }

      const data = await response.json();
      return {
        id: contract.id,
        documentId: data.document_id,
        signingUrl: data.signing_url,
      };
    });

    // Promise.allSettled prevents one bad email from terminating the entire batch
    const results = await Promise.allSettled(chunkPromises);

    results.forEach((res, index) => {
      const contract = chunk[index];
      if (res.status === "fulfilled") {
        successful.push(res.value);
      } else {
        failed.push({
          id: contract.id,
          error: res.reason instanceof Error ? res.reason.message : String(res.reason),
        });
      }
    });

    // Rate-limit buffer between chunks to maintain stable socket pool
    if (i + concurrencyLimit < contracts.length) {
      await new Promise((resolve) => setTimeout(resolve, delayBetweenChunksMs));
    }
  }

  return { successful, failed };
}

import asyncio
import httpx
from typing import List, Dict, Any

async def send_single_agreement(client: httpx.AsyncClient, sem: asyncio.Semaphore, item: Dict[str, Any], api_key: str):
    async with sem:
        try:
            res = await client.post(
                "https://signb.ee/api/v1/send",
                headers={"Authorization": f"Bearer {api_key}"},
                json={
                    "markdown": item["markdown"],
                    "recipient_name": item["name"],
                    "recipient_email": item["email"],
                    "metadata": {"batch_id": "batch_annual_nda", "user_id": item["id"]}
                },
                timeout=15.0
            )
            res.raise_for_status()
            data = res.json()
            return {"id": item["id"], "success": True, "document_id": data["document_id"]}
        except Exception as e:
            return {"id": item["id"], "success": False, "error": str(e)}

async def dispatch_all_batch(items: List[Dict[str, Any]], api_key: str, max_concurrent: int = 15):
    sem = asyncio.Semaphore(max_concurrent)
    async with httpx.AsyncClient() as client:
        tasks = [send_single_agreement(client, sem, item, api_key) for item in items]
        results = await asyncio.gather(*tasks)
    return results

-- Master batch record tracking overall progress
CREATE TABLE contract_batches (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    title VARCHAR(255) NOT NULL,
    total_count INT NOT NULL,
    dispatched_count INT DEFAULT 0,
    signed_count INT DEFAULT 0,
    failed_count INT DEFAULT 0,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    completed_at TIMESTAMP WITH TIME ZONE
);

-- Individual items within the batch
CREATE TABLE batch_contracts (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    batch_id UUID REFERENCES contract_batches(id) ON DELETE CASCADE,
    recipient_email VARCHAR(255) NOT NULL,
    recipient_name VARCHAR(255) NOT NULL,
    signbee_document_id VARCHAR(64),
    status VARCHAR(32) DEFAULT 'queued', -- queued, dispatched, signed, failed
    error_message TEXT,
    retry_count INT DEFAULT 0,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    signed_at TIMESTAMP WITH TIME ZONE
);

CREATE INDEX idx_batch_contracts_lookup ON batch_contracts(batch_id, status);
CREATE INDEX idx_batch_signbee_doc ON batch_contracts(signbee_document_id);

export async function redriveFailedBatchContracts(batchId: string) {
  const failedItems = await db.select()
    .from(batchContracts)
    .where(and(
      eq(batchContracts.batchId, batchId),
      eq(batchContracts.status, "failed")
    ));

  console.log(`Found ${failedItems.length} failed agreements to re-drive in batch ${batchId}`);

  // Re-run batch dispatch using standard concurrency limiter
  for (const contract of failedItems) {
    try {
      const res = await sendSingleAgreement(contract);
      await db.update(batchContracts)
        .set({ status: "dispatched", signbeeDocumentId: res.document_id, error_message: null })
        .where(eq(batchContracts.id, contract.id));
    } catch (err: any) {
      await db.update(batchContracts)
        .set({ retry_count: contract.retry_count + 1, error_message: err.message })
        .where(eq(batchContracts.id, contract.id));
    }
  }
}