Update mutable business profile fields (PATCH semantics).
Fields not present in the body are left untouched. Identity fields
(registration_number, country) and verification-state fields
(kyb_status, kyb_level, verification_mode) and the
verification provider applicant linkage are intentionally not editable here.
Once a business has been verified, the fields used in the
verification decision — company_name and tax_id — become
locked. Changing them after the fact would silently drift the
on-record identity from what the KYB provider / external attestation
evaluated. Operational fields (legal_address, contact_email)
stay editable so a business that relocates or changes ops contact
doesn't need a re-verify. To change a locked field, superadmin must
run kyb-reset first.
"Verified" is checked redundantly so the lock survives data
inconsistencies (e.g. legacy rows where verification_source is
NONE but kyb_status is APPROVED, or rows where the verification
provider created an applicant but the webhook hasn't landed yet):
kyb_status == approved(urbanpayx-decided approval)external_verification_status == verified(external attestation)verification_source != none(canonical post-decision state)- an identity verification applicant already exists for this business
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Update mutable profile fields on a business customer using PATCH semantics: only the fields you send are changed, and any field omitted from the body is left untouched. On success it returns the full updated business record. If nothing actually changes (every provided value matches what is already stored), the record is returned unchanged and no audit entry is written.
Only the following fields can be edited here: company_name, legal_address, tax_id, and contact_email. Identity fields (registration_number, country), verification-state fields (kyb_status, kyb_level, verification_mode), and the verification linkage are not editable through this endpoint.
Authentication & access
- Requires a client API token:
Authorization: Bearer <token>. - The caller must hold the
kyb.businesses.writepermission and have the OWNER or OPERATIONS role.
Path parameters
| Parameter | In | Description |
|---|---|---|
business_id | path | Identifier of the business customer to update. Must belong to your client. |
Request body
All fields are optional. Send only the fields you want to change.
| Field | Type | Constraints |
|---|---|---|
company_name | string | 1–255 characters. Leading/trailing whitespace is trimmed; a value that is empty after trimming is ignored. |
legal_address | string | Up to 512 characters. Trimmed; send an empty string to clear it. |
tax_id | string | Up to 128 characters. Trimmed; send an empty string to clear it. |
contact_email | string (email) | A valid email address, or an empty string to clear it. Stored lowercased. |
legal_address, tax_id, and contact_email accept an empty string as an explicit "clear this field" signal. Omitting a field entirely (PATCH semantics) leaves it as-is.
Identity fields lock after verification
Once a business has been verified, the two fields used in the verification decision — company_name and tax_id — become locked and can no longer be changed through this endpoint. Attempting to change a locked field returns 409. Operational fields (legal_address, contact_email) remain editable so a business that relocates or changes its operations contact does not need to re-verify.
A business is treated as verified (and therefore identity-locked) when any of the following holds: its KYB status is approved, its external attestation status is verified, its verification source is no longer unset, or a verification has already been initiated for it. To change a locked identity field, request a KYB reset from your account manager so the business can be re-verified.
Response
200 OK returns the updated business record (BusinessCustomerResponse), including id, company_name, registration_number, country, legal_address, tax_id, contact_email, kyb_status, verification_mode, kyb_level, external_verification_status, verification_source, external_verification_provider, external_verification_ref, external_verified_at, is_active, and created_at.
Error responses
| Status | When |
|---|---|
404 | No business customer with this business_id exists under your client |
409 | An attempt to change a locked identity field (company_name or tax_id) after the business has been verified |
422 | Request body failed validation (e.g. company_name too long, invalid contact_email, field over its length limit) |
Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.