Learn how to build a cash flow report and familiarize yourself with the Teal API along the way. You’ll create an Instance, Teal’s representation of a business, give it a ledger to represent a bank account, create and categorize transactions, and see a real cash flow report complete with starting and ending balances.

Before following this guide, You’ll need to complete the steps in Initial Setup 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 edit these templates in the Developer Portal or via the API. You’ll likely want to do this later when you get to creating a tailored chart of accounts based on your users’ unique needs.

​
Create an Instance

Create an Instance on your Platform for a hypothetical business, ACME Goods Inc, by using the Create Instance endpoint, /v0/platform/instances. Use the coa_template_id that you copied from the previous step. We’ll use Jan 1, 2024, as the entries_start date, indicating the beginning of the business’ activity, but just note that you won’t be able to enter any transactions or run any reports that have dates before the start date.

You can read more about creating new Instances in the Instances overview.

curl --request POST \
--url 'https://api.sandbox.teal.dev/v0/platform/instances' \
--header 'authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "ACME Goods Inc",
    "accounting_package": "platformgl",
    "coa_template_id": <your selected chart of accounts id>,
    "entries_start": "2024-01-01T00:00:00Z",
    "subscription": "tier1"
}'

​
2. Populate transactions into Teal

Next, you’ll need to create a ledger for the business’ bank account and transaction data for your cash flow report to use.

​
Create a financial account ledger

Every financial account a business has needs to be represented by a ledger. To do this, you need to create a new financial account ledger by calling the Create Ledger endpoint, /v0/ledgers.

Financial account 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.

Create a ledger for a bank account with Chase:

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
}'

By setting the report_cash_flow parameter to true Teal will know to analyze the cash flow in and out of this financial account ledger when we generate the cash flow report.

​
Submit the transactions

To submit the transactions to Teal, use the create transactions endpoint, /v0/transactions. For each transaction, we’ll include the ID of the financial account ledger we just created as the ledger_id, an amount in a 2 decimal float, a datetime of when the transaction occurred, a description telling us about the transaction, and an id to prevent duplicate transactions.

We encourage you to prepare and submit a diverse set of banking transactions so that you can see Teal in action.

Submitting the transactions via API is only one method of populating transaction 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": <your financial account ledger id>, 
        "amount": -101.93,
        "datetime": "2024-01-02T00:00:00Z",
        "description": "COSTCO Wholesale",
        "id":"txn_1",
    },
    {
        "ledger_id": <your financial account ledger id>, 
        "amount": 2218.23,
        "datetime": "2024-01-04T00:00:00Z",
        "description": "Deposit",
        "id":"txn_2",
    },
]'

​
3. Generate a cash flow report

You’ve set up an Instance and submitted transactions to 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 for the year, call the Get Cash Flow Report endpoint, /v0/reports/cash-flow with the start_date of the beginning of the year and an end_date the end of the year.

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

​
Interpreting the cash flow report object

The cash flow report will analyze all cash -bearing accounts that have 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 the business had across all financial account ledgers marked with the report_cash_flow parameter, on the report’s start_date and end_date, respectively.
  • The starting_balances and ending_balances objects will break down starting_debit_balance and ending_debit_balance by financial account ledger.
  • The cash_flow_ledgers object contains the ledgers that contributed to changing the total cash balance over the reporting period 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 generate a more informative cash flow report, we need to categorize these transactions.

​
4. Configure the auto-categorizer

We’ll use the auto-categorizer to set up rules to categorize the transactions and others like them.

Open the Categorization section of the Developer portal. Here you’ll see the configuration panels for each step in the auto-categorization pipeline.

Whenever a new transaction is created, either manually using the API or via a data-integration, it is sent through a sequence of rules-based steps, where each step attempts to match it to a ledger in the Instance’s chart of accounts. Auto-categorization provides a better user experience for the end user, as they will not need to manually categorize the majority of transactions.

The auto-categorization pipeline consists of four categorization steps, each of which can be independently configured. You can read more about each step in our categorization config guide.

Try writing a couple rules to match the descriptions of some of the transactions you’ve created. For example, you might want one that categorizes all transactions with “COSTCO” in the description as “Supplies Expense”. You’ll want to write a rule like

match(".*COSTCO", t.description)

in the Expression, and set “Supplies Expense” as the destination ledger. Use your chart of accounts as a reference for what ledgers you can categorize transactions as.

See the guide for writing categorization rules for more examples and tips.

​
5. Test the auto-categorizer

You can run auto-categorization tests to check the accuracy and recategorize transactions for specific ledgers from within the Developer portal.

Once you are ready to test your auto-categorization configuration, select the Instance we created in step 1 from the dropdown menu. Select a financial account ledger in the dropdown menu. Now you can click Run Test to view the output of auto-categorization for the transactions contained in that ledger. Running the test will give a preview of the auto-categorization results, but will not apply the changes to the Instances’ data.

When you are satisfied with the results of the auto-categorizer, press Recategorize to apply these changes to the Instances’s data. You can now generate a new cash flow report with the updated categories.

​
6. View an updated cash flow report

Generate a new cash flow report using the same method as before.

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

Congratulations! The new cash flow report object now displays the updated categories.

​
Next steps

You’re now ready to dive into Teal’s more detailed guides on how to build your accounting software offering.

A good next step is to visit the Cash Flow Report guide. This guide will go into further detail on the Cash Flow report and how to embed it into your front-end application so the end user can interact with it.

Initial setupOverview