Skip to main content

API Reference

Types of methods

API methods are categorized into one of four types:

  • get
  • create
  • update
  • delete

Objects may have fields specific for a type of method. For example, the payee field of a transaction is only available in a create method. This field doesn't exist in objects returned from a get method (payee_id is used instead).

Fields specific to a type of request are marked as such in the notes.

id is a special field. All objects have an id field. However, you don't need to specify an id in a create method; all create methods will return the created id back to you.

All update and delete methods take an id to specify the desired object. update takes the fields to update as a second argument — it does not take a full object. That means even if a field is required, you don't have to pass it to update. For example, a category requires the group_id field, however updateCategory(id, { name: "Food" }) is a valid call. Required means that an update can't set the field to null and create method must always have it.

Primitives

These are types.

NameTypeNotes
idstringUUID
monthstringYYYY-MM
datestringYYYY-MM-DD
amountintegerA currency amount is an integer representing the value without any decimal places. Usually it’s value * 100, but it depends on your currency. For example, a USD amount of $120.30 would be 12030.

Budgets

getBudgetMonths

getBudgetMonths() Promise<month[]>

getBudgetMonth

getBudgetMonth(monthmonth) Promise<Budget>

setBudgetAmount

setBudgetAmount(monthmonth, idcategoryId, amountvalue) Promise<null>

setBudgetCarryover

setBudgetCarryover(monthmonth, idcategoryId, boolflag) Promise<null>

holdBudgetForNextMonth

holdBudgetForNextMonth(monthmonth, amountvalue) Promise<null>

resetBudgetHold

resetBudgetHold(monthmonth) Promise<null>

Transactions

Transaction

FieldTypeRequired?Notes
ididno
accountidyes
datedateyes
amountamountno
payeeidnoIn a create request, this overrides payee_name.
payee_namestringno
If given, a payee will be created with this name. If this matches an already existing payee, it will use it.
* Only available in a create request
imported_payeestringnoThis can be anything. Meant to represent the raw description when importing, allowing the user to see the original value.
categoryidno
notesstringno
imported_idstringnoA unique id usually given by the bank, if importing. Use this is avoid duplicate transactions.
transfer_idstringnoIf a transfer, the id of the transaction in the other account for the transfer. See transfers.
clearedbooleannoA flag indicating if the transaction has cleared or not.
subtransactionsTransaction[]no
An array of subtransactions for a split transaction. See split transactions.
* Only available in a get or create request

Split transactions

A split transaction has several sub-transactions that split the total amount across them. You can create a split transaction by specifying an an array of sub-transactions in the subtransactions field.

Subtransactions can specify the following fields, and amount is the only required field:

  • amount
  • category_id
  • notes

If the amounts of the sub-transactions do not equal the total amount of the transaction, currently the API call will succeed but an error with be displayed within the app.

Transfers

Existing transfers will have the transfer_id field which points to the transaction on the other side. You should not change this or you will cause unexpected behavior. (You are allowed to set this when importing, however.)

If you want to create a transfer, use the transfer payee for the account you wish to transfer to/from. Load the payees, use the transfer_acct field of the payee to find the account you want to transfer to/from assign that payee to the transaction. A transfer with a transaction in both accounts will be created. (See transfer payees.)

Methods

addTransactions

addTransactions(idaccountId, Transaction[]transactions, bool?runTransfers = false, bool?learnCategories = false) Promise<id[]>

Adds multiple transactions at once. Does not reconcile (see importTransactions). Returns an array of ids of the newly created transactions.

This method does not avoid duplicates. Use importTransactions if you want the full reconcile behavior.

This method has the following optional flags:

  • runTransfers: create transfers for transactions where transfer payee is given (defaults to false)
  • learnCategories: update Rules based on the category field in the transactions (defaults to false)

This method is mainly for custom importers that want to skip all the automatic stuff because it wants to create raw data. You probably want to use importTransactions.

importTransactions

importTransactions(idaccountId, Transaction[]transactions) Promise<{ errors, added, updated }>

Adds multiple transactions at once, while going through the same process as importing a file or downloading transactions from a bank. In particular, all rules are run on the specified transactions before adding them. Use addTransactions instead for adding raw transactions without post-processing.

The import will "reconcile" transactions to avoid adding duplicates. Transactions with the same imported_id will never be added more than once. Otherwise, the system will match transactions with the same amount and with similar dates and payees and try to avoid duplicates. If not using imported_id you should check the results after importing.

It will also create transfers if a transfer payee is specified. See transfers.

This method returns an object with the following fields:

  • added: an array of ids of transactions that were added
  • updated: an array of ids of transactions that were updated (such as being cleared)
  • errors: any errors that occurred during the process (most likely a single error with no changes to transactions)

getTransactions

