Skip to main content

KYC verification

Roja verifies every user's identity before they can trade on the marketplace. The KYC service supports several verification methods; which ones apply to a user depends on their ID type.

Discover what's needed​

Start with these two read endpoints and let them drive your UI:

  • GET /v1/kyc/methods — the verification methods available per ID type.
  • GET /v1/kyc/status — where this user currently stands: what's verified, what's pending, what's still required.

Identity documents​

NIN / BVN identity
  • POST /v1/kyc/identity/lookup — look up an identity number (NIN or BVN).
  • POST /v1/kyc/identity/validate — validate the user's claimed details against the registry record.
  • POST /v1/kyc/identity/verify-paired — verify a NIN+BVN pair together.
  • POST /v1/kyc/bvn-premium/verify and POST /v1/kyc/bvn-face/verify — richer BVN checks, the latter matched against a live face capture.
Government ID and photo ID
  • POST /v1/kyc/government-id/lookup — driver's licence, passport and other government IDs.
  • POST /v1/kyc/photoid/verify — verify an uploaded photo ID document.
Liveness
  • POST /v1/kyc/selfie/verify — selfie liveness and face match against the identity record.
Supporting documents
  • POST /v1/kyc/utility/verify — utility bill.
  • POST /v1/kyc/employment/verify — employment details.
  • POST /v1/kyc/statement/review — submit a bank statement for review.

Hosted verification widget​

For mobile and web clients, the hosted widget wraps the full document + face flow with the provider:

Create a session

POST /v1/kyc/widget/session returns a session for the embedded widget.

Run the widget

Hand the session to the widget SDK in your client and let the user complete the capture flow.

Confirm

POST /v1/kyc/widget/confirm tells Roja the widget flow finished; poll GET /v1/kyc/status for the outcome.

Address verification​

Physical address verification has both a direct API and a widget flow:

  • POST /v1/kyc/address/verify starts a verification; GET /v1/kyc/address/verify/{verification_id} reads its progress.
  • Widget flow: POST /v1/kyc/address/widget/session → POST /v1/kyc/address/widget/confirm → GET /v1/kyc/address/widget/status.

Verification outcomes are asynchronous — registries and document reviews take time. Treat GET /v1/kyc/status as the source of truth and design your onboarding to resume gracefully.