This Quick start guide will walk you through the steps to build your first cash flow report, familiarizing you with the Teal API along the way.

You’ll need to have completed the steps in Initial Setup guide before following this guide.

​
1. Configure a new instance

​
Select a chart of accounts

Every instance needs to have a Chart of Accounts (CoA). Your Platform comes with default templates that you can use. Visit the Developer Portal to select a template for your new Instance. Take note of the coa_template_id associated with the chart of accounts you’d like to use.

You can view and edit these templates in the Developer Portal or via the API. You’ll likely want to do this later when you get to tailoring your chart of accounts based on your unique user’s needs.

​
Create an instance

Create an instance by calling the Create Instance endpoint. Replace the query parameters with your desired instance name, the coa_template_id that you copied from the Developer Portal, and the appropriate start date in ISO 8061 format for your new instance.

You can read more about how to set an appropriate start date in the instance configuration guide. For testing purposes, you can just pick an arbitrary date. Just note that you won’t be able to enter any transactions or run any reports that have dates before the start date.
curl --request POST \
--url 'https://api.sandbox.teal.dev/v0/platform/instances?name=INSTANCE_NAME&entries_start=STARTDATE&coa_template_id=TEMPLATE_ID' \
--header 'authorization: Bearer <token>'

​
2. Populate transactions into Teal

In this step, we’ll populate some transaction data into Teal that our cash flow report will later report on.

​
Create a financial account ledger

Before you can submit transactions to Teal, you need to Create a new financial account ledger by calling the Create Ledger endpoint. This ledger will represent the financial account in which the transactions occurred.

These ledgers are unique to each instance and represent their corresponding financial accounts in the real world. For information on how to set these ledgers up properly, visit creating ledgers

For this exercise, let’s create a bank account ledger with the following parameters:

--sort_code 1050
--name Chase Checking 1234
--ledger_type asset
--debit_credit debit
--financial_account_type bank_account
--report_cash_flow true

curl --request POST \
--url 'https://api.sandbox.teal.dev/v0/ledgers' \
--header 'authorization: Bearer <token>' \
--header 'teal-instance-id: <instance_id>' \
--header 'Content-Type: application/json' \
--data '{"sort_code": "1050", "name": "Chase Checking 1234", "ledger_type": "asset", "debit_credit": "debit", "financial_account_type": "bank_account", "report_cash_flow": true}'

You’ll notice that we set the report_cash_flow parameter to true. This is because we want the cash flow report to analyze the cash flow in and out of this financial account ledger. When we generate the cash flow report later, it will rely on this parameter to know which ledgers to analyze. You can learn more in the cash flow report guide.

​
Submit the transactions

In this step, you will use the Create transactions endpoint to submit transactions. We encourage you prepare and submit a diverse set of banking transactions so that you can see Teal in action.

When building with Teal, submitting the transactions via API is only one method of populating transactions data. You can also use our data integrations so that Teal can do the work for you of fetching and reconciling transactions for you from a 3rd party data source.

curl --request POST \
--url https://api.sandbox.teal.dev/v0/transactions \
--header 'authorization: Bearer <token>' \
--header 'teal-instance-id: <instance_id>' \
--header 'Content-Type: application/json' \
--data '[{"ledger_id": "7JRNsKwy2Lw66caxVU7WGC", "amount":100,"datetime":"2023-08-01T00:00:00Z","description":"A sample transaction","id":"t_12345","metadata": {}}]'

​
3. Generate a cash flow report

You’ve set up a instance and submitted transactions into their financial account ledger. Now you’re ready to generate a cash flow report.

​
Generate the cash flow report

To generate the cash flow report, call the Get Cash Flow Report endpoint with the appropriate start_date and end_date parameters.

curl --request GET \
--url 'https://api.sandbox.teal.dev/v0/reports/cash-flow?start_date=START_DATE&end_date=END_DATE' \
--header 'authorization: Bearer <token>' \
--header 'teal-instance-id: <instance_id>'

​
Interpreting the cash flow report object

This cash flow report will analyze all cash bearing accounts that were created with the report_cash_flow parameter. Here’s how to interpret the report object:

  • The cash-flow-report endpoint will return starting_debit_balance and ending_debit_balance. These are the total amounts of cash that the business had across all financial account ledgers marked with the report_cash_flow parameter, on the start_date and end_date of the report, respectively.
  • The starting_balances and ending_balances JSON objects will break down starting_debit_balance and ending_debit_balance by financial account ledger.
  • The cash_flow_ledgers JSON object will report out which ledgers contributed to changing the total cash balance over the reporting period between start_date and end_date, and by how much. It also reports on the individual line items and journal entries that contributed to the change, if you want to provide the ability to provide further detail to the user.
  • The changes reported by the cash_flow_ledgers object will equal exactly the difference between the starting_debit_balance and ending_debit_balance amounts.
  • For more information on how to present this report to the end user in your front-end, check out our cash flow report guide.

​
Transaction auto-categorization

You’ll notice that in this cash flow object, the only two ledgers that changed the cash balance were uncategorized cash inflows and uncategorized cash outflows. That’s not very informative! This is because transaction auto-categorization has not yet been enabled. To auto-categorize these transactions and generate a more informative cash flow report, let’s move on to the auto-categorization quick start guide.

Charts of accountsQuick start 2: Auto-categorization