Skip to main content

API Reference

Budgets
Transactions
Accounts
Categories
Category Groups
Payees
Rules
Misc

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.