1
Create a financial account ledger
Real-world financial accounts are represented by financial account ledgers. You create these ledgers like any ledger by using the Create Ledger endpoint.Financial account ledgers must have a
financial_account_type
. By selecting the financial account type, we
set smart defaults to ensure that the accounting treatment is accurate. For example, setting financial_account_type
to
bank
automatically sets type
to asset
, debit_credit
to debit
, and report_cash_flow
to true
.Each real-world financial acount should have its own individual ledger. You can see the complete list of supported financial
account types here.
2
Map the ledger
Once you have created a financial account ledger, you must store the association between the
ledger_id
of the
financial account ledger and the real-world financial account it represents.We call this mapping, and you will use this mapping for various use cases such as submitting transactions.3
Set the opening balance
It is important that the balance of the financial account ledger matches that of the real-world financial account on
your user’s start date, or else their accounting will be inaccurate.If the real-world financial account was opened before your user’s start date,
an opening balance must be set via the Opening Balance endpoint.
Best practices
Map financial account ledgers at the beginning
Map financial account ledgers at the beginning
If you already have access to financial accounts for the customer, for example, because you already
serve them a banking or payroll product, then it’s a good idea to create a ledger for each financial
account as soon as you create the user’s account in Teal.
Give descriptive names to ledgers
Give descriptive names to ledgers
When creating a financial account ledger, it’s important to give it a descriptive name so
the end user can distinguish which account is which in case they ever open a 2nd account
of the same type. We recommend using a naming convention that includes the last 4 digits
of the account number, which is generally considered not to be sensitive information. For
security and compliance reasons, we do not recommend including any more digits than the last four.For example, “Chase Checking **5959” is a good name for a ledger, whereas “Bank Account 1” is not.
Make ledgers representing platform controlled financial accounts non-editable
Make ledgers representing platform controlled financial accounts non-editable
If you control the financial account (e.g. via a neobanking/Baas offering), then you may
want to make the ledger non-user-editable by setting the
editable
parameter to False
when using the Create Ledger endpoint. This will
prevent the user from editing any line entry that is assigned to the ledger. They will still
be able to categorize the transactions and edit the rest of the journal entry. This feature
ensures that the user does not accidently break the sync between the Teal ledger and the
transactions submitted from the financial account.For example, if you submit a transaction for a $10 expense for “Starbucks” using the
Create Transaction endpoint, Teal will automatically generate a
journal entry with two line entries. One line entry will credit $10 to the bank account ledger,
the other line entry will debit $10 to an expense ledger (depending on your
auto-categorization config). If the bank account ledger
is set to editable
= False, then the user will be able to change the $10 debit to the
expense ledger, but not the $10 credit to the bank account ledger.