Overview
An Instance represents a single business (SMB) in Teal. It represents your customers’ SMB accounting data; you can also think of it as a “set of books” for your users.
Use the Create Instance endpoint and set their name, subscription_tier, accounting_package, entries_start, and coa_template_id.
Remember to store the association between an instance in Teal and their associated entity in your product.
Instance anatomy
Accounting package
The accounting_package attribute defines the source of truth for a set of books and what features a customer has access to. There are two accounting package options:
platformgl: Our build-your-own solution allows you to build your own bespoke accounting software to fit your users unique needs. A chart of accounts template is required for allplatformglinstances.quickbooks: Integrate a customer’s existing QuickBooks account. Please note that not all features are available for Instances using QuickBooks as their accounting package.
Once an Instance’s accounting package has been set, it cannot be changed.
We plan on integrating with more popular accounting packages soon. If you have a specific accounting package you’d like an integration for, please reach out to us.
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 |
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 (PlatformGL only)
A chart of accounts template (the coa_template_id parameter) is required for all new PlatformGL 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 /v0/platform/instances and send the necessary parameters: name, subscription_tier, accounting_package, entries_start, for quickbooks Instances and additionally coa_template_id for platformgl Instances. This step is usually done as part of onboarding where the user will also need to do some additional setup.
- New QuickBooks users will need to follow your QuickBooks auth flow, which will set up and configure all their ledgers from their existing QuickBooks account.
- New PlatformGL 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 /v0/platform/instances/{id}.
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