Document Trust Service (`DOCUMENTTRUST`)

Full document verification: OCR extraction → validation → government authority reconciliation → PASS / REVIEW / FAIL decision.

Use this when you need to confirm that a physical identity document is structurally valid and matches official records (FRSC, PVC, Passport, NIN).

Related: Document Validate Service (validation only, no authority) · Full API Guide

Quick reference

Item	Value
Service SKU	`DOCUMENTTRUST`
Method	`POST`
Path	`/api/v1/document/trust`
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 Orcha OCR and extracts identity fields.
Runs classification, format, expiry, and cross-field checks.
Reconciles extracted data against the matching government API:
- Passport → passport authority
- Driver's licence → FRSC
- Voter's card → PVC
- NIN slip → NIN
Returns a structured decision (PASS, REVIEW, or FAIL), trustScore, per-check breakdown, and audit evidence.

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 (tries handlers until required fields are extracted)
`passport`	International Passport
`drivers_license`	Driver's Licence (FRSC)
`voters_card`	Permanent Voter's Card (PVC)
`nin_slip`	NIN Slip

Example request

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

Example response

{
  "status": true,
  "message": "Successful",
  "code": "200",
  "transactionRef": "N202608121100001234",
  "apiVersion": "v1",
  "data": {
    "sessionId": "a1b2c3d4e5f67890abcdef1234567890",
    "customerReference": "CUST-001",
    "decision": "PASS",
    "trustScore": 0.91,
    "mode": "trust",
    "docTypeRequested": "drivers_license",
    "docTypeDetected": "drivers_license",
    "processedAtUtc": "2026-08-12T10:00:00Z",
    "processingDurationMs": 4200,
    "summary": {
      "headline": "Document passed trust checks.",
      "checksPassed": 12,
      "checksFailed": 0,
      "checksReview": 0,
      "checksSkipped": 0
    },
    "checks": [
      {
        "code": "DOC_CLASSIFICATION",
        "category": "classification",
        "status": "pass",
        "message": "Document classified as drivers license.",
        "confidence": 0.95
      },
      {
        "code": "AUTHORITY_RECORD_FOUND",
        "category": "authorityReconcile",
        "status": "pass",
        "message": "Authority record found.",
        "confidence": 1.0
      }
    ],
    "extractedData": {
      "documentType": "drivers_license",
      "fields": {
        "fullName": "JOHN DOE",
        "licenseNumber": "ABC12345678",
        "expiryDate": "15-03-2028"
      }
    },
    "authorityData": {
      "source": "frsc",
      "recordFound": true,
      "fields": {
        "licenseNumber": "ABC12345678",
        "fullName": "JOHN DOE"
      }
    },
    "audit": {
      "auditRef": "a1b2c3d4e5f67890abcdef1234567890",
      "evidenceRetentionUntilUtc": "2033-08-12T10:00:00Z",
      "documentImageHash": "sha256:abc123...",
      "documentImagePath": "125215/document-trust/a1b2.../front.jpg"
    }
  }
}

Decisions

Decision	Meaning	Suggested action
`PASS`	All critical checks passed	Proceed with onboarding
`REVIEW`	Non-critical mismatch or expiring soon	Queue for manual review
`FAIL`	Critical failure (format, expiry, authority mismatch, etc.)	Reject or request resubmission

trustScore (0–1) is a summary metric. decision is the primary business outcome.

Billing

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

Each successful response includes transactionRef for wallet reconciliation.

Retrieve a session later

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

Not billed. Returns the stored session JSON for your institution.

Prerequisites

DOCUMENTTRUST enabled in your institution offerings with pricing.
Sufficient wallet balance or active subscription.
Supported document types: passport, driver's licence, voter's card, NIN slip.

When to use Document Trust vs Document Validate

Need	Use
Confirm document matches government records	Document Trust (`DOCUMENTTRUST`)
OCR + format/expiry checks only, no authority lookup	Document Validate
Selfie / liveness / face match	Separate biometric products (`LIVELINESSCHECK`, `FACECOMPARISON`, etc.)

See the full Document Trust API Guide for check codes, processing flow, and configuration.

Document Trust Service (DOCUMENTTRUST)