Create an account

Creates a new multi-currency account for the authenticated customer.

POST /api/accounts

cURL

company

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

201

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": "INFORMATION_TECHNOLOGY", "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" }, "currentState": { "status": "PENDING", "createdAt": "2026-01-15T10:30:00Z", "reason": { "code": "DOCUMENT_REJECTED", "message": "Document is illegible", "details": {} } }, "ownershipPercentage": 50 } ] }, "assets": [ { "asset": "BRL", "allowsVirtualAccounts": false, "status": "ONBOARDING" } ], "requirements": { "currentlyDue": [ { "type": "DOCUMENT", "documentType": "ARTICLES_OF_ASSOCIATION", "documentSubType": "FRONT_SIDE", "group": "IDENTITY_VERIFICATION", "options": [ "ARTICLES_OF_ASSOCIATION" ], "uboId": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "requiredMetadata": [ "country" ], "metadata": {}, "reason": { "code": "DOCUMENT_REJECTED", "message": "Document is illegible", "details": {} } } ], "pendingVerification": [ { "type": "DOCUMENT", "documentType": "ARTICLES_OF_ASSOCIATION", "documentSubType": "FRONT_SIDE", "group": "IDENTITY_VERIFICATION", "options": [ "ARTICLES_OF_ASSOCIATION" ], "uboId": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "requiredMetadata": [ "country" ], "metadata": {}, "reason": { "code": "DOCUMENT_REJECTED", "message": "Document is illegible", "details": {} } } ], "errors": [ { "type": "DOCUMENT", "documentType": "ARTICLES_OF_ASSOCIATION", "documentSubType": "FRONT_SIDE", "group": "IDENTITY_VERIFICATION", "options": [ "ARTICLES_OF_ASSOCIATION" ], "uboId": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "requiredMetadata": [ "country" ], "metadata": {}, "reason": { "code": "DOCUMENT_REJECTED", "message": "Document is illegible", "details": {} } } ], "satisfied": [ { "type": "DOCUMENT", "documentType": "ARTICLES_OF_ASSOCIATION", "documentSubType": "FRONT_SIDE", "group": "IDENTITY_VERIFICATION", "options": [ "ARTICLES_OF_ASSOCIATION" ], "uboId": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "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.

Body

application/json

Request body for creating a new account.

assets · object[] · required

Desired asset currencies. At least one required; each code must be unique.

Minimum array length: 1

Show child attributes

owner · Company · object · required

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

Company

Individual

Show child attributes

Response

201

application/json

Account created.

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