Account Identifier

Account identifiers are unique identifiers for a specific ledger account within a business. They are used in both API inputs and outputs to specify a given ledger account. They are typically used when categorizing transactions or creating categorization rules.

Account identifiers are polymorphic. There are multiple types of identifiers for different use cases which we discuss below.

AccountId

The first use case is the intuitive AccountId type, which is a unique ID object for a ledger account. This kind of identifier is unique across all businesses and all ledger accounts.

Request Body

type · string

AccountId indicates we’re using an AccountId identifier type.

id · string

The unique identifier string for the ledger account.

Account ID Example

{
  "type": "AccountId",
  "id": "e95c8640-f87b-43bf-a9c6-cabc7ebfdec6"
}

Account IDs are useful when users create their own ledger accounts, which are not guaranteed to have stable names. To refer to these accounts will need to use the AccountId type.

StableName

The second use case is the StableName type, which is a stable identifier for an account present in your chart of accounts template. This kind of identifier is useful for identifying equivalent accounts across businesses, e.g., referring to the ACCOUNTS_RECEIVABLE account across different businesses, since those may have different AccountIds but will have the same StableName.

This is useful for situations where you are building a workflow for a specific account type, e.g. ACCOUNTS_RECEIVABLE and don’t want to look up the unique account ID for each business.

Limitations

While useful, there are two limitations to note with stable names:

1. End-users with access to the general ledger can create their own ledger accounts, which will not have stable names. To refer to these accounts will need to use the AccountId type.
2. Some templated account types are specific to industries. If you have customers with different Charts. If you try to use a stable name for an account which does not exist for a business, you will receive an error.

Request Body

type · string

StableName indicates we’re using a StableName identifier type.

stable_name · string

The stable identifier string for the ledger account.

Stable Name Example

{
  "type": "StableName",
  "stable_name": "CHARITABLE_CONTRIBUTIONS"
}

References

• Required vs. Optional Template Accounts