> ## 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. # Open a named account > Step-by-step guide to opening a BRL account held in the account owner's name. ## Overview A named account is a fiat account held in the account owner's name. Use `NAMED` for Brazilian residents and `NAMED_NON_RESIDENT` for non-residents. Every account is multi-currency, so crypto support is always included alongside the fiat assets you enable. Named accounts follow Trace Finance's compliance baseline and add segment-specific information and documents on top, depending on the owner's profile (payment facilitators, non-residents, startups, crypto businesses, funds, and exchange operators). The exact set for your account is always returned in `requirements.currentlyDue` when you create it. See [BRL named accounts](/guides/compliance/brl-named-accounts) for the full checklist. ## Prerequisites * Valid [authentication credentials](/guides/authentication). * Account owner details: legal name (or first and last name for an individual), tax ID, industry, expected monthly volume, and address. * The document checklist for the owner's segment. See [BRL named accounts](/guides/compliance/brl-named-accounts). The documents that apply to your account appear in `requirements.currentlyDue` after creation. ## Steps Submit a request with the fiat assets to enable and the account owner's details. Set each fiat asset's `accountType` to `NAMED`, or to `NAMED_NON_RESIDENT` for a non-resident owner. Crypto support is always included, so you don't declare it or set its `accountType`. ```bash theme={"theme":"tokyo-night"} curl --request POST \ --url https://api.sandbox.tracefinance.com/v1/accounts \ --header 'Authorization: Bearer ' \ --header 'X-Idempotency-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "assets": [ { "code": "BRL", "accountType": "NAMED" } ], "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" } } }' ``` The response returns the account in `ACTION_REQUIRED` status, with the document types required for onboarding listed under `requirements.currentlyDue`. For an individual owner, set `owner.type` to `INDIVIDUAL` and provide `firstName` and `lastName` instead of `legalName`. To fix a rejected field after creation, use [`PATCH /v1/accounts/{accountId}`](/api-reference/fx-account/accounts/update-account) to replace the owner profile before submitting for review. Named accounts often require additional segment-specific documents, for example for payment facilitators, non-residents, startups, crypto businesses, funds, or exchange operators. Whatever applies to your account is listed in `requirements.currentlyDue`. See [BRL named accounts](/guides/compliance/brl-named-accounts) for the full breakdown by segment. The creation response includes a `requirements.currentlyDue` array listing every document you need to provide. Each item carries a `type` discriminator. `ACCOUNT_DOCUMENT` and `UBO_DOCUMENT` name a specific `documentType`, while `IDENTITY_VERIFICATION` and `INCORPORATION_DOCUMENT` are grouped requirements whose `options` array lists the acceptable document types together with the `subTypes` and `requiredMetadata` each option needs. Upload documents against the `/v1/accounts/{accountId}/documents` endpoint, setting `holder.type` to `ACCOUNT` and `holder.referenceId` to the account ID: ```bash theme={"theme":"tokyo-night"} curl --request POST \ --url https://api.sandbox.tracefinance.com/v1/accounts//documents \ --header 'Authorization: Bearer ' \ --header 'X-Idempotency-Key: ' \ --form 'body={"documentType":"ARTICLES_OF_ASSOCIATION","holder":{"type":"ACCOUNT","referenceId":""}};type=application/json' \ --form 'file=@/path/to/articles-of-association.pdf' ``` Returns `204 No Content`. Upload one document per request, repeating for every requirement listed in `currentlyDue`. Company-owned accounts require at least one beneficial owner (UBO). Register each UBO with their identity, contact, and address details. `phone` and `email` are required so we can reach the UBO for follow-up during compliance review. ```bash theme={"theme":"tokyo-night"} curl --request POST \ --url https://api.sandbox.tracefinance.com/v1/accounts//ubos \ --header 'Authorization: Bearer ' \ --header 'X-Idempotency-Key: ' \ --header 'Content-Type: application/json' \ --data '{ "name": "João Silva", "taxId": { "value": "12345678909", "type": "CPF" }, "address": { "addressLine1": "Rua das Flores, 100", "city": "São Paulo", "state": "SP", "country": "BR", "postalCode": "01234-567" }, "phone": "5511999999999", "email": "joao.silva@example.com", "ownershipPercentage": 50.0, "isLegalRepresentative": false }' ``` The response includes the UBO's `id`, which you'll need for uploading their documents. Individual accounts have no UBOs, so skip this step and the next one. Each UBO needs identity documents. Use the same `/v1/accounts/{accountId}/documents` endpoint, this time setting `holder.type` to `UBO` and `holder.referenceId` to the UBO's `id`. Identity documents typically require a `documentSubType` (for example `FRONT_SIDE` or `BACK_SIDE`) and a `metadata.country`: ```bash theme={"theme":"tokyo-night"} curl --request POST \ --url https://api.sandbox.tracefinance.com/v1/accounts//documents \ --header 'Authorization: Bearer ' \ --header 'X-Idempotency-Key: ' \ --form 'body={"documentType":"ID_CARD","documentSubType":"FRONT_SIDE","holder":{"type":"UBO","referenceId":""},"metadata":{"country":"BR"}};type=application/json' \ --form 'file=@/path/to/ubo-id-front.pdf' ``` Returns `204 No Content`. Repeat for every side and every UBO registered on the account. Once all required documents are uploaded, submit the account for compliance review. This endpoint has no request body: ```bash theme={"theme":"tokyo-night"} curl --request POST \ --url https://api.sandbox.tracefinance.com/v1/accounts//review \ --header 'Authorization: Bearer ' \ --header 'X-Idempotency-Key: ' ``` Returns `202 Accepted`. The account transitions from `ACTION_REQUIRED` to `REVIEWING`. If any documents are still missing or rejected, the API returns `422` with a `MISSING_DOCUMENTS_FOR_REVIEW` error listing the outstanding `documentType` names. After review is approved, each asset activates on its own pipeline. The crypto wallet always activates first, since it has no manual steps, but the crypto wallet activating does not move the account to `ACTIVE`. The account moves through `OPENING` and becomes `ACTIVE` only once a fiat asset finishes onboarding. Subscribe to the [`ACCOUNT_ASSET_ACTIVATED`](/api-reference/fx-webhook/events/account/account-asset-activated) and [`ACCOUNT_ASSET_FAILED`](/api-reference/fx-webhook/events/account/account-asset-failed) webhooks to react as each asset finishes, or poll [`GET /v1/accounts/{accountId}`](/api-reference/fx-account/accounts/get-account). Each entry in the response's `assets` array carries its own provider-account `status` (`ONBOARDING`, `ACTIVE`, `FAILED`, `FROZEN`, `DEACTIVATED`) so you can see which assets are ready. Once the account is active, retrieve the incoming transfer details for each active asset: ```bash theme={"theme":"tokyo-night"} curl --request GET \ --url https://api.sandbox.tracefinance.com/v1/accounts//fundingInstructions \ --header 'Authorization: Bearer ' ``` ```json Response theme={"theme":"tokyo-night"} [ { "asset": "BRL", "type": "PIX_KEY", "rail": "PIX_KEY", "keyType": "CNPJ", "key": "12345678000101", "accountIdentifier": null } ] ``` For a named account, the BRL Pix key is registered in the account owner's name, so `keyType` reflects the owner's tax ID (`CNPJ` for a company, `CPF` for an individual). Filter the catalog with the optional `asset` and `rail` query parameters when you only need one rail for an asset. ## What happens next * [Make a deposit](/journeys/deposit) — fund the account with BRL or crypto. * [Execute a swap](/journeys/swap) — convert between the account's assets.