YNAB
App · Accounting & Finance · 5 actions
Work with your YNAB budget: list budgets, accounts, and categories with their balances, read transactions, and add new ones. Amounts are plain currency figures; YNAB's milliunits are converted for you.
Actions
| Action | What it does |
|---|---|
| Create a transaction | Add one transaction to a budget account. |
| List accounts | List a budget's accounts with their current, cleared, and uncleared balances as currency amounts. |
| List budgets | List the budgets on your YNAB account, with the id each of the other actions can be pointed at. |
| List categories | List a budget's category groups and the categories inside them, with what is assigned, spent, and left this month. |
| List transactions | List a budget's transactions, optionally only those since a date or only the ones still needing attention. |
Create a transaction
Add one transaction to a budget account. Use a negative amount for money spent and a positive amount for money received.
Inputs
- Budget ID
budget_idtext - Optional. Which budget to use. Defaults to the budget you most recently opened in YNAB. List budgets to find an id.
- Account ID
account_idtextRequired - Which account the transaction belongs to. List accounts to find the id.
- Date
datetextRequired - The transaction date, as YYYY-MM-DD.
- Amount
amounttextRequired - The amount as a normal currency figure, for example -12.50 for money spent or 1500 for money received. YNAB's milliunit conversion is handled for you.
- Payee
payee_nametext - Optional. Who the money went to or came from. YNAB creates the payee if it does not exist yet.
- Category ID
category_idtext - Optional. Which category to file this under. List categories to find the id.
- Memo
memotext - Optional. A free-text memo on the transaction.
- Cleared status
clearedtext - Optional. Whether the transaction has cleared the account. YNAB defaults to uncleared.One of:
uncleared,cleared,reconciled. - Approved
approvedtrue/false - Optional. Whether the transaction is approved. On by default; turn it off to leave it for review in YNAB.Default:
true.
Outputs
transactionobject- The transaction as YNAB stored it.
Example output
{
"transaction": {
"account_id": "bb20b20b-2b2b-4b2b-8b2b-2b2b2b2b2b2b",
"account_name": "Everyday Checking",
"amount": -12.5,
"approved": true,
"category_id": "ee50e50e-5e5e-4e5e-8e5e-5e5e5e5e5e5e",
"category_name": "Dining Out",
"cleared": "uncleared",
"date": "2024-01-15",
"deleted": false,
"flag_color": null,
"id": "cc30c30c-3c3c-4c3c-8c3c-3c3c3c3c3c3c",
"import_id": null,
"memo": "Lunch",
"payee_id": "dd40d40d-4d4d-4d4d-8d4d-4d4d4d4d4d4d",
"payee_name": "Corner Deli",
"transfer_account_id": null
}
}List accounts
List a budget's accounts with their current, cleared, and uncleared balances as currency amounts.
Inputs
- Budget ID
budget_idtext - Optional. Which budget to use. Defaults to the budget you most recently opened in YNAB. List budgets to find an id.
Outputs
accountslist- The budget's accounts.
countnumber- How many accounts were returned.
Example output
{
"accounts": [
{
"balance": 1204.55,
"cleared_balance": 1180.05,
"closed": false,
"deleted": false,
"id": "bb20b20b-2b2b-4b2b-8b2b-2b2b2b2b2b2b",
"last_reconciled_at": "2024-01-10T09:00:00+00:00",
"name": "Everyday Checking",
"note": null,
"on_budget": true,
"type": "checking",
"uncleared_balance": 24.5
}
],
"count": 1
}List budgets
List the budgets on your YNAB account, with the id each of the other actions can be pointed at.
Inputs
None.
Outputs
budgetslist- The budgets on the account.
countnumber- How many budgets were returned.
Example output
{
"budgets": [
{
"currency_code": "USD",
"first_month": "2023-01-01",
"id": "aa10a10a-1a1a-4a1a-8a1a-1a1a1a1a1a1a",
"last_modified_on": "2024-01-15T18:22:11+00:00",
"last_month": "2024-02-01",
"name": "My Budget"
}
],
"count": 1
}List categories
List a budget's category groups and the categories inside them, with what is assigned, spent, and left this month.
Inputs
- Budget ID
budget_idtext - Optional. Which budget to use. Defaults to the budget you most recently opened in YNAB. List budgets to find an id.
Outputs
category_groupslist- The budget's category groups, each with its categories nested inside.
countnumber- How many categories were returned across all groups.
Example output
{
"category_groups": [
{
"categories": [
{
"activity": -87.25,
"balance": 112.75,
"budgeted": 200.0,
"category_group_id": "ff60f60f-6f6f-4f6f-8f6f-6f6f6f6f6f6f",
"deleted": false,
"goal_percentage_complete": null,
"goal_target": null,
"goal_type": null,
"hidden": false,
"id": "ee50e50e-5e5e-4e5e-8e5e-5e5e5e5e5e5e",
"name": "Dining Out",
"note": null
}
],
"deleted": false,
"hidden": false,
"id": "ff60f60f-6f6f-4f6f-8f6f-6f6f6f6f6f6f",
"name": "Just for Fun"
}
],
"count": 1
}List transactions
List a budget's transactions, optionally only those since a date or only the ones still needing attention.
Inputs
- Budget ID
budget_idtext - Optional. Which budget to use. Defaults to the budget you most recently opened in YNAB. List budgets to find an id.
- Since date
since_datetext - Optional. Only transactions on or after this date, as YYYY-MM-DD.
- Only show
transaction_typetext - Optional. Narrow to transactions that still need attention.One of:
uncategorized(Uncategorized only),unapproved(Unapproved only).
Outputs
countnumber- How many transactions were returned.
transactionslist- The matching transactions.
Example output
{
"count": 1,
"transactions": [
{
"account_id": "bb20b20b-2b2b-4b2b-8b2b-2b2b2b2b2b2b",
"account_name": "Everyday Checking",
"amount": -12.5,
"approved": true,
"category_id": "ee50e50e-5e5e-4e5e-8e5e-5e5e5e5e5e5e",
"category_name": "Dining Out",
"cleared": "uncleared",
"date": "2024-01-15",
"deleted": false,
"flag_color": null,
"id": "cc30c30c-3c3c-4c3c-8c3c-3c3c3c3c3c3c",
"import_id": null,
"memo": "Lunch",
"payee_id": "dd40d40d-4d4d-4d4d-8d4d-4d4d4d4d4d4d",
"payee_name": "Corner Deli",
"transfer_account_id": null
}
]
}