Skip to content

Instantly share code, notes, and snippets.

@phrohdoh
Last active Apr 30, 2019
Embed
What would you like to do?
YNAB API v1 OpenAPIv2 YAML
swagger: '2.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
schemes:
- https
host: api.youneedabudget.com
basePath: /v1
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
produces:
- application/json
responses:
'200':
description: The user info
schema:
$ref: '#/definitions/UserResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/ErrorResponse'
/budgets:
get:
tags:
- Budgets
summary: List budgets
description: Returns budgets list with summary information
operationId: getBudgets
produces:
- application/json
parameters: []
responses:
'200':
description: The list of budgets
schema:
$ref: '#/definitions/BudgetSummaryResponse'
'404':
description: No budgets were found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/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
produces:
- application/json
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
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
type: integer
format: int64
responses:
'200':
description: The requested budget
schema:
$ref: '#/definitions/BudgetDetailResponse'
'404':
description: The specified budget was not found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/ErrorResponse'
'/budgets/{budget_id}/settings':
get:
tags:
- Budgets
summary: Budget Settings
description: Returns settings for a budget
operationId: getBudgetSettingsById
produces:
- application/json
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
type: string
responses:
'200':
description: The requested budget settings
schema:
$ref: '#/definitions/BudgetSettingsResponse'
'404':
description: The specified Budget was not found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/ErrorResponse'
'/budgets/{budget_id}/accounts':
get:
tags:
- Accounts
summary: Account list
description: Returns all accounts
operationId: getAccounts
produces:
- application/json
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
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
type: integer
format: int64
responses:
'200':
description: The list of requested accounts
schema:
$ref: '#/definitions/AccountsResponse'
'404':
description: No nccounts were found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/ErrorResponse'
'/budgets/{budget_id}/accounts/{account_id}':
get:
tags:
- Accounts
summary: Single account
description: Returns a single account
operationId: getAccountById
produces:
- application/json
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
type: string
- name: account_id
in: path
description: The id of the account
required: true
type: string
format: uuid
responses:
'200':
description: The requested account
schema:
$ref: '#/definitions/AccountResponse'
'404':
description: The requested account was not found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/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
produces:
- application/json
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
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
type: integer
format: int64
responses:
'200':
description: The categories grouped by category group
schema:
$ref: '#/definitions/CategoriesResponse'
'404':
description: No categories were found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/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
produces:
- application/json
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
type: string
- name: category_id
in: path
description: The id of the category
required: true
type: string
responses:
'200':
description: The requested category
schema:
$ref: '#/definitions/CategoryResponse'
'404':
description: The category not was found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/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
produces:
- application/json
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
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
type: string
format: date
- name: category_id
in: path
description: The id of the category
required: true
type: string
responses:
'200':
description: The requested month category
schema:
$ref: '#/definitions/CategoryResponse'
'404':
description: The month category was not was found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/ErrorResponse'
patch:
tags:
- Categories
summary: Update a category for a specific month
description: Update a category for a specific month
operationId: updateMonthCategory
produces:
- application/json
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
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
type: string
format: date
- name: category_id
in: path
description: The id of the category
required: true
type: string
- name: data
in: body
description: The category to update
required: true
schema:
$ref: '#/definitions/SaveMonthCategoryWrapper'
responses:
'200':
description: The month category was successfully updated
schema:
$ref: '#/definitions/CategoryResponse'
'400':
description: The request could not be understood due to malformed syntax or validation error(s)
schema:
$ref: '#/definitions/ErrorResponse'
'/budgets/{budget_id}/payees':
get:
tags:
- Payees
summary: List payees
description: Returns all payees
operationId: getPayees
produces:
- application/json
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
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
type: integer
format: int64
responses:
'200':
description: The requested list of payees
schema:
$ref: '#/definitions/PayeesResponse'
'404':
description: No payees were found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/ErrorResponse'
'/budgets/{budget_id}/payees/{payee_id}':
get:
tags:
- Payees
summary: Single payee
description: Returns single payee
operationId: getPayeeById
produces:
- application/json
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
type: string
- name: payee_id
in: path
description: The id of the payee
required: true
type: string
responses:
'200':
description: The requested payee
schema:
$ref: '#/definitions/PayeeResponse'
'404':
description: The payee was not found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/ErrorResponse'
'/budgets/{budget_id}/payee_locations':
get:
tags:
- Payee Locations
summary: List payee locations
description: Returns all payee locations
operationId: getPayeeLocations
produces:
- application/json
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
type: string
responses:
'200':
description: The list of payee locations
schema:
$ref: '#/definitions/PayeeLocationsResponse'
'404':
description: No payees locations were found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/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
produces:
- application/json
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
type: string
- name: payee_location_id
in: path
description: id of payee location
required: true
type: string
responses:
'200':
description: The payee location
schema:
$ref: '#/definitions/PayeeLocationResponse'
'404':
description: The payee location was not found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/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
produces:
- application/json
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
type: string
- name: payee_id
in: path
description: id of payee
required: true
type: string
responses:
'200':
description: The list of requested payee locations
schema:
$ref: '#/definitions/PayeeLocationsResponse'
'404':
description: No payees locations were found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/ErrorResponse'
'/budgets/{budget_id}/months':
get:
tags:
- Months
summary: List budget months
description: Returns all budget months
operationId: getBudgetMonths
produces:
- application/json
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
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
type: integer
format: int64
responses:
'200':
description: The list of budget months
schema:
$ref: '#/definitions/MonthSummariesResponse'
'404':
description: No budget months were found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/ErrorResponse'
'/budgets/{budget_id}/months/{month}':
get:
tags:
- Months
summary: Single budget month
description: Returns a single budget month
operationId: getBudgetMonth
produces:
- application/json
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
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
type: string
format: date
responses:
'200':
description: The budget month detail
schema:
$ref: '#/definitions/MonthDetailResponse'
'404':
description: The budget month was not found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/ErrorResponse'
'/budgets/{budget_id}/transactions':
get:
tags:
- Transactions
summary: List transactions
description: Returns budget transactions
operationId: getTransactions
produces:
- application/json
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
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
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
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
type: integer
format: int64
responses:
'200':
description: The list of requested transactions
schema:
$ref: '#/definitions/TransactionsResponse'
'400':
description: An error occurred
schema:
$ref: '#/definitions/ErrorResponse'
'404':
description: No transactions were found
schema:
$ref: '#/definitions/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
produces:
- application/json
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
type: string
- name: data
in: body
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
schema:
$ref: '#/definitions/SaveTransactionsWrapper'
responses:
'201':
description: The transaction or transactions were successfully created
schema:
$ref: '#/definitions/SaveTransactionsResponse'
'400':
description: The request could not be understood due to malformed syntax or validation error(s).
schema:
$ref: '#/definitions/ErrorResponse'
'409':
description: A transaction on the same account with the same import_id already exists.
schema:
$ref: '#/definitions/ErrorResponse'
patch:
tags:
- Transactions
summary: Update multiple transactions
description: 'Updates multiple transactions, by ''id'' or ''import_id''.'
operationId: updateTransactions
produces:
- application/json
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
type: string
- name: data
in: body
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
schema:
$ref: '#/definitions/SaveTransactionsWrapper'
responses:
'209':
description: The transactions were successfully updated
schema:
$ref: '#/definitions/SaveTransactionsResponse'
'400':
description: The request could not be understood due to malformed syntax or validation error(s).
schema:
$ref: '#/definitions/ErrorResponse'
'/budgets/{budget_id}/transactions/{transaction_id}':
get:
tags:
- Transactions
summary: Single transaction
description: Returns a single transaction
operationId: getTransactionById
produces:
- application/json
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
type: string
- name: transaction_id
in: path
description: The id of the transaction
required: true
type: string
responses:
'200':
description: The requested transaction
schema:
$ref: '#/definitions/TransactionResponse'
'404':
description: The transaction was not found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/ErrorResponse'
put:
tags:
- Transactions
summary: Updates an existing transaction
description: Updates a transaction
operationId: updateTransaction
produces:
- application/json
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
type: string
- name: transaction_id
in: path
description: The id of the transaction
required: true
type: string
- name: data
in: body
description: The transaction to update
required: true
schema:
$ref: '#/definitions/SaveTransactionWrapper'
responses:
'200':
description: The transaction was successfully updated
schema:
$ref: '#/definitions/TransactionResponse'
'400':
description: The request could not be understood due to malformed syntax or validation error(s)
schema:
$ref: '#/definitions/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
produces:
- application/json
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
type: string
- name: transactions
in: body
description: The list of transactions to create
required: true
schema:
$ref: '#/definitions/BulkTransactions'
responses:
'201':
description: The bulk request was processed sucessfully
schema:
$ref: '#/definitions/BulkResponse'
'400':
description: The request could not be understood due to malformed syntax or validation error(s)
schema:
$ref: '#/definitions/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
produces:
- application/json
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
type: string
- name: account_id
in: path
description: The id of the account
required: true
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
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
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
type: integer
format: int64
responses:
'200':
description: The list of requested transactions
schema:
$ref: '#/definitions/TransactionsResponse'
'404':
description: No transactions were found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/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
produces:
- application/json
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
type: string
- name: category_id
in: path
description: The id of the category
required: true
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
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
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
type: integer
format: int64
responses:
'200':
description: The list of requested transactions
schema:
$ref: '#/definitions/HybridTransactionsResponse'
'404':
description: No transactions were found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/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
produces:
- application/json
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
type: string
- name: payee_id
in: path
description: The id of the payee
required: true
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
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
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
type: integer
format: int64
responses:
'200':
description: The list of requested transactions
schema:
$ref: '#/definitions/HybridTransactionsResponse'
'404':
description: No transactions were found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/ErrorResponse'
'/budgets/{budget_id}/scheduled_transactions':
get:
tags:
- Scheduled Transactions
summary: List scheduled transactions
description: Returns all scheduled transactions
operationId: getScheduledTransactions
produces:
- application/json
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
type: string
responses:
'200':
description: The list of requested scheduled transactions
schema:
$ref: '#/definitions/ScheduledTransactionsResponse'
'404':
description: No scheduled transactions were found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/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
produces:
- application/json
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
type: string
- name: scheduled_transaction_id
in: path
description: The id of the scheduled transaction
required: true
type: string
responses:
'200':
description: The requested Scheduled Transaction
schema:
$ref: '#/definitions/ScheduledTransactionResponse'
'404':
description: The scheduled transaction was not found
schema:
$ref: '#/definitions/ErrorResponse'
default:
description: An error occurred
schema:
$ref: '#/definitions/ErrorResponse'
securityDefinitions:
bearer:
type: apiKey
name: Authorization
in: header
definitions:
ErrorResponse:
type: object
required:
- error
properties:
error:
$ref: '#/definitions/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: '#/definitions/UserWrapper'
UserWrapper:
type: object
required:
- user
properties:
user:
$ref: '#/definitions/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: '#/definitions/BudgetSummaryWrapper'
BudgetSummaryWrapper:
type: object
required:
- budgets
properties:
budgets:
type: array
items:
$ref: '#/definitions/BudgetSummary'
BudgetDetailResponse:
type: object
required:
- data
properties:
data:
$ref: '#/definitions/BudgetDetailWrapper'
BudgetDetailWrapper:
type: object
required:
- budget
- server_knowledge
properties:
budget:
$ref: '#/definitions/BudgetDetail'
server_knowledge:
type: integer
format: int64
description: The knowledge of the server
BudgetSettingsResponse:
type: object
required:
- data
properties:
data:
$ref: '#/definitions/BudgetSettingsWrapper'
BudgetSettingsWrapper:
type: object
required:
- settings
properties:
settings:
$ref: '#/definitions/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: '#/definitions/DateFormat'
currency_format:
$ref: '#/definitions/CurrencyFormat'
BudgetSettings:
type: object
required:
- date_format
- currency_format
properties:
date_format:
$ref: '#/definitions/DateFormat'
currency_format:
$ref: '#/definitions/CurrencyFormat'
BudgetDetail:
allOf:
- $ref: '#/definitions/BudgetSummary'
- type: object
properties:
accounts:
type: array
items:
$ref: '#/definitions/Account'
payees:
type: array
items:
$ref: '#/definitions/Payee'
payee_locations:
type: array
items:
$ref: '#/definitions/PayeeLocation'
category_groups:
type: array
items:
$ref: '#/definitions/CategoryGroup'
categories:
type: array
items:
$ref: '#/definitions/Category'
months:
type: array
items:
$ref: '#/definitions/MonthDetail'
transactions:
type: array
items:
$ref: '#/definitions/TransactionSummary'
subtransactions:
type: array
items:
$ref: '#/definitions/SubTransaction'
scheduled_transactions:
type: array
items:
$ref: '#/definitions/ScheduledTransactionSummary'
scheduled_subtransactions:
type: array
items:
$ref: '#/definitions/ScheduledSubTransaction'
AccountsResponse:
type: object
required:
- data
properties:
data:
$ref: '#/definitions/AccountsWrapper'
AccountsWrapper:
type: object
required:
- accounts
- server_knowledge
properties:
accounts:
type: array
items:
$ref: '#/definitions/Account'
server_knowledge:
type: integer
format: int64
description: The knowledge of the server
AccountResponse:
type: object
required:
- data
properties:
data:
$ref: '#/definitions/AccountWrapper'
AccountWrapper:
type: object
required:
- account
properties:
account:
$ref: '#/definitions/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: '#/definitions/CategoryGroupsWrapper'
CategoryGroupsWrapper:
type: object
required:
- category_groups
- server_knowledge
properties:
category_groups:
type: array
items:
$ref: '#/definitions/CategoryGroupWithCategories'
server_knowledge:
type: integer
format: int64
description: The knowledge of the server
CategoryResponse:
type: object
required:
- data
properties:
data:
$ref: '#/definitions/CategoryWrapper'
CategoryWrapper:
type: object
required:
- category
properties:
category:
$ref: '#/definitions/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: '#/definitions/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: '#/definitions/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: '#/definitions/PayeesWrapper'
PayeesWrapper:
type: object
required:
- payees
- server_knowledge
properties:
payees:
type: array
items:
$ref: '#/definitions/Payee'
server_knowledge:
type: integer
format: int64
description: The knowledge of the server
PayeeResponse:
type: object
required:
- data
properties:
data:
$ref: '#/definitions/PayeeWrapper'
PayeeWrapper:
type: object
required:
- payee
properties:
payee:
$ref: '#/definitions/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: '#/definitions/PayeeLocationsWrapper'
PayeeLocationsWrapper:
type: object
required:
- payee_locations
properties:
payee_locations:
type: array
items:
$ref: '#/definitions/PayeeLocation'
PayeeLocationResponse:
type: object
required:
- data
properties:
data:
$ref: '#/definitions/PayeeLocationWrapper'
PayeeLocationWrapper:
type: object
required:
- payee_location
properties:
payee_location:
$ref: '#/definitions/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: '#/definitions/TransactionsWrapper'
TransactionsWrapper:
type: object
required:
- transactions
- server_knowledge
properties:
transactions:
type: array
items:
$ref: '#/definitions/TransactionDetail'
server_knowledge:
type: integer
format: int64
description: The knowledge of the server
HybridTransactionsResponse:
type: object
required:
- data
properties:
data:
$ref: '#/definitions/HybridTransactionsWrapper'
HybridTransactionsWrapper:
type: object
required:
- transactions
properties:
transactions:
type: array
items:
$ref: '#/definitions/HybridTransaction'
SaveTransactionWrapper:
type: object
required:
- transaction
properties:
transaction:
$ref: '#/definitions/SaveTransaction'
SaveTransactionsWrapper:
type: object
properties:
transaction:
$ref: '#/definitions/SaveTransaction'
transactions:
type: array
items:
$ref: '#/definitions/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.<br><br>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.<br><br>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:
description: 'If a single transaction was specified, the transaction that was saved'
$ref: '#/definitions/TransactionDetail'
transactions:
type: array
description: 'If multiple transactions were specified, the transactions that were saved'
items:
$ref: '#/definitions/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: '#/definitions/TransactionWrapper'
TransactionWrapper:
type: object
required:
- transaction
properties:
transaction:
$ref: '#/definitions/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: '#/definitions/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: '#/definitions/SubTransaction'
HybridTransaction:
allOf:
- $ref: '#/definitions/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: '#/definitions/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: '#/definitions/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: '#/definitions/BulkIdWrapper'
BulkTransactions:
type: object
required:
- transactions
properties:
transactions:
type: array
items:
$ref: '#/definitions/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: '#/definitions/ScheduledTransactionsWrapper'
ScheduledTransactionsWrapper:
type: object
required:
- scheduled_transactions
properties:
scheduled_transactions:
type: array
items:
$ref: '#/definitions/ScheduledTransactionDetail'
ScheduledTransactionResponse:
type: object
required:
- data
properties:
data:
$ref: '#/definitions/ScheduledTransactionWrapper'
ScheduledTransactionWrapper:
type: object
required:
- scheduled_transaction
properties:
scheduled_transaction:
$ref: '#/definitions/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: '#/definitions/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: '#/definitions/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: '#/definitions/MonthSummariesWrapper'
MonthSummariesWrapper:
type: object
required:
- months
- server_knowledge
properties:
months:
type: array
items:
$ref: '#/definitions/MonthSummary'
server_knowledge:
type: integer
format: int64
description: The knowledge of the server
MonthDetailResponse:
type: object
required:
- data
properties:
data:
$ref: '#/definitions/MonthDetailWrapper'
MonthDetailWrapper:
type: object
required:
- month
properties:
month:
$ref: '#/definitions/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: '#/definitions/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: '#/definitions/Category'
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment