> ## Documentation Index > Fetch the complete documentation index at: https://docs.trycherry.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a manual bank institution + accounts (write scope) > Create (or idempotently update) a manual bank institution and its accounts — the first step of the no-Plaid flow: create accounts here, then push their transactions through POST /transactions using the same `institutionName` and each account's `externalId`. Idempotent per (institution, account externalId): re-posting the same institution upserts onto the same synthetic bank item, and accounts absent from a later POST are left in place. An institution stays pinned to the entity it was first created under; posting it with a different `entityId` is a 409 conflict. Declare `openingBalance` (+ `openingBalanceDate`) so the books start from the real balance — Cherry posts it to the General Ledger and rolls it forward as transactions arrive. New accounts are auto-mapped to ledger accounts by kind (`ledgerMapped` in the response says whether that succeeded). Requires the `write` scope. ## OpenAPI ````yaml /openapi.json post /bank-accounts openapi: 3.0.3 info: title: Cherry API version: 1.0.0 description: >- Cherry's public developer API — programmatic access to a business's books as Cherry keeps them: bank transactions with their categorizations, the chart of accounts, the double-entry journal, financial statements, legal entities, the tax-obligation calendar, and the fiscal health score. Authenticate every request with an API key: `Authorization: Bearer ck_live_…`. Keys are created in the Cherry app and are scoped to one business (tenant) — there is no tenant id in any URL. Keys carry a `read` and/or `write` scope; every GET needs `read`, mutations need `write`. Conventions: successful responses wrap the payload in `{ "data": … }`; list endpoints add `{ "meta": { "pagination": { limit, offset, nextOffset } } }` — pass `nextOffset` back as `offset` until it is null. Errors are `{ "error": string, "reason"?: string }` with conventional status codes. Dates are `YYYY-MM-DD`; money amounts are numbers in the row's currency. Requests are rate-limited per key with token buckets (429 + `Retry-After` when exhausted); report generation has a smaller budget than plain reads. servers: - url: https://api.trycherry.ai/v1 security: - bearerAuth: [] tags: - name: Transactions description: Bank feed rows and their categorizations. - name: Accounts description: The tenant's chart of accounts. - name: Bank accounts description: >- Connected bank accounts — Plaid-linked and manual. Manual institutions are how developers without a Plaid connection bring their own accounts and transactions. - name: Journal description: The double-entry journal (entries and lines). - name: Reports description: Trial balance and financial statements. - name: Entities description: Legal entities behind the tenant. - name: Obligations description: The tax/compliance calendar Cherry tracks. - name: Health description: Cherry's composite fiscal readiness score. - name: Meta description: The API's own machine-readable contract. paths: /bank-accounts: post: tags: - Bank accounts summary: Create a manual bank institution + accounts (write scope) description: >- Create (or idempotently update) a manual bank institution and its accounts — the first step of the no-Plaid flow: create accounts here, then push their transactions through POST /transactions using the same `institutionName` and each account's `externalId`. Idempotent per (institution, account externalId): re-posting the same institution upserts onto the same synthetic bank item, and accounts absent from a later POST are left in place. An institution stays pinned to the entity it was first created under; posting it with a different `entityId` is a 409 conflict. Declare `openingBalance` (+ `openingBalanceDate`) so the books start from the real balance — Cherry posts it to the General Ledger and rolls it forward as transactions arrive. New accounts are auto-mapped to ledger accounts by kind (`ledgerMapped` in the response says whether that succeeded). Requires the `write` scope. operationId: createBankAccounts requestBody: required: true content: application/json: schema: type: object required: - institutionName - accounts properties: entityId: type: string format: uuid description: >- Legal entity to attach the institution to (UUID from GET /entities). Defaults to the tenant's primary entity. institutionName: type: string minLength: 1 maxLength: 80 description: >- Display name of the bank — also the key you pass to POST /transactions. accounts: type: array minItems: 1 maxItems: 20 items: type: object required: - externalId - name - kind properties: externalId: type: string maxLength: 64 pattern: ^[A-Za-z0-9._-]+$ description: >- Your stable key for the account (account number, IBAN, nickname). Referenced by every pushed transaction. name: type: string minLength: 1 maxLength: 120 currency: type: string pattern: ^[A-Z]{3}$ default: USD description: ISO 4217, e.g. USD. kind: type: string enum: - checking - savings - credit_card description: >- Drives ledger auto-mapping and keeps credit cards out of the cash position. openingBalance: type: number description: >- Balance as of openingBalanceDate, major units (positive for money held; Plaid sign applies to transactions, not this figure). openingBalanceDate: type: string format: date example: institutionName: First Community Bank accounts: - externalId: checking-1234 name: Business Checking ••1234 currency: USD kind: checking openingBalance: 18250.75 openingBalanceDate: '2026-01-01' responses: '201': description: The created (or updated) institution and its accounts content: application/json: schema: type: object properties: data: type: object properties: itemId: type: string description: Synthetic id of the manual bank item. accounts: type: array items: type: object properties: externalId: type: string bankAccountId: type: string format: uuid ledgerMapped: type: boolean example: data: itemId: >- manual:11111111-1111-1111-1111-111111111111:first-community-bank accounts: - externalId: checking-1234 bankAccountId: 22222222-2222-2222-2222-222222222222 ledgerMapped: true '400': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Error: type: object required: - error properties: error: type: string description: Stable machine-readable error code. reason: type: string description: Human-readable explanation. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: ck_live_… description: >- Cherry API key, created in the app. Sent as `Authorization: Bearer ck_live_…`. ````