Verify Attestation

curl --request POST \
  --url https://api.truthlocks.com/v1/verify \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "attestation_id": "660e8400-e29b-41d4-a716-446655440001",
  "payload_b64url": "eyJzdWJqZWN0IjoiZGlkOnRydXRobG9jazoxMjMiLCJ2ZXJpZmllZCI6dHJ1ZX0",
  "document_hash_hex": "a1b2c3d4e5f6..."
}
'

{
  "verdict": "VALID",
  "valid": true,
  "details": {
    "issuer_id": "550e8400-e29b-41d4-a716-446655440000",
    "issuer_name": "Acme University",
    "log_index": 42
  }
}

Verification

Verify Attestation

Performs a full cryptographic and status verification of an attestation.

Verdict Truth Table

Verdict	Valid	Description
VALID	true	Signature correct, attestation active
REVOKED	false	Attestation explicitly revoked
SUPERSEDED	false	Replaced by newer attestation
ALTERED	false	Signature verification failed
UNKNOWN	false	Attestation not found

POST

verify

Verify Attestation

curl --request POST \
  --url https://api.truthlocks.com/v1/verify \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "attestation_id": "660e8400-e29b-41d4-a716-446655440001",
  "payload_b64url": "eyJzdWJqZWN0IjoiZGlkOnRydXRobG9jazoxMjMiLCJ2ZXJpZmllZCI6dHJ1ZX0",
  "document_hash_hex": "a1b2c3d4e5f6..."
}
'

{
  "verdict": "VALID",
  "valid": true,
  "details": {
    "issuer_id": "550e8400-e29b-41d4-a716-446655440000",
    "issuer_name": "Acme University",
    "log_index": 42
  }
}

Performs a comprehensive multi-step verification of an attestation. The pipeline resolves the attestation, checks document integrity, validates status (revoked, superseded, expired), resolves issuer governance metadata, verifies the cryptographic signature against the issuer’s public key, checks the transparency log inclusion proof, and evaluates platform policies. Returns a single verdict with detailed reasons, transparency log data, and full issuer governance context including both current and snapshot-at-mint values. This endpoint is publicly accessible and does not require authentication.

Parameters

attestation_id

string

required

The UUID of the attestation to verify. This is the unique identifier returned when the attestation was originally minted.

payload_b64url

string

Base64url-encoded payload for signature verification. If provided, the system verifies that the SHA-256 hash of this payload matches the stored payload_hash. Use this to confirm you hold the exact original content that was attested.

document_hash_hex

string

SHA-256 hex hash of the original document for integrity verification. If provided, compared against the stored document_hash. Use this when you want to verify a file’s integrity without sending the full payload over the wire. The comparison is case-insensitive.

Document hash verification

When you include document_hash_hex in your verification request, the platform compares it against the document_hash stored at mint time. Two additional reason codes may appear in the reasons array of the response:

Reason	Verdict	Description
`document_hash_mismatch`	`ALTERED`	The provided hash does not match the stored document hash. The content has been modified since it was protected.
`document_hash_not_stored`	(continues verification)	The attestation was minted without a document hash, so the check cannot be performed. Verification continues with signature and log checks.

The document_hash is set automatically during minting. The platform resolves it from three sources in priority order: an embedded claims.document.sha256 in the payload, an explicit document_hash field in the mint request, or an auto-computed SHA-256 of the payload bytes.

Verdict reference

Every verification request returns exactly one verdict value.

Verdict	Description
`VALID`	Cryptographically valid and trusted
`ALTERED`	Document hash mismatch — the content has been modified
`REVOKED`	Explicitly revoked by the issuer
`SUPERSEDED`	A newer version of this attestation exists. Follow `superseded_by_attestation_id` in the response to find the replacement.
`EXPIRED`	The attestation has passed its validity period
`INVALID`	Cryptographic signature verification failed
`NOT_FOUND`	No attestation exists with the given ID
`UNKNOWN_ISSUER`	The issuer could not be resolved or is no longer trusted

Superseded attestations

When an attestation has been replaced by a newer version, the verdict is SUPERSEDED and the response includes a superseded_by_attestation_id field pointing to the replacement. Use this to follow the version chain:

{
  "verdict": "SUPERSEDED",
  "superseded_by_attestation_id": "880e8400-e29b-41d4-a716-446655440003",
  "reasons": ["attestation_superseded"]
}

To verify the latest version, make a second request using the superseded_by_attestation_id value as the attestation_id.

Billing and rate limits

API verification requests are metered against your organization’s billing plan. The consumer portal at verify.truthlocks.com provides unlimited free verification for end-users.

Channel	Auth required	Metered	Rate limit
`POST /v1/verify` (API)	No	Yes — counted against the issuer’s plan quota	Plan-dependent
verify.truthlocks.com (Portal)	No	No — free and unlimited	Fair-use rate limiting only

When the issuer’s API verification quota is exhausted, the endpoint returns HTTP 402 with the BILLING_LIMIT error code. Upgrade your plan or wait for the quota to reset at the start of the next billing cycle.

402 — Quota exhausted

{
  "code": "BILLING_LIMIT",
  "message": "API verification quota exhausted for the current billing cycle. Upgrade your plan or use the free consumer portal at verify.truthlocks.com.",
  "http_status": 402
}

For most use cases, share a verification link instead of calling the API directly. Portal verifications are free and provide a rich UI with issuer branding, governance details, and document integrity checks.Verification link format: https://verify.truthlocks.com/a/{attestation_id}

Authorizations

X-API-Key

string

header

required

API key for machine-to-machine authentication

Body

application/json

attestation_id

string<uuid>

required

The unique identifier of the attestation to verify.

payload_b64url

string

document_hash_hex

string

SHA-256 hex hash of the original document for integrity verification. If provided, compared against the stored document_hash. Use this when you want to verify a file's integrity without sending the full payload over the wire.

Response

200 - application/json

Verification result

verdict

enum<string>

VALID: Signature verified and attestation is active
REVOKED: Attestation was explicitly revoked
SUPERSEDED: Attestation replaced by a newer version
ALTERED: Signature verification failed (tampered)
INVALID: General validation failure
UNKNOWN: Attestation not found

Available options:

VALID,

INVALID,

REVOKED,

ALTERED,

SUPERSEDED,

UNKNOWN

valid

boolean

details

object

Show child attributes

List velocity anomalies List Verification Packs

​Parameters

​Document hash verification

​Verdict reference

​Superseded attestations

​Billing and rate limits

Authorizations

Body

Response

Parameters

Document hash verification

Verdict reference

Superseded attestations

Billing and rate limits