Update user

put

https://api.balampay.com/sandbox/v1/users/{userId}

Update an existing user's information. All fields are optional — only the fields you include will be updated.

Automatic Re-verification:
If a sensitive field changes (e.g., name, birth_date, address, SSN, document info), automatic KYC/KYB re-verification is triggered in the background. The response includes requires_reverification to indicate this.

Response includes:

updated_fields — List of fields that were actually changed
requires_reverification — Whether KYC/KYB re-verification was triggered
eligible_products — Updated product eligibility after the change
missing_fields — KYC/KYB fields still required (if any)
warnings — Non-fatal issues (e.g., document upload failures)

Authentication: Both x-api-key header and Authorization: Bearer <token> header are required.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

userId

uuid

required

The unique identifier of the user

Body Params

Fields to update. All fields are optional — only include the ones you want to change.

Request to update a user. All fields are optional — only include the ones you want to change. Accepts both individual and business user fields.

first_name

string

User's first name

middle_name

string

User's middle name

last_name

string

User's last name

string

Valid email address

phone

string

Phone number in E.164 format

birth_date

string

^\d{4}-\d{2}-\d{2}$

Date of birth in YYYY-MM-DD format

nationality

string

3-letter ISO country code

gender

string

enum

Gender of the user

Allowed:

address_street

string

Street address

address_street_2

string

Apartment, suite, unit, etc.

address_city

string

City

address_state

string

State or province code

address_zip_code

string

ZIP or postal code

address_country

string

3-letter ISO country code

document_type

string

Government ID document type

document_number

string

Government ID document number

document_country

string

3-letter ISO country code of document

ssn

string

Social Security Number (USA only)

ein

string

Employer Identification Number (USA business)

cpf

string

Brazil CPF (individual tax ID)

curp

string

Mexico CURP (individual ID)

rfc

string

Mexico RFC (tax ID)

cnpj

string

Brazil CNPJ (business tax ID)

tax_id

string

Generic tax ID (international)

tax_id_type

string

Type of the generic tax ID

business_legal_name

string

Legal registered business name

business_trade_name

string

Trade name if different from legal name

doing_business_as

string

DBA name

business_type

string

enum

Business entity type

business_industry

array of strings

NAICS subsector codes (array)

business_industry

business_description

string

Description of business activities

business_website

uri

Business website URL

formation_date

string

^\d{4}-\d{2}-\d{2}$

Date of incorporation in YYYY-MM-DD format

formation_state

string

State/region where business was formed

representative_first_name

string

Legal representative's first name

representative_last_name

string

Legal representative's last name

representative_title

string

Representative's title (CEO, Director, etc.)

representative_birth_date

string

^\d{4}-\d{2}-\d{2}$

Representative's date of birth in YYYY-MM-DD format

representative_ssn

string

Representative's SSN (USA only)

source_of_funds

string

enum

Origin of funds

account_purpose

string

enum

Purpose of the account

employment_status

string

enum

Employment status. Required for ACT virtual accounts.

Allowed:

current_employer

string

Name of current employer. Applicable when employment_status is 'employed'.

income_source

string

Source of income. Applicable when employment_status is 'self_employed', 'retired', or 'unemployed'.

occupation

string

User's occupation

immigration_status

string

enum

U.S. residency status for non-U.S. citizens. Required for ACT virtual accounts (international individuals).

Allowed:

additional_info

object

Additional information for ACT virtual accounts (international individuals and international businesses). Required fields for eligibility: has_us_bank_account and has_denied_bank_account. Other fields (past_owner_interaction, any_politically_exposed_person, past_business_interaction) are optional and default to 'No' if not provided. If any field is 'Yes', provide an explanation in the corresponding '_explain' field.

pep_status

boolean

Is the user a Politically Exposed Person?

expected_monthly_payments

string

enum

Expected monthly transaction volume

Allowed:

identifying_information

array of objects

Tax IDs and government-issued identification documents with file uploads

identifying_information

associated_persons

array of objects

Ultimate Beneficial Owners and authorized signers (business only)

associated_persons

documents

array of objects

Legacy document array (use identifying_information.documents instead)

documents

tos_accepted_version

string

metadata

object

Custom key-value pairs

Headers

x-api-key

string

required

API key for authentication

Responses

401

Unauthorized - Invalid or missing authentication token

500

Internal Server Error

200User updated successfully

400Bad Request - Invalid input data

403Forbidden - Cannot update verified users

404User not found

409Conflict - Email or phone already exists

429Too Many Requests - Rate limit exceeded