Create User

Use the Create User API to register a user under an existing customer. You can create a user in two ways: register a new person entirely, or link an existing corporate stakeholder.

Prerequisites

• The customer must be in Clear status (v5 onboarding) or Completed status (v1/v4 onboarding). Complete customer onboarding first.
• When a customer is created, Nium automatically creates a default user from the applicant's details and returns their userHashId in the Create Customer response.
• The x-user-id header is mandatory on Create User — pass the default user's userHashId as the caller.

Access types

Access Type	What it allows
view	Read-only — retrieve customer details, check balances, view transaction history
edit	Full access — initiate transactions, manage account settings, and all view capabilities

KYC requirements

Whether KYC is required depends on the user's scenario:

Scenario	KYC required?	Remarks
Default user (auto-created at onboarding)	No	KYC completed during customer creation
Stakeholder already verified through biometric mode	No	KYC completed during customer creation
New user — edit access type	Yes	Biometric (EU)
Stakeholder verified through manual process	Yes	Biometric (EU)
New user — view access type	No	Screening only
Stakeholder — view access type	No	Screening only

note

edit access users require full biometric KYC verification. view access users require screening only.

Option A — New person

Use when the person's details are not already present in Nium's system.

Required fields: region, customerHashId, accessType, firstName, lastName, nationality, dateOfBirth, email, externalId, mobile, mobileCountryCode, address, deviceDetails, and documents (power_of_attorney — required only when a client-user is creating the customer-user)

note

Letter of Authority (power_of_attorney): When a client-user creates a customer-user, a power_of_attorney document is required. Upload the file first using the Create a File API and pass the returned fileId in the documents array.

Request:

POST /api/v1/client/{clientHashId}/users
x-user-id: <default-user-userHashId> or <client-user-userHashId>
Content-Type: application/json

{
  "region": "EU",
  "customerHashId": "df35f425-e2f2-4cfc-b07b-5e62e84cd8e6",
  "accessType": "edit",
  "firstName": "Lue",
  "middleName": "Heather",
  "lastName": "Schuster",
  "nationality": "FR",
  "dateOfBirth": "1990-03-03",
  "externalId": "fdbfe7ee-310c-4896-902d-2821a3db0592",
  "email": "lue.schuster@example.com",
  "mobile": "5608713094",
  "mobileCountryCode": "65",
  "documents": [
    {
      "type": "power_of_attorney",
      "fileIds": ["9fc6e2a5-786f-4c25-bd6d-1f4c9b9b2b44"]
    }
  ],
  "address": {
    "addressLine1": "38 Beach Road, 06-11",
    "addressLine2": "South Beach Tower",
    "city": "Singapore",
    "postcode": "189768",
    "country": "SG",
    "state": ""
  },
  "deviceDetails": {
    "ipCountryCode": "IN",
    "deviceInfo": "Macintosh; Intel Mac OS X",
    "ipAddress": "167.103.24.253",
    "sessionId": "5aadd5c9-7174-40ff-9da4-a03fee2456b6"
  }
}

Response:

{
  "userHashId": "a3b4c5d6-e7f8-9012-abcd-ef1234567890",
  "externalId": "fdbfe7ee-310c-4896-902d-2821a3db0592",
  "status": "pending",
  "kycStatus": "pending"
}

note

The user is created in pending status. Configure the USER_STATUS_WEBHOOK to receive kycStatus updates.

• If kycStatus="kyc_required" → call Submit KYC to activate access.
• If kycStatus="kyc_not_required" → no further action needed. Wait for webhook for final status.

Request fields:

Field	Type	Required	Description
region	string	Yes	Region for the user. Use EU for Phase 1.
customerHashId	string (UUID)	Yes	Identifier of the customer under which this user is being created.
accessType	string	Yes	view — read-only; edit — transact and manage.
firstName	string	Yes	User's first name.
middleName	string	No	User's middle name.
lastName	string	Yes	User's last name.
nationality	string	Yes	ISO 3166-1 alpha-2 country code (e.g. FR).
dateOfBirth	string	Yes	YYYY-MM-DD format.
email	string	Yes	User's email address.
externalId	string	Yes	Your reference ID. Alphanumeric and hyphens only, max 36 chars. Must be unique per client.
mobile	string	Yes	Mobile number, digits only, without country code.
mobileCountryCode	string	Yes	Country dial code (e.g. 65 for Singapore).
documents	array	Conditional	Required when a client-user creates a customer-user. Must include a power_of_attorney document.
documents[].type	string	Yes (if documents present)	Document type. Use power_of_attorney for Letter of Authority.
documents[].fileIds	array of strings	Yes (if documents present)	File IDs returned by the Create a File API.
address	object	Yes	User's residential address.
address.addressLine1	string	Yes	Street address, line 1.
address.addressLine2	string	No	Street address, line 2.
address.city	string	Yes	City.
address.postcode	string	Yes	Postal or ZIP code.
address.country	string	Yes	ISO 3166-1 alpha-2 country code.
address.state	string	Yes	State or province.
deviceDetails	object	Yes	Device and session info of the caller.
deviceDetails.ipCountryCode	string	Yes	ISO 3166-1 alpha-2 country code of the IP address.
deviceDetails.deviceInfo	string	Yes	User-agent or device description string.
deviceDetails.ipAddress	string	Yes	IP address of the caller's device.
deviceDetails.sessionId	string	Yes	Unique session identifier (UUID).

Option B — Stakeholder link (corporate customers only)

Use when the person is already on the corporate KYB record (e.g. a director or UBO). Nium resolves their personal details automatically from the existing record — no need to re-submit PII.

Required fields: region, customerHashId, existingEntityReferenceId, accessType, deviceDetails

Request:

POST /api/v1/client/{clientHashId}/users
x-user-id: <default-user-userHashId>
Content-Type: application/json

{
  "region": "EU",
  "customerHashId": "df35f425-e2f2-4cfc-b07b-5e62e84cd8e6",
  "externalId": "fdbfe7ee-310c-4896-902d-2821a3db0592",
  "existingEntityReferenceId": "9fc6e2a5-786f-4c25-bd6d-1f4c9b9b2b44",
  "accessType": "edit",
  "deviceDetails": {
    "ipCountryCode": "IN",
    "deviceInfo": "Macintosh; Intel Mac OS X",
    "ipAddress": "167.103.24.253",
    "sessionId": "5aadd5c9-7174-40ff-9da4-a03fee2456b6"
  }
}

Response:

{
  "userHashId": "a3b4c5d6-e7f8-9012-abcd-ef1234567890",
  "externalId": "fdbfe7ee-310c-4896-902d-2821a3db0592",
  "status": "pending",
  "kycStatus": "pending"
}

Request fields:

Field	Type	Required	Description
region	string	Yes	Region for the user. Use EU for Phase 1.
customerHashId	string (UUID)	Yes	Identifier of the corporate customer under which this user is being created.
existingEntityReferenceId	string (UUID)	Yes	Reference ID of the stakeholder from the Create Customer response.
accessType	string	Yes	view — read-only; edit — transact and manage.
externalId	string	No	Your reference ID. Alphanumeric and hyphens only, max 36 chars. Must be unique per client.
deviceDetails	object	Yes	Device and session info of the caller. See Option A for field details.

Error codes

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