Bulk attestation guide

Why not the web flow?

• The web flow is rate-limited per IP. ExistBefore enforces ~1 attestation per minute per IP. A nightly batch of 10 000 hashes would take a week — and that's by design, the rate limit is what keeps the public service free.
• The web flow is interactive. Each attestation walks through file selection, hash computation in the browser, PDF generation, download — none of which you need when the hash already exists.
• The web flow has no programmatic output. You get a PDF certificate per attestation. For batch processing you usually want JSON: attestation IDs, T1/T2 status callbacks, machine-parseable evidence bundles. The API gives you that natively.
• Enterprise volume needs SLA-backed callbacks. Polling 10 000 status endpoints to find out when T1 lands is wasteful. With an enterprise contract you get a webhook that notifies your system when each attestation reaches T1 and T2.

CertiSigma SDK (Python).

Iterate over your batch, attest each hash, persist the returned attestation IDs. The SDK handles connection pooling, retries with exponential backoff, and structured error types.

client = CertiSigmaClient(api_key=os.environ["CERTISIGMA_API_KEY"])
result = client.attest_hash(hash_hex)  # Full example loads with JavaScript.

CertiSigma SDK (JavaScript / Node).

The same shape, with native Promise concurrency. Tune the concurrency cap to your contract's rate limit — the SDK will backpressure rather than dropping requests.

const client = new CertiSigmaClient({ apiKey: process.env.CERTISIGMA_API_KEY });
const result = await client.attestHash(hashHex);  // Full example loads with JavaScript.

Census CLI (no API key, public rate limits).

For one-off batches up to a few hundred hashes, the Census CLI is the fastest path. It uses the same public endpoints as ExistBefore (no API key, public IP-based rate limits) and reads hashes from stdin or a file.

census attest --hash YOUR_SHA256_HEX --json  # Full example loads with JavaScript.

Install: pip install certisigma-census or npm install -g @certisigma/census.

Status callbacks (webhooks).

For enterprise contracts, you can register a webhook URL once. Every time an attestation crosses a tier boundary (T0 → T1, T1 → T2), CertiSigma POSTs a signed payload to your endpoint. Your batch-tracking database receives the update without polling.

# Register a webhook (one-time setup, via the developer portal or the API).
curl -X POST https://api.certisigma.ch/webhooks \
  -H "Authorization: Bearer $CERTISIGMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-system.example.com/certisigma-webhook",
    "events": ["attestation.t1_confirmed", "attestation.t2_confirmed"]
  }'

# CertiSigma POSTs to your URL with a signed payload.
# Verify the signature with the public key from /keys/{webhook_signing_key_id}.

Next steps.

• For the SDK and full API reference: developers.certisigma.ch — covers all five endpoints (attest, verify, status, evidence, keys), webhook registration, and SDK installation for every language.
• For an enterprise contract (volume pricing, SLA-backed T1/T2, dedicated keys): /enterprise/ — single email, no form.
• For a developer key without an enterprise contract (pay-as-you-go, public webhooks): /api/ — self-serve.
• To verify a single hash interactively (the original ExistBefore flow): existbefore.com.

FAQ

Can I use the same API key for the SDK and the web flow? No. The web flow uses a server-side proxy key managed by ExistBefore. Your SDK key is yours alone — issued to your organization, scoped to attest, and rate-limited per your contract.

Does the SDK store hashes anywhere? No. The SDK only forwards hashes to the API. Persistence (which hashes you've attested, with what logical IDs) is your responsibility — typically a database column next to the original record.

What happens if the network drops mid-batch? The SDK retries with exponential backoff. After the maximum retry budget, the call raises a structured error you can catch and reconcile later. Idempotency: re-attesting the same hash returns the same attestation ID — never a duplicate.

Can I attest 1 million hashes per day? Yes — but not on the public free rate limit. An enterprise contract sizes the rate limit and SLA to your peak load.