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

# Accounts and balances

> Open accounts, read balances and receive money by bank transfer.

An account holds money in one currency. You can hold several accounts in the same currency, for example "Operations" and "Payroll" in GBP.

Scopes: `accounts:read` to list, `accounts:write` to open.

## Open an account

```bash curl theme={null}
curl https://api.talescria.com/v1/accounts \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: open-gbp-operations" \
  -H "Content-Type: application/json" \
  -d '{"currency": "GBP", "name": "Operations", "accountType": "operational"}'
```

```python Python theme={null}
resp = requests.post(
    "https://api.talescria.com/v1/accounts",
    headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "open-gbp-operations"},
    json={"currency": "GBP", "name": "Operations", "accountType": "operational"},
    timeout=30,
)
account = resp.json()["account"]
```

| Field | Notes |
| - | - |
| `currency` | One of `USD`, `GBP`, `EUR`, `NGN`, `KES`, `ZAR`, `GHS`. |
| `name` | Required, up to 100 characters. It's how you tell accounts in the same currency apart. |
| `accountType` | `operational` (default), `checking`, `debit` or `safeguard`. Use `safeguard` for client money you hold on others' behalf. |

### The default account

The first account you open in a currency becomes that currency's **default** (`isDefault: true`). Card payments from [checkout](https://docs.talescria.com/guides/checkout.md) in that currency land in the default account. Payment links and invoices name their own receiving account.

## Read balances

`GET /v1/accounts` returns every account with three balances:

```json theme={null}
{
  "accountId": "acct_01M2P8GP7RSDXN81CXRFM2HFV7",
  "status": "ok",
  "name": "Operations",
  "currency": "GBP",
  "isDefault": true,
  "accountType": "operational",
  "available": { "minorUnits": "125000", "currency": "GBP" },
  "posted": { "minorUnits": "125000", "currency": "GBP" },
  "pending": { "minorUnits": "0", "currency": "GBP" }
}
```

Show `available` as the balance: it's `posted` minus what outgoing payments have reserved (`pending`). See [Money](https://docs.talescria.com/concepts/money.md).

The response also has `totals`, one entry per currency, adding up the accounts that resolved.

### Unresolved accounts

Rarely, an account can't be read accurately. It's still listed, so you know it exists, but with `status: "unresolved"`, a `reason`, and **no amounts**. Leave it out of any total and try again later. `unresolved` at the top level counts them.

## Receive money by bank transfer

Where an account can receive bank transfers, it carries `deposit`: the details a payer sends money to.

```json theme={null}
"deposit": {
  "status": "ready",
  "scheme": "faster_payments",
  "fields": [
    { "key": "account_number", "label": "Account number", "value": "12345678" },
    { "key": "sort_code", "label": "Sort code", "value": "04-00-04" }
  ]
}
```

* Render `fields` in order using each `label`. The fields differ by currency: an account number and sort code for GBP, an IBAN and BIC for EUR.
* `status: "pending"` means the details are being set up and can't receive money yet. `fields` is absent until they're `ready`.
* No `deposit` means the account doesn't receive bank transfers. It can still hold money and pay out.

Money that arrives is credited to the account automatically.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.