Verify Hash API

Public endpoint to verify that a document's validation hash is authentic. This endpoint does not require authentication and is designed to be called by anyone who has a document hash (e.g., printed on the document footer).

Verify Hash

GET /functions/v1/verify-hash?hash=<validation-hash>

Query Parameters

Parameter	Type	Required	Description
hash	string	Yes	The SHA-256 validation hash to verify

Example Request

curl "https://<project-ref>.supabase.co/functions/v1/verify-hash?hash=a1b2c3d4e5f6789..."

Response (Verified — 200)

{
  "verified": true,
  "validation_hash": "a1b2c3d4e5f6789...",
  "timestamp": "2026-04-13T10:00:00Z",
  "rules_summary": {
    "layers": [
      {
        "name": "Schema Validation",
        "status": "passed"
      },
      {
        "name": "Business Rules",
        "status": "passed"
      }
    ]
  },
  "documents_generated": ["COMMERCIAL_INVOICE", "PACKING_LIST"],
  "route": {
    "origin_country": "US",
    "destination_country": "DE"
  },
  "message": "This document was validated on 4/13/2026 and has not been modified since."
}

Response (Not Found — 404)

{
  "verified": false,
  "message": "This hash is not recognized. The document may have been altered or the hash is invalid."
}

Response Fields

Field	Type	Description
verified	boolean	true if the hash matches a known validation record
validation_hash	string	The hash that was verified (echoed back)
timestamp	string	ISO 8601 timestamp of when validation occurred
rules_summary	object	Summary of the validation layers and their results
documents_generated	array	List of document types generated from this validation
route.origin_country	string	Country of origin (ISO 3166-1 alpha-2)
route.destination_country	string	Destination country (ISO 3166-1 alpha-2)
message	string	Human-readable verification message

Error Codes

HTTP Status	Error Code	Description
400	KLV_VAL_001	hash query parameter is required

Usage

The verification hash is embedded in the footer of every generated document. Recipients can verify document authenticity by:

1. Scanning the QR code on the document (which encodes the verification URL)
2. Visiting https://klervex.com/verify/<hash>
3. Or calling this API endpoint directly

A verified: true response confirms that:

• The document was generated by Klervex
• The shipment data passed validation at the stated timestamp
• The document has not been modified since generation