YNAB API Javascript (Node) Library
NOTE: The YNAB API is currently only available to Early Access users. If you are interested in requesting access before the API is generally available, please fill out this form.
Please read the YNAB API documentation for an overview of using the API and a complete list of available resources.
This client is generated using the Swagger Code Generator.
Installation
First, install the module with npm (or yarn):
npm install ynab
Then, depending upon your usage context, add a reference to it:
CommonJS / Node
const ynab = require("ynab");
ESM / TypeScript
import * as ynab from "ynab";
Browser
The dist/browser/ynab.js
file (located in node_modules/ynab after installation) is specifically built to run in a browser / window context and exports ynab
variable to global namespace. No other dependencies are needed.
<script src="ynab.js" async></script>
...
<script>
var ynab = window.ynab;
</script>
Usage
To use this client, you must
obtain an access token from
the My Account area of the YNAB web
application.
const accessToken = "b43439eaafe2_this_is_fake_b43439eaafe2";
const ynabAPI = new ynab.api(accessToken);
(async function() {
const budgetsResponse = await ynabAPI.budgets.getBudgets();
const budgets = budgetsResponse.data.budgets;
for(let budget of budgets) {
console.log(`Budget Name: ${budget.name}`);
}
})();
Error Handling
If a response is returned with a code >= 300, instead of returning the response,
the response will be "thrown" as an error to be caught.
const ynab = require("ynab");
const accessToken = "invalid_token";
const ynabAPI = new ynab.api(accessToken);
const budgetsResponse = ynabAPI.budgets.getBudgets()
.then(budgetsResponse => {
})
.catch(e => {
console.log(e);
});
Utilities
There are several utilities available on the utils
export to make working
with ISO dates and milliunits a bit
easier.
getCurrentMonthInISOFormat(): string;
getCurrentDateInISOFormat(): string;
convertFromISODateString(isoDateString: string): Date;
convertMilliUnitsToCurrencyAmount(milliunits: number, currencyDecimalDigits: number): number;
Examples
See the examples
folder for example usage scenarios.
Methods
The following methods are available in this library. For more details on parameters and usage, the TypeScript declaration file can be referenced.
| Method | Description |
---|
Budgets | budgets.getBudgets() | Returns budgets list with summary information |
| budgets.getBudgetById(id) | Returns a single budget with all related entities |
Accounts | accounts.getAccounts(budgetId) | Returns all accounts |
| accounts.getAccountById(budgetId, id) | Returns a single account |
Categories | categories.getCategories(budgetId) | Returns all categories grouped by category group. |
| categories.getCategoryById(budgetId, id) | Returns a single category |
Payees | payees.getPayees(budgetId) | Returns all payees |
| payees.getPayeeById(budgetId, id) | Returns single payee |
Payee Locations | payeeLocations.getPayeeLocations(budgetId) | Returns all payee locations |
| payeeLocations.getPayeeLocationById(budgetId, id) | Returns a single payee location |
| payeeLocations.getPayeeLocationsByPayee(budgetId, id) | Returns all payee locations for the specified payee |
Months | months.getBudgetMonths(budgetId) | Returns all budget months |
| months.getBudgetMonth(budgetId, month) | Returns a single budget month |
Transactions | transactions.getTransactions(budgetId) | Returns budget transactions |
| transactions.getTransactionsByAccount(budgetId, id) | Returns all transactions for a specified account |
| transactions.getTransactionsByCategory(budgetId, id) | Returns all transactions for a specified category |
| transactions.getTransactionsById(budgetId, id) | Returns a single transaction |
| transactions.updateTransaction(budgetId, id, transaction) | Updates a transaction |
| transactions.createTransaction(budgetId, transaction) | Creates a new transaction |
| transactions.bulkCreateTransactions(budgetId, transactions) | Creates multiple transactions |
Scheduled Transactions | scheduledTransactions.getScheduledTransactions(budgetId) | Returns all scheduled transactions |
| scheduledTransactions.getScheduledTransactionById(budgetId, id) | Returns a single scheduled transaction |
Development
To build and compile:
npm install
npm run build
To run tests:
npm test
License
Copyright (c) 2018 You Need A Budget, LLC
Licensed under the Apache-2.0 license