The eKYC Check Object

An ekyc check verifies an individual's declared identity attributes against authoritative data
sources, without collecting a document. It targets individuals only, is created with is_internal
set to true, and resolves synchronously: the create response already carries the result.

Product documentation: eKYC.

Prerequisites

The check reads the individual record rather than the request body. Four fields must be set on the
individual before creation:

first_name
last_name
birth_date
address.country

A missing field returns 400 naming it. Set them with
Update an individual.

address.country also determines availability. It must be one of:

AE AR AT AU BE BR CH CL CO CZ DE DK ES FI FR GB GH ID IE IT JO JP KE KW MX MY
NG NL NO OM PE PH PL PT SA SE SK TR US VN ZA

Any other value returns 400, as does a supported country for which no verification profile is
configured on the workspace.

Create an eKYC check

POST /v1/checks/ekyc — Create an eKYC check.

curl -X POST https://api.dotfile.com/v1/checks/ekyc \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"individual_id": "4b36ce30-3d90-421a-b2d9-a046e5e4cfef"}'

Field	Type	Required	Description
`individual_id`	`uuid`	yes	the individual to verify
`settings`	object	no	per-check override of the values below

`settings` field	Type	Default	Description
`vendor`	enum	`gbg`	the only accepted value
`automatic_approval`	boolean	`true`	resolves a `match` to `approved` without human review
`automatic_rejection`	boolean	`true`	resolves an `inconsistent` to `rejected` without human review

400 is also returned when the workspace check limit is reached.

Decision and status

data.decision is the vendor-agnostic outcome of the identity match:

Value	Meaning
`match`	the identity was confirmed against the data sources
`inconclusive`	insufficient data to decide
`inconsistent`	the data found contradicts the declared identity

status is derived from data.decision and the two settings flags:

`data.decision`	Settings	Resulting `status`
`match`	`automatic_approval: true`	`approved`
`match`	`automatic_approval: false`	`need_review`
`inconsistent`	`automatic_rejection: true`	`rejected`
`inconsistent`	`automatic_rejection: false`	`need_review`
`inconclusive`	any	`need_review`

inconclusive never resolves automatically.

Response

Field	Description
`data.result`	`approved`, `rejected` or `error`
`data.decision`	`match`, `inconclusive` or `inconsistent`
`data.information`	the identity that was verified: `first_name`, `last_name`, `birth_date`, `address`
`data.vendor`	`name`, `profile_id`, `profile_name`, `country`, `score`
`data.fraud_signals`	`trust`, `fraud_score`, `email_verification`, `email_validation`, `mobile_validation`; `null` when no signals were returned
`data.ai.interpretation`	plain-language reading of the result, or `null`
`data.settings`	the settings the check ran with
`data.review`	`comment`, `reviewed_at`, `reviewer_type`, `user`

data.fraud_signals covers the individual's email address and phone number. These are evaluated
within the same request; no separate check exists for them. See
Email and phone verification.

subtype is always null on an ekyc check.

Review

PATCH /v1/checks/ekyc/{id}/review — Review an eKYC check.

curl -X PATCH https://api.dotfile.com/v1/checks/ekyc/$CHECK_ID/review \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "approve", "comment": "Address confirmed against the utility bill"}'

Field	Type	Required	Description
`action`	`approve` \| `reject`	yes	the decision
`comment`	string	no	recorded on `data.review`
`override`	boolean	no	permits changing a check already in `approved` or `rejected`

data.review.reviewer_type is set to api.

Retrieval

Retrieve an eKYC check returns the full object, data included.

Retrieve a case and List checks return the check envelope
only — id, individual_id, type, status, subtype, timestamps — without data.

The Check.Started, Check.Approved, Check.Rejected and Check.ReviewNeeded
webhook events carry the complete check object, data included.

The Check object — the shared envelope, statuses and review mechanics
Templates — creating the check from a verification policy rather than per call