Accounts
Account management endpoints
List accounts
Credential: a company's API key or OAuth token.
Retrieves your company's chart of accounts. The list is sorted by
accountNumber ascending unless sortBy and sortOrder say otherwise;
rows that tie on publicAccountId or name are ordered by
accountNumber. Pass an account's id as accountId when
creating journal entries or draft journal entries, or to filter the
journal-entry list.
Results are cached for 5 seconds. A create, update or delete through this API drops the cached list, so a read that follows the write reflects it; a list read that was already in flight during the write can serve the previous rows for up to 5 seconds.
Required Scope
accounts-read
query Parameters
sortByField to sort by. Rows that tie on publicAccountId or name are ordered by accountNumber, which is unique within the company.
sortOrderSort direction
List accounts › Responses
List of accounts for the company
idThe unique identifier of the account
nameName of the account
accountNumberAccount type number
publicAccountIdPublic account id that the account maps to
ledgerTypeType of ledger account. Only BALANCE_SHEET and PROFIT_AND_LOSS accounts can be used in journal entries.
debitCreditThe side a journal-entry line on this account pre-selects: debit or credit. This is the Debit/Credit choice on the account form. It does not decide how a balance is reported; accountClassification does.
requiredDimensionIdsIDs of the dimensions this account requires: every journal entry line posting to the account must carry a value from each of them, or the entry is refused with JOURNAL_TAG_REQUIRED_DIMENSION_MISSING. Empty when the account requires none. This is the account setting as stored: a dimension that has since been deactivated stays listed and is not enforced until it is active again, so match the ids against the dimensions list, which returns active dimensions only.
accountClassificationAccount classification (ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE)
controlAccountTypeControl account type. ACCOUNTS_RECEIVABLE requires customerId on journal entries, ACCOUNTS_PAYABLE requires vendorId. Null for regular accounts.
vatCodeIdVAT code applied by default to journal-entry lines on this account, or null
Create an account
Credential: a company's API key or OAuth token.
Creates an account in the chart of accounts. The account number must be free
within the company (409 LEDGER_ACCOUNT_NUMBER_ALREADY_EXISTS otherwise).
A BALANCE_SHEET or PROFIT_AND_LOSS account states its
accountClassification; a heading or total account needs none. A control
account's classification has to fit its tag: ACCOUNTS_RECEIVABLE is an
asset, ACCOUNTS_PAYABLE a liability (400
LEDGER_CONTROL_ACCOUNT_CLASSIFICATION_MISMATCH otherwise).
The account opens with a zero balance; an opening balance is posted as a journal entry.
Required Scope
accounts-write
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Create an account › Request Body
nameName of the account
accountNumberAccount number, unique within the company
ledgerTypeKind of account. Only BALANCE_SHEET and PROFIT_AND_LOSS accounts take postings; HEADING, HEADING_BREAK, TOTAL_FROM and TOTAL_INTERVALS structure the chart.
accountClassificationClassification of a postable account; required whenever the request sets ledgerType to BALANCE_SHEET or PROFIT_AND_LOSS. Decides which statement the account belongs to and which side a journal-entry line on it pre-selects. It cannot be cleared.
controlAccountTypeMarks a control account. Lines on an ACCOUNTS_RECEIVABLE account need a customerId, lines on an ACCOUNTS_PAYABLE account a supplierId. The classification must fit: receivable is an ASSET, payable a LIABILITY. Null clears it.
debitCreditThe side a journal-entry line on this account pre-selects: debit or credit. Omitted on create, it follows accountClassification (ASSET and EXPENSE pre-select debit, the rest credit); an account with no classification, which only a heading or total account can be, pre-selects debit. It cannot be cleared.
vatCodeIdVAT code applied by default to journal-entry lines on this account. Null clears it.
currencyCurrency the account is kept in, as an ISO 4217 code. Applies to a BALANCE_SHEET account only; every other account is kept in the company's base currency and the field is ignored. Moving an account off BALANCE_SHEET resets it to the base currency.
tagsFree-form tags for grouping accounts (at most 25, each at most 50 characters)
mapsToThe account number this account reports under. When set, publicAccountId reports it instead of accountNumber. Null clears it.
totalFromFor a TOTAL_FROM account: the first account number to sum from; the total runs up to the account's own number. Required whenever the request sets ledgerType to TOTAL_FROM.
For a TOTAL_INTERVALS account: the account-number ranges to sum (at most 50). Required whenever the request sets ledgerType to TOTAL_INTERVALS.
Create an account › Responses
Account created successfully
idThe unique identifier of the account
nameName of the account
accountNumberAccount type number
publicAccountIdPublic account id that the account maps to
ledgerTypeType of ledger account. Only BALANCE_SHEET and PROFIT_AND_LOSS accounts can be used in journal entries.
debitCreditThe side a journal-entry line on this account pre-selects: debit or credit. This is the Debit/Credit choice on the account form. It does not decide how a balance is reported; accountClassification does.
requiredDimensionIdsIDs of the dimensions this account requires: every journal entry line posting to the account must carry a value from each of them, or the entry is refused with JOURNAL_TAG_REQUIRED_DIMENSION_MISSING. Empty when the account requires none. This is the account setting as stored: a dimension that has since been deactivated stays listed and is not enforced until it is active again, so match the ids against the dimensions list, which returns active dimensions only.
currencyThe currency the account is kept in (ISO 4217). A balance-sheet account may be kept in a foreign currency; every other account is kept in the company's base currency.
tagsFree-form tags for grouping accounts
createdAtWhen the account was created
updatedAtWhen the account was last changed
accountClassificationAccount classification (ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE)
controlAccountTypeControl account type. ACCOUNTS_RECEIVABLE requires customerId on journal entries, ACCOUNTS_PAYABLE requires vendorId. Null for regular accounts.
vatCodeIdVAT code applied by default to journal-entry lines on this account, or null
mapsToThe account number this account reports under. When set, publicAccountId follows it.
totalFromFor a TOTAL_FROM account: the first account number it sums from, up to the account's own number
For a TOTAL_INTERVALS account: the account-number ranges it sums
deactivatedAtWhen the account was deactivated, or null while it is active
Get an account
Credential: a company's API key or OAuth token.
Returns a single account with every field the write endpoints accept, so a read after a write shows what was stored.
Required Scope
accounts-read
path Parameters
accountIdAccount ID
Get an account › Responses
Account details
idThe unique identifier of the account
nameName of the account
accountNumberAccount type number
publicAccountIdPublic account id that the account maps to
ledgerTypeType of ledger account. Only BALANCE_SHEET and PROFIT_AND_LOSS accounts can be used in journal entries.
debitCreditThe side a journal-entry line on this account pre-selects: debit or credit. This is the Debit/Credit choice on the account form. It does not decide how a balance is reported; accountClassification does.
requiredDimensionIdsIDs of the dimensions this account requires: every journal entry line posting to the account must carry a value from each of them, or the entry is refused with JOURNAL_TAG_REQUIRED_DIMENSION_MISSING. Empty when the account requires none. This is the account setting as stored: a dimension that has since been deactivated stays listed and is not enforced until it is active again, so match the ids against the dimensions list, which returns active dimensions only.
currencyThe currency the account is kept in (ISO 4217). A balance-sheet account may be kept in a foreign currency; every other account is kept in the company's base currency.
tagsFree-form tags for grouping accounts
createdAtWhen the account was created
updatedAtWhen the account was last changed
accountClassificationAccount classification (ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE)
controlAccountTypeControl account type. ACCOUNTS_RECEIVABLE requires customerId on journal entries, ACCOUNTS_PAYABLE requires vendorId. Null for regular accounts.
vatCodeIdVAT code applied by default to journal-entry lines on this account, or null
mapsToThe account number this account reports under. When set, publicAccountId follows it.
totalFromFor a TOTAL_FROM account: the first account number it sums from, up to the account's own number
For a TOTAL_INTERVALS account: the account-number ranges it sums
deactivatedAtWhen the account was deactivated, or null while it is active
Delete an account
Credential: a company's API key or OAuth token.
Deletes an account that nothing refers to. An account with postings, a
system role, a bank account, a default on a customer or supplier, or any
other reference is refused with 409 LEDGER_DELETE_BLOCKED; the response
details.blockers lists each reason with a count.
Required Scope
accounts-write
path Parameters
accountIdAccount ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Delete an account › Responses
Account deleted successfully
Update an account
Credential: a company's API key or OAuth token.
Updates an account. Only the fields provided in the request are changed;
send null to clear an optional field such as vatCodeId. name and
accountNumber cannot be cleared (400 LEDGER_FIELD_NOT_CLEARABLE).
Required Scope
accounts-write
path Parameters
accountIdAccount ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Update an account › Request Body
accountClassificationClassification of a postable account; required whenever the request sets ledgerType to BALANCE_SHEET or PROFIT_AND_LOSS. Decides which statement the account belongs to and which side a journal-entry line on it pre-selects. It cannot be cleared.
controlAccountTypeMarks a control account. Lines on an ACCOUNTS_RECEIVABLE account need a customerId, lines on an ACCOUNTS_PAYABLE account a supplierId. The classification must fit: receivable is an ASSET, payable a LIABILITY. Null clears it.
debitCreditThe side a journal-entry line on this account pre-selects: debit or credit. Omitted on create, it follows accountClassification (ASSET and EXPENSE pre-select debit, the rest credit); an account with no classification, which only a heading or total account can be, pre-selects debit. It cannot be cleared.
vatCodeIdVAT code applied by default to journal-entry lines on this account. Null clears it.
currencyCurrency the account is kept in, as an ISO 4217 code. Applies to a BALANCE_SHEET account only; every other account is kept in the company's base currency and the field is ignored. Moving an account off BALANCE_SHEET resets it to the base currency.
tagsFree-form tags for grouping accounts (at most 25, each at most 50 characters)
mapsToThe account number this account reports under. When set, publicAccountId reports it instead of accountNumber. Null clears it.
totalFromFor a TOTAL_FROM account: the first account number to sum from; the total runs up to the account's own number. Required whenever the request sets ledgerType to TOTAL_FROM.
For a TOTAL_INTERVALS account: the account-number ranges to sum (at most 50). Required whenever the request sets ledgerType to TOTAL_INTERVALS.
nameName of the account
accountNumberAccount number, unique within the company
ledgerTypeKind of account. Setting a postable type requires accountClassification in the same request; setting TOTAL_FROM requires totalFrom, and TOTAL_INTERVALS requires intervals.
Update an account › Responses
Account updated successfully
idThe unique identifier of the account
nameName of the account
accountNumberAccount type number
publicAccountIdPublic account id that the account maps to
ledgerTypeType of ledger account. Only BALANCE_SHEET and PROFIT_AND_LOSS accounts can be used in journal entries.
debitCreditThe side a journal-entry line on this account pre-selects: debit or credit. This is the Debit/Credit choice on the account form. It does not decide how a balance is reported; accountClassification does.
requiredDimensionIdsIDs of the dimensions this account requires: every journal entry line posting to the account must carry a value from each of them, or the entry is refused with JOURNAL_TAG_REQUIRED_DIMENSION_MISSING. Empty when the account requires none. This is the account setting as stored: a dimension that has since been deactivated stays listed and is not enforced until it is active again, so match the ids against the dimensions list, which returns active dimensions only.
currencyThe currency the account is kept in (ISO 4217). A balance-sheet account may be kept in a foreign currency; every other account is kept in the company's base currency.
tagsFree-form tags for grouping accounts
createdAtWhen the account was created
updatedAtWhen the account was last changed
accountClassificationAccount classification (ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE)
controlAccountTypeControl account type. ACCOUNTS_RECEIVABLE requires customerId on journal entries, ACCOUNTS_PAYABLE requires vendorId. Null for regular accounts.
vatCodeIdVAT code applied by default to journal-entry lines on this account, or null
mapsToThe account number this account reports under. When set, publicAccountId follows it.
totalFromFor a TOTAL_FROM account: the first account number it sums from, up to the account's own number
For a TOTAL_INTERVALS account: the account-number ranges it sums
deactivatedAtWhen the account was deactivated, or null while it is active