Overview
An Instance represents the accounting data of a business entity (SMB) in Teal. You can think of it as a “set of books” for your users.
Use the Create Instance endpoint and set their name, subscription_tier, entries_start, coa_template_id, and parent_id (if applicable, see Multi-entity organizations).
Remember to store the association between an instance in Teal and their associated entity in your product.
Instance anatomy
Multi-entity organizations
To represent more complex business structures, an instance can be configured as a subsidiary of another instance by providing a parent_id.
The parent_id can be provided when creating the instance, or updated later with the Update Instance endpoint.
Subsidiary relationships are currently restricted to one level. This means a subsidiary cannot have its own subsidiaries. Additionally, a subsidiary can have only one parent.
Subscription tier
Subscription tiers unlock reporting and advanced features for your users. By default, Instances have a tier0 subscription and can be upgraded to higher tiers using the Update Subscription endpoint.
| Name | Level | Features |
|---|---|---|
| Inactive | tier0 | — |
| Basic | tier1 | Basic reports, line entry categories |
| Advanced | tier2 | Balance sheet |
| Premium | tier3 | Filter reports using tags |
| Professional services | tier4 | Full service accounting |
| Consolidations | tier5 | Consolidated reports for multi-entity organizations |
Contact us for Instance tier pricing levels. Instances in Sandbox environments are always free.
Start date
The entries_start parameter is the start date from which the API will sync an Instance’s accounting data. Transactions or journal entries cannot be entered before the start date, but you will be able to read reports.
You will generally set a start date that is the beginning of the financial year that your Instances will begin tracking their books on your Platform, or the start date of their business, whichever is sooner.
You cannot add transactions to an Instance from before their start date.
Chart of accounts
A chart of accounts template (the coa_template_id parameter) is required for all new Instances to generate their ledgers. You can view and manage your templates in the Developer Portal or using the Chart of Account Template endpoints.
Creating Instances
Use the Create Instance endpoint to create a new Instance. This step is usually done as part of onboarding where the user will also need to do some additional setup.
Users will need to select their chart of accounts template, if you provide multiple options. They will also need to create ledgers corresponding to each of their financial accounts and provide data connections, if necessary. Finally, if they are not a brand-new business they will have to set opening balances to ensure their balance sheet is accurate.
Deleting and deactivating Instances
Delete sandbox Instances using a delete request to Delete Instance endpoint.
Production Instances can be deactivated by downgrading their subscription_tier to tier0 using the Update Subscription endpoint.
Note downgrading an Instance will not deactivate any Plaid or Unit links the Instance may have. Deactivate those separately using the Delete Ledger Transaction Source endpoint to ensure you are not charged for active connections on an inactive account.
Relevant resources
- Chart of accounts configuration
- Configure data integrations
- Configure your QuickBooks integration
- Set ledger opening balances