GreenID connector — verification lifecycle
A KYX verification is the connector's one stateful resource. This page describes how it moves from creation to a terminal outcome, and how GreenID's states are normalised to Ark's. How each step is implemented is in the architecture; how to call each step is in endpoints.
End-to-end process
A verification starts IN_PROGRESS. The platform submits one or more identity documents while it
stays in progress, then polls status until GreenID reaches a terminal outcome (or routes it to
manual review). The connector holds no state of its own beyond the id mapping — every status is
read live from GreenID.
Verification status
POST /v1/kyx, GET /v1/kyx/{id}, and POST /v1/kyx/{id}/documents all return a
verificationStatus normalised from GreenID's overallVerificationStatus:
| GreenID status | Ark status |
|---|---|
VERIFIED, VERIFIED_ADMIN, VERIFIED_WITH_CHANGES | VERIFIED |
IN_PROGRESS | IN_PROGRESS |
PENDING | UNDER_REVIEW |
LOCKED_OUT | DECLINED |
FAILED | FAILED |
ERROR | ERRORED |
Any other GreenID value is treated as a connector error (500 PAR100013 KYX_CONNECTOR_ERROR).
Documents may only be submitted while the verification is
IN_PROGRESS. Once it leaves that state,POST …/documentsis rejected.
Document status
GET /v1/kyx/{id}/documents reports a per-document verificationStatus (the raw GreenID source
state) and a normalised verificationStatusCategory:
| GreenID document state | Ark category |
|---|---|
VERIFIED, VERIFIED_ADMIN, VERIFIED_WITH_CHANGES, NOT_FOUND_ON_LIST, MATCH_FALSE_POSITIVE | VERIFIED |
IN_PROGRESS, PENDING, MATCH_REVIEW_REQUIRED | PENDING |
ERROR | ERRORED |
FAILED, AUTOFAIL, NOT_CONTRIBUTING, FOUND_ON_LIST, MATCH_CONFIRMED, LOCKED_OUT | FAILED |
Any other state leaves verificationStatusCategory unset.