Developers

API

This is the documentation of all available API methods. The API has not been released yet, but it will be available in the next update. This section is a work in progress.

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>

Examples

Transactions

Transaction

FieldTypeRequired?Notes
ididno
account_ididyes
datedateyes
amountamountno
payee_ididnoIn a create request, this overrides payee.
payeestringno
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.
category_ididno
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.
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) Promise<id[]>

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

If a transfer payee is given, this method does not create a transfer. Use importTransactions if you want to create transfers.

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

importTransactions

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

Adds multiple transactions at once, but goes through the same process as importing a file or downloading transactions from a bank. You probably want to use this one. Returns an array of ids of the newly created transactions.

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.

filterTransactions

filterTransactions(idaccountId, stringtext) Promise<Transaction[]>

Search for transactions that match text in accountId. It will return transactions where any field (payee name, category name, amount, etc) matches text. Returns an array of Transaction objects.

This will be documented better and improved in the future.

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, [{
account_id: "e2564e8c-ec96-43d7-92ce-3b91ee9d2d69",
date: "2019-08-20",
amount: 1200,
payee: "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")
// Find transactions with the amount of 3.91. Currently this
// assumes you are using a currency with two decimal places.
await filterTransactions(accountId, "3.91")
// 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.

Tranferring 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.

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_idboolyes
is_incomeboolnoDefaults to false

Methods

getCategories

getCategories() Promise<Categories[]>

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.

Examples

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.

Examples

Payee rules

Payee rule

FieldTypeRequired?Notes
ididno
payee_ididyes
typestringyesMust be one of equals or contains
valuestringnoValue to match imported payee names on

Methods

getPayeeRules

getPayees(idpayeeId) Promise<PayeeRule[]>

Get all payees rules for payeeId.

createPayeeRule

createPayeeRule(idpayeeId, PayeeRulerule) Promise<id>

Create a payee rule for payeeId. Returns the id of the new rule.

updatePayeeRule

updatePayeeRule(idid, objectfields) Promise<id>

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

deletePayeeRule

deletePayeeRule(idid) Promise<null>

Delete a payee rule.

Examples

{
payee_id: "08fc54b5-3baa-4874-bef4-470c238d25ac",
type: "contains",
value: "grocery"
}