Statuses and codes
This page is the authoritative vocabulary for statuses, webhook events, and structured reasons you will see in the dashboard, webhooks, and API. Prefer these enums over free-text errorMessage when branching application logic.
Payload field layout lives in Webhook Payload. Failure handling is in Failure and Review Events.
Three layers of status
A single webhook can carry different statuses at different layers. Do not treat them as synonyms.
| Layer | Field | Scope |
|---|---|---|
| Delivery event | top-level event | Why this webhook was sent |
| Flow / request | flowStatus (webhook) · status on a flow result / verification request (API) | Overall outcome of the verification run |
| Step result | data.<type>.status | Outcome of one step (DV, PoA, form, …) |
Example: a DV step can be FAILED with reasons: ["DOCUMENT_EXPIRED"] while you still handle a later step, or the whole flow can move to REQUIRES_MANUAL_REVIEW after a REVIEW event.
Webhook event values
Verification results
| Value | Meaning | Typical next action |
|---|---|---|
COMPLETED | The step or flow completed successfully | Trust data / flowStatus; provision the user |
FAILED | The step or flow failed automatically | Read structured reasons; allow retry or reject |
REVIEW | Human review is required | Do not reject yet. Wait for a later final event |
REJECTED | Explicit rejection (often after manual review) | Treat as declined |
NOTIFICATION | Lifecycle notification (not a step result) | Route on eventData.type |
AML updates
| Value | Meaning |
|---|---|
PRODUCED | Initial AML screening result produced |
REFRESHED | Ongoing monitoring refreshed matches |
MODERATED | An AML match was moderated (approved / rejected / escalated) |
Notification eventData.type
Used only when event is NOTIFICATION:
| Type | Meaning |
|---|---|
DOCUMENT_EXPIRED | A verified identity document has expired |
KYC_RESULT_EXPIRED | A KYC / flow result has passed its retention or validity window |
FLOW_RISK_REEVALUATED | Risk scores were recomputed (for example after tag changes) |
Flow and verification-request status
flowStatus on result webhooks and status on verification requests / flow results use the same overall lifecycle:
| Status | Meaning |
|---|---|
PENDING | Created; user has not finished |
QUEUED | Waiting to be processed |
PROCESSING | Automated checks in progress |
COMPLETED | Finished successfully |
FAILED | Finished with an automatic failure |
CANCELLED | Cancelled before completion |
REQUIRES_MANUAL_REVIEW | Waiting on an operator decision |
REQUIRES_ADMIN_REVIEW | Waiting on an admin-level decision |
REJECTED | Explicitly rejected |
Step result status (data.<type>.status)
Individual step results (document verification, PoA, form, and related types) use:
| Status | Meaning |
|---|---|
PASSED | Step checks passed |
FAILED | Step checks failed |
PARTIAL | Incomplete or partially successful result |
REQUIRES_MANUAL_REVIEW | Operator must decide |
REQUIRES_ADMIN_REVIEW | Admin must decide |
Webhook examples may show intermediate labels such as REVIEW on a nested result while the flow is under review. Treat REVIEW at the event / flow layer as “keep pending,” and use the final COMPLETED / FAILED / REJECTED event as the decision to act on in your product.
Document verification reasons (data.dv.reasons[])
Empty when no reason is reported. Values come from the API DvReason enum.
Document quality and authenticity
| Code | Typical meaning |
|---|---|
WRONG_DOCUMENT_TYPE | Submitted type does not match what the step allows |
DOCUMENT_TYPE_NOT_DEFINED | Type could not be determined |
DOCUMENT_TYPE_CHECK | Type validation failed |
DOCUMENT_NOT_FOUND | No usable document in the capture |
DOCUMENT_SCORE_BELOW_THRESHOLD | Authenticity / quality score below configured minimum |
SECURITY_CHECK_FAILED | Built-in security features failed checks |
DOCUMENT_ALTERATION_DETECTED | Signs of alteration |
DOCUMENT_TAMPERING_DETECTED | Signs of tampering |
FAKE_DOCUMENT_DETECTED | Classified as fake |
SCREEN_REPLAY_ATTACK_DETECTED | Screen / replay presentation attack |
PAPER_COPY_DETECTED | Paper copy rather than original |
BLACK_AND_WHITE_COPY | B/W copy of a color document |
ELECTRONIC_DEVICE | Capture from another screen/device |
SECURITY_TEXT | Security text check failed |
IMAGE_PATTERNS | Image-pattern check failed |
PHOTO_EMBEDDINGS | Portrait embedding consistency failed |
Country, age, and field rules
| Code | Typical meaning |
|---|---|
COUNTRY_FILTER | Country not allowed by whitelist/blacklist |
DOCUMENT_COUNTRY_MISMATCH | Country does not match expected value |
DOCUMENT_COUNTRY_MISSING | Country could not be read |
DATE_OF_EXPIRY_NOT_VALID | Expiry invalid or document expired |
DATE_OF_EXPIRY_NOT_READABLE | Expiry unreadable |
DATE_OF_EXPIRY_FIELD_MISSING | Expiry field missing |
DATE_OF_BIRTH_BELOW_MINIMUM_AGE | Below the flow’s minimum age |
REQUIRED_FIELDS_MISMATCH | Required extracted fields inconsistent |
Face, liveness, and uniqueness
| Code | Typical meaning |
|---|---|
FACE_MATCH_CHECK | Face match against the document failed |
FACE_MATCH_CHECK_ONE_CLICK | Face match failed in a one-click / reuse path |
LIVENESS_CHECK_FAILED | Liveness overall failed |
LIVENESS_ANTISPOOF_FAILED | Anti-spoofing failed |
LIVENESS_BRIGHTNESS_FAILED | Lighting / brightness out of range |
LIVENESS_EYES_CLOSED_FAILED | Eyes closed |
LIVENESS_WEARING_SUNGLASSES_FAILED | Sunglasses detected |
LIVENESS_FACE_OCCLUDED_FAILED | Face occluded |
LIVENESS_SHARPNESS_FAILED | Image not sharp enough |
LIVENESS_FACE_CONSISTENCY_FAILED | Face consistency across frames failed |
UNIQUENESS_CHECK | Biometric uniqueness / duplicate identity check failed |
DOCUMENT_ALREADY_USED_BY_ANOTHER_USER | Document already bound to another identity |
DOCUMENT_FINGERPRINT_COMPUTATION | Document fingerprinting failed |
Other
| Code | Typical meaning |
|---|---|
OVERALL_STATUS | Aggregate step status failed without a more specific code |
UNKNOWN | Unclassified reason |
Proof of address reasons (data.poa.reason)
| Code | Typical meaning |
|---|---|
DOCUMENT_TYPE_NOT_ALLOWED | Type not accepted for PoA |
NAME_MISMATCH | Name does not match the verified identity |
DATE_TOO_OLD | Document older than allowed window |
INVALID_DOCUMENT | Document not valid for PoA |
UNRECOGNIZED_ADDRESS | Address could not be recognized |
UNKNOWN | Unclassified reason |
Other step types (form, phone, wallet, kyb, geolocation, spid) may expose optional reason / errorMessage strings. Prefer structured fields when present; use errorMessage for diagnostics only.
KYB and AML statuses
KYB moderation (ModerationResultStatus)
| Status | Meaning |
|---|---|
ACQUIRING | Collecting company / ownership data |
PENDING_MODERATION | Waiting for review |
REVIEW_REQUIRED | Needs human review |
SUCCESS | Moderated successfully |
FAILED | Failed |
PEP & sanctions (KYB)
| Status | Meaning |
|---|---|
PENDING | Not started |
IN_PROGRESS | Screening in progress |
REVIEW | Match requires review |
SUCCESS | Cleared |
FAILED | Failed |
AML moderation decisions
When an AML match is moderated: approved, rejected, or escalated.
See AML and KYB for operational workflows.
Transaction monitoring decisions
Transaction monitoring returns a synchronous verdict derived from combined rule risk:
| Decision | Meaning |
|---|---|
ALLOW | Below review threshold, proceed |
REVIEW | At or above review threshold, hold for investigation |
BLOCK | At or above block threshold, do not proceed |
See Transaction Monitoring for the Allow / Review / Block model and TM guides for rules and thresholds.
Manual review
| Concept | Value / event |
|---|---|
| Flagged for review | Result status REQUIRES_MANUAL_REVIEW · webhook event: REVIEW |
| Operator decision | Manual review result: approved, rejected, or failed |
| After decision | Follow-up webhook with COMPLETED, FAILED, or REJECTED |
Do not mark the end user as rejected on REVIEW alone. See Manual review.
Related
- Webhook structure, envelopes and delivery
- Webhook payload, field-level examples
- OpenAPI reference, generated schemas (
DvReason,ResultStatus,VerificationRequestStatus, …)