Submit KYC

Use the Submit User KYC API to initiate identity verification for a user. KYC is required for new users with edit access, and for stakeholders not previously verified through biometric KYC.

EU supports biometric KYC only.

When to call this API

After creating a user, check the kycStatus in the USER_STATUS_WEBHOOK response:

• kycStatus="kyc_required" → call Submit KYC before the user can access APIs.
• kycStatus="kyc_not_required" → skip this step. The user is already active.

Request

POST /api/v1/client/{clientHashId}/userKyc
Content-Type: application/json

{
  "entityReferenceId": "9fc6e2a5-786f-4c25-bd6d-1f4c9b9b2b44",
  "region": "EU",
  "kycMode": "biometric_kyc"
}

Request fields:

Field	Type	Required	Description
entityReferenceId	string (UUID)	Yes	The userHashId or externalId of the user to submit KYC for.
region	string	Yes	Region for the KYC submission. Use EU for Phase 1.
kycMode	string	Yes	KYC method. Use biometric_kyc.

Response

{
  "userHashId": "a3b4c5d6-e7f8-9012-abcd-ef1234567890",
  "externalId": "fdbfe7ee-310c-4896-902d-2821a3db0592",
  "status": "pending",
  "kycStatus": "pending",
  "kycMode": "biometric_kyc",
  "biometricUrl": "https://kyc-provider.example.com/session/abc123xyz"
}

Share the biometricUrl with the user. They complete the biometric check directly through the hosted link. Once complete, Nium processes the result automatically and you receive a USER_STATUS_WEBHOOK event with kycStatus: verified.

KYC flow

Submit KYC (POST /userKyc)
│
▼
Returns biometricUrl
│
▼
Share URL with user → user completes biometric check
│
▼
kycStatus: initiated → submitted
│
▼
Nium reviews result
│
▼
kycStatus: verified → user status: clear

Error codes

HTTP	Error	Cause	Fix
400	entityReferenceId is mandatory	Missing user identifier	Send userHashId or externalId
400	kycmode not supported	Wrong KYC mode	Use biometric_kyc
400	Unsupported region for user KYC	Non-EU region	EU only in Phase 1
404	User not found for the given client	Invalid entityReferenceId	Verify via List/Get User