> ## Documentation Index > Fetch the complete documentation index at: https://docs.tracefinance.com/llms.txt > Use this file to discover all available pages before exploring further. # Update a beneficial owner > Updates a beneficial owner using patch semantics. Only provided fields are changed. ## OpenAPI ````yaml apis/fx-account/openapi.yml PATCH /v1/accounts/{accountId}/ubos/{uboId} openapi: 3.1.1 info: title: FX Account API version: 1.0.0 description: API for managing multi-currency accounts on the Trace Finance platform. servers: - url: https://api.sandbox.tracefinance.com description: Sandbox security: - bearerAuth: [] tags: - name: Accounts description: Create, list, and manage multi-currency accounts. - name: Beneficial owners description: Manage beneficial owners (UBOs) for company-owned accounts. - name: Funding instructions description: Retrieve funding instructions for depositing into an account. - name: Balances description: Retrieve fiat and crypto balances for an account. paths: /v1/accounts/{accountId}/ubos/{uboId}: patch: tags: - Beneficial owners summary: Update a beneficial owner description: >- Updates a beneficial owner. All fields are optional (patch semantics) — only provided fields are updated. operationId: updateUbo parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/UboId' - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/TraceVersion' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateUBORequest' examples: nameOnly: summary: Update name only value: name: João Carlos Silva full: summary: Update all fields value: name: João Carlos Silva taxId: value: '98765432100' type: CPF address: addressLine1: Av. Paulista, 1000 city: São Paulo state: SP country: BR postalCode: 01310-100 ownershipPercentage: 75 responses: '200': description: Beneficial owner updated. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/UBOResponse' '400': description: Invalid request. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidTaxId: summary: UBO taxId fails the type-specific validator value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: VALIDATE_TAX_ID message: Tax ID is invalid for the given type field: body:taxId.value params: {} invalidData: summary: Request body failed validation value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: REQUIRED message: Parameter 'body:name' not found in request field: body:name params: {} '401': $ref: '#/components/responses/UnauthorizedError' '404': description: Account or beneficial owner not found. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: accountNotFound: $ref: '#/components/examples/AccountNotFound' uboNotFound: $ref: '#/components/examples/UboNotFound' '422': description: Business rule violation. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: ubosNotAllowedForIndividual: summary: >- Account has an individual owner (UBOs apply only to companies) value: code: UBOS_NOT_ALLOWED_FOR_INDIVIDUAL message: UBOs are not allowed for individual accounts details: taxId: '12345678900' accountNotModifiable: summary: Account is not in a modifiable state value: code: ACCOUNT_NOT_MODIFIABLE message: Account is not in a modifiable state details: accountId: 5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c approvedUbo: summary: Cannot modify a UBO that has already been approved value: code: APPROVED_UBO message: Cannot modify an approved UBO details: uboId: a1b2c3d4-e5f6-7890-1234-567890abcdef insufficientOwnership: summary: UBO ownership percentage is below the 25% threshold value: code: INSUFFICIENT_OWNERSHIP message: Beneficial owner ownership percentage must be at least 25% details: taxId: '12345678900' ownershipPercentage: 10 components: parameters: AccountId: name: accountId in: path required: true description: UUID of the account. schema: type: string format: uuid UboId: name: uboId in: path required: true description: UUID of the beneficial owner. schema: type: string format: uuid IdempotencyKey: name: X-Idempotency-Key in: header required: true description: >- Unique key to ensure idempotent request processing. Required on all `POST`, `PUT`, and `PATCH` requests. schema: type: string format: uuid TraceVersion: name: X-Trace-Version in: header required: false description: API version. Omit to use the default version. schema: type: string example: '1' schemas: UpdateUBORequest: type: object description: >- Request body for updating a beneficial owner. All fields are optional (patch semantics). properties: name: type: string description: Full legal name of the beneficial owner. example: João Silva taxId: $ref: '#/components/schemas/TaxIdRequest' address: $ref: '#/components/schemas/AddressRequest' phone: type: string description: Contact phone number with country code. example: '5511999999999' email: type: string format: email description: Contact email address. example: joao.silva@example.com ownershipPercentage: type: - number - 'null' format: double description: Percentage of ownership. example: 75 isLegalRepresentative: type: - boolean - 'null' description: >- Whether this beneficial owner is the legal representative of the account. example: false UBOResponse: type: object properties: id: type: string format: uuid example: b2c3d4e5-f6a7-8901-bcde-f12345678901 readOnly: true name: type: string example: João Silva taxId: $ref: '#/components/schemas/TaxIdResponse' address: $ref: '#/components/schemas/AddressResponse' phone: type: string example: '5511999999999' email: type: string format: email example: joao.silva@example.com ownershipPercentage: type: - number - 'null' format: double example: 50 isLegalRepresentative: type: boolean example: false currentState: $ref: '#/components/schemas/UBOState' required: - id - name - taxId - address - phone - email - isLegalRepresentative - currentState ErrorResponse: type: object description: >- Standard error envelope. The HTTP response also carries an `X-Request-Id` header — reference it when contacting Trace Finance support. See [Errors](/guides/principles/errors). properties: code: type: string description: Machine-readable error code. message: type: string description: Human-readable description. details: type: object additionalProperties: true required: - code - message TaxIdRequest: type: object description: >- Tax identifier for the owner or beneficial owner. Validated against the type-specific format rules. properties: value: type: string description: Tax identifier digits or alphanumeric value (depending on type). example: '11222333000181' type: $ref: '#/components/schemas/TaxIdType' required: - value - type AddressRequest: type: object properties: addressLine1: type: string example: Rua das Flores, 100 addressLine2: type: - string - 'null' example: Suite 456 city: type: string example: São Paulo state: type: string example: SP country: $ref: '#/components/schemas/Country' postalCode: type: string example: 01234-567 required: - addressLine1 - city - state - country - postalCode TaxIdResponse: type: object description: Tax identifier returned for an owner or beneficial owner. properties: value: type: string example: '11222333000181' type: $ref: '#/components/schemas/TaxIdType' required: - value - type AddressResponse: type: object properties: addressLine1: type: string example: Rua das Flores, 100 addressLine2: type: - string - 'null' example: Suite 456 city: type: string example: São Paulo state: type: - string - 'null' example: SP country: $ref: '#/components/schemas/Country' postalCode: type: string example: 01234-567 required: - addressLine1 - city - country - postalCode UBOState: type: object description: A point-in-time state of a beneficial owner. properties: status: type: string enum: - PENDING - APPROVED - REJECTED example: PENDING reason: $ref: '#/components/schemas/Reason' createdAt: type: string format: date-time example: '2026-01-15T10:30:00Z' required: - status - createdAt TaxIdType: type: string description: > Country-specific tax identifier type. The type itself implies the country (`CPF`/`CNPJ` are Brazilian, `CUIT`/`CUIL` are Argentine, `RUT_CL` is Chilean, etc.). enum: - CPF - CNPJ - CUIT - CUIL - RUT_CL - RUT_UY - CI_UY - RUC - DNI_PE - NIT - CC - RFC - RUC_PY - CI_PY - NIPC - NIF_PT - CIF - NIF_ES - NIE - SIREN - SIRET - NIF_FR - PARTITA_IVA - CODICE_FISCALE - UST_IDNR - STEUER_ID - KVK - BSN - BCE - NN_BE - ORGANISATIONSNUMMER - PERSONNUMMER - ORGANISASJONSNUMMER - FODSELSNUMMER - UID_CH - AHV - VAT_GB - NIN - EIN - SSN - ITIN - BN_CA - SIN - ABN - TFN - USCC - CORPORATE_NUMBER_JP - MY_NUMBER - BRN_KR - RRN - GSTIN - PAN - INN_RU - COMPANY_NUMBER_IL - TEUDAT_ZEHUT - TRADE_LICENSE - EMIRATES_ID - CIPC - SA_ID example: CNPJ Country: type: string description: ISO 3166-1 alpha-2 country code. example: BR enum: - AF - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BV - BR - IO - BN - BG - BF - BI - CV - KH - CM - CA - KY - CF - TD - CL - CN - CX - CC - CO - KM - CD - CG - CK - CR - HR - CU - CW - CY - CZ - CI - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - SZ - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - MK - RO - RU - RW - RE - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - GS - SS - ES - LK - SD - SR - SJ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - UM - US - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW - AX Reason: type: - object - 'null' description: Explains why a state transition occurred. properties: code: type: string description: Machine-readable error code. example: DOCUMENT_REJECTED message: type: string description: Human-readable description. example: Document is illegible details: type: object additionalProperties: true description: Additional context. May be empty. example: {} required: - code - message - details headers: RequestId: description: >- Unique request identifier emitted on every response. Reference it when contacting Trace Finance support so we can trace the request end-to-end. See [Errors](/guides/principles/errors). schema: type: string format: uuid responses: UnauthorizedError: description: Missing or invalid authentication token. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidToken: $ref: '#/components/examples/InvalidToken' expiredToken: $ref: '#/components/examples/ExpiredToken' examples: AccountNotFound: summary: Account does not exist for the authenticated customer value: code: RESOURCE_NOT_FOUND message: >- Account with given parameters [Account.id:5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c, Customer.id:c1a2b3c4-d5e6-7890-abcd-ef1234567890] not found details: resource: Account parameters: Account.id: 5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c Customer.id: c1a2b3c4-d5e6-7890-abcd-ef1234567890 UboNotFound: summary: Beneficial owner does not exist on the account value: code: RESOURCE_NOT_FOUND message: >- UBO with given parameters [UBO.id:a1b2c3d4-e5f6-7890-1234-567890abcdef] not found details: resource: UBO parameters: UBO.id: a1b2c3d4-e5f6-7890-1234-567890abcdef InvalidToken: summary: Bearer token is invalid or malformed value: code: INVALID_ACCESS_TOKEN message: Invalid access token details: {} ExpiredToken: summary: Bearer token has expired value: code: EXPIRED_ACCESS_TOKEN message: Expired access token details: {} securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT bearer token. Include as `Authorization: Bearer `. See the [Authentication](/guides/authentication) guide for how to obtain one. ````