← Back to home

checksum

Sign In

API Reference

Proof and verify document endpoints

Use the proof endpoint to create an integrity-stamped PDF and the verify endpoint to confirm a signed document matches the stored checksum.

Authentication endpoints

Clients first obtain a JWT from the auth service, then send it as a Bearer token on protected requests.

Public

POST /api/auth/token

curl -X POST "https://api.checksum.id/api/auth/token"   -H "Content-Type: application/json"   -d '{"email":"user@example.com","password":"your-password"}'

Token request

200 OK

  • { "token": "<jwt>", "tokenType": "Bearer", "expiresInSeconds": 3600 }
  • Send email + password to receive a bearer token for subsequent protected API calls.

Protected calls

Authorization header

  • Authorization: Bearer <jwt>
  • Use the returned JWT on all proof-document requests and other authenticated endpoints.

Authenticated

POST /api/proofDocument

Requires JWT

Accepts a PDF, computes a checksum, stores a signed record, and returns a proofed copy for download.

curl -X POST "https://api.checksum.id/api/proofDocument"   -H "Authorization: Bearer $TOKEN"   -H "X-Verify-Base-Url: https://app.checksum.id/verify"   -F "file=@contract.pdf"   -F "position=top-right"   -F "format=qr"

Request

multipart/form-data

  • file — required PDF to proof
  • position — optional: top-left, top-center, top-right, bottom-left, bottom-center, bottom-right
  • format — optional: qr or uuid
  • X-Verify-Base-Url — optional absolute URL used inside the stamped verification payload

Success

200 OK

  • Returns the proofed PDF file as a download.
  • The file is stamped with a verification marker and includes response headers for auditing.

Error states

400, 403, 422

  • 400 — file missing or unreadable
  • 403 — usage quota reached or access blocked
  • 422 — uploaded file is not a valid PDF

Response headers

  • Content-Disposition: attachment; filename=contract-proofed.pdf
  • X-Document-Id: <uuid>
  • X-Document-Checksum: <sha256>
  • X-Document-Checksum-Algorithm: SHA-256
  • X-Document-Signed-By: user@example.com
  • X-Document-Signed-On: 2026-03-14T12:34:56Z

Authenticated

POST /api/verifyDocument

Requires JWT

Accepts a proofed PDF, extracts the embedded document identifier, recomputes the hash, and compares it against the on-file registry.

curl -X POST "https://api.checksum.id/api/verifyDocument"   -H "Authorization: Bearer <jwt>"   -F "file=@proofed-contract.pdf"

Request

multipart/form-data

  • file — required proofed PDF to verify

Success

200 OK

  • { "result": "matches", "signedBy": "user@example.com", "signedOn": "2026-03-14T12:34:56Z" }

Mismatch

409 Conflict

  • { "result": "does not match", "signedBy": "user@example.com", "signedOn": "2026-03-14T12:34:56Z" }

Validation failures

404, 422

  • 404 — the embedded document id is unknown to the registry
  • 422 — the PDF does not contain an embedded checksum id