getTransactions(idaccountId, datestartDate, dateendDate) Promise<Transaction[]>

Get all the transactions in accountId between the specified dates (inclusive). Returns an array of Transaction objects.

updateTransaction

updateTransaction(idid, objectfields) Promise<null>

Update fields of a transaction. fields can specify any field described in Transaction.

deleteTransaction

deleteTransaction(idid) Promise<null>

Delete a transaction.

Examples

// Create a transaction of $12.00. A payee of "Kroger" will be
// automatically created if it does not exist already and
// assigned to the transaction.

await importTransactions(accountId, [
{
date: '2019-08-20',
amount: 1200,
payee_name: 'Kroger',
category_id: 'c179c3f4-28a6-4fbd-a54d-195cced07a80',
},
]);
// Get all transactions in an account for the month of August
// (it doesn't matter that August 31st doesn't exist).

await getTransactions(accountId, '2019-08-01', '2019-08-31');
// Assign the "Food" category to a transaction

let categories = await getCategories();
let foodCategory = category.find(cat => cat.name === 'Food');
await updateTransaction(id, { category_id: foodCategory.id });

Accounts

Account

FieldTypeRequired?Notes
ididno
namestringyes
typestringyesMust be a valid type. See notes below.
offbudgetboolnoDefaults to false
closedboolnoDefaults to false

Account types

The account type must be one of these valid strings:

  • checking
  • savings
  • credit
  • investment
  • mortgage
  • debt
  • other

The account type does not effect anything currently. It's simply extra information about the account.

Closing accounts

Avoid setting the closed property directly to close an account; instead use the closeAccount method. If the account still has money in it you will be required to specify another account to transfer the current balance to. This will help track your money correctly.

If you want to fully delete an account and remove it entirely from the system, use deleteAccount. Note that if it's an on-budget account, any money coming from that account will disappear.

Methods

getAccounts

getAccounts() Promise<Account[]>

Get all accounts. Returns an array of Account objects.

createAccount

createAccount(Accountaccount, amount?initialBalance = 0) Promise<id>

Create an account with an initial balance of initialBalance (defaults to 0). Remember that amount has no decimal places. Returns the id of the new account.

updateAccount

updateAccount(idid, objectfields) Promise<null>

Update fields of an account. fields can specify any field described in Account.

closeAccount

closeAccount(idid, id?transferAccountId, id?transferCategoryId) Promise<null>

Close an account. transferAccountId and transferCategoryId are optional if the balance of the account is 0, otherwise see next paragraph.

If the account has a non-zero balance, you need to specify an account with transferAccountId to transfer the money into. If you are transferring from an on-budget account to an off-budget account, you can optionally specify a category with transferCategoryId to categorize the transfer transaction.

Transferring money to an off-budget account needs a category because money is taken out of the budget, so it needs to come from somewhere.

If you want to simply delete an account, see deleteAccount.

reopenAccount

reopenAccount(idid) Promise<null>

Reopen a closed account.

deleteAccount

deleteAccount(idid) Promise<null>

Delete an account.

getAccountBalance

getAccountBalance(idid, Date?cutoff) Promise<number>

Gets the balance for an account. If a cutoff is given, it gives the account balance as of that date. If no cutoff is given, it uses the current date as the cutoff.

Examples

// Create a savings accounts
createAccount({
name: "Ally Savings",
type: "savings
})
// Get all accounts

let accounts = await getAccounts();

Categories

Category

FieldTypeRequired?Notes
ididno
namestringyes
group_ididyes
is_incomeboolnoDefaults to false

Methods

getCategories

getCategories() Promise<Category[]>

Get all categories.

createCategory

createCategory(Categorycategory) Promise<id>

Create a category. Returns the id of the new account.

updateCategory

updateCategory(idid, objectfields) Promise<null>

Update fields of a category. fields can specify any field described in Category.

deleteCategory

deleteCategory(idid) Promise<null>

Delete a category.

Examples

{
name: "Food",
group_id: "238d4d38-a512-4e28-9bbe-e96fd5d99251"
}

Income categories

Set is_income to true to create an income category. The group_id of the category should point to the existing income group category (currently only one ever exists, see category group).

Category groups

Category group

FieldTypeRequired?Notes
ididno
namestringyes
is_incomeboolnoDefaults to false
categoriesCategory[]no
An array of categories in this group. Not valid when creating or updating a category group
Only available in a get.
{
name: 'Bills';
}

Income category groups

There should only ever be one income category group,

Methods

getCategoryGroups

getCategoryGroups() Promise<CategoryGroup[]>

Get all category groups.

createCategoryGroup

createCategoryGroup(CategoryGroupgroup) Promise<id>

Create a category group. Returns the id of the new group.

updateCategoryGroup

updateCategoryGroup(idid, objectfields) Promise<id>

