​
Overview

End users are the customers your platform serves. Each one carries the identity and verification data the banking partner needs to let them hold and move funds. End users come in two shapes:
  • Individuals (KYC) — a natural person, verified through Know Your Customer checks.
  • Businesses (KYB) — a company plus its directors and ultimate beneficial owners, verified through Know Your Business checks.
Only LINKED_MEMBER accounts can create and manage end users. See Account types & capabilities.

List end users

Page through every end user you’ve onboarded.

Create an individual (KYC)

Onboard a natural person.

Create a business (KYB)

Onboard a company with its persons.

Update an end user

Patch profile fields after creation.

​
Onboarding flow

1

Create the end user

Submit the individual (KYC) or business (KYB) create request with the core profile and address. For individuals, verificationMethod defaults to hosted_kyc, so the response includes a hosted KYC link your end user completes.
2

Upload documents (if required)

Where verification needs supporting evidence — or for USD services — upload identity and proof-of-address documents. See Document upload.
3

Wait for verification

The end user sits in pending_verification until the banking partner completes checks, then transitions to active. Subscribe to Webhooks for status changes rather than polling.
4

Use the end user

Once active, link the end user to virtual accounts, payees, and payments.

​
End user object

​
id
string
Unique Balansas identifier (UUID). Use this everywhere.
​
fr_end_user_id
string
Banking partner end user ID (reference only).
​
first_name
string
First name (1–100 characters).
​
last_name
string
Last name (1–100 characters).
​
email
string
Valid email (max 255 characters).
​
status
string
pending_verification, active, or inactive.
​
created_at
string
ISO 8601 timestamp.
​
updated_at
string
ISO 8601 timestamp.

​
Individual (KYC) create request

​
firstName
string
required
1–100 characters.
​
lastName
string
required
1–100 characters.
​
email
string
required
Valid email, max 255 characters.
​
dob
string
required
Date of birth, YYYY-MM-DD.
​
address
object
required
Nested address — line1, city, postalCode, and country (2-letter ISO) are required; line2 and state are optional.
​
phone
string
Optional; required for USD services (max 20 chars).
​
nationality
string | string[]
2-letter ISO code or array of codes. Required for USD services.
​
birthCountry
string
2-letter ISO code.
​
identificationDocument
object
{ type, number } where type is one of PASSPORT, NATIONAL_ID, DRIVERS_LICENCE, WORK_PERMIT. Required for USD services.
​
verificationMethod
string
hosted_kyc (default) or pdf_upload. pdf_upload requires umbrellaLinkId and a kycReportBase64. See PPA Mode.
​
umbrellaLinkId
string
UUID. Provision under a Balansas-managed master business in PPA Mode.
curl -X POST https://stagingapi.balansas.com/functions/v1/customer-api/end-users \
  -H "x-api-key: sk_test_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-CSRF-Token: <64-char-hex>" \
  -H "Content-Type: application/json" \
  -d '{
        "firstName": "John",
        "lastName": "Smith",
        "email": "[email protected]",
        "dob": "1990-04-12",
        "address": {
          "line1": "10 Downing St",
          "city": "London",
          "postalCode": "SW1A 2AA",
          "country": "GB"
        }
      }'

​
Business (KYB) create request

The business create request nests the company profile under business and its people under businessPersons.
​
business
object
required
Company profile. Requires companyName, type (one of LIMITED_LIABILITY_COMPANY, PUBLIC_LIMITED_COMPANY, PARTNERSHIP, SOLE_PROPRIETORSHIP, OTHER), registrationNumber, registrationDate (YYYY-MM-DD), email, incorporationCountry, plus registeredAddress and tradingAddress.
​
businessPersons
array
required
At least one person. Each entry has a person profile, types (one or more of UBO, DIRECTOR), and an ownership percentage (0–100).
​
sector
string
Business sector (max 100 characters).

​
Document upload

Some verification flows require supporting documents (identity, proof of address). Upload them against an end user as base64-encoded file data.
​
endUserId
string
required
UUID of the end user the document belongs to.
​
documentType
string
required
One of IDENTITY_VERIFICATION, identity, proof_of_address, other.
​
fileName
string
required
1–255 characters.
​
fileData
string
required
Base64-encoded file contents.
​
mimeType
string
required
One of application/pdf, image/jpeg, image/png.

Upload a verification document

Full request and response in the API Reference.

​
Updating an end user

Use the update (PATCH) endpoint to amend profile fields — name, email, phone, nationality, identification document — after creation. Send only the fields you want to change.

Update an end user

See the patchable fields in the API Reference.