Docs
Trustedcopy API
Register the documents you issue, and verify documents you receive. The structure below is final; live calls and keys open with the engine launch.
Overview
Trustedcopy is a rail. An issuer registers a document at the moment it's produced; anyone who later receives it can verify it against that registration. The issuer earns each time one of their documents is verified.
- Register at issuance — dashboard upload, one API call, or the self-hosted SDK.
- Verify anywhere — the recipient submits the document; the rail returns a verdict.
- Issuer earns — every resolved verification pays the issuer at the price they set.
Register once, verifiable forever. A registered document proves itself anywhere, indefinitely — no re-registration, no expiry. Trustedcopy retains only an irreversible fingerprint, never the document or its contents.
POST /v1/register
Submit a document to register it. Registration is asynchronous: the call returns a registry_id and a processing status immediately, and a registration.completed webhook fires when the fingerprint is committed and the stamped document is ready.
POST /v1/register Authorization: Bearer tc_live_… Idempotency-Key: "a1b2c3" Content-Type: application/pdf → 202 Accepted { "registry_id": "TC-4X8K2", "status": "processing", "stamped_document_url": "…" }
POST /v1/verify
Submit a received document to verify it. Returns one of the four verdicts below. The document is processed only to verify it, then immediately discarded — only the verification result is retained.
POST /v1/verify Authorization: Bearer tc_live_… Content-Type: application/pdf → 200 OK { "verdict": "authenticated_original", "issuer": "Hartwell Insurance Agency", "registered": "2026-03-03" }
Registration handshake (local fingerprinting)
For the self-hosted SDK, documents never leave your environment. Registration uses a three-step handshake so the fingerprint is computed locally and only the fingerprint is committed:
- Intent — your system declares an intent to register and receives a short-lived client token.
- Client token — the SDK computes the irreversible fingerprint locally, inside your environment.
- Commit — only the fingerprint (never the document) is committed to the registry against your account.
On this tier, documents never leave your systems — the one place that claim holds.
Webhooks
Subscribe an endpoint to receive signed event payloads. Verify the signature with the endpoint's signing secret (revealed once, rotatable).
registration.completed— a document finished registering; stamped file ready.registration.failed— a document couldn't be registered (e.g., unreadable capture).verification.resolved— a verification against your registry resolved.payout.sent— a payout was sent to your connected account.
Ramp & rate limits
A newly-activated issuer registers on a ramp — up to 250 registrations/day during the first weeks, lifting to full capacity on a stated date or as registration history builds. This is never a mystery limit: the ceiling and the date are shown on your dashboard, and exceeding it returns a clear, actionable response.
POST /v1/register → 429 Too Many Requests { "error": "ramp_limit_reached", "message": "Daily registration ramp of 250 reached. Full capacity on Aug 12 or as your history builds.", "retry_after": 43200 }
Back off until retry_after (seconds) elapses, or contact us if your launch needs a higher starting ramp. Established issuers have no ramp.
Keys & idempotency
Every request is authenticated with an API key. Test keys never touch the live registry.
All POST requests accept an Idempotency-Key header — safely retry a request without double-registering or double-charging.
Verdicts
Verification returns exactly one of four verdicts. The language is deliberate: the system affirms authenticity; it never accuses.
authenticated_original — matched to a registered original. Returns issuer name, document type, and registration date.unable_to_authenticate — no match to a registered original. This is not a determination that the document is inauthentic.not_registered — the document isn't registered with Trustedcopy. No charge for this check.unreadable — the capture couldn't be read clearly enough to check. Re-capture is free.See the public verification page for how these appear to recipients.