Document Validate Service (`DOCUMENTTRUST_VALIDATE`)

Document validation without authority lookup: OCR extraction → format / expiry / cross-field checks → PASS / REVIEW / FAIL decision.

Use this when you only need to verify that a document image is readable and the extracted fields look valid — without calling FRSC, PVC, Passport, or NIN authority APIs.

Related: Document Trust Service (includes authority reconciliation) · Full API Guide

Quick reference

Item	Value
Service SKU	`DOCUMENTTRUST_VALIDATE`
Method	`POST`
Path	`/api/v1/document/validate`
Content-Type	`multipart/form-data`
Billed	Yes — every completed session (including `FAIL` decisions)
Auth	Institution secret API key

What it does

Uploads the document image to OCR and extracts identity fields.
Runs classification, format, expiry, and cross-field checks.
Skips all government authority reconciliation.
Returns decision, trustScore, per-check breakdown, and audit evidence.

Authority-related checks appear as skipped in the checks array. The response does not include authorityData.

Request

Form fields

Field	Type	Required	Default	Description
`documentImage`	file	Yes	—	Front of document (photo or scan)
`documentImageBack`	file	No	—	Back of document (stored for audit; not used in OCR v1)
`docType`	string	No	`auto`	Document type hint (see below)
`customerReference`	string	No	—	Your internal customer or case reference

`docType` values

Value	Document
`auto`	Auto-detect
`passport`	International Passport
`drivers_license`	Driver's Licence
`voters_card`	Permanent Voter's Card (PVC)
`nin_slip`	NIN Slip

Example request

curl -X POST "https://api.dikript.com/api/v1/document/validate" \
  -H "X-Dikript-Api-Key: YOUR_SECRET_KEY" \
  -F "documentImage=@nin_slip.jpg" \
  -F "docType=nin_slip" \
  -F "customerReference=CUST-002"

Example response

{
  "status": true,
  "message": "Successful",
  "code": "200",
  "transactionRef": "N202608121200005678",
  "apiVersion": "v1",
  "data": {
    "sessionId": "b2c3d4e5f678901234567890abcdef12",
    "customerReference": "CUST-002",
    "decision": "PASS",
    "trustScore": 0.88,
    "mode": "validate",
    "docTypeRequested": "nin_slip",
    "docTypeDetected": "nin_slip",
    "processedAtUtc": "2026-08-12T11:00:00Z",
    "processingDurationMs": 3100,
    "summary": {
      "headline": "Document passed validation checks.",
      "checksPassed": 8,
      "checksFailed": 0,
      "checksReview": 0,
      "checksSkipped": 4
    },
    "checks": [
      {
        "code": "DOC_CLASSIFICATION",
        "category": "classification",
        "status": "pass",
        "message": "Document classified as nin slip.",
        "confidence": 0.92
      },
      {
        "code": "NIN_FORMAT_VALID",
        "category": "format",
        "status": "pass",
        "message": "NIN format is valid.",
        "confidence": 0.98
      },
      {
        "code": "AUTHORITY_RECORD_FOUND",
        "category": "authorityReconcile",
        "status": "skipped",
        "message": "Authority reconciliation skipped in validate mode.",
        "confidence": null
      }
    ],
    "extractedData": {
      "documentType": "nin_slip",
      "fields": {
        "fullName": "JANE DOE",
        "nin": "12345678901"
      }
    },
    "audit": {
      "auditRef": "b2c3d4e5f678901234567890abcdef12",
      "evidenceRetentionUntilUtc": "2033-08-12T11:00:00Z",
      "documentImageHash": "sha256:def456...",
      "documentImagePath": "125215/document-trust/b2c3.../front.jpg"
    }
  }
}

Note: authorityData is omitted in validate mode.

Decisions

Decision	Meaning	Suggested action
`PASS`	Extraction and validation checks passed	Proceed (or run separate authority verification if needed)
`REVIEW`	Minor issue (e.g. expiring soon, type mismatch)	Manual review
`FAIL`	Missing fields, invalid format, expired document	Reject or request resubmission

Billing

HTTP status	Billed?
`200` — completed session (any `decision`)	Yes
`400` — validation error	No
`401` / `403` — auth or service access	No
Insufficient balance	No

Validate mode is typically priced lower than full Document Trust because no authority APIs are called. Confirm pricing in your institution offerings.

Retrieve a session later

Sessions from validate mode are stored under the same session model:

GET /api/v1/document/trust/{sessionId}

Not billed.

Prerequisites

DOCUMENTTRUST_VALIDATE enabled in your institution offerings with pricing.
Sufficient wallet balance or active subscription.

When to use Document Validate vs Document Trust

Scenario	Recommended service
Pre-screen document quality before a full KYC step	Document Validate
Confirm NIN/passport/licence exists at government source	Document Trust
Lower cost per check, no authority API usage	Document Validate
Full auditable trust decision with authority match	Document Trust

Supported checks (validate mode)

Category	Examples
Classification	`DOC_CLASSIFICATION`, `DOC_TYPE_MISMATCH`
Extraction	`EXTRACTION_COMPLETE`, `EXTRACTION_FAILED`
Format	`PASSPORT_FORMAT_VALID`, `NIN_FORMAT_VALID`, `VIN_FORMAT_VALID`, `LICENSE_FORMAT_VALID`
Expiry	`DOCUMENT_NOT_EXPIRED`, `DOCUMENT_EXPIRING_SOON`
Cross-field	`CROSS_FIELD_CONSISTENT`
Authority	All `_MATCH_AUTHORITY` and `AUTHORITY_RECORD_FOUND` → skipped*

See the full Document Trust API Guide for the complete check code reference.

Document Validate Service (DOCUMENTTRUST_VALIDATE)