Identity Layer

eKYC-AI

Active

Digital-only identity verification with no document upload required. Accepts biometric scores from your device SDK — liveness detection and face match — and cross-checks personal details against national databases. Designed for mobile-first onboarding flows where the customer completes verification on their own device.

Endpoint

POST/api/ekyc/verify

How it works

Your device SDK captures biometrics

Liveness score and face match score are generated client-side by your existing mobile SDK.

Pass scores to eKYC-AI

Send the scores along with customer details. No raw biometric data or images leave the device.

Database cross-check

Name, date of birth and national ID are verified against the relevant national database for the jurisdiction.

Compliance decision

A structured decision with compliance flags is returned. Cases requiring review are added to the Shield queue.

Request parameters

Parameter	Type	Required	Description
`customer_id`	string	Yes	Your internal reference for this customer.
`full_name`	string	Yes	Full legal name provided by the customer during onboarding.
`jurisdiction`	string	Yes	One of: CA (Canada), AE (UAE), SA (KSA). Determines compliance rules and database sources.
`date_of_birth`	string	No	Date of birth in YYYY-MM-DD format. Required for database cross-check.
`national_id`	string	No	National ID number for database verification.
`phone`	string	No	Mobile number. Used for SIM-based identity corroboration.
`email`	string	No	Email address. Used for identity corroboration.
`method`	string	No	One of: liveness_check, database_lookup, document_scan, biometric_match (default: liveness_check).
`liveness_score`	number	No	Liveness score 0–100 from your device SDK. Scores below 70 trigger rejection.
`face_match_score`	number	No	Face match score 0–100 from your device SDK. Scores below 70 trigger rejection.

Response fields

Parameter	Type	Required	Description
`success`	boolean	Yes	Whether the API call succeeded.
`data.status`	string	Yes	Verification decision: approved, rejected, or review_required.
`data.risk_level`	string	Yes	Risk level: low, medium, high, or critical.
`data.confidence_score`	integer	Yes	AI confidence in the decision, 0–100.
`data.checks_passed`	array	Yes	List of verification checks that passed, e.g. liveness_verified, database_match.
`data.liveness_verified`	boolean	Yes	Whether liveness check passed based on provided liveness_score.
`data.face_match_verified`	boolean	Yes	Whether face match passed based on provided face_match_score.
`data.database_match`	boolean	Yes	Whether the provided details matched the national database.
`data.compliance_flags`	array	Yes	List of compliance issues found. Each flag has: rule_id, severity, message, suggestion.
`data.requires_human_review`	boolean	Yes	If true, the case is added to the review queue for a compliance officer.
`data.ai_recommendation`	string	Yes	Plain-English explanation of the decision and recommended action.
`processing_time_ms`	integer	Yes	Total processing time in milliseconds.

Code example

curl -X POST \
  https://shield.kodexa.systems/api/ekyc/verify \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "CUST-AE-001",
    "full_name": "Ahmed Al Mansoori",
    "jurisdiction": "AE",
    "date_of_birth": "1985-03-22",
    "national_id": "784-1985-1234567-8",
    "method": "liveness_check",
    "liveness_score": 96,
    "face_match_score": 94
  }'

Example response

json

{
  "success": true,
  "data": {
    "status": "approved",
    "risk_level": "low",
    "confidence_score": 95,
    "checks_passed": [
      "liveness_verified",
      "face_match_verified",
      "database_match",
      "name_match"
    ],
    "liveness_verified": true,
    "face_match_verified": true,
    "database_match": true,
    "ai_recommendation": "Strong liveness score (96) and face match (94). Identity confirmed via national database. Approved for onboarding.",
    "compliance_flags": [],
    "requires_human_review": false,
    "review_reasons": [],
    "request_id": "ekyc_1716000000_abc123",
    "created_at": "2026-05-22T04:00:00.000Z"
  },
  "processing_time_ms": 312,
  "jurisdiction": "AE",
  "plugin": "ekyc"
}