Skip to main content
GET
Entity accounts

Overview

Accounts are child resources of person and company entities. Use them to register multiple accounts per customer, including accounts in different currencies. Every account has a client-defined externalId, an ISO 4217 currency, and at least one payment identifier. Account data is isolated to the current organization.

Endpoints

The same CRUD exists for three entity lookups, matching update by external ID and PATCH /entities/by-tax-id/{taxId}: {accountId} is always the Gu1 account UUID from create/list. Tax ID lookup ignores punctuation and letter case (CUIT 20-12345678-9 matches 20123456789). It uses the same alphanumeric key as org-level tax uniqueness (idx_entities_org_norm_tax_id). URL-encode the path segment if the value contains reserved characters. Reading requires entities:read. Mutations require entities:edit with the legacy entities:write fallback.

Account fields

Accepted account types

accountType accepts only one of these values:
  • Generic: bank_account, personal, business, other
  • Bank deposits: checking, savings, business_checking, business_savings, payroll, pension, money_market, fixed_deposit
  • Investment and custody: investment, brokerage, custody, escrow
  • Payments and digital funds: payment, wallet, virtual_account, prepaid, merchant
  • Credit: credit, loan
  • Institutional operations: correspondent, settlement, clearing, cash_management
Use bank_account when you know the account is held at a bank but do not know its product type, and use other only when no category represents it. An unknown enum value returns 400 VALIDATION_ERROR. At least one of accountNumber, cbu, cvu, iban, or alias is required when creating an account.

Create example

Create with your externalId instead of the Gu1 UUID:
Create by tax ID (punctuation optional):
Setting isPrimary: true removes the primary flag from other accounts of the same entity and currency.

Errors