Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
YNAB API v1 OpenAPI v3 YAML
openapi: 3.0.0
info:
description: Our API uses a REST based design, leverages the JSON data format, and relies
upon HTTPS for transport. We respond with meaningful HTTP response codes and
if an error occurs, we include error details in the response body. API
Documentation is at https://api.youneedabudget.com
version: 1.0.0
title: YNAB API Endpoints
tags:
- name: User
- name: Budgets
- name: Accounts
description: The accounts for a budget
- name: Categories
description: The categories for a budget
- name: Payees
description: The payees for a budget
- name: Payee Locations
description: When you enter a transaction and specify a payee on the YNAB mobile apps,
the GPS coordinates for that location are stored, with your permission, so
that the next time you are in the same place (like the Grocery store) we
can pre-populate nearby payees for you! It’s handy and saves you
time. This resource makes these locations available. Locations will not
be available for all payees.
- name: Months
description: Each budget contains one or more months, which is where To be Budgeted,
Age of Money and category (budgeted / activity / balances) amounts are
available.
- name: Transactions
description: The transactions for a budget
- name: Scheduled Transactions
description: The scheduled transactions for a budget
security:
- bearer:
[]
paths:
/user:
get:
tags:
- User
summary: User info
description: Returns authenticated user information
operationId: getUser
responses:
"200":
description: The user info
content:
application/json:
schema:
$ref: "#/components/schemas/UserResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/budgets:
get:
tags:
- Budgets
summary: List budgets
description: Returns budgets list with summary information
operationId: getBudgets
responses:
"200":
description: The list of budgets
content:
application/json:
schema:
$ref: "#/components/schemas/BudgetSummaryResponse"
"404":
description: No budgets were found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}":
get:
tags:
- Budgets
summary: Single budget
description: Returns a single budget with all related entities. This resource is
effectively a full budget export.
operationId: getBudgetById
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: last_knowledge_of_server
in: query
description: The starting server knowledge. If provided, only entities that have
changed since last_knowledge_of_server will be included.
required: false
schema:
type: integer
format: int64
responses:
"200":
description: The requested budget
content:
application/json:
schema:
$ref: "#/components/schemas/BudgetDetailResponse"
"404":
description: The specified budget was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/settings":
get:
tags:
- Budgets
summary: Budget Settings
description: Returns settings for a budget
operationId: getBudgetSettingsById
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
responses:
"200":
description: The requested budget settings
content:
application/json:
schema:
$ref: "#/components/schemas/BudgetSettingsResponse"
"404":
description: The specified Budget was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/accounts":
get:
tags:
- Accounts
summary: Account list
description: Returns all accounts
operationId: getAccounts
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: last_knowledge_of_server
in: query
description: The starting server knowledge. If provided, only entities that have
changed since last_knowledge_of_server will be included.
required: false
schema:
type: integer
format: int64
responses:
"200":
description: The list of requested accounts
content:
application/json:
schema:
$ref: "#/components/schemas/AccountsResponse"
"404":
description: No nccounts were found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/accounts/{account_id}":
get:
tags:
- Accounts
summary: Single account
description: Returns a single account
operationId: getAccountById
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: account_id
in: path
description: The id of the account
required: true
schema:
type: string
format: uuid
responses:
"200":
description: The requested account
content:
application/json:
schema:
$ref: "#/components/schemas/AccountResponse"
"404":
description: The requested account was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/categories":
get:
tags:
- Categories
summary: List categories
description: Returns all categories grouped by category group. Amounts (budgeted,
activity, balance, etc.) are specific to the current budget month (UTC).
operationId: getCategories
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: last_knowledge_of_server
in: query
description: The starting server knowledge. If provided, only entities that have
changed since last_knowledge_of_server will be included.
required: false
schema:
type: integer
format: int64
responses:
"200":
description: The categories grouped by category group
content:
application/json:
schema:
$ref: "#/components/schemas/CategoriesResponse"
"404":
description: No categories were found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/categories/{category_id}":
get:
tags:
- Categories
summary: Single category
description: Returns a single category. Amounts (budgeted, activity, balance, etc.)
are specific to the current budget month (UTC).
operationId: getCategoryById
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: category_id
in: path
description: The id of the category
required: true
schema:
type: string
responses:
"200":
description: The requested category
content:
application/json:
schema:
$ref: "#/components/schemas/CategoryResponse"
"404":
description: The category not was found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/months/{month}/categories/{category_id}":
get:
tags:
- Categories
summary: Single category for a specific budget month
description: Returns a single category for a specific budget month. Amounts
(budgeted, activity, balance, etc.) are specific to the current budget
month (UTC).
operationId: getMonthCategoryById
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: month
in: path
description: The budget month in ISO format (e.g. 2016-12-01) ("current" can also
be used to specify the current calendar month (UTC))
required: true
schema:
type: string
format: date
- name: category_id
in: path
description: The id of the category
required: true
schema:
type: string
responses:
"200":
description: The requested month category
content:
application/json:
schema:
$ref: "#/components/schemas/CategoryResponse"
"404":
description: The month category was not was found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
patch:
tags:
- Categories
summary: Update a category for a specific month
description: Update a category for a specific month
operationId: updateMonthCategory
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: month
in: path
description: The budget month in ISO format (e.g. 2016-12-01) ("current" can also
be used to specify the current calendar month (UTC))
required: true
schema:
type: string
format: date
- name: category_id
in: path
description: The id of the category
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/SaveMonthCategoryWrapper"
description: The category to update
required: true
responses:
"200":
description: The month category was successfully updated
content:
application/json:
schema:
$ref: "#/components/schemas/CategoryResponse"
"400":
description: The request could not be understood due to malformed syntax or
validation error(s)
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/payees":
get:
tags:
- Payees
summary: List payees
description: Returns all payees
operationId: getPayees
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: last_knowledge_of_server
in: query
description: The starting server knowledge. If provided, only entities that have
changed since last_knowledge_of_server will be included.
required: false
schema:
type: integer
format: int64
responses:
"200":
description: The requested list of payees
content:
application/json:
schema:
$ref: "#/components/schemas/PayeesResponse"
"404":
description: No payees were found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/payees/{payee_id}":
get:
tags:
- Payees
summary: Single payee
description: Returns single payee
operationId: getPayeeById
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: payee_id
in: path
description: The id of the payee
required: true
schema:
type: string
responses:
"200":
description: The requested payee
content:
application/json:
schema:
$ref: "#/components/schemas/PayeeResponse"
"404":
description: The payee was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/payee_locations":
get:
tags:
- Payee Locations
summary: List payee locations
description: Returns all payee locations
operationId: getPayeeLocations
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
responses:
"200":
description: The list of payee locations
content:
application/json:
schema:
$ref: "#/components/schemas/PayeeLocationsResponse"
"404":
description: No payees locations were found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/payee_locations/{payee_location_id}":
get:
tags:
- Payee Locations
summary: Single payee location
description: Returns a single payee location
operationId: getPayeeLocationById
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: payee_location_id
in: path
description: id of payee location
required: true
schema:
type: string
responses:
"200":
description: The payee location
content:
application/json:
schema:
$ref: "#/components/schemas/PayeeLocationResponse"
"404":
description: The payee location was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/payees/{payee_id}/payee_locations":
get:
tags:
- Payee Locations
summary: List locations for a payee
description: Returns all payee locations for the specified payee
operationId: getPayeeLocationsByPayee
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: payee_id
in: path
description: id of payee
required: true
schema:
type: string
responses:
"200":
description: The list of requested payee locations
content:
application/json:
schema:
$ref: "#/components/schemas/PayeeLocationsResponse"
"404":
description: No payees locations were found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/months":
get:
tags:
- Months
summary: List budget months
description: Returns all budget months
operationId: getBudgetMonths
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: last_knowledge_of_server
in: query
description: The starting server knowledge. If provided, only entities that have
changed since last_knowledge_of_server will be included.
required: false
schema:
type: integer
format: int64
responses:
"200":
description: The list of budget months
content:
application/json:
schema:
$ref: "#/components/schemas/MonthSummariesResponse"
"404":
description: No budget months were found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/months/{month}":
get:
tags:
- Months
summary: Single budget month
description: Returns a single budget month
operationId: getBudgetMonth
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: month
in: path
description: The budget month in ISO format (e.g. 2016-12-01) ("current" can also
be used to specify the current calendar month (UTC))
required: true
schema:
type: string
format: date
responses:
"200":
description: The budget month detail
content:
application/json:
schema:
$ref: "#/components/schemas/MonthDetailResponse"
"404":
description: The budget month was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/transactions":
get:
tags:
- Transactions
summary: List transactions
description: Returns budget transactions
operationId: getTransactions
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: since_date
in: query
description: If specified, only transactions on or after this date will be
included. The date should be ISO formatted (e.g. 2016-12-30).
required: false
schema:
type: string
format: date
- name: type
in: query
description: If specified, only transactions of the specified type will be
included. 'uncategorized' and 'unapproved' are currently supported.
required: false
schema:
type: string
enum:
- uncategorized
- unapproved
- name: last_knowledge_of_server
in: query
description: The starting server knowledge. If provided, only entities that have
changed since last_knowledge_of_server will be included.
required: false
schema:
type: integer
format: int64
responses:
"200":
description: The list of requested transactions
content:
application/json:
schema:
$ref: "#/components/schemas/TransactionsResponse"
"400":
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"404":
description: No transactions were found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
post:
tags:
- Transactions
summary: Create a single transaction or multiple transactions
description: Creates a single transaction or multiple transactions. If you provide a
body containing a 'transaction' object, a single transaction will be
created and if you provide a body containing a 'transactions' array,
multiple transactions will be created.
operationId: createTransaction
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/SaveTransactionsWrapper"
description: The transaction or transactions to create. To create a single
transaction you can specify a value for the 'transaction' object and
to create multiple transactions you can specify an array of
'transactions'. It is expected that you will only provide a value for
one of these objects.
required: true
responses:
"201":
description: The transaction or transactions were successfully created
content:
application/json:
schema:
$ref: "#/components/schemas/SaveTransactionsResponse"
"400":
description: The request could not be understood due to malformed syntax or
validation error(s).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"409":
description: A transaction on the same account with the same import_id already
exists.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
patch:
tags:
- Transactions
summary: Update multiple transactions
description: Updates multiple transactions, by 'id' or 'import_id'.
operationId: updateTransactions
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/SaveTransactionsWrapper"
description: The transactions to update. Optionally, transaction 'id' value(s) can
be specified as null and an 'import_id' value can be provided which
will allow transaction(s) to updated by their import_id.
required: true
responses:
"209":
description: The transactions were successfully updated
content:
application/json:
schema:
$ref: "#/components/schemas/SaveTransactionsResponse"
"400":
description: The request could not be understood due to malformed syntax or
validation error(s).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/transactions/{transaction_id}":
get:
tags:
- Transactions
summary: Single transaction
description: Returns a single transaction
operationId: getTransactionById
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: transaction_id
in: path
description: The id of the transaction
required: true
schema:
type: string
responses:
"200":
description: The requested transaction
content:
application/json:
schema:
$ref: "#/components/schemas/TransactionResponse"
"404":
description: The transaction was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
put:
tags:
- Transactions
summary: Updates an existing transaction
description: Updates a transaction
operationId: updateTransaction
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: transaction_id
in: path
description: The id of the transaction
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/SaveTransactionWrapper"
description: The transaction to update
required: true
responses:
"200":
description: The transaction was successfully updated
content:
application/json:
schema:
$ref: "#/components/schemas/TransactionResponse"
"400":
description: The request could not be understood due to malformed syntax or
validation error(s)
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/transactions/bulk":
post:
tags:
- Deprecated
summary: Bulk create transactions
description: Creates multiple transactions. Although this endpoint is still
supported, it is recommended to use 'POST
/budgets/{budget_id}/transactions' to create multiple transactions.
operationId: bulkCreateTransactions
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/BulkTransactions"
description: The list of transactions to create
required: true
responses:
"201":
description: The bulk request was processed sucessfully
content:
application/json:
schema:
$ref: "#/components/schemas/BulkResponse"
"400":
description: The request could not be understood due to malformed syntax or
validation error(s)
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/accounts/{account_id}/transactions":
get:
tags:
- Transactions
summary: List account transactions
description: Returns all transactions for a specified account
operationId: getTransactionsByAccount
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: account_id
in: path
description: The id of the account
required: true
schema:
type: string
- name: since_date
in: query
description: If specified, only transactions on or after this date will be
included. The date should be ISO formatted (e.g. 2016-12-30).
required: false
schema:
type: string
format: date
- name: type
in: query
description: If specified, only transactions of the specified type will be
included. 'uncategorized' and 'unapproved' are currently supported.
required: false
schema:
type: string
enum:
- uncategorized
- unapproved
- name: last_knowledge_of_server
in: query
description: The starting server knowledge. If provided, only entities that have
changed since last_knowledge_of_server will be included.
required: false
schema:
type: integer
format: int64
responses:
"200":
description: The list of requested transactions
content:
application/json:
schema:
$ref: "#/components/schemas/TransactionsResponse"
"404":
description: No transactions were found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/categories/{category_id}/transactions":
get:
tags:
- Transactions
summary: List category transactions
description: Returns all transactions for a specified category
operationId: getTransactionsByCategory
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: category_id
in: path
description: The id of the category
required: true
schema:
type: string
- name: since_date
in: query
description: If specified, only transactions on or after this date will be
included. The date should be ISO formatted (e.g. 2016-12-30).
required: false
schema:
type: string
format: date
- name: type
in: query
description: If specified, only transactions of the specified type will be
included. 'uncategorized' and 'unapproved' are currently supported.
required: false
schema:
type: string
enum:
- uncategorized
- unapproved
- name: last_knowledge_of_server
in: query
description: The starting server knowledge. If provided, only entities that have
changed since last_knowledge_of_server will be included.
required: false
schema:
type: integer
format: int64
responses:
"200":
description: The list of requested transactions
content:
application/json:
schema:
$ref: "#/components/schemas/HybridTransactionsResponse"
"404":
description: No transactions were found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/payees/{payee_id}/transactions":
get:
tags:
- Transactions
summary: List payee transactions
description: Returns all transactions for a specified payee
operationId: getTransactionsByPayee
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: payee_id
in: path
description: The id of the payee
required: true
schema:
type: string
- name: since_date
in: query
description: If specified, only transactions on or after this date will be
included. The date should be ISO formatted (e.g. 2016-12-30).
required: false
schema:
type: string
format: date
- name: type
in: query
description: If specified, only transactions of the specified type will be
included. 'uncategorized' and 'unapproved' are currently supported.
required: false
schema:
type: string
enum:
- uncategorized
- unapproved
- name: last_knowledge_of_server
in: query
description: The starting server knowledge. If provided, only entities that have
changed since last_knowledge_of_server will be included.
required: false
schema:
type: integer
format: int64
responses:
"200":
description: The list of requested transactions
content:
application/json:
schema:
$ref: "#/components/schemas/HybridTransactionsResponse"
"404":
description: No transactions were found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/scheduled_transactions":
get:
tags:
- Scheduled Transactions
summary: List scheduled transactions
description: Returns all scheduled transactions
operationId: getScheduledTransactions
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
responses:
"200":
description: The list of requested scheduled transactions
content:
application/json:
schema:
$ref: "#/components/schemas/ScheduledTransactionsResponse"
"404":
description: No scheduled transactions were found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/budgets/{budget_id}/scheduled_transactions/{scheduled_transaction_id}":
get:
tags:
- Scheduled Transactions
summary: Single scheduled transaction
description: Returns a single scheduled transaction
operationId: getScheduledTransactionById
parameters:
- name: budget_id
in: path
description: The id of the budget ("last-used" can also be used to specify the
last used budget)
required: true
schema:
type: string
- name: scheduled_transaction_id
in: path
description: The id of the scheduled transaction
required: true
schema:
type: string
responses:
"200":
description: The requested Scheduled Transaction
content:
application/json:
schema:
$ref: "#/components/schemas/ScheduledTransactionResponse"
"404":
description: The scheduled transaction was not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
default:
description: An error occurred
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
servers:
- url: https://api.youneedabudget.com/v1
components:
securitySchemes:
bearer:
type: apiKey
name: Authorization
in: header
schemas:
ErrorResponse:
type: object
required:
- error
properties:
error:
$ref: "#/components/schemas/ErrorDetail"
ErrorDetail:
type: object
required:
- id
- name
- detail
properties:
id:
type: string
name:
type: string
detail:
type: string
UserResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/UserWrapper"
UserWrapper:
type: object
required:
- user
properties:
user:
$ref: "#/components/schemas/User"
User:
type: object
required:
- id
properties:
id:
type: string
format: uuid
DateFormat:
type: object
description: The date format setting for the budget. In some cases the format will
not be available and will be specified as null.
required:
- format
properties:
format:
type: string
CurrencyFormat:
type: object
description: The currency format setting for the budget. In some cases the format
will not be available and will be specified as null.
required:
- iso_code
- example_format
- decimal_digits
- decimal_separator
- symbol_first
- group_separator
- currency_symbol
- display_symbol
properties:
iso_code:
type: string
example_format:
type: string
decimal_digits:
type: integer
format: int32
decimal_separator:
type: string
symbol_first:
type: boolean
group_separator:
type: string
currency_symbol:
type: string
display_symbol:
type: boolean
BudgetSummaryResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/BudgetSummaryWrapper"
BudgetSummaryWrapper:
type: object
required:
- budgets
properties:
budgets:
type: array
items:
$ref: "#/components/schemas/BudgetSummary"
BudgetDetailResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/BudgetDetailWrapper"
BudgetDetailWrapper:
type: object
required:
- budget
- server_knowledge
properties:
budget:
$ref: "#/components/schemas/BudgetDetail"
server_knowledge:
type: integer
format: int64
description: The knowledge of the server
BudgetSettingsResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/BudgetSettingsWrapper"
BudgetSettingsWrapper:
type: object
required:
- settings
properties:
settings:
$ref: "#/components/schemas/BudgetSettings"
BudgetSummary:
type: object
required:
- id
- name
properties:
id:
type: string
format: uuid
name:
type: string
last_modified_on:
type: string
format: date-time
description: The last time any changes were made to the budget from either a web
or mobile client.
first_month:
type: string
format: date
description: The earliest budget month.
last_month:
type: string
format: date
description: The latest budget month.
date_format:
$ref: "#/components/schemas/DateFormat"
currency_format:
$ref: "#/components/schemas/CurrencyFormat"
BudgetSettings:
type: object
required:
- date_format
- currency_format
properties:
date_format:
$ref: "#/components/schemas/DateFormat"
currency_format:
$ref: "#/components/schemas/CurrencyFormat"
BudgetDetail:
allOf:
- $ref: "#/components/schemas/BudgetSummary"
- type: object
properties:
accounts:
type: array
items:
$ref: "#/components/schemas/Account"
payees:
type: array
items:
$ref: "#/components/schemas/Payee"
payee_locations:
type: array
items:
$ref: "#/components/schemas/PayeeLocation"
category_groups:
type: array
items:
$ref: "#/components/schemas/CategoryGroup"
categories:
type: array
items:
$ref: "#/components/schemas/Category"
months:
type: array
items:
$ref: "#/components/schemas/MonthDetail"
transactions:
type: array
items:
$ref: "#/components/schemas/TransactionSummary"
subtransactions:
type: array
items:
$ref: "#/components/schemas/SubTransaction"
scheduled_transactions:
type: array
items:
$ref: "#/components/schemas/ScheduledTransactionSummary"
scheduled_subtransactions:
type: array
items:
$ref: "#/components/schemas/ScheduledSubTransaction"
AccountsResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/AccountsWrapper"
AccountsWrapper:
type: object
required:
- accounts
- server_knowledge
properties:
accounts:
type: array
items:
$ref: "#/components/schemas/Account"
server_knowledge:
type: integer
format: int64
description: The knowledge of the server
AccountResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/AccountWrapper"
AccountWrapper:
type: object
required:
- account
properties:
account:
$ref: "#/components/schemas/Account"
Account:
type: object
required:
- id
- name
- type
- on_budget
- closed
- note
- balance
- cleared_balance
- uncleared_balance
- transfer_payee_id
- deleted
properties:
id:
type: string
format: uuid
name:
type: string
type:
type: string
description: "The type of account. Note: payPal, merchantAccount,
investmentAccount, and mortgage types have been deprecated and will
be removed in the future."
enum:
- checking
- savings
- cash
- creditCard
- lineOfCredit
- otherAsset
- otherLiability
- payPal
- merchantAccount
- investmentAccount
- mortgage
on_budget:
type: boolean
description: Whether this account is on budget or not
closed:
type: boolean
description: Whether this account is closed or not
note:
type: string
balance:
type: integer
format: int64
description: The current balance of the account in milliunits format
cleared_balance:
type: integer
format: int64
description: The current cleared balance of the account in milliunits format
uncleared_balance:
type: integer
format: int64
description: The current uncleared balance of the account in milliunits format
transfer_payee_id:
type: string
format: uuid
description: The payee id which should be used when transferring to this account
deleted:
type: boolean
description: Whether or not the account has been deleted. Deleted accounts will
only be included in delta requests.
CategoriesResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/CategoryGroupsWrapper"
CategoryGroupsWrapper:
type: object
required:
- category_groups
- server_knowledge
properties:
category_groups:
type: array
items:
$ref: "#/components/schemas/CategoryGroupWithCategories"
server_knowledge:
type: integer
format: int64
description: The knowledge of the server
CategoryResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/CategoryWrapper"
CategoryWrapper:
type: object
required:
- category
properties:
category:
$ref: "#/components/schemas/Category"
CategoryGroup:
type: object
required:
- id
- name
- hidden
- deleted
properties:
id:
type: string
format: uuid
name:
type: string
hidden:
description: Whether or not the category group is hidden
type: boolean
deleted:
type: boolean
description: Whether or not the category group has been deleted. Deleted
category groups will only be included in delta requests.
CategoryGroupWithCategories:
allOf:
- $ref: "#/components/schemas/CategoryGroup"
- type: object
required:
- categories
properties:
categories:
type: array
description: Category group categories. Amounts (budgeted, activity,
balance, etc.) are specific to the current budget month (UTC).
items:
$ref: "#/components/schemas/Category"
Category:
type: object
required:
- id
- category_group_id
- name
- hidden
- note
- budgeted
- activity
- balance
- goal_type
- goal_creation_month
- goal_target
- goal_target_month
- goal_percentage_complete
- deleted
properties:
id:
type: string
format: uuid
category_group_id:
type: string
format: uuid
name:
type: string
hidden:
description: Whether or not the category is hidden
type: boolean
original_category_group_id:
description: If category is hidden this is the id of the category group it
originally belonged to before it was hidden.
type: string
format: uuid
note:
type: string
budgeted:
type: integer
format: int64
description: Budgeted amount in milliunits format
activity:
type: integer
format: int64
description: Activity amount in milliunits format
balance:
type: integer
format: int64
description: Balance in milliunits format
goal_type:
type: string
enum:
- TB
- TBD
- MF
- null
description: The type of goal, if the cagegory has a goal (TB=Target Category
Balance, TBD=Target Category Balance by Date, MF=Monthly Funding)
goal_creation_month:
type: string
format: date
description: The month a goal was created
goal_target:
type: integer
format: int64
description: The goal target amount in milliunits
goal_target_month:
type: string
format: date
description: If the goal type is 'TBD' (Target Category Balance by Date), this is
the target month for the goal to be completed
goal_percentage_complete:
type: integer
format: int32
description: The percentage completion of the goal
deleted:
type: boolean
description: Whether or not the category has been deleted. Deleted categories
will only be included in delta requests.
PayeesResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/PayeesWrapper"
PayeesWrapper:
type: object
required:
- payees
- server_knowledge
properties:
payees:
type: array
items:
$ref: "#/components/schemas/Payee"
server_knowledge:
type: integer
format: int64
description: The knowledge of the server
PayeeResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/PayeeWrapper"
PayeeWrapper:
type: object
required:
- payee
properties:
payee:
$ref: "#/components/schemas/Payee"
Payee:
type: object
required:
- id
- name
- transfer_account_id
- deleted
properties:
id:
type: string
format: uuid
name:
type: string
transfer_account_id:
description: If a transfer payee, the account_id to which this payee transfers to
type: string
deleted:
type: boolean
description: Whether or not the payee has been deleted. Deleted payees will only
be included in delta requests.
PayeeLocationsResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/PayeeLocationsWrapper"
PayeeLocationsWrapper:
type: object
required:
- payee_locations
properties:
payee_locations:
type: array
items:
$ref: "#/components/schemas/PayeeLocation"
PayeeLocationResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/PayeeLocationWrapper"
PayeeLocationWrapper:
type: object
required:
- payee_location
properties:
payee_location:
$ref: "#/components/schemas/PayeeLocation"
PayeeLocation:
type: object
required:
- id
- payee_id
- latitude
- longitude
- deleted
properties:
id:
type: string
format: uuid
payee_id:
type: string
format: uuid
latitude:
type: string
longitude:
type: string
deleted:
type: boolean
description: Whether or not the payee location has been deleted. Deleted payee
locations will only be included in delta requests.
TransactionsResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/TransactionsWrapper"
TransactionsWrapper:
type: object
required:
- transactions
- server_knowledge
properties:
transactions:
type: array
items:
$ref: "#/components/schemas/TransactionDetail"
server_knowledge:
type: integer
format: int64
description: The knowledge of the server
HybridTransactionsResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/HybridTransactionsWrapper"
HybridTransactionsWrapper:
type: object
required:
- transactions
properties:
transactions:
type: array
items:
$ref: "#/components/schemas/HybridTransaction"
SaveTransactionWrapper:
type: object
required:
- transaction
properties:
transaction:
$ref: "#/components/schemas/SaveTransaction"
SaveTransactionsWrapper:
type: object
properties:
transaction:
$ref: "#/components/schemas/SaveTransaction"
transactions:
type: array
items:
$ref: "#/components/schemas/SaveTransaction"
SaveTransaction:
type: object
required:
- account_id
- date
- amount
properties:
account_id:
type: string
format: uuid
date:
type: string
format: date
amount:
type: integer
format: int64
description: The transaction amount in milliunits format
payee_id:
type: string
format: uuid
description: The payee for the transaction
payee_name:
type: string
maxLength: 50
description: The payee name. If a payee_name value is provided and payee_id has
a null value, the payee_name value will be used to resolve the payee
by either (1) a matching payee rename rule (only if import_id is
also specified) or (2) a payee with the same name or (3) creation of
a new payee.
category_id:
type: string
format: uuid
description: The category for the transaction. Split and Credit Card Payment
categories are not permitted and will be ignored if supplied. If an
existing transaction has a Split category it cannot be changed.
memo:
type: string
maxLength: 100
cleared:
type: string
enum:
- cleared
- uncleared
- reconciled
description: The cleared status of the transaction
approved:
type: boolean
description: Whether or not the transaction is approved. If not supplied,
transaction will be unapproved by default.
flag_color:
type: string
enum:
- red
- orange
- yellow
- green
- blue
- purple
- null
description: The transaction flag
import_id:
type: string
maxLength: 36
description: "If specified, the new transaction will be assigned this import_id
and considered \"imported\". *At the time of import* we will attempt
to match \"imported\" transactions with non-imported (i.e.
\"user-entered\") transactions.
Transactions imported through
File Based Import or Direct Import (not through the API) are
assigned an import_id in the format:
'YNAB:[milliunit_amount]:[iso_date]:[occurrence]'. For example, a
transaction dated 2015-12-30 in the amount of -$294.23 USD would
have an import_id of 'YNAB:-294230:2015-12-30:1'. If a second
transaction on the same account was imported and had the same date
and same amount, its import_id would be
'YNAB:-294230:2015-12-30:2'. Using a consistent format will prevent
duplicates through Direct Import and File Based Import.
If
import_id is omitted or specified as null, the transaction will be
treated as a \"user-entered\" transaction. As such, it will be
eligible to be matched against transactions later being imported
(via DI, FBI, or API)."
SaveTransactionsResponse:
type: object
required:
- data
properties:
data:
type: object
required:
- transaction_ids
properties:
transaction_ids:
type: array
description: The transaction ids that were saved
items:
type: string
transaction:
$ref: "#/components/schemas/TransactionDetail"
transactions:
type: array
description: If multiple transactions were specified, the transactions that
were saved
items:
$ref: "#/components/schemas/TransactionDetail"
duplicate_import_ids:
type: array
description: If multiple transactions were specified, a list of import_ids
that were not were created because of an existing import_id
found on the same account
items:
type: string
TransactionResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/TransactionWrapper"
TransactionWrapper:
type: object
required:
- transaction
properties:
transaction:
$ref: "#/components/schemas/TransactionDetail"
TransactionSummary:
type: object
required:
- id
- date
- amount
- memo
- cleared
- approved
- flag_color
- account_id
- payee_id
- category_id
- transfer_account_id
- transfer_transaction_id
- matched_transaction_id
- import_id
- deleted
properties:
id:
type: string
date:
type: string
format: date
amount:
type: integer
format: int64
description: The transaction amount in milliunits format
memo:
type: string
cleared:
type: string
enum:
- cleared
- uncleared
- reconciled
description: The cleared status of the transaction
approved:
type: boolean
description: Whether or not the transaction is approved
flag_color:
type: string
enum:
- red
- orange
- yellow
- green
- blue
- purple
- null
description: The transaction flag
account_id:
type: string
format: uuid
payee_id:
type: string
format: uuid
category_id:
type: string
format: uuid
transfer_account_id:
type: string
format: uuid
description: If a transfer transaction, the account to which it transfers
transfer_transaction_id:
type: string
format: uuid
description: If a transfer transaction, the id of transaction on the other side
of the transfer
matched_transaction_id:
type: string
format: uuid
description: If transaction is matched, the id of the matched transaction
import_id:
type: string
description: "If the Transaction was imported, this field is a unique (by
account) import identifier. If this transaction was imported
through File Based Import or Direct Import and not through the API,
the import_id will have the format:
'YNAB:[milliunit_amount]:[iso_date]:[occurrence]'. For example, a
transaction dated 2015-12-30 in the amount of -$294.23 USD would
have an import_id of 'YNAB:-294230:2015-12-30:1'. If a second
transaction on the same account was imported and had the same date
and same amount, its import_id would be
'YNAB:-294230:2015-12-30:2'."
deleted:
type: boolean
description: Whether or not the transaction has been deleted. Deleted
transactions will only be included in delta requests.
TransactionDetail:
allOf:
- $ref: "#/components/schemas/TransactionSummary"
- type: object
required:
- account_name
- payee_name
- category_name
- subtransactions
properties:
account_name:
type: string
payee_name:
type: string
category_name:
type: string
subtransactions:
type: array
description: If a split transaction, the subtransactions.
items:
$ref: "#/components/schemas/SubTransaction"
HybridTransaction:
allOf:
- $ref: "#/components/schemas/TransactionSummary"
- type: object
required:
- type
- parent_transaction_id
- account_name
- payee_name
- category_name
properties:
type:
type: string
enum:
- transaction
- subtransaction
description: Whether the hybrid transaction represents a regular transaction
or a subtransaction
parent_transaction_id:
type: string
description: For subtransaction types, this is the id of the pararent
transaction. For transaction types, this id will be always be
null.
account_name:
type: string
payee_name:
type: string
category_name:
type: string
SaveMonthCategoryWrapper:
type: object
required:
- category
properties:
category:
$ref: "#/components/schemas/SaveMonthCategory"
SaveMonthCategory:
type: object
required:
- budgeted
properties:
budgeted:
type: integer
format: int64
description: Budgeted amount in milliunits format
BulkIdWrapper:
type: object
required:
- bulk
properties:
bulk:
$ref: "#/components/schemas/BulkIds"
BulkIds:
type: object
required:
- transaction_ids
- duplicate_import_ids
properties:
transaction_ids:
type: array
description: The list of Transaction ids that were created.
items:
type: string
duplicate_import_ids:
type: array
description: If any Transactions were not created because they had an import_id
matching a transaction already on the same account, the specified
import_id(s) will be included in this list.
items:
type: string
BulkResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/BulkIdWrapper"
BulkTransactions:
type: object
required:
- transactions
properties:
transactions:
type: array
items:
$ref: "#/components/schemas/SaveTransaction"
SubTransaction:
type: object
required:
- id
- transaction_id
- amount
- memo
- payee_id
- category_id
- transfer_account_id
- deleted
properties:
id:
type: string
transaction_id:
type: string
amount:
type: integer
format: int64
description: The subtransaction amount in milliunits format
memo:
type: string
payee_id:
type: string
format: uuid
category_id:
type: string
format: uuid
transfer_account_id:
type: string
format: uuid
description: If a transfer, the account_id which the subtransaction transfers to
deleted:
type: boolean
description: Whether or not the subtransaction has been deleted. Deleted
subtransactions will only be included in delta requests.
ScheduledTransactionsResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/ScheduledTransactionsWrapper"
ScheduledTransactionsWrapper:
type: object
required:
- scheduled_transactions
properties:
scheduled_transactions:
type: array
items:
$ref: "#/components/schemas/ScheduledTransactionDetail"
ScheduledTransactionResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/ScheduledTransactionWrapper"
ScheduledTransactionWrapper:
type: object
required:
- scheduled_transaction
properties:
scheduled_transaction:
$ref: "#/components/schemas/ScheduledTransactionDetail"
ScheduledTransactionSummary:
type: object
required:
- id
- date_first
- date_next
- frequency
- amount
- memo
- flag_color
- account_id
- payee_id
- category_id
- transfer_account_id
- deleted
properties:
id:
type: string
format: uuid
date_first:
type: string
format: date
description: The first date for which the Scheduled Transaction was scheduled.
date_next:
type: string
format: date
description: The next date for which the Scheduled Transaction is scheduled.
frequency:
type: string
enum:
- never
- daily
- weekly
- everyOtherWeek
- twiceAMonth
- every4Weeks
- monthly
- everyOtherMonth
- every3Months
- every4Months
- twiceAYear
- yearly
- everyOtherYear
amount:
type: integer
format: int64
description: The scheduled transaction amount in milliunits format
memo:
type: string
flag_color:
type: string
enum:
- red
- orange
- yellow
- green
- blue
- purple
- null
description: The scheduled transaction flag
account_id:
type: string
format: uuid
payee_id:
type: string
format: uuid
category_id:
type: string
format: uuid
transfer_account_id:
type: string
format: uuid
description: If a transfer, the account_id which the scheduled transaction
transfers to
deleted:
type: boolean
description: Whether or not the scheduled transaction has been deleted. Deleted
scheduled transactions will only be included in delta requests.
ScheduledTransactionDetail:
allOf:
- $ref: "#/components/schemas/ScheduledTransactionSummary"
- type: object
required:
- account_name
- payee_name
- category_name
- subtransactions
properties:
account_name:
type: string
payee_name:
type: string
category_name:
type: string
subtransactions:
type: array
description: If a split scheduled transaction, the subtransactions.
items:
$ref: "#/components/schemas/ScheduledSubTransaction"
ScheduledSubTransaction:
type: object
required:
- id
- scheduled_transaction_id
- amount
- memo
- payee_id
- category_id
- transfer_account_id
- deleted
properties:
id:
type: string
format: uuid
scheduled_transaction_id:
type: string
format: uuid
amount:
type: integer
format: int64
description: The scheduled subtransaction amount in milliunits format
memo:
type: string
payee_id:
type: string
format: uuid
category_id:
type: string
format: uuid
transfer_account_id:
type: string
format: uuid
description: If a transfer, the account_id which the scheduled subtransaction
transfers to
deleted:
type: boolean
description: Whether or not the scheduled subtransaction has been
deleted. Deleted scheduled subtransactions will only be included in
delta requests.
MonthSummariesResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/MonthSummariesWrapper"
MonthSummariesWrapper:
type: object
required:
- months
- server_knowledge
properties:
months:
type: array
items:
$ref: "#/components/schemas/MonthSummary"
server_knowledge:
type: integer
format: int64
description: The knowledge of the server
MonthDetailResponse:
type: object
required:
- data
properties:
data:
$ref: "#/components/schemas/MonthDetailWrapper"
MonthDetailWrapper:
type: object
required:
- month
properties:
month:
$ref: "#/components/schemas/MonthDetail"
MonthSummary:
type: object
required:
- month
- note
- income
- budgeted
- activity
- to_be_budgeted
- age_of_money
- deleted
properties:
month:
type: string
format: date
note:
type: string
income:
type: integer
format: int64
description: "The total amount in transactions categorized to 'Inflow: To be
Budgeted' in the month"
budgeted:
type: integer
format: int64
description: The total amount budgeted in the month
activity:
type: integer
format: int64
description: "The total amount in transactions in the month, excluding those
categorized to 'Inflow: To be Budgeted'"
to_be_budgeted:
type: integer
format: int64
description: The available amount for 'To be Budgeted'
age_of_money:
type: integer
format: int32
description: The Age of Money as of the month
deleted:
type: boolean
description: Whether or not the month has been deleted. Deleted months will only
be included in delta requests.
MonthDetail:
allOf:
- $ref: "#/components/schemas/MonthSummary"
- type: object
required:
- categories
properties:
categories:
type: array
description: The budget month categories. Amounts (budgeted, activity,
balance, etc.) are specific to the {month} parameter specified.
items:
$ref: "#/components/schemas/Category"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment