# Bank accounts

> Link a client's bank accounts to an entity, or create CSV accounts and fill them with transactions from your own systems.

Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer <API key or access token>`.

## Create a CSV bank account and import transactions into it

`POST /api/public/v1/entities/{entityId}/bank-accounts/import`

SDK: `prosaic.bankAccounts.createWithTransactions(entityId, params)`

Creates a CSV bank account for the entity — one fed by imported files —
with its account in the entity's chart so its lines can be reconciled,
then imports the transactions into it. All or nothing.

Use this when the entity has no account for the statement, or when its
matching account is a bank feed, which can't take imported
transactions. The new account sits beside the feed account, so both
will need reconciling; prefer importing into an existing CSV account
with `POST /entities/{entityId}/bank-accounts/{bankAccountId}/import`.

The account belongs to the caller. Amounts are from the account
holder's side: money in positive, money out negative; never 0.

### Path parameters

- `entityId` (string, required)

### Request body

Content type: `application/json`

- `filename` (string, required)
- `transactions` (array of objects, required)
  - `date` (string, required)
  - `description` (string, required)
  - `amount` (number, required)
  - `transactionType` (string)
  - `payee` (string)
  - `code` (string)
  - `reference` (string)
  - `particulars` (string)
  - `bankTransactionId` (string)
- `name` (string, required)
- `institution` (string, required)
- `accountNumber` (string)

### Responses

- `201`: Successful response
  - `data` (object, required)
    - `bankAccountId` (string, required)
    - `bankAccountName` (string, required)
    - `institution` (string, nullable, required)
    - `accountNumber` (string, nullable, required)
    - `importId` (string, nullable, required)
    - `transactionsImported` (number, required)
    - `message` (string, required)
  - `meta` (object)
    - `count` (number, required)
- `400`: Invalid body (`VALIDATION_ERROR`, `INVALID_ROW_DATE`, `ZERO_AMOUNT_TRANSACTION`)
- `401`: Invalid or missing API key or token
- `404`: Entity not found or not accessible
- `500`: Internal server error

### Example (Node SDK)

```ts
const { data } = await prosaic.bankAccounts.createWithTransactions(entityId, {
  filename: 'Example Ltd',
  transactions: [
    {
      date: '2026-04-01',
      description: 'Office supplies',
      amount: 100,
    },
  ],
  name: 'Example Ltd',
  institution: 'string',
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/bank-accounts/import \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "Example Ltd",
    "transactions": [
      {
        "date": "2026-04-01",
        "description": "Office supplies",
        "amount": 100
      }
    ],
    "name": "Example Ltd",
    "institution": "string"
  }'
```

## Link bank accounts to an entity

`POST /api/public/v1/entities/{entityId}/bank-accounts`

SDK: `prosaic.bankAccounts.link(entityId, params)`

Links existing bank accounts to the entity, creating each one's general
ledger account in the entity's chart of accounts. Linking only ever adds:
accounts already on the entity are left as they are, and no account is
unlinked.

Each account must belong to a client of the entity — find them with
`GET /api/public/v1/clients/{clientId}/bank-accounts` — and must not be
linked to a different entity.

### Path parameters

- `entityId` (string, required)

### Request body

Content type: `application/json`

- `bankAccountIds` (array of strings, required)

### Responses

- `200`: Successful response
  - `data` (array of objects, required)
    - `id` (string, required)
    - `entityId` (string, nullable, required)
    - `externalId` (string, required)
    - `name` (string, required)
    - `alias` (string, nullable, required)
    - `institution` (string, nullable, required)
    - `accountNumber` (string, nullable, required)
    - `logoUrl` (string, nullable, required)
    - `type` (string, required)
    - `sourceType` (string, nullable, required)
    - `entityAccount` (object, nullable, required)
      - `id` (string, required)
      - `updatedAt` (string)
      - `reportCategoryReviewedAt` (string, nullable)
      - `reportCategoryReviewVersion` (number)
      - `code` (string, required)
      - `name` (string, required)
      - `type` (string, required)
      - `subtype` (string, required)
      - `reportGroup` (object, nullable, required)
        - `id` (string, required)
        - `key` (string, required)
        - `name` (string, required)
        - `status` (string, required)
        - `accountType` (string, required)
      - `reportCategory` (object, nullable, required)
        - `id` (string, required)
        - `key` (string, required)
        - `name` (string, required)
        - `status` (string, required)
      - `taxCode` (string, required)
      - `description` (string, nullable, required)
      - `mappedCode` (string, nullable, required)
      - `isSystem` (boolean, required)
      - `systemRole` (string, nullable)
      - `parentId` (string, nullable)
      - `isExcluded` (boolean)
      - `isIncluded` (boolean)
      - `source` (string): One of: `template`, `overridden`, `custom`.
  - `meta` (object)
    - `count` (number, required)
- `400`: Validation failed (`VALIDATION_ERROR`), an ID does not exist (`INVALID_BANK_ACCOUNT_IDS`), or an account does not belong to a client of the entity (`BANK_ACCOUNTS_CLIENT_MISMATCH`)
- `401`: Unauthorized - Invalid or missing API key/token
- `404`: Entity not found or not accessible
- `409`: An account is already linked to a different entity (`BANK_ACCOUNT_ASSIGNED_TO_DIFFERENT_ENTITY`)
- `500`: Internal server error

### Example (Node SDK)

```ts
const { data } = await prosaic.bankAccounts.link(entityId, {
  bankAccountIds: ['BANK_ACCOUNT_ID'],
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/bank-accounts \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bankAccountIds": [
      "BANK_ACCOUNT_ID"
    ]
  }'
```

## Import transactions into a CSV bank account

`POST /api/public/v1/entities/{entityId}/bank-accounts/{bankAccountId}/import`

SDK: `prosaic.bankAccounts.importTransactions(entityId, bankAccountId, params)`

Adds transactions to one of the entity's CSV bank accounts — the kind
fed by imported files (`sourceType: csv` on the bank account). Bank
feeds (`akahu`, `siss`) can't take imported transactions; create a
separate CSV account with `POST /entities/{entityId}/bank-accounts/import`
instead.

Rows the account already holds (same date, amount and description)
are skipped, so importing an overlapping statement is safe. Amounts
are from the account holder's side: money in positive, money out
negative. Zero amounts are rejected.

### Path parameters

- `entityId` (string, required)
- `bankAccountId` (string, required)

### Request body

Content type: `application/json`

- `filename` (string, required)
- `transactions` (array of objects, required)
  - `date` (string, required)
  - `description` (string, required)
  - `amount` (number, required)
  - `transactionType` (string)
  - `payee` (string)
  - `code` (string)
  - `reference` (string)
  - `particulars` (string)
  - `bankTransactionId` (string)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `bankAccountId` (string, required)
    - `bankAccountName` (string, required)
    - `importId` (string, nullable, required)
    - `transactionsImported` (number, required)
    - `transactionsSkipped` (number, required)
    - `message` (string, required)
  - `meta` (object)
    - `count` (number, required)
- `400`: Invalid body (`VALIDATION_ERROR`, `INVALID_ROW_DATE`,
`ZERO_AMOUNT_TRANSACTION`), a bank feed account
(`BANK_ACCOUNT_NOT_CSV`), or an account missing its owner or bank
(`BANK_ACCOUNT_NOT_IMPORTABLE`)

- `401`: Invalid or missing API key or token
- `404`: The entity or bank account wasn't found, or isn't accessible (`BANK_ACCOUNT_NOT_FOUND`)
- `500`: Internal server error

### Example (Node SDK)

```ts
const { data } = await prosaic.bankAccounts.importTransactions(entityId, bankAccountId, {
  filename: 'Example Ltd',
  transactions: [
    {
      date: '2026-04-01',
      description: 'Office supplies',
      amount: 100,
    },
  ],
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/bank-accounts/$BANK_ACCOUNT_ID/import \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "Example Ltd",
    "transactions": [
      {
        "date": "2026-04-01",
        "description": "Office supplies",
        "amount": 100
      }
    ]
  }'
```