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 all platformgl instances.
  • 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.

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.

NameLevelFeatures
Inactivetier0
Basictier1Basic reports, line entry categories
Advancedtier2Balance sheet
Premiumtier3Filter reports using tags
Professional servicestier4Full service accounting
Consolidationstier5Consolidated 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 (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