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 into review — delivered as a REVIEW event with flowStatus: "REVIEW", while reading the same flow result via the API returns REQUIRES_MANUAL_REVIEW.

---

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)
TRANSACTION_ALERT	A Transaction Monitoring rule raised an alert

---

Canonical webhook event types

These are the values a webhook endpoint subscribes to, and the value carried in type on a V2 payload. They are not the same vocabulary as the event field above: event is derived from a verification's status and collapses every notification to NOTIFICATION, so it cannot distinguish a DV result from a KYB result, or one notification kind from another.

Only these values are accepted. Wildcards are not: a selection is always stored as exact values, so a later addition to this catalog cannot widen a subscription you already made. The live catalog for a deployment is served by GET /organizations/{organizationId}/webhooks/events.

Verification

Event type	Fired when
verification.dv.completed · .failed · .review	A document-verification result reaches that state
verification.poa.completed · .failed · .review	A proof-of-address result reaches that state
verification.form.completed · .failed · .review	A form result reaches that state
verification.spid.completed · .failed · .review	A SPID / CIE result reaches that state
verification.phone.completed · .failed · .review	A phone-verification result reaches that state
verification.wallet.completed · .failed · .review	A wallet result reaches that state
verification.kyb.completed · .failed · .review	A KYB result reaches that state
verification.geolocation.completed · .failed · .review	A geolocation result reaches that state
verification.aml.produced · .refreshed · .moderated	An AML screening result is produced, refreshed by ongoing monitoring, or moderated
verification.document.expired	A verified identity document has expired
verification.kyc.expired	A KYC / flow result passed its validity window

Flow

Event type	Fired when
flow.risk.reevaluated	Risk scores were recomputed for a flow result
flow.completed	Every step the flow asks for has a passing result. V2 only.

Transaction

Event type	Fired when
transaction.alert.created	A Transaction Monitoring rule raised an alert. Not flow-bound, so an endpoint's flow filter does not apply.

KYC Passport

Event type	Status
kyc_passport.verification.updated	Reserved. Present in the catalog and subscribable, but not yet emitted. V2 only.

Availability notes

• Events marked V2 only have no pre-registry payload, so a LEGACY_V1 endpoint cannot subscribe to them; the API rejects the combination when you save it. See Payload Versions.
• Session webhooks cannot subscribe to transaction.alert.created or kyc_passport.verification.updated.
• The catalog API also returns an advisory group (VERIFICATION, FLOW, TRANSACTION, KYC_PASSPORT) and flowScoped flag for building a selection UI. Groups are never stored.

---

Flow and verification-request status

flowStatus on result webhooks and status on verification requests / flow results describe the same verification run, but use different vocabularies. Webhooks speak the event vocabulary; the API exposes the full lifecycle.

Webhook flowStatus

Status	Meaning
PROCESSING	Automated checks in progress
COMPLETED	Finished successfully
FAILED	Finished with an automatic failure
CANCELLED	Cancelled before completion
REVIEW	Waiting on a human review decision
REJECTED	Explicitly rejected

flowStatus never carries PENDING, QUEUED, or REQUIRES_MANUAL_REVIEW: webhooks are not sent for runs the user has not finished, and review states are always delivered as REVIEW.

API status (flow results / verification requests)

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 a human review decision
REJECTED	Explicitly rejected

When a webhook reports flowStatus: "REVIEW", reading the same flow result or verification request via the API returns REQUIRES_MANUAL_REVIEW.

---

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
REVIEW	Human review in progress (DV only)

Document verification is the only step type that can enter review; in webhooks its result status is delivered as REVIEW, and reading the same DV result via the API returns REQUIRES_MANUAL_REVIEW. KYB results use their own vocabulary (ModerationResultStatus, below).

warning

REVIEW — at the event, flow, or step layer — means “keep pending.” 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	Webhook event: REVIEW · API result status REQUIRES_MANUAL_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.

---

API errors

HTTP API failures use a structured body (BaxeError):

{
  "code": 10201,
  "errorTag": "invalid_api_key",
  "message": "optional human-readable detail"
}

Field	Meaning
code	Numeric error code (stable enough for support; prefer errorTag in app logic when present)
errorTag	Machine-readable tag from the API ErrorTags enum
message	Optional detail; do not rely on exact wording for branching

Authentication and configuration

HTTP	errorTag	Typical causes
401	invalid_api_key	Publishable key used on a server endpoint; typo/truncated key; request sent to the wrong host (for example docs.zyphe.com instead of api.zyphe.com); key revoked
401	missing_api_key	No x-api-key header
401 / 403	origin_not_allowed	Publishable key used from a browser origin not in Allowed Origins
403 / other	permission_denied, forbidden	Key or role cannot perform the operation
4xx	product_not_active	Product entitlement missing (for example Export API not enabled)

Numeric code 10201 is commonly returned with errorTag: "invalid_api_key". Fix checklist:

1. Use a secret key (zyphe_sk_…) for backend calls — API keys
2. Call https://api.zyphe.com — Environment setup
3. Confirm the key still exists in the dashboard and was copied completely
4. Align sandbox/production usage — Sandbox mode

Other tags you may see while integrating

errorTag	Meaning (integration context)
flow_not_found	Wrong flow id or sandbox/production mismatch
verification_request_not_found	Bad VR id or sandbox mismatch
step_order_violation / step_already_completed	Completing steps out of order on the direct-API path
bad_request / request_deserialization	Invalid JSON or schema
rate_limit_exceeded	Too many requests; back off and retry

The full ErrorTags enum is listed in the OpenAPI schema. Webhook events and result statuses above are separate from these API tags.

---

Related

• Webhook endpoints, configuring destinations and subscriptions
• Payload versions, LEGACY_V1 and V2
• Webhook structure, envelopes and delivery
• Webhook payload, field-level examples
• API keys, secret vs publishable
• Environment setup, base URLs
• OpenAPI reference, generated schemas (DvReason, ResultStatus, VerificationRequestStatus, ErrorTags, …)