Skip to main content

KYX lifecycle — verification journey

How a KYX (Know Your X) verification moves through its lifecycle, from the platform caller's perspective. For the call contract see endpoints → parties.

KYX is the unified identity-verification contract: KYC for individuals, KYB for businesses. It is a separate journey from the parties lifecycle:

  • A KYX session is identified by an arkVerificationId (the checkId returned by POST /v1/parties/kyx), not by a party id.
  • POST /v1/parties/kyx creates no party record and never changes party status.
  • Every follow-up call (status, document upload, document list, verification data) is keyed by that arkVerificationId.

The platform relays the verification: the state lives with the backing identity provider and is read live on every call.

End-to-end journey​

A verification starts IN_PROGRESS. The caller submits one or more identity documents, polls status until it reaches a terminal outcome (or is routed to manual review), and can retrieve detailed verification data. SOLE_TRADER cannot initiate a KYX check — the initiate route returns 501.

Verification status​

POST /v1/parties/kyx and GET /v1/parties/kyx/{arkVerificationId} return one of these statuses; an unrecognised value raises 422 PAR022001.

Document status​

POST /v1/parties/kyx/{arkVerificationId}/documents returns a per-document verificationStatus:

ReportedDocument status
in progress / under reviewPENDING
verifiedVERIFIED
anything elseFAILED

Documents​

A document upload carries exactly one of two variants:

  • identityDocument — an identity document: type (PASSPORT / DRIVERS_LICENCE / NATIONAL_HEALTH_ID), region, country, documentDetails, optional extraData.
  • fileUpload — a document in the document-based verification format: applicationId, file, documentType, plus card-name fields. Schema: IdentityDocumentFileUpload.

Supplying neither → 400 GEN000000. GET /v1/parties/kyx/{arkVerificationId}/documents lists outcomes, each with a documentType (DRIVERS_LICENCE, PASSPORT, NATIONAL_HEALTH_ID, ASIC_REGISTRATION, ABR_REGISTRATION).

The single-document fetch GET /v1/parties/kyx/{arkVerificationId}/documents/{documentId} is a stub — it always returns 501.

Identity providers​

A KYX check runs against the identity provider configured for your client/brand, so individual (KYC) and business (KYB) checks can be served by different providers. The provider-specific verification mechanics are documented in that provider's own docs.