API reference

Lattice API Documentation

Choose a product group, inspect the endpoint contract, send a request, and confirm the response before connecting payroll or verification workflows.

Base URLhttps://lattice-be.onrender.com/api/v1Open live OpenAPI

Before you begin

Authentication

Protected Lattice SDK routes use the X-Lattice-API-Key header. Squad bridge calls are server-side wrappers, so your frontend should never expose Squad secret keys.

X-Lattice-API-Key: YOUR_LATTICE_API_KEY
Content-Type: application/json

SDK orchestration

Verify and disburse

Runs proof-of-life, document, BVN, anomaly, VIQ, and optional payment orchestration in one request.

POST/api/v1/sdk/verify-and-disburse

Requires: X-Lattice-API-Key

Parameters

NameTypeRequiredDescription

worker_idstringYesWorker record to verify.

pay_cycle_idstringYesPayroll cycle being gated.

evidenceobjectNoPre-collected liveness, BVN, face, and document signals.

initiate_transferbooleanNoWhen true, attempts a Squad-backed release for PASS VIQs.

Sample Request

curl -X POST "https://lattice-be.onrender.com/api/v1/sdk/verify-and-disburse" \
  -H "Content-Type: application/json" \
  -H "X-Lattice-API-Key: YOUR_LATTICE_API_KEY" \
  -d '{
    "worker_id": "EDU-OG-00095",
    "pay_cycle_id": "MAY-2026",
    "evidence": {
      "liveness": { "status": "PASSED", "confidence": 0.96 },
      "face_match": { "status": "MATCH", "similarity": 0.98 },
      "bvn": { "status": "BVN_MATCH", "provider": "SQUAD" },
      "documents": { "status": "DOCUMENTS_CLEAN", "flags": [] }
    },
    "initiate_transfer": false
  }'

Responses

{
  "status": "success",
  "verification_session_id": "vsn_9a72",
  "viq": {
    "worker_id": "EDU-OG-00095",
    "trust_score": 94,
    "verdict": "PASS",
    "payment_status": "READY"
  }
}

Verification sessions

Create verification session

Creates a verification session for a worker before salary release.

POST/api/v1/verification/sessions

Parameters

NameTypeRequiredDescription

worker_idstringYesWorker to verify.

pay_cycle_idstringYesPay cycle the session belongs to.

Sample Request

{
  "worker_id": "EDU-OG-00095",
  "pay_cycle_id": "MAY-2026"
}

Responses

{
  "id": "vsn_9a72",
  "status": "PENDING",
  "worker_id": "EDU-OG-00095",
  "pay_cycle_id": "MAY-2026"
}

Verification sessions

Submit evidence

Submits identity, liveness, BVN, deepfake, and document evidence for scoring.

POST/api/v1/verification/sessions/{session_id}/evidence

Parameters

NameTypeRequiredDescription

session_idpath stringYesVerification session identifier.

livenessobjectNoLiveness challenge outcome.

documentsobjectNoDocument consistency result and flags.

bvnobjectNoBVN match result, usually backed by Squad rails.

Sample Request

{
  "liveness": { "status": "PASSED", "confidence": 0.96 },
  "deepfake": { "status": "CLEAN", "synthetic_probability": 0.02 },
  "documents": {
    "status": "DOCUMENTS_CLEAN",
    "summary": "No contradictions found."
  }
}

Responses

{
  "id": "vsn_9a72",
  "status": "EVIDENCE_RECEIVED",
  "risk_flags": []
}

Verification sessions

Finalize session

Finalizes evidence review and generates the signed VIQ decision.

POST/api/v1/verification/sessions/{session_id}/finalize

Parameters

NameTypeRequiredDescription

session_idpath stringYesVerification session identifier.

Responses

{
  "session_id": "vsn_9a72",
  "viq_id": "viq_4f1d",
  "verdict": "PASS",
  "trust_score": 94
}

AI checks

Evaluate document consistency

Checks appointment dates, first salary dates, missing records, and document contradictions.

POST/api/v1/ai/document-consistency/evaluate

Parameters

NameTypeRequiredDescription

worker_idstringNoOptional worker context.

documentsarrayYesStructured document facts to compare.

Sample Request

{
  "documents": [
    { "type": "appointment_letter", "issued_at": "2018-04-11" },
    { "type": "first_salary_record", "issued_at": "2018-05-31" }
  ]
}

Responses

