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 (LEGACY_V1)

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
SUBMITTED	A KYB application was submitted (KYB only)	Do not provision yet. Wait for a final event
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, or 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.submitted	A KYB application was submitted and its checks started. Not an outcome
verification.kyb.completed · .failed · .review	A KYB case reaches that state. See KYB event lifecycle
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 cases use their own vocabulary (KYB case status, 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 case status

Status	Meaning
OPEN	The applicant is filling in the flow. An idle draft is cancelled after 30 days and resumed on the next save
PROCESSING	Submitted; the case's checks are running
WAITING_INPUT	A document request or clarification is open with the applicant
ACTION_REQUIRED	A person has to act (a screening match that holds, an escalation)
READY_FOR_REVIEW	Every check finished; waiting for a decision
APPROVED	Approved by a decision
REJECTED	Rejected by a decision
CANCELLED	Abandoned, or the country changed before submission

APPROVED and REJECTED are not final: a case can be reopened by a resubmission, a quality review, or a periodic re-review. Each opening is an episode (CREATED, RESUBMITTED, QA_REOPENED, PERIODIC_REVIEW). How to work each status: Reviewing KYB cases.

KYB moderation (ModerationResultStatus)

The deprecated data.kyb object still carries the previous ModerationResultStatus vocabulary (ACQUIRING, PENDING_MODERATION, REVIEW_REQUIRED, SUCCESS, FAILED) for existing integrations. ENRICHING no longer exists. New integrations should read the case status from data.kybCase.status.

KYB event lifecycle

Each case transition that reaches a webhook, with the canonical event and the legacy event value:

Transition	Canonical event	Legacy event
Submission (OPEN → PROCESSING)	verification.kyb.submitted	SUBMITTED
→ ACTION_REQUIRED	verification.kyb.review	REVIEW
→ READY_FOR_REVIEW because the case's own checks finished	none	none
→ READY_FOR_REVIEW for any other cause	verification.kyb.review	REVIEW
Reopened (→ PROCESSING after a decision)	verification.kyb.review	REVIEW
→ APPROVED	verification.kyb.completed	COMPLETED
→ REJECTED	verification.kyb.failed	FAILED
→ CANCELLED	none	none

Only completed means the business was approved. review is also sent when an already approved company is reopened, so do not treat it as a new company. How to act on each event is in the KYB guide.

KYB decision reason codes

A decision's reasonCode classifies why it was taken:

Code	Meaning
CDD_INCOMPLETE	Customer due diligence could not be completed
SANCTIONS_CONFIRMED	A sanctions match was confirmed
PEP_CONFIRMED	A PEP match was confirmed
ADVERSE_MEDIA	Adverse media about the company or its people
OUTSIDE_RISK_APPETITE	The company is outside the organization's risk appetite
SUSPECTED_FRAUD	Fraud is suspected
APPLICANT_UNRESPONSIVE	The applicant did not answer requests
OTHER	Anything else. The default for a decision that owes a reason and sends no code

KYB decision refusals

When a decision is refused, the error carries its own errorTag (all 400):

errorTag	Meaning
kyb_case_not_decidable	The case's status does not accept this decision
kyb_case_not_ready	An approval needs the case in READY_FOR_REVIEW
kyb_case_exception_required	The approval rests on something that needs a recorded exception first
kyb_case_rejecting_hit	A confirmed match in a category the policy rejects stands on the case
kyb_case_reason_required	The decision needs a reason
kyb_case_decision_not_authorized	The approval matrix does not let this caller take this decision
kyb_case_second_signature_required	The confirmation of a proposal must come from a person other than the proposer

Publishing a compliance policy draft that still has open questions returns 409 with compliance_policy_open_questions.

KYB screening match resolution

Outcome	Meaning
FALSE_POSITIVE	The match is not the subject. Needs at least one discriminator. The only outcome that releases a match
TRUE_POSITIVE	The match is the subject
UNDETERMINED	Not decided yet; the match holds
CUSTOMER_CONTACTED	Waiting on the customer; the match holds

Discriminators: DATE_OF_BIRTH, NATIONALITY, TAX_OR_ID_NUMBER, ADDRESS, GENDER, OTHER (with a note).

KYB document-request types

Every item in a KYB document-request payload carries a requestType:

Type	Meaning
STANDARD	Asks the applicant to upload a named document
CLARIFICATION	Asks the applicant to re-confirm or update specific business-information fields
UBO_DECLARATION	Reopens the beneficial-owner step for a fresh declaration when ownership discovery could not resolve one
DIRECTOR_DECLARATION	The same for the director step
OWNERSHIP_CONFIRMATION	Asks the applicant to confirm or correct the owners and directors on file, when a case is reopened

The two declaration types require ownership discovery to be enabled on the step, and block approval while outstanding.

KYB document-request status

Status	Meaning
PENDING	Awaiting the applicant
UPLOADED	Submitted, under review
APPROVED	Accepted (terminal)
REJECTED	Rejected (terminal, cannot be reopened)

KYB screening strategy

Which population of natural persons a KYB case must identify and screen before approval: ubo (the default), directors, or uboAndDirectors. See KYB steps and configuration.

KYB due-diligence level

Recorded on the case as SIMPLIFIED, STANDARD (the default), or ENHANCED. ENHANCED adds a financial-documents requirement. An approver can also record it on the decision, where the dueDiligenceLevel field takes simplified, standard, or enhanced.

PEP & sanctions screening (KYB)

Status	Meaning
PENDING	Not started
IN_PROGRESS	Screening in progress
REVIEW	Match requires review
SUCCESS	Cleared
FAILED	Failed

AML result moderation (data.aml.status)

These values describe the moderation state carried by AML webhook payloads. They are separate from the KYB PEP and sanctions screening states above.

Status	Meaning
PENDING	Waiting for a moderation decision
APPROVED	The AML result was approved
REJECTED	The AML result was rejected
ESCALATED	The AML result was 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, …)