> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Entity accounts

> Register and manage financial accounts owned by a person or company entity.

## 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](/en/api-reference/entities/update-by-external-id) and `PATCH /entities/by-tax-id/{taxId}`:

| Method           | Path                                                         | Entity lookup                   |
| ---------------- | ------------------------------------------------------------ | ------------------------------- |
| `GET` `POST`     | `/entities/{id}/accounts`                                    | Gu1 UUID                        |
| `PATCH` `DELETE` | `/entities/{id}/accounts/{accountId}`                        | Gu1 UUID                        |
| `GET` `POST`     | `/entities/by-external-id/{externalId}/accounts`             | Your `externalId` (exact match) |
| `PATCH` `DELETE` | `/entities/by-external-id/{externalId}/accounts/{accountId}` | Your `externalId`               |
| `GET` `POST`     | `/entities/by-tax-id/{taxId}/accounts`                       | Tax ID, denormalized            |
| `PATCH` `DELETE` | `/entities/by-tax-id/{taxId}/accounts/{accountId}`           | Tax ID, denormalized            |

`{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

| Field           | Type    |    Required | Description                                                       |
| --------------- | ------- | ----------: | ----------------------------------------------------------------- |
| `externalId`    | string  |         Yes | Account identifier in your system; unique within the organization |
| `currency`      | string  |         Yes | ISO 4217 code, such as `USD`, `ARS`, or `BRL`                     |
| `accountType`   | enum    |          No | Canonical account type; see the accepted values below             |
| `status`        | string  |          No | `active`, `inactive`, `frozen`, or `closed`; default `active`     |
| `countryCode`   | string  |          No | ISO 3166-1 alpha-2 country                                        |
| `accountNumber` | string  | Conditional | Generic account number                                            |
| `cbu`           | string  | Conditional | 22-digit CBU                                                      |
| `cvu`           | string  | Conditional | 22-digit CVU                                                      |
| `iban`          | string  | Conditional | IBAN, up to 34 characters                                         |
| `alias`         | string  | Conditional | Account alias                                                     |
| `bankName`      | string  |          No | Bank or financial institution                                     |
| `bankCode`      | string  |          No | Client-defined bank code                                          |
| `isPrimary`     | boolean |          No | Primary account for the entity and currency                       |
| `metadata`      | object  |          No | Client-specific additional data                                   |
| `openedAt`      | string  |          No | ISO 8601 opening timestamp                                        |
| `closedAt`      | string  |          No | ISO 8601 closing timestamp                                        |

### 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

```bash theme={null}
curl -X POST "https://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "account-usd-001",
    "currency": "USD",
    "accountType": "savings",
    "accountNumber": "ACC-001",
    "countryCode": "AR",
    "isPrimary": true
  }'
```

```json theme={null}
{
  "success": true,
  "account": {
    "id": "77c2ca62-4528-4d2e-a424-ff7c0ee7ab18",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "account-usd-001",
    "currency": "USD",
    "accountType": "savings",
    "status": "active",
    "accountNumber": "ACC-001",
    "isPrimary": true
  }
}
```

Create with your `externalId` instead of the Gu1 UUID:

```bash theme={null}
curl -X POST "https://api.gu1.ai/entities/by-external-id/merchant-99/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "account-usd-001",
    "currency": "USD",
    "accountType": "savings",
    "accountNumber": "ACC-001",
    "isPrimary": true
  }'
```

Create by tax ID (punctuation optional):

```bash theme={null}
curl -X POST "https://api.gu1.ai/entities/by-tax-id/20-12345678-9/accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "account-ars-001",
    "currency": "ARS",
    "cbu": "0000003100000000000001"
  }'
```

Setting `isPrimary: true` removes the primary flag from other accounts of the same entity and currency.

## Errors

| HTTP  | Code               | When                                                                                  |
| ----- | ------------------ | ------------------------------------------------------------------------------------- |
| `400` | `VALIDATION_ERROR` | Input is invalid, `accountType` is outside the enum, or no payment identifier remains |
| `404` | `NOT_FOUND`        | Entity or account does not exist in the current organization                          |
| `409` | `CONFLICT`         | `externalId` already exists in the current organization                               |