User Management

What is a user?

When you integrate with Nium, your team — and potentially your customers' teams — will need to interact with Nium's APIs. That could mean reading customer details, creating new customers, initiating transactions, checking transaction history, or managing account settings. Anyone who interacts with these APIs, directly or on behalf of a customer, is a user in Nium's system.

Think of it this way: when you onboard a corporate customer, that business may have multiple people who need access — an operations manager who should only view balances and transactions, and a finance director who should be able to initiate payments. User Management lets you register each of these individuals and declare exactly what level of access they should have.

Every user in Nium has one of two access types:

• view — Read-only. Can retrieve customer details, check balances, and view transaction history. Cannot initiate any changes.
• edit — Full access. Can initiate transactions, manage account settings, and do everything view can do.

A user is always linked to a specific customer account — users cannot exist independently. The first user for any customer is created automatically by Nium when that customer completes onboarding (the default user). You use that default user's userHashId as the caller identity (x-user-id header) when creating additional users under the same customer.

Key concepts

Term	Description
Customer	An onboarded business or individual account
User	A person authorized to interact with Nium APIs on behalf of a customer account
defaultUser	Auto-created when a customer completes onboarding. Its userHashId is used as x-user-id when creating further users
userHashId	Nium's unique identifier for a user
client-user	A user created at the client level (your platform level)
customer-user	A user created under a specific customer account
externalId	Your own reference ID for the user — alphanumeric and hyphens, max 36 chars, unique per client
accessType	view (read-only) or edit (transact + manage)
existingEntityReferenceId	Reference ID of a stakeholder already registered during customer onboarding — use this to link an existing corporate stakeholder as a user without re-entering their details
LOA	Letter of Authority — required when a client-user creates a customer-user on behalf of a customer

APIs

Operation	Method	Endpoint	Reference
Create User	POST	/api/v1/client/{clientHashId}/users	Create User
List Users	GET	/api/v1/client/{clientHashId}/users	List Users
Get User	GET	/api/v1/client/{clientHashId}/user/{userHashId}	Get User
Update User	PUT	/api/v1/client/{clientHashId}/user/{userHashId}	Update User
User Lifecycle	POST	/api/v1/client/{clientHashId}/user/{userHashId}/lifecycle	User Lifecycle
Submit KYC	POST	/api/v1/client/{clientHashId}/userKyc	Submit User KYC

Prerequisites

Before creating a user:

• The customer must be in Clear status (v5 onboarding) or Completed status (v1/v4 onboarding) — complete customer onboarding first.
• The x-user-id header is mandatory on Create User — pass the default user's userHashId as the caller.

In this section

• Create User — Register a new person or link an existing corporate stakeholder as a user
• Submit KYC — Complete biometric identity verification for users who require it
• Manage Users — List, retrieve, and update user profiles
• Suspend / Revoke User — Temporarily suspend or permanently revoke user access
• Reference — Status codes, KYC statuses, webhook payload, and error codes