Bank Feeds API

Create bank account The *Create bank account* endpoint creates a new [bank account](https://docs.codat.io/bank-feeds-api#/schemas/BankAccount) for a given company's connection. [Bank accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankAccount) are financial accounts maintained by a bank or other financial institution. **Integration-specific behavior** Required data may vary by integration. To see what data to post, first call [Get create/update bank account model](https://docs.codat.io/bank-feeds-api#/operations/get-create-update-bankAccounts-model).

Create bank feed account mapping The *Create bank account mapping* endpoint creates a new mapping between a source bank account and a potential account in the accounting software (target account). A bank feed account mapping is a specified link between the source account (provided by the Codat user) and the target account (the end user's account in the underlying software). To find valid target account options, first call the [List bank feed account mappings](https://docs.codat.io//bank-feeds-api#/operations/get-bank-account-mapping) endpoint. > **For custom builds only** > > Only use this endpoint if you are building your own account management UI. #### Account mapping variability The method of mapping the source account to the target account varies depending on the accounting software your company uses. #### Mapping options: 1. **API Mapping**: Integrate the mapping journey directly into your application for a seamless user experience. 2. **Codat UI Mapping**: If you prefer a quicker setup, you can utilize Codat's provided user interface for mapping. 3. **Accounting Platform Mapping**: For some accounting software, the mapping process must be conducted within the software itself. ### Integration-specific behavior | Bank Feed Integration | API Mapping | Codat UI Mapping | Accounting Platform Mapping | | --------------------- | ----------- | ---------------- | --------------------------- | | Xero | ✅ | ✅ | | | FreeAgent | ✅ | ✅ | | | Oracle NetSuite | ✅ | ✅ | | | Exact Online (NL) | ✅ | ✅ | | | QuickBooks Online | | | ✅ | | Sage | | | ✅ |

Create bank transactions The *Create bank transactions* endpoint creates new [bank transactions](https://docs.codat.io/bank-feeds-api#/schemas/BankTransactions) for a given company's connection. [Bank transactions](https://docs.codat.io/bank-feeds-api#/schemas/BankTransactions) are records of monetary amounts that have moved in and out of an SMB's bank account. **Integration-specific behavior** The required properties may vary based on the integration. For detailed requirements specific to each accounting software, refer to the API reference examples. Alternatively, you can view the [Get create bank transaction model](https://docs.codat.io/bank-feeds-api#/operations/get-create-bank-transactions-model) for more information.

Create source accounts The _Batch create source accounts_ endpoint allows you to create multiple representations of your SMB's bank accounts within Codat's domain. The company can then map the source account to an existing or new target account in their accounting software. > ### Versioning > If you are integrating the Bank Feeds solution with Codat after August 1, 2024, please use the v2 version of the API, as detailed in the schema below. For integrations completed before August 1, 2024, select the v1 version from the schema dropdown below.

Create company Use the *Create company* endpoint to create a new [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) that represents your customer in Codat. A [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) represents a business sharing access to their data. Each company can have multiple [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data. If forbidden characters (see `name` pattern) are present in the request, a company will be created with the forbidden characters removed. For example, `Company (Codat[1])` with be created as `Company Codat1`.

Create connection Creates a connection for the company by providing a valid `platformKey`. Use the [List Integrations](https://docs.codat.io/platform-api#/operations/list-integrations) endpoint to access valid platform keys.

Create single source account The _Create Source Account_ endpoint allows you to create a representation of a bank account within Codat's domain. The company can then map the source account to an existing or new target account in their accounting software. > ### Versioning > If you are integrating the Bank Feeds solution with Codat after August 1, 2024, please use the v2 version of the API, as detailed in the schema below. For integrations completed before August 1, 2024, select the v1 version from the schema dropdown below.

Delete all source account credentials The _Delete Bank Account Credentials_ endpoint serves as a comprehensive mechanism for revoking all existing authorization credentials that a company employs to establish its Bank Feed connection. In cases where multiple credential sets have been generated, a single API call to this endpoint revokes all of them.

Delete a company The *Delete company* endpoint permanently deletes a [company](https://docs.codat.io/bank-feeds-api#/schemas/Company), its [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) and any cached data. This operation is irreversible. A [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) represents a business sharing access to their data. Each company can have multiple [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.

Delete connection Revoke and remove a connection from a company. This operation is not reversible. The end user would need to reauthorize a new data connection if you wish to view new data for this company.

Delete source account The _Delete source account_ endpoint enables you to remove a source account. Removing a source account will also remove any mapping between the source bank feed bank accounts and the target bankfeed bank account.

Generate source account credentials The _Generate bank account credentials_ endpoint can be used to generate credentials for QuickBooks Online to authenticate the Bank Feed in the QBO portal. Each time this endpoint is called, a new set of credentials will be generated. The old credentials will still be valid until the revoke credentials endpoint is used, which will revoke all credentials associated to the data connection. > **For QuickBooks Online only** > > Only call this endpoint when onboarding SMBs that use QuickBooks Online.

Generate one-time password The *Generate OTP* endpoint generates a one-time password (OTP) for a bank feed connection. The OTP is returned along with an expiry time, after which it will no longer be valid. > **For Sage only** > > Only call this endpoint for connections to Sage. Calling it for other integrations will return an error.

List bank feed accounts The *List bank accounts* endpoint returns information about a source bank account and any current or potential target mapping accounts. A bank feed account mapping is a specified link between the source account (provided by the Codat user) and the target account (the end user's account in the underlying software). > **For custom builds only** > > Only use this endpoint if you are building your own account management UI.

Get company The *Get company* endpoint returns a single company for a given `companyId`. A [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) represents a business sharing access to their data. Each company can have multiple [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.

Get company access token Use the _Get company access token_ endpoint to return an access token for the specified company ID. The token is valid for one day. The token is required by Codat's embeddable UIs (such as [Connections SDK](https://docs.codat.io/auth-flow/optimize/connection-management) and [Link SDK](https://docs.codat.io/auth-flow/authorize-embedded-link)) to verify the identity of the user and improve the reliability of data provided by them.

Get company information Use the *Get company information* endpoint to return information about the company available from the underlying accounting software. ### Supported Integrations | Integration | Supported | |-----------------------|-----------| | Oracle NetSuite | Yes | | Xero | Yes | | Exact | No | | FreeAgent | No | | Sage | No | | QuickBooks Online | No |

Get connection Returns a specific connection for a company when valid identifiers are provided. If the identifiers are for a deleted company and/or connection, a not found response is returned.

Get create bank transactions model The *Get create bank account transactions model* endpoint returns the expected data for the request payload when creating [bank account transactions](https://docs.codat.io/bank-feeds-api#/schemas/BankTransactions) for a given company and integration. [Bank account transactions](https://docs.codat.io/bank-feeds-api#/schemas/BankTransactions) are records of money that has moved in and out of an SMB's bank account. **Integration-specific behavior** See the *response examples* for integration-specific indicative models.

Get create/update bank account model The *Get create/update bank account model* endpoint returns the expected data for the request payload when creating and updating a [bank account](https://docs.codat.io/bank-feeds-api#/schemas/BankAccount) for a given company and integration. [Bank accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankAccount) are financial accounts maintained by a bank or other financial institution. **Integration-specific behavior** See the *response examples* for integration-specific indicative models.

Get create operation The **Get create operation** endpoint returns a specific [write operation](/using-the-api/push) identified by the `pushOperationKey` that was performed on the company. Write operations are actions that send requests to Codat, enabling the creation, updating, deletion of records, or uploading attachments in the connected accounting software. For bank feeds, your push operations will only relate to the `bankTransactions` data type.

Get latest sync The _Get latest sync_ endpoint returns the status for a given source account's [most recent sync](https://docs.codat.io/bank-feeds-api#/schemas/SyncStatusResult). A sync is a single execution that fetches bank transactions from a connected bank account and records them in the company's accounting software.

Get sync The _Get sync_ endpoint returns the [sync status](https://docs.codat.io/bank-feeds-api#/schemas/SyncStatusResult) for a given 'syncId'. A sync is a single execution that fetches bank transactions from a connected bank account and records them in the company's accounting software.

List bank accounts The *List bank accounts* endpoint returns a list of [bank accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankAccount) for a given company's connection. [Bank accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankAccount) are financial accounts maintained by a bank or other financial institution. Before using this endpoint, you must have [retrieved data for the company](https://docs.codat.io/bank-feeds-api#/operations/refresh-company-data).

List companies The *List companies* endpoint returns a list of [companies](https://docs.codat.io/bank-feeds-api#/schemas/Company) associated to your instances. A [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) represents a business sharing access to their data. Each company can have multiple [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data. ## Filter by tags The *List companies* endpoint supports the filtering of companies using [tags](https://docs.codat.io/using-the-api/managing-companies#add-metadata-to-a-company). It supports the following operators with [Codat’s query language](https://docs.codat.io/using-the-api/querying): - equals (`=`) - not equals (`!=`) - contains (`~`) For example, you can use the querying to filter companies tagged with a specific foreign key, region, or owning team: - Foreign key: `uid = {yourCustomerId}` - Region: `region != uk` - Owning team and region: `region = uk && owningTeam = invoice-finance`

List connections List the connections for a company.

List create operations The **List create operations** endpoint returns a list of [write operations](/using-the-api/push) performed on the company. Write operations are actions that send requests to Codat, enabling the creation, updating, deletion of records, or uploading attachments in the connected accounting software. For bank feeds, use this endpoint to view write operations related to the `bankTransactions` data type.

List source accounts The _List source accounts_ endpoint returns a list of [source accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankFeedAccount) for a given company's connection. [Source accounts](https://docs.codat.io/bank-feeds-api#/schemas/BankFeedAccount) are the bank's bank account within Codat's domain from which transactions are synced into the accounting platform. > ### Versioning > If you are integrating the Bank Feeds solution with Codat after August 1, 2024, please use the v2 version of the API, as detailed in the schema below. For integrations completed before August 1, 2024, select the v1 version from the schema dropdown below.

Replace company Use the *Replace company* endpoint to replace the existing name, description, and tags of the company. Calling the endpoint will replace existing values even if new values haven't been defined in the payload. A [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) represents a business sharing access to their data. Each company can have multiple [connections](https://docs.codat.io/bank-feeds-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.

Run ad-hoc sync The _Run ad-hoc sync_ endpoint immediately runs a sync with a fetch period from the last successful sync to the execution time of the new sync. A sync is a single execution that fetches bank transactions from a connected bank account and records them in the company's accounting software. Use either the [_Get latest sync_](https://docs.codat.io/bank-feeds-api#/operations/get-latest-managed-bank-feed-sync) endpoint or the [_Get sync_](https://docs.codat.io/bank-feeds-api#/operations/fetch-managed-bank-feed-sync-by-id) endpoint to get the result of this sync.

Unlink connection This allows you to deauthorize a connection, without deleting it from Codat. This means you can still view any data that has previously been pulled into Codat, and also lets you re-authorize in future if your customer wishes to resume sharing their data.

Update company Use the *Update company* endpoint to update the name, description, or tags of the company. The *Update company* endpoint doesn't have any required fields. If any of the fields provided are `null` or not provided, they won't be included in the update. A [company](https://docs.codat.io/bank-feeds-api#/schemas/Company) represents a business sharing access to their data.

Update source account The _Update source account_ endpoint updates a single source account for a single data connection connected to a single company. ### Tips and pitfalls * This endpoint makes it possible to update the `accountName`, `status`, and `balance` fields. * The `status` field can only be updated to 'disconnected'. * The `balance` field can only be updated on accounts that are **not** 'connected'. * Updates made here apply exclusively to source accounts and will not affect target accounts in the accounting software.