Update fields of a category group. fields can specify any field described in CategoryGroup.

deleteCategoryGroup

deleteCategoryGroup(idid) Promise<null>

Delete a category group.

Payees

Payee

FieldTypeRequired?Notes
ididno
namestringyes
categoryidno
transfer_acctidnoThe id of the account this payee transfers to/from, if this is a transfer payee.
{
name: "Kroger",
category: "a1bccbd1-039e-410a-ba05-a76b97a74fc8"
}

Transfers

Transfers use payees to indicate which accounts to transfer money to/from. This lets the system use the same payee matching logic to manage transfers as well.

Each account has a corresponding "transfer payee" already created in the system. If a payee is a transfer payee, it will have the transfer_acct field set to an account id. Use this to create transfer transactions with importTransactions.

Methods

getPayees

getPayees() Promise<Payee[]>

Get all payees.

createPayee

createPayee(Payeepayee) Promise<id>

Create a payee. Returns the id of the new payee.

updatePayee

updatePayee(idid, objectfields) Promise<id>

Update fields of a payee. fields can specify any field described in Payee.

deletePayee

deletePayee(idid) Promise<null>

Delete a payee.

mergePayees

mergePayees(idtargetId, id[]mergeIds) Promise<null>

Merge one or more payees into the target payee, retaining the name of the target.

Rules

ConditionOrAction

FieldTypeRequired?Notes
fieldstringyes
opstringyes
valuestringyes

Rule

FieldTypeRequired?Notes
ididno
stagestringyesMust be one of pre, default, or post.
conditionsOpstringnoMust be one of and or or.
conditionsConditionOrAction[]no
actionsConditionOrAction[]no

Payee rule

FieldTypeRequired?Notes
ididno
payee_ididyes
stagestringyesMust be one of pre, default, or post.
conditionsOpstringnoMust be one of and or or.
conditionsConditionOrAction[]no
actionsConditionOrAction[]no

Methods

getRules

getRules() Promise<Rule[]>

Get all rules.

getPayeeRules

getPayeeRules(idpayeeId) Promise<PayeeRule[]>

Get all payees rules for payeeId.

createRule

createRule(Rulerule) Promise<Rule>

Create a rule. Returns the new rule, including the id.

updateRule

updateRule(idid, objectfields) Promise<Rule>

Update fields of a rule. fields can specify any field described in Rule. Returns the updated rule.

deleteRule

deleteRule(idid) Promise<null>

Delete a rule.

Examples

{
stage: 'pre',
conditionsOp: 'and',
conditions: [
{
field: 'payee',
op: 'is',
value: 'test-payee',
},
],
actions: [
{
op: 'set',
field: 'category',
value: 'fc3825fd-b982-4b72-b768-5b30844cf832',
},
],
}

Misc

BudgetFile

FieldTypeRequired?Notes
namestringyesThe budget's name.
cloudFileIdstringyesThe id for the budget on the server. This is usually a UUID.
groupIdstringyesThe group id for the budget.
hasKeybooleanyesIf the file has an encryption key.
encryptKeyIdstringnoThe encryption key ID for the file, if it is encrypted.
statestringnoRemote files have this set to "remote".
idstringnoThe local budget file's local ID.

InitConfig

FieldTypeRequired?Notes
serverURLstringnoThe URL of your Actual Budget server.
passwordstringnoThe password of your Actual Budget server.
dataDirstringnoThe directory to store locally cached budget files.

Methods

init

init({ InitConfigconfig }) Promise<void>

Initializes the API by connecting to an Actual Budget server.

shutdown

shutdown() Promise<void>

Shuts down the API. This will close any open budget and clean up any resources.

sync

sync() Promise<void>

Synchronizes the locally cached budget files with the server's copy.

runBankSync

runBankSync({ stringaccountId }) Promise<void>

Run the 3rd party (gocardless, simplefin) bank sync operation. This will download the transactions and insert them into the ledger.

runImport

runImport({ stringbudgetName, funcfunc }) Promise<void>

Creates a new budget file with the given name, and then runs the custom importer function to populate it with data.

getBudgets

getBudgets() Promise<BudgetFile[]>

Returns a list of all budget files either locally cached or on the remote server. Remote files have a state field and local files have an id field.

loadBudget

loadBudget({ stringsyncId }) Promise<void>

Load a locally cached budget file.

downloadBudget

downloadBudget({ stringsyncId, string?password }) Promise<void>

Load a budget file. If the file exists locally, it will load from there. Otherwise, it will download the file from the server.

batchBudgetUpdates

batchBudgetUpdates({ funcfunc }) Promise<void>

Performs a batch of budget updates. This is useful for making multiple changes to the budget in a single call to the server.

runQuery

runQuery({ ActualQLquery }) Promise<unknown>

Allows running any arbitrary ActualQL query on the open budget.