Get a verification result

GET

/api/kyc/verifications/:id

GET

/api/kyc/verifications/:id

curl https://sandbox-api.toden.co/api/kyc/verifications/id \
     -H "Authorization: Bearer <apiKey>"

{
  "addressIntel": null,
  "attempt": 1,
  "attempts": [],
  "checkStatus": "verified",
  "completedAt": "2026-04-27T12:00:05.000Z",
  "country": "NG",
  "createdAt": "2026-04-27T12:00:00.000Z",
  "deviceRules": null,
  "externalUserId": "user_42",
  "faceSearch": null,
  "hold": null,
  "idType": "bvn",
  "metadata": {
    "loanId": "loan_20191"
  },
  "multiId": null,
  "result": {
    "dataMatch": true,
    "dateOfBirth": "1990-01-01",
    "facialMatch": {
      "confidence": 85,
      "match": true
    },
    "facialMatchSkipped": null,
    "facialMatchSource": "gov_record",
    "firstName": "ADA",
    "gender": "f",
    "idNumber": "00000000001",
    "idNumberMasked": "0000•••001",
    "lastName": "EXAMPLE",
    "middleName": null
  },
  "review": null,
  "status": "approved",
  "statusHistory": [],
  "submittedAt": "2026-04-27T12:00:00.000Z",
  "supportingDocuments": null,
  "verificationId": "ver_01j9x2k4m8",
  "workflow": {
    "id": "wf_AbC123dEf456",
    "name": "Identity verification",
    "version": 3
  }
}

Returns the full result, including the verified identity, the decision history and earlier attempts. result is present only when the checks passed; reason and reasonCode only when they did not.

Before the applicant submits, the same identifier returns the unsubmitted attempt, with data holding what they have entered so far. A workflow can withhold fields from this response through its returned-data settings.

Error codes

`error`	Status	Meaning
`Verification not found`	404	No verification or session with that id for this organisation and environment.
`Missing or invalid Authorization header`	401	No bearer credential was sent.
`Invalid API key`	401	The key is unknown or revoked.
`environment_mismatch`	403	The key belongs to an environment this host does not serve.
`origin_not_allowed`	403	The request origin is not on the publishable key allowlist.
`ip_not_allowed`	403	The caller address is not on the secret key allowlist.
`organization_suspended`	403	The organisation is suspended.
`secret_key_required`	403	A publishable key was used on a secret-key endpoint.

Requires a secret (sk_) key. A publishable key receives 403 secret_key_required.

Authentication

AuthorizationBearer

Send the API key as a Bearer token. Each operation states whether a publishable key is enough or a secret key is required.

Path parameters

idstringRequired

The verification identifier. A session identifier works too, because a verification keeps the identifier of its session.

Response

The verification result, or the unsubmitted attempt.

VerificationResultobject

The full result of a submitted verification. Fields may be withheld by the workflow returned-data settings.

VerificationAttemptDataobject

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error