Skip to main content
POST
/
v1
/
truth
/
document
/
verify
Verify Document Truth
curl --request POST \
  --url https://api.truthlocks.com/v1/truth/document/verify \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "document_hash": "<string>",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "claim_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'
{
  "verification_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "document_hash": "<string>",
  "status": "pending",
  "results": [
    {}
  ],
  "verifications": [
    {}
  ],
  "claims": [
    {
      "claim_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "claim_type": "<string>",
      "payload": {},
      "evidence": [
        {}
      ],
      "status": "pending",
      "receipt_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "attestations": [
        {
          "attestation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "witness_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "claim_hash": "<string>",
          "signature": "<string>",
          "status": "pending",
          "created_at": "2023-11-07T05:31:56Z"
        }
      ],
      "verified_at": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z"
}
Submits a document to the verification pipeline for automated AI analysis followed by optional human review. The platform extracts content, computes integrity hashes, runs anomaly detection, and produces a verification determination. Documents are processed asynchronously. The response includes a document_id that you can use to poll for results via the Get Document endpoint, or subscribe to the document.verified webhook event. The platform supports PDF, images (PNG, JPEG, TIFF), and structured data files (JSON, XML). Maximum file size is 50 MB after base64 encoding.

​
Authentication

Requires X-API-Key header or Bearer JWT token. Tenant-scoped via X-Tenant-ID.

​
Request Body

​
agent_id
string
required
The identifier of the agent submitting the document for verification. Must be registered and active within the tenant. Format: maip-agent:ULID.
​
document_type
string
Classification of the document. Helps the AI pipeline select the appropriate extraction model. Common values: - contract — legal contracts and agreements - invoice — financial invoices - certificate — certificates, licenses, or credentials - report — compliance or audit reports - identity — identity documents (passport, driver’s license) - other — unclassified documents
​
file_name
string
Original file name with extension. Used for display and to infer content type when not explicitly set.
​
document_hash
string
Client-computed SHA-256 hex digest of the original file bytes (before base64 encoding). If provided, the platform verifies the hash matches the uploaded content. Recommended for integrity assurance.
​
document_b64
string
required
The document content as a base64-encoded string. Maximum 50 MB after encoding.

​
Response

​
document_id
string
Unique identifier for the document verification record. Format: maip-doc:ULID.
​
status
string
Initial processing status. Always processing on submission.
​
extraction_hash
string
The platform-computed SHA-256 hex digest of the uploaded document bytes.
​
created_at
string
ISO 8601 timestamp of when the document was submitted.

​
Processing Pipeline

1

Upload and Hash

Document is received, decoded, and SHA-256 hashed. If document_hash was provided, it is validated against the computed hash.
2

AI Extraction

Content is extracted using OCR and document understanding models. Key fields are identified based on document_type.
3

Anomaly Detection

AI models scan for signs of tampering, forgery, inconsistencies, and metadata anomalies.
4

AI Verdict

An automated determination is produced with a confidence score.
5

Human Review (optional)

If confidence is below threshold or the document type requires it, the document is routed to a human reviewer.
6

Receipt Minted

A MAIP receipt is minted recording the final verification determination.
The document_b64 field must contain only the base64-encoded document content. Do not include data URI prefixes (e.g., data:application/pdf;base64,).

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Body

application/json
​
document_hash
string
required

SHA-256 hash of the document

​
agent_id
string<uuid>
required

Requesting agent

​
claim_ids
string<uuid>[]

Specific claims to verify against

Response

Document verification result

​
verification_id
string<uuid>
​
document_id
string<uuid>
​
document_hash
string
​
status
enum<string>
Available options:
pending,
verified,
failed
​
results
object[]
​
verifications
object[]
​
claims
object[]
​
created_at
string<date-time>