> For the complete documentation index, see [llms.txt](https://docs.kick.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kick.co/api/api-reference/financial-accounts.md).

# Financial Accounts

List a workspace's financial accounts and their sync health, then rename one, change its bookkeeping dates, move it to another entity, or delete it.

A financial account is a bank, card, loan, or payment account whose transactions Kick keeps books for. Listing takes the workspace as a required `workspaceId` query param and returns accounts across every entity in it. The other endpoints address a single account by its uuid alone, with no workspace in the path. The list covers accounts of every `source`: integrations such as `plaid` or `stripe`, file imports, and manual accounts. Pass `entityIds` to narrow it to specific entities, either as one value or as a repeated query param. An entity outside the workspace is rejected with `400`. Accounts your integration opened through [Plaid Connections](https://docs.kick.co/api/api-reference/plaid-connections.md) or [Stripe Connections](https://docs.kick.co/api/api-reference/stripe-connections.md) show up here too.

Updates are partial: fields left out of the body keep their current value, and a body with no fields is rejected with `400`. Pass `null` to `bookkeepingStartDate` to follow the entity's bookkeeping start date again, or to `bookkeepingEndDate` to make the account open-ended. Changing either date regenerates the account's journal entries. A start date before the entity's bookkeeping start date or an end date before the start date is rejected with `400`. A change blocked by the account's state answers `409` with the reason: the start date can't move while the account is reconciled or has an opening balance, and the end date can't fall before the end of one of its bank reconciliations.

Moving an account takes its transactions, documents, and accounting data to another entity of the same workspace and keeps its bookkeeping dates. Moving it to the entity it already belongs to changes nothing. An entity of another workspace is rejected with `400`, and so is a move when the account's journal entries post to an account that doesn't exist in the target entity's Chart of Accounts.

Deleting an account is permanent and removes its transactions with it. An integration connection left with no accounts is deleted too. An account that manual journal entries post to answers `409` unless you pass `forceDeletion=true`, which deletes those journal entries as well. An account referenced by consolidation eliminating entries answers `409` either way.

Updating, moving, or deleting an account whose workspace is on the Read-only plan is refused with `403`, while listing still works. Pagination and error formats work as described in [Getting Started](https://docs.kick.co/api/readme.md).

## List financial accounts

> Returns the financial accounts assigned to the entities of the workspace given by \`workspaceId\`, whatever their source. A workspace outside the organization reads as not found. \`entityIds\` optionally narrows the list to specific entities; a single or a repeated query param both work, and an entity outside the workspace is rejected with 400. Results are paged with \`limit\`/\`offset\`. \`transactionsSyncedAt\`, \`balanceSyncedAt\`, \`syncStatus\` and \`syncErrorCode\` roll up every connection feeding the account: the sync times are the latest across them, and the account reads as \`healthy\` as long as one of them still syncs.

```json
{"openapi":"3.0.2","info":{"title":"Kick Platform API","version":"v1"},"servers":[{"description":"Production","url":"https://use.kick.co/api"}],"security":[{"organizationAccessToken":[]}],"components":{"securitySchemes":{"organizationAccessToken":{"description":"Organization access token issued by Kick, sent as `Authorization: Bearer kick_org_...`.","scheme":"bearer","type":"http"}}},"paths":{"/platform/v1/financial-accounts":{"get":{"description":"Returns the financial accounts assigned to the entities of the workspace given by `workspaceId`, whatever their source. A workspace outside the organization reads as not found. `entityIds` optionally narrows the list to specific entities; a single or a repeated query param both work, and an entity outside the workspace is rejected with 400. Results are paged with `limit`/`offset`. `transactionsSyncedAt`, `balanceSyncedAt`, `syncStatus` and `syncErrorCode` roll up every connection feeding the account: the sync times are the latest across them, and the account reads as `healthy` as long as one of them still syncs.","operationId":"financialAccounts.list","parameters":[{"in":"query","name":"limit","schema":{"default":100,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","schema":{"default":0,"minimum":0,"nullable":true,"type":"integer"}},{"description":"Workspace whose accounts are listed. A workspace outside the organization reads as not found.","in":"query","name":"workspaceId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Only accounts of these entities of the workspace. A single value or a repeated `entityIds` query param both work. An entity outside the workspace is rejected.","in":"query","name":"entityIds","schema":{"items":{"format":"uuid","type":"string"},"minItems":1,"nullable":true,"type":"array"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"accountNumberMask":{"description":"Last digits of the account number.","nullable":true,"type":"string"},"balance":{"description":"Latest balance reported by the source, null when unknown.","nullable":true,"type":"number"},"balanceSyncedAt":{"description":"Last time the balance was synced from any of the account's sources. Null when it never was.","format":"date-time","nullable":true,"type":"string"},"bookkeepingEndDate":{"description":"Last day Kick keeps books for the account, as YYYY-MM-DD. Null when the account is open-ended.","format":"date","nullable":true,"type":"string"},"bookkeepingStartDate":{"description":"First day Kick keeps books for the account, as YYYY-MM-DD. Null when the account follows the entity's bookkeeping start date.","format":"date","nullable":true,"type":"string"},"createdAt":{"format":"date-time","type":"string"},"disabled":{"description":"Whether syncing new transactions is turned off.","type":"boolean"},"entityId":{"format":"uuid","type":"string"},"id":{"format":"uuid","type":"string"},"institutionName":{"nullable":true,"type":"string"},"name":{"nullable":true,"type":"string"},"source":{"description":"Where the account's transactions come from: an integration (`plaid`, `stripe`, ...), a file import, or manual entry.","enum":["stripe","gusto","adp_run","file_import","plaid","mercury","ramp","paypal","manual","billcom","check","deposit","relay"],"type":"string"},"syncErrorCode":{"description":"Why syncing stopped, set only when `syncStatus` is `error`. `disconnected`: the connection lost its authorization and must be reconnected. `mfa_required`: the institution asks for multi-factor authentication. `item_not_supported`: the institution no longer supports the connection. `item_removed`: the connection was removed at the institution.","enum":["disconnected","mfa_required","item_not_supported","item_removed"],"nullable":true,"type":"string"},"syncStatus":{"description":"Health of the connections feeding the account. `healthy` when at least one of them syncs; `error` when every one of them is broken and needs the user to reconnect; `not_connected` when nothing syncs the account (manual entry, file imports, or a removed connection).","enum":["healthy","error","not_connected"],"type":"string"},"transactionsSyncedAt":{"description":"Last time transactions were synced from any of the account's sources. Null when they never were.","format":"date-time","nullable":true,"type":"string"},"type":{"enum":["checking","savings","credit_card","loan","line_of_credit","investment","payment_processor","payroll_processor","cash","other"],"type":"string"}},"required":["id","entityId","name","type","source","institutionName","accountNumberMask","balance","disabled","bookkeepingStartDate","bookkeepingEndDate","transactionsSyncedAt","balanceSyncedAt","syncStatus","syncErrorCode","createdAt"],"type":"object"},"type":"array"},"pagination":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"required":["limit","offset","total"],"type":"object"}},"required":["data","pagination"],"type":"object"}}},"description":"200"},"400":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"400"},"401":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"401"},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"404"},"429":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"429"}},"summary":"List financial accounts","tags":["financialAccounts"]}}}}
```

## Update a financial account

> Updates the fields present in the body and leaves the others untouched. To move the account to another entity, use the move endpoint. \`bookkeepingStartDate\` and \`bookkeepingEndDate\` accept \`null\` to clear the current value, and changing either regenerates the account's journal entries. A date that is out of range is rejected with 400; a date change blocked by the account's reconciliations or opening balance is rejected with 409. An account outside the organization's book of business reads as not found.

```json
{"openapi":"3.0.2","info":{"title":"Kick Platform API","version":"v1"},"servers":[{"description":"Production","url":"https://use.kick.co/api"}],"security":[{"organizationAccessToken":[]}],"components":{"securitySchemes":{"organizationAccessToken":{"description":"Organization access token issued by Kick, sent as `Authorization: Bearer kick_org_...`.","scheme":"bearer","type":"http"}}},"paths":{"/platform/v1/financial-accounts/{financialAccountId}":{"patch":{"description":"Updates the fields present in the body and leaves the others untouched. To move the account to another entity, use the move endpoint. `bookkeepingStartDate` and `bookkeepingEndDate` accept `null` to clear the current value, and changing either regenerates the account's journal entries. A date that is out of range is rejected with 400; a date change blocked by the account's reconciliations or opening balance is rejected with 409. An account outside the organization's book of business reads as not found.","operationId":"financialAccounts.update","parameters":[{"in":"path","name":"financialAccountId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A unique key that makes the request idempotent. Retrying with the same key within 24 hours replays the original response (marked with `Idempotent-Replayed: true`) instead of executing again.","in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":255,"minLength":1,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"bookkeepingEndDate":{"description":"Last day Kick keeps books for the account, as YYYY-MM-DD. Pass null to keep the account open-ended. Can't be before the account's bookkeeping start date or the closing date of one of its bank reconciliations.","format":"date","nullable":true,"type":"string"},"bookkeepingStartDate":{"description":"First day Kick keeps books for the account, as YYYY-MM-DD. Pass null to follow the entity's bookkeeping start date. Can't be before the entity's bookkeeping start date or after `bookkeepingEndDate`, and can't change while the account is reconciled or has an opening balance.","format":"date","nullable":true,"type":"string"},"name":{"description":"Display name of the account.","maxLength":100,"minLength":1,"type":"string"}},"type":"object"}}},"description":"Body"},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"financialAccount":{"properties":{"accountNumberMask":{"description":"Last digits of the account number.","nullable":true,"type":"string"},"balance":{"description":"Latest balance reported by the source, null when unknown.","nullable":true,"type":"number"},"balanceSyncedAt":{"description":"Last time the balance was synced from any of the account's sources. Null when it never was.","format":"date-time","nullable":true,"type":"string"},"bookkeepingEndDate":{"description":"Last day Kick keeps books for the account, as YYYY-MM-DD. Null when the account is open-ended.","format":"date","nullable":true,"type":"string"},"bookkeepingStartDate":{"description":"First day Kick keeps books for the account, as YYYY-MM-DD. Null when the account follows the entity's bookkeeping start date.","format":"date","nullable":true,"type":"string"},"createdAt":{"format":"date-time","type":"string"},"disabled":{"description":"Whether syncing new transactions is turned off.","type":"boolean"},"entityId":{"format":"uuid","type":"string"},"id":{"format":"uuid","type":"string"},"institutionName":{"nullable":true,"type":"string"},"name":{"nullable":true,"type":"string"},"source":{"description":"Where the account's transactions come from: an integration (`plaid`, `stripe`, ...), a file import, or manual entry.","enum":["stripe","gusto","adp_run","file_import","plaid","mercury","ramp","paypal","manual","billcom","check","deposit","relay"],"type":"string"},"syncErrorCode":{"description":"Why syncing stopped, set only when `syncStatus` is `error`. `disconnected`: the connection lost its authorization and must be reconnected. `mfa_required`: the institution asks for multi-factor authentication. `item_not_supported`: the institution no longer supports the connection. `item_removed`: the connection was removed at the institution.","enum":["disconnected","mfa_required","item_not_supported","item_removed"],"nullable":true,"type":"string"},"syncStatus":{"description":"Health of the connections feeding the account. `healthy` when at least one of them syncs; `error` when every one of them is broken and needs the user to reconnect; `not_connected` when nothing syncs the account (manual entry, file imports, or a removed connection).","enum":["healthy","error","not_connected"],"type":"string"},"transactionsSyncedAt":{"description":"Last time transactions were synced from any of the account's sources. Null when they never were.","format":"date-time","nullable":true,"type":"string"},"type":{"enum":["checking","savings","credit_card","loan","line_of_credit","investment","payment_processor","payroll_processor","cash","other"],"type":"string"}},"required":["id","entityId","name","type","source","institutionName","accountNumberMask","balance","disabled","bookkeepingStartDate","bookkeepingEndDate","transactionsSyncedAt","balanceSyncedAt","syncStatus","syncErrorCode","createdAt"],"type":"object"}},"required":["financialAccount"],"type":"object"}}},"description":"200"},"400":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"400"},"401":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"401"},"403":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"403"},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"404"},"409":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"409"},"429":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"429"}},"summary":"Update a financial account","tags":["financialAccounts"]}}}}
```

## Move a financial account to another entity

> Moves the account to another entity of the same workspace, together with its transactions, documents and accounting data. The account's bookkeeping dates are kept. Moving to the entity the account already belongs to changes nothing. An entity of another workspace is rejected with 400. An account outside the organization's book of business reads as not found.

```json
{"openapi":"3.0.2","info":{"title":"Kick Platform API","version":"v1"},"servers":[{"description":"Production","url":"https://use.kick.co/api"}],"security":[{"organizationAccessToken":[]}],"components":{"securitySchemes":{"organizationAccessToken":{"description":"Organization access token issued by Kick, sent as `Authorization: Bearer kick_org_...`.","scheme":"bearer","type":"http"}}},"paths":{"/platform/v1/financial-accounts/{financialAccountId}/move":{"post":{"description":"Moves the account to another entity of the same workspace, together with its transactions, documents and accounting data. The account's bookkeeping dates are kept. Moving to the entity the account already belongs to changes nothing. An entity of another workspace is rejected with 400. An account outside the organization's book of business reads as not found.","operationId":"financialAccounts.move","parameters":[{"in":"path","name":"financialAccountId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"A unique key that makes the request idempotent. Retrying with the same key within 24 hours replays the original response (marked with `Idempotent-Replayed: true`) instead of executing again.","in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":255,"minLength":1,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"entityId":{"description":"Entity of the same workspace to move the account to. The account's transactions, documents and accounting data move with it.","format":"uuid","type":"string"}},"required":["entityId"],"type":"object"}}},"description":"Body"},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"financialAccount":{"properties":{"accountNumberMask":{"description":"Last digits of the account number.","nullable":true,"type":"string"},"balance":{"description":"Latest balance reported by the source, null when unknown.","nullable":true,"type":"number"},"balanceSyncedAt":{"description":"Last time the balance was synced from any of the account's sources. Null when it never was.","format":"date-time","nullable":true,"type":"string"},"bookkeepingEndDate":{"description":"Last day Kick keeps books for the account, as YYYY-MM-DD. Null when the account is open-ended.","format":"date","nullable":true,"type":"string"},"bookkeepingStartDate":{"description":"First day Kick keeps books for the account, as YYYY-MM-DD. Null when the account follows the entity's bookkeeping start date.","format":"date","nullable":true,"type":"string"},"createdAt":{"format":"date-time","type":"string"},"disabled":{"description":"Whether syncing new transactions is turned off.","type":"boolean"},"entityId":{"format":"uuid","type":"string"},"id":{"format":"uuid","type":"string"},"institutionName":{"nullable":true,"type":"string"},"name":{"nullable":true,"type":"string"},"source":{"description":"Where the account's transactions come from: an integration (`plaid`, `stripe`, ...), a file import, or manual entry.","enum":["stripe","gusto","adp_run","file_import","plaid","mercury","ramp","paypal","manual","billcom","check","deposit","relay"],"type":"string"},"syncErrorCode":{"description":"Why syncing stopped, set only when `syncStatus` is `error`. `disconnected`: the connection lost its authorization and must be reconnected. `mfa_required`: the institution asks for multi-factor authentication. `item_not_supported`: the institution no longer supports the connection. `item_removed`: the connection was removed at the institution.","enum":["disconnected","mfa_required","item_not_supported","item_removed"],"nullable":true,"type":"string"},"syncStatus":{"description":"Health of the connections feeding the account. `healthy` when at least one of them syncs; `error` when every one of them is broken and needs the user to reconnect; `not_connected` when nothing syncs the account (manual entry, file imports, or a removed connection).","enum":["healthy","error","not_connected"],"type":"string"},"transactionsSyncedAt":{"description":"Last time transactions were synced from any of the account's sources. Null when they never were.","format":"date-time","nullable":true,"type":"string"},"type":{"enum":["checking","savings","credit_card","loan","line_of_credit","investment","payment_processor","payroll_processor","cash","other"],"type":"string"}},"required":["id","entityId","name","type","source","institutionName","accountNumberMask","balance","disabled","bookkeepingStartDate","bookkeepingEndDate","transactionsSyncedAt","balanceSyncedAt","syncStatus","syncErrorCode","createdAt"],"type":"object"}},"required":["financialAccount"],"type":"object"}}},"description":"200"},"400":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"400"},"401":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"401"},"403":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"403"},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"404"},"429":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"429"}},"summary":"Move a financial account to another entity","tags":["financialAccounts"]}}}}
```

## Delete a financial account

> Permanently deletes a financial account together with its transactions. An integration connection left without accounts is deleted with it. An account that manual journal entries post to answers 409 unless \`forceDeletion=true\` is passed, in which case those journal entries are deleted too. This can't be undone. An account outside the organization's book of business reads as not found.

```json
{"openapi":"3.0.2","info":{"title":"Kick Platform API","version":"v1"},"servers":[{"description":"Production","url":"https://use.kick.co/api"}],"security":[{"organizationAccessToken":[]}],"components":{"securitySchemes":{"organizationAccessToken":{"description":"Organization access token issued by Kick, sent as `Authorization: Bearer kick_org_...`.","scheme":"bearer","type":"http"}}},"paths":{"/platform/v1/financial-accounts/{financialAccountId}":{"delete":{"description":"Permanently deletes a financial account together with its transactions. An integration connection left without accounts is deleted with it. An account that manual journal entries post to answers 409 unless `forceDeletion=true` is passed, in which case those journal entries are deleted too. This can't be undone. An account outside the organization's book of business reads as not found.","operationId":"financialAccounts.delete","parameters":[{"in":"path","name":"financialAccountId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Delete the account even when manual journal entries post to it; the journal entries posting to the account are deleted with it. Without it, such an account answers 409. An account referenced by consolidation eliminating entries answers 409 either way.","in":"query","name":"forceDeletion","schema":{"default":"false","enum":["true","false"],"type":"string"}},{"description":"A unique key that makes the request idempotent. Retrying with the same key within 24 hours replays the original response (marked with `Idempotent-Replayed: true`) instead of executing again.","in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":255,"minLength":1,"type":"string"}}],"responses":{"200":{"description":"200"},"400":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"400"},"401":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"401"},"403":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"403"},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"404"},"409":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"409"},"429":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"},"traceId":{"nullable":true,"type":"string"}},"required":["message"],"type":"object"}}},"description":"429"}},"summary":"Delete a financial account","tags":["financialAccounts"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kick.co/api/api-reference/financial-accounts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
