Update an account

Replace the owner profile and asset selection for an account that has not been submitted for review yet.

PATCH /api/accounts/{accountId}

Update an account

cURL

curl --request PATCH \
  --url https://api.sandbox.tracefinance.com/api/accounts/{accountId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '
{
  "owner": {
    "type": "COMPANY",
    "legalName": "Acme Ltda",
    "taxId": {
      "value": "11222333000181",
      "type": "CNPJ"
    },
    "industry": "SOFTWARE_DEVELOPMENT",
    "expectedMonthlyVolume": "FROM_0_TO_50000",
    "incorporateDate": "2018-05-12",
    "isStartup": false,
    "address": {
      "addressLine1": "Rua das Flores, 100",
      "addressLine2": "Suite 456",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "postalCode": "01234-567"
    }
  }
}
'

200

Example

{ "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890", "customer": { "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890" }, "owner": { "type": "COMPANY", "legalName": "Acme Ltda", "taxId": { "value": "11222333000181", "type": "CNPJ" }, "industry": "SOFTWARE_DEVELOPMENT", "expectedMonthlyVolume": "FROM_0_TO_50000", "address": { "addressLine1": "Rua das Flores, 100", "city": "São Paulo", "country": "BR", "postalCode": "01234-567", "addressLine2": "Suite 456", "state": "SP" }, "ubos": [ { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "João Silva", "taxId": { "value": "11222333000181", "type": "CNPJ" }, "address": { "addressLine1": "Rua das Flores, 100", "city": "São Paulo", "country": "BR", "postalCode": "01234-567", "addressLine2": "Suite 456", "state": "SP" }, "phone": "5511999999999", "email": "[e-mail]", "isLegalRepresentative": false, "currentState": { "status": "PENDING", "createdAt": "2026-01-15T10:30:00Z", "reason": { "code": "DOCUMENT_REJECTED", "message": "Document is illegible", "details": {} } }, "ownershipPercentage": 50 } ] }, "assets": [ { "currency": "BRL", "allowsVirtualAccounts": false, "status": "ONBOARDING" } ], "requirements": { "currentlyDue": [ { "type": "ACCOUNT_DOCUMENT", "documentType": "ARTICLES_OF_ASSOCIATION", "documentSubType": "FRONT_SIDE", "requiredMetadata": [ "country" ], "metadata": {}, "reason": { "code": "DOCUMENT_REJECTED", "message": "Document is illegible", "details": {} } } ], "pendingVerification": [ { "type": "ACCOUNT_DOCUMENT", "documentType": "ARTICLES_OF_ASSOCIATION", "documentSubType": "FRONT_SIDE", "requiredMetadata": [ "country" ], "metadata": {}, "reason": { "code": "DOCUMENT_REJECTED", "message": "Document is illegible", "details": {} } } ], "errors": [ { "type": "ACCOUNT_DOCUMENT", "documentType": "ARTICLES_OF_ASSOCIATION", "documentSubType": "FRONT_SIDE", "requiredMetadata": [ "country" ], "metadata": {}, "reason": { "code": "DOCUMENT_REJECTED", "message": "Document is illegible", "details": {} } } ], "satisfied": [ { "type": "ACCOUNT_DOCUMENT", "documentType": "ARTICLES_OF_ASSOCIATION", "documentSubType": "FRONT_SIDE", "requiredMetadata": [ "country" ], "metadata": {}, "reason": { "code": "DOCUMENT_REJECTED", "message": "Document is illegible", "details": {} } } ] }, "tags": [ { "key": "psp", "value": "Amazon" }, { "key": null, "value": "hidden" }, { "key": "compliance-tier", "value": "high" } ], "currentState": { "status": "ACTION_REQUIRED", "createdAt": "2026-01-15T10:30:00Z", "reason": { "code": "DOCUMENT_REJECTED", "message": "Document is illegible", "details": {} } }, "states": [ { "status": "ACTION_REQUIRED", "createdAt": "2026-01-15T10:30:00Z", "reason": { "code": "DOCUMENT_REJECTED", "message": "Document is illegible", "details": {} } } ], "createdAt": "2026-01-15T10:30:00Z", "updatedAt": "2026-01-15T10:30:00Z", "sourceAccountId": null }

Authorizations

Authorization · string · header · required

JWT bearer token. Include as Authorization: Bearer <token>. See the Authentication guide for how to obtain one.

Headers

X-Trace-Version · string

API version. Omit to use the default version.

Example:

"1"

X-Idempotency-Key · string<uuid> · required

Unique key to ensure idempotent request processing. Required on all POST, PUT, and PATCH requests.

Path Parameters

accountId · string<uuid> · required

UUID of the account.

Body

application/json

Request body for updating an account. The supplied owner replaces the current owner profile; assets are not modifiable after creation.

owner · Company · object · required

The legal entity that owns the account. Discriminated by type.

Company

Individual

Show child attributes

Response

200

application/json

Account updated.

id · string<uuid> · required · read-only

Example:

"a1b2c3d4-5e6f-7890-abcd-ef1234567890"

customer · object · required

Show child attributes

owner · Company · object · required

The legal entity that owns the account. Discriminated by type.

Company

Individual

Show child attributes

assets · object[] · required

Assets enabled on the account, with the onboarding status of the underlying provider account.

Show child attributes

requirements · object · required

Requirement buckets grouped by lifecycle stage.

Show child attributes

tags · object[] · required

System-managed labels attached to the account. Some tags propagate to operations executed against this account.

Show child attributes

Example:

[
  { "key": "psp", "value": "Amazon" },
  { "key": null, "value": "hidden" },
  { "key": "compliance-tier", "value": "high" }
]

currentState · object · required

A point-in-time state of the account.

Show child attributes

states · object[] · required

Full state history of the account.

Show child attributes

createdAt · string<date-time> · required · read-only

Example:

"2026-01-15T10:30:00Z"

updatedAt · string<date-time> · required · read-only

Example:

"2026-01-15T10:30:00Z"

sourceAccountId · string<uuid> | null

Parent account ID. Null for named accounts.

Example:

null