Reference
User status
status | subStatus | Remarks | Next action |
|---|---|---|---|
pending | null | User creation request is submitted. | Wait for the USER_STATUS_WEBHOOK event for the next step. |
pending | awaiting_kyc | User KYC completion is pending. | Call the Submit KYC API with biometric_kyc mode. |
pending | under_review | Nium is reviewing the KYC submission. | Wait for Nium to take further action. |
pending | rfi_requested | Nium has raised a Request for Information (RFI). | Respond to the RFI. |
rejected | — | User creation is rejected. | Check the webhook for details and resubmit if permitted. |
clear | — | The user has been successfully created and is active. | No action required. |
suspended | — | User has been suspended. | Use action=clear to reinstate, or action=revoke to permanently remove access. See Suspend / Revoke User. |
revoked | — | User access has been permanently removed. | No further action possible. Contact Nium support if this was done in error. |
KYC status
kycStatus | Remarks |
|---|---|
pending | Initial state after user creation. Wait for the USER_STATUS_WEBHOOK for the next step. |
kyc_required | KYC must be completed before the user can access APIs. Call Submit KYC with biometric_kyc. |
kyc_not_required | No KYC needed — applies to view access users, or stakeholders whose KYC was already completed during customer creation. |
initiated | The biometric KYC process has started but the user has not yet completed it. |
submitted | The user has completed the biometric check. Nium is processing the result. |
verified | Biometric KYC is complete and verified. The user is fully active. |
Webhook
Configure the USER_STATUS_WEBHOOK event to receive real-time updates on user status and KYC status changes.
{
"template": "USER_STATUS_WEBHOOK",
"clientHashId": "85116947-8fae-4a57-8798-cab145127945",
"customerHashId": "86902c74-c25d-4a2d-b195-b708a6c54734",
"userHashId": "b067dd90-3f9a-4f12-95b7-9eb0b395c558",
"entityReferenceId": "4c590404-983a-418e-b582-98578ca74eac",
"status": "clear",
"subStatus": null,
"kycStatus": "verified",
"redirectUrl": "Onfido URL"
}
Error codes
Create User
| HTTP | Error | Cause | Fix |
|---|---|---|---|
400 | x-user-id is mandatory | x-user-id header missing | Pass the default user's userHashId in the header |
400 | User not found for the given x-user-id | Caller user does not exist | Use a valid userHashId |
400 | User creation is allowed only when the customer status is Clear | Customer not yet approved | Complete customer onboarding first |
400 | customerHashId does not resolve to an existing customer | Invalid customer ID | Verify customerHashId |
400 | User already exists with externalId: … | Duplicate externalId | Use a unique externalId |
400 | existingEntityReferenceId is not applicable for an individual customer | Stakeholder link used on an individual customer | Use Option A (new person) instead |
400 | firstName is mandatory / email is not valid | Missing or invalid required fields | Provide all required PII fields |
400 | documents.type and documents.fileIds are mandatory | Incomplete document object | Include both fields or omit the documents array entirely |
Submit KYC
| 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 |