Skip to main content
Before following this guide, complete the steps in Initial Setup.
1

Create an Instance

  1. Select a chart of accounts
Every Instance needs to have a Chart of Accounts (CoA). We provide you with default templates that you can use, which you can access in the Developer Portal or via the List all Chart of Accounts Templates endpoint.
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.
  1. Create the Instance
Call the Create Instance endpoint. You can choose your parameters, but here are some suggestions:
  • Use the coa_template_id that you copied from the previous step.
  • Set your entries_start date to 2024-01-01T00:00:00Z. This date indicates the beginning of the business’ activity, or the migration date from another accounting system.
  • Set your subscription to tier3. More on subscription tiers can be found here
    You won’t be able to import any transactions or run any reports that have dates before the entries_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": "tier3"
}'
2

Import transactions

  1. Create a ledger
Create a ledger representing the bank account by calling the Create Ledger endpoint. Set the financial_account_type to bank_account.
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
}'
  1. Create a source account
Create a Transaction Source Account and link it to the ledger using the ledger_id.
curl --request POST \
--url 'https://api.sandbox.teal.dev/v0/source-accounts/business' \
--header 'authorization: Bearer <token>' \
--header 'teal-instance-id: <instance_id>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Chase Checking 1234",
    "ledger_id": <ledger_id of the Chase ledger>
}'
  1. Manually import transactions
Manually import transactions via the Create Transactions endpoint. For each transaction, we’ll include 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.
You can also use our native Plaid integration to automate the process of importing transactions to Teal.
curl --request POST \
--url https://api.sandbox.teal.dev/v0/source-accounts/{source_account_id}/transactions \
--header 'authorization: Bearer < token >' \
--header 'teal-instance-id: < instance_id >' \
--header 'Content-Type: application/json' \
--data '[
    {
        "amount": -101.93,
        "datetime": "2024-01-02T00:00:00Z",
        "description": "COSTCO Wholesale",
        "id":"txn_1",
    },
    {
        "amount": 2218.23,
        "datetime": "2024-01-04T00:00:00Z",
        "description": "Deposit",
        "id":"txn_2",
    },
]'
3

Generate a cash flow report

Call the Get Cash Flow Report and select a start_date and an end_date.
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

The cash flow report will analyze all cash-bearing ledgers 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.