Get verification status

code

GET /api/kyc/status/:verificationId

Returns the minimal lifecycle state of a verification — pending, verified, failed, not_found, or error. This endpoint is publishable-safe: it can be called with the pk_ key that ships in your SDK, so it deliberately returns no PII, no match scores, and no result data. To read the full result + extracted biodata, use Get verification result with a secret (sk_) key from your backend.

Webhooks are the recommended way to learn about completion without polling.

Authentication: Authorization: Bearer pk_… or sk_… (required). A verification is only visible to the organization that created it.

Request

shell

curl "https://identity.myaza.app/api/kyc/status/ver_01j9..." \
  -H "Authorization: Bearer $MYAZA_PUBLISHABLE_KEY"

Responses

Every response includes verificationId, status, and createdAt.

`pending` / `verified`

json

{
  "verificationId": "ver_01j9...",
  "status": "verified",
  "createdAt": "2026-04-27T12:00:00.000Z",
  "completedAt": "2026-04-27T12:00:05.000Z"
}

A verified status here confirms the verification passed — but carries no identity data. Fetch the full result with a secret key to read the biodata and facial-match score.

`failed` / `error`

failed means the verification completed but validations did not pass (e.g. face mismatch, insufficient credit). error means a system problem occurred. Both include a human-readable reason and a stable reasonCode you can branch on — see failure reason codes.

json

{
  "verificationId": "ver_01j9...",
  "status": "failed",
  "reason": "The user's selfie does not match the photo on file with the government database (match confidence 48%, minimum 70% required).",
  "reasonCode": "selfie_mismatch",
  "createdAt": "2026-04-27T12:00:00.000Z",
  "completedAt": "2026-04-27T12:00:05.000Z"
}

`not_found`

The ID number was not found in the government database. Carries reason and reasonCode (identity_not_found).

json

{
  "verificationId": "ver_01j9...",
  "status": "not_found",
  "reason": "The BVN number was not found in the government database.",
  "reasonCode": "identity_not_found",
  "createdAt": "2026-04-27T12:00:00.000Z",
  "completedAt": "2026-04-27T12:00:05.000Z"
}

Errors

Status	Body	Cause
`404`	`{ "error": "Verification not found" }`	Unknown ID, or it belongs to another organization.
`401`	`{ "error": "Invalid API key" }`	Auth failed.

Polling guidance

If you must poll, do so with backoff (e.g. every 2–3 seconds, widening over time) and stop once status is no longer pending. Prefer webhooks for production. Once complete, fetch the full result from your backend.