{
  "status": "DOCUMENTS_CLEAN",
  "severity": "NONE",
  "flags": [],
  "summary": "No document contradictions found."
}

AI checks

Verify biometric template

Compares a newly captured biometric template against an institution's enrolled biometric template.

POST/api/v1/ai/biometrics/verify-template

Requires: X-Lattice-API-Key

Parameters

NameTypeRequiredDescription

enrolled_templateobjectYesExisting biometric template from the institution's HR or identity system.

captured_templateobjectYesFresh biometric template captured during verification.

thresholdnumberNoSimilarity threshold. Defaults to 0.86.

Sample Request

curl -X POST "https://lattice-be.onrender.com/api/v1/ai/biometrics/verify-template" \
  -H "Content-Type: application/json" \
  -H "X-Lattice-API-Key: YOUR_LATTICE_API_KEY" \
  -d '{
    "enrolled_template": {
      "modality": "fingerprint",
      "vector": [0.12, 0.43, 0.52, 0.18, 0.76, 0.22, 0.31, 0.64]
    },
    "captured_template": {
      "modality": "fingerprint",
      "vector": [0.11, 0.44, 0.50, 0.2, 0.75, 0.23, 0.3, 0.65]
    },
    "threshold": 0.86
  }'

Responses

{
  "status": "BIOMETRIC_MATCH",
  "similarity": 0.998421,
  "threshold": 0.86,
  "modality": "fingerprint",
  "reference_source": "request.enrolled_template"
}

AI checks

Enroll worker biometric

Stores a worker's enrolled biometric template for future verification sessions.

POST/api/v1/ai/biometrics/workers/{worker_id}/enroll

Requires: X-Lattice-API-Key

Parameters

NameTypeRequiredDescription

worker_idpath stringYesWorker record receiving the enrolled template.

templateobjectYesFace, fingerprint, iris, or voice template vector plus optional provider metadata.

Sample Request

{
  "template": {
    "modality": "face",
    "provider": "Institution HR biometric register",
    "vector": [0.12, 0.43, 0.52, 0.18, 0.76, 0.22, 0.31, 0.64]
  }
}

Responses

{
  "worker_id": "wrk_123",
  "status": "ENROLLED",
  "modality": "face",
  "quality": { "usable": true, "dimension": 8 }
}

Squad bridge

Account lookup

Looks up bank account identity before a VIQ-linked transfer is initiated.

POST/api/v1/squad/account-lookup

Parameters

NameTypeRequiredDescription

bank_codestringYesNIP bank code for the receiving bank.

account_numberstringYesRecipient account number to validate.

Sample Request

{
  "bank_code": "000013",
  "account_number": "0123456789"
}

Responses

{
  "success": true,
  "provider": "SQUAD",
  "data": {
    "account_name": "JENNY SQUAD",
    "account_number": "0123456789"
  }
}

Billing

Buy verification credits

Initiates a Squad checkout for Lattice credits. Each successful verification consumes one credit. Each credit costs ₦150.

POST/api/v1/billing/credit-purchases

Requires: X-Lattice-API-Key

Parameters

NameTypeRequiredDescription

creditsnumberYesNumber of verification credits to purchase at ₦150 each.

customer_namestringYesInstitution or billing account name.

emailstringYesBilling email used by Squad checkout.

Sample Request

curl -X POST "https://lattice-be.onrender.com/api/v1/billing/credit-purchases" \
  -H "Content-Type: application/json" \
  -H "X-Lattice-API-Key: YOUR_LATTICE_API_KEY" \
  -d '{
    "credits": 1000,
    "customer_name": "Ogun State Ministry of Education",
    "email": "billing@education.og.gov.ng"
  }'

Responses

{
  "credits": 1000,
  "amount_naira": "150000.00",
  "status": "PENDING",
  "checkout_url": "https://checkout.squadco.com/..."
}

Webhooks

Receive Squad webhook

Receives payment confirmations and attaches the event to the Lattice audit trail.

POST/api/v1/webhooks/squad

Parameters

NameTypeRequiredDescription

x-squad-signatureheaderRecommendedSignature header used to verify source authenticity.

eventobjectYesSquad webhook payload.

Sample Request

{
  "event": "transfer.success",
  "transaction_reference": "LAT-MAY-2026-00095",
  "amount": 24500000,
  "status": "success"
}

Responses

{
  "received": true,
  "status": "ACKNOWLEDGED"
}