> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Auto-generate budgets
> This endpoint will automatically create budgets for several categories based on existing transactions; these budgets are returned as an array. Specifically, budgets will only be generated if the `user` has at least one `transaction` in a given category during each of the two previous calendar months. For example, if the request is made on March 6, and there is at least one "Bills & Utilities" `transaction` in both January and February, a budget will be generated for "Bills & Utilities."
If there are two "Bills & Utilities" transactions in February but none in January, no budget will be generated for that category. If budgets already exist for particular categories, new budgets will be generated and returned based on the available transactions. If one or more budgets remain unchanged, they will nevertheless be returned in the response. If no transaction data for the `user` meet the above criteria, a `422 Unprocessable Entity` error will be returned with status code 4221 along with the message, `There aren't enough transactions to automatically create any budgets`. Autogenerated categories include: `Auto & Transport`, `Bills & Utilities`, `Business Services`, `Education`, `Entertainment`, `Fees & Charges`, `Financial`, `Food & Dining`, `Health & Fitness`, `Home`, `Kids`, `Personal Care`, `Shopping`, `Taxes`, `Travel`, `Uncategorized`, and `Income`.
## OpenAPI
````yaml openapi/nexus/v1.yaml POST /budgets/generate
openapi: 3.0.0
info:
contact:
name: Nexus API
url: https://www.mx.com
version: 1.0.0
title: Nexus API
description: >-
Legacy clients can use Nexus API for all their connectivity needs. If you
are a new client refer to our Platform API. Review our [Nexus API
Guides](/nexus) for more information.
servers:
- url: https://int-data.moneydesktop.com/
- url: https://data.moneydesktop.com/
security:
- sessionToken: []
tags:
- name: accounts
- name: beats
- name: budgets
- name: categories
- name: extended transaction history
- name: goals
- name: holdings
- name: identity
- name: insights
- name: institutions
- name: jobs
- name: member credentials
- name: members
- name: merchants
- name: microdeposits
- name: monthly cash flow profile
- name: notifications
- name: scheduled payments
- name: sessions
- name: spending plan
- name: taggings
- name: tags
- name: transaction rules
- name: transactions
- name: user
- name: verification
paths:
/budgets/generate:
post:
tags:
- budgets
summary: Auto-generate budgets
description: >
This endpoint will automatically create budgets for several categories
based on existing transactions; these budgets are returned as an array.
Specifically, budgets will only be generated if the `user` has at least
one `transaction` in a given category during each of the two previous
calendar months. For example, if the request is made on March 6, and
there is at least one "Bills & Utilities" `transaction` in both January
and February, a budget will be generated for "Bills & Utilities."
If there are two "Bills & Utilities" transactions in February
but none in January, no budget will be generated for that category. If
budgets already exist for particular categories, new budgets will be
generated and returned based on the available transactions. If one or
more budgets remain unchanged, they will nevertheless be returned in the
response. If no transaction data for the `user` meet the above criteria,
a `422 Unprocessable Entity` error will be returned with status code
4221 along with the message, `There aren't enough transactions to
automatically create any budgets`. Autogenerated categories include:
`Auto & Transport`, `Bills & Utilities`, `Business Services`,
`Education`, `Entertainment`, `Fees & Charges`, `Financial`, `Food &
Dining`, `Health & Fitness`, `Home`, `Kids`, `Personal Care`,
`Shopping`, `Taxes`, `Travel`, `Uncategorized`, and `Income`.
operationId: generateBudgets
responses:
'200':
description: OK
content:
application/vnd.mx.nexus.v1+json:
schema:
$ref: '#/components/schemas/BudgetResponseBody'
components:
schemas:
BudgetResponseBody:
properties:
budget:
$ref: '#/components/schemas/BudgetResponse'
type: object
BudgetResponse:
properties:
amount:
description: >-
A goal amount set by the user for a category's transaction total
during a month.
example: 153
type: number
category_guid:
description: Unique identifier for the budget category. Defined by MX.
example: CAT-bd56d35a-a9a7-6e10-66c1-5b9cc1b6c81a
type: string
nullable: false
created_at:
description: >-
Date and time the budget was created, represented in ISO 8601 format
with timestamp.
example: '2018-10-18T19:51:26.000Z'
type: string
guid:
description: Unique identifier for the budget. Defined by MX.
example: BGT-6ca0e3ef-c65e-4655-8b5a-275a3c19c21d
type: string
is_exceeded:
description: >-
If the budget has been exceeded, this field will be true. Otherwise,
this field will be false.
example: true
type: boolean
is_off_track:
description: >-
If the budget is off track, this field will be true. Otherwise, this
field will be false.
example: true
type: boolean
metadata:
description: Additional information a partner can store on the budget.
example: some metadata
nullable: true
type: string
name:
description: >-
The name of the budget that is visible to the user (ie "Food",
"Bills", "Entertainment", etc).
example: Food & Dining
type: string
nullable: true
off_track_percentage:
description: The percentage amount of off track spending. (Deprecated).
nullable: true
type: number
parent_guid:
description: Unique identifier for the parent budget. Defined by MX.
nullable: true
type: string
percent_spent:
description: >-
The percentage of a budget that has been spent during the current
calendar month Calculated as the transaction total divided by the
amount and then multiplied by 100.A value of zero will be returned
when `amount` is zero.
example: 1276.34
nullable: true
type: number
projected_spending:
description: The projected amount of spending for the budget.
example: 3562.4
type: number
revision:
description: The revision number of this budget record.
example: 561
type: integer
transaction_total:
description: The cumulative amount of all transactions under the budget.
example: 1952.8
updated_at:
description: >-
Date and time the budget was updated, represented in ISO 8601 format
with timestamp.
example: 2022-06-14T21:17:11+00:00"
user_guid:
description: Unique identifier for the user. Defined by MX.
example: USR-11141024-90b3-1bce-cac9-c06ced52ab4c
securitySchemes:
sessionToken:
description: >
### MX Session Token
- Request an API token using the read API token endpoint in the MX SSO
API.
- Exchange an API token for a session token.
- A session token is obtained by sending a POST request to /sessions
- The session token will be used in each request made for the user. It should be passed in an `MD-SESSION-TOKEN` HTTP header as shown below.
- This session token is valid for 30 minutes from the time it was created. The 30 minute expiration counter is refreshed with each call.
- If you send a request with an expired session token you'll receive an error code of `4011`.
```
curl -i https://int-data.moneydesktop.com/accounts \
-H 'MD-SESSION-TOKEN:
CWforZl1Vn2vC_v6H4rnQRT1DoWpDouJAV-_5TBmiQRAtA8rsOG_BoajTiOSsL0A3bd-bmHXlA-eQzc9ywItKg'
\
-H 'Content-Type: application/vnd.mx.nexus.v1+json' \
-H 'Accept: application/vnd.mx.nexus.v1+json'
```
In documentation code examples, replace `` with the
session token.
type: apiKey
name: MD-SESSION-TOKEN
in: header
````