From b00382e191659a660bfb4c2c203b4ac53b727150 Mon Sep 17 00:00:00 2001 From: Justin Flannery Date: Thu, 26 Dec 2024 16:40:42 -0700 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=97=20openapi=20spec?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- openapi.yaml | 5141 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 5141 insertions(+) create mode 100644 openapi.yaml diff --git a/openapi.yaml b/openapi.yaml new file mode 100644 index 0000000..3a46448 --- /dev/null +++ b/openapi.yaml @@ -0,0 +1,5141 @@ +openapi: 3.0.2 +info: + title: Lunch Money API - v2 + description: |- + This is a version of the Lunch Money API described using the the OpenAPI 3.X + specification. + + The goal of this project is to validate an "API Design First" approach + for the Lunch Money API, which should allow us to gather developer feedback + prior to implementation in order to develop API endpoints more quickly. + + This version of the API will differ from the existing v1 beta version. For + more information on the changes please see the + [v2 API Changelog](https://lm-v2-api-mock-data-f24357049a1b.herokuapp.com/v2/changelog) + + Some useful links: + - [Current v1 Lunch Money API Documentation](https://lunchmoney.dev) + - [v2 API Changelog](https://lm-v2-api-mock-data-f24357049a1b.herokuapp.com/v2/changelog) + - [OpenAPI API YAML Specification](https://lm-v2-api-mock-data-f24357049a1b.herokuapp.com/v2/openapi/) + - [Awesome Lunch Money Projects](https://lunchmoney.dev/#awesome-projects) + + termsOfService: https://lunchmoney.dev/#current-status + contact: + email: devsupport@lunchmoney.app + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0.html + version: 2.7.4 + +servers: + - url: https://lm-v2-api-mock-data-f24357049a1b.herokuapp.com/v2 + description: + Static Mock v2 Lunch Money API Server + # This service implements the v2 API using static mock data. Requests to POST/PUT/DELETE endpoints are honored and return + # response that a real implementation of the API would provide, but no data is actually changed.
+ # Using this server is a good way to become familiar with the API
+ # To use this server set your Bearer token to any string with 11 or more characters. + - url: https://lm-v2-api-v1-proxy-08a8f2bf0c0c.herokuapp.com/v2 + description: + v2 via v1 API Lunch Money API Server + # This service implements the v2 API by translating the requests into v1 API calls and therefore uses real data.
+ # To use this server set your Bearer token to a real Lunch Money API key.
+ # Users may wish to create a new Budgeting Account as a "Developer Sandbox" to avoid overwriting any data in their real account + +tags: + - name: me + description: Access details about the current user + - name: categories + description: Access to categories + externalDocs: + description: Learn more about categories + url: https://support.lunchmoney.app/setup/categories + - name: manual_accounts + description: Access to manual accounts (formerly called assets) + externalDocs: + description: Learn more about manual accounts + url: https://support.lunchmoney.app/setup/linked-accounts#how-are-manually-managed-account-balances-updated + - name: plaid_accounts + description: Access to accounts synced via Plaid + externalDocs: + description: Learn more about synced accounts + url: https://support.lunchmoney.app/setup/linked-accounts#how-often-should-i-expect-new-transactions-to-get-imported + - name: recurring + description: Access to recurring items + externalDocs: + url: https://support.lunchmoney.app/finances/recurring-items + - name: tags + description: Access to tags + externalDocs: + description: Learn more about tags + url: https://support.lunchmoney.app/setup/tags + - name: transactions + description: Access to transactions + externalDocs: + description: Learn more about transactions + url: https://support.lunchmoney.app/finances/transactions + - name: transactions (bulk) + description: Bulk Access to transactions + externalDocs: + description: Learn more about transactions + url: https://support.lunchmoney.app/finances/transactions + - name: transactions (group) + description: Group or ungroup transactions + externalDocs: + description: Learn more about transactions + url: https://support.lunchmoney.app/finances/transactions + - name: transactions (split) + description: Split or unsplit transactions + externalDocs: + description: Learn more about transactions + url: https://support.lunchmoney.app/finances/transactions + +components: + schemas: + userObject: + properties: + name: + type: string + description: User's name + email: + type: string + description: User's email + id: + type: integer + format: int64 + description: Unique identifier for user + account_id: + type: integer + format: int64 + description: Unique identifier for the associated budgeting account + budget_name: + type: string + description: Name of the associated budgeting account + primary_currency: + description: Primary currency from user's settings + allOf: + - $ref: "#/components/schemas/currencyEnum" + api_key_label: + type: string + nullable: true + description: User-defined label of the developer API key used. Returns null if nothing has been set. + required: + - name + - email + - id + - account_id + - budget_name + - primary_currency + - api_key_label + type: object + additionalProperties: false + + # The categoryObject is used to represent a category that is not a + # category group. Therefore the is_group attribute is always false + categoryObject: + type: object + additionalProperties: false + properties: + id: + type: integer + format: int64 + nullable: false + description: A system defined unique identifier for the category. + name: + type: string + nullable: false + description: The name of the category. + minLength: 1 + maxLength: 100 + description: + type: string + nullable: true + description: The description of the category or `null` if not set. + maxLength: 200 + is_income: + type: boolean + nullable: false + description: If true, the transactions in this category will be treated as income. + exclude_from_budget: + type: boolean + nullable: false + description: If true, the transactions in this category will be excluded from the budget. + exclude_from_totals: + type: boolean + nullable: false + description: If true, the transactions in this category will be excluded from totals. + updated_at: + type: string + format: date-time + nullable: false + description: The date and time of when the category was last updated (in the ISO 8601 extended format). + created_at: + type: string + format: date-time + nullable: false + description: The date and time of when the category was created (in the ISO 8601 extended format). + group_id: + type: integer + format: int64 + nullable: true + description: The ID of the category group this category belongs to or `null` if the category doesn't belong to a group, or is itself a category group. + is_group: + type: boolean + description: If true, the category is a group that can be a parent to other categories. + children: + type: array + items: + $ref: "#/components/schemas/childCategoryObject" + description: For category groups, this will populate with details about the categories that belong to this group. The objects in this array are similar to Category Objects but do not include the `is_income`, `exclude_from_budget`, and `exclude_from_totals` properties as these are inherited from the Category Group. In addition the `is_group` property will always be `false``, and there will be no `children` attribute. + archived: + type: boolean + description: If true, the category is archived and not displayed in relevant areas of the Lunch Money app. + archived_at: + type: string + format: date-time + nullable: true + description: The date and time of when the category was last archived (in the ISO 8601 extended format). + order: + type: number + nullable: true + description: An index specifying the position in which the category is displayed on the categories page in the Lunch Money GUI. For categories within a category group the order index is relative to the other categories within the group.
This value for this property will be `null` for categories created via the API until they are modified on the Categories page in the Lunch Money GUI. + required: + - id + - name + - description + - is_income + - exclude_from_budget + - exclude_from_totals + - updated_at + - created_at + - group_id + - is_group + - archived + - archived_at + - order + + # The childCategoryObject is basically a categoryObject that has no + # `children` attribute. We create this to ensure that no categories + # are added to a category group if they have children and are a group + # We also remove the `is_income`, `exclude_from_budget` and `exclude_from_totals` + # attributes since these are inherited from the Category Group + childCategoryObject: + type: object + x-internal: true # Don't display in schemas section of docs + additionalProperties: false + properties: + id: + type: integer + format: int64 + nullable: false + description: A system defined unique identifier for the category. + name: + type: string + nullable: false + description: The name of the category. + minLength: 1 + maxLength: 100 + description: + type: string + nullable: true + description: The description of the category or `null` if not set. + maxLength: 200 + updated_at: + type: string + format: date-time + nullable: false + description: The date and time of when the category was last updated (in the ISO 8601 extended format). + created_at: + type: string + format: date-time + nullable: false + description: The date and time of when the category was created (in the ISO 8601 extended format). + group_id: + type: integer + format: int64 + nullable: true + description: The ID of the category group this category belongs to or `null` if the category doesn't belong to a group, or is itself a category group. + is_group: + type: boolean + enum: + - false + description: Will always be false for a category that is part of category group. + archived: + type: boolean + description: If true, the category is archived and not displayed in relevant areas of the Lunch Money app. + archived_at: + type: string + format: date-time + nullable: true + description: The date and time of when the category was last archived (in the ISO 8601 extended format). + order: + type: number + nullable: true + description: An index specifying the position in which the category is displayed on the categories page in the Lunch Money GUI. For categories within a category group the order index is relative to the other categories within the group. + required: + - id + - name + - description + - updated_at + - created_at + - group_id + - is_group + - archived + - archived_at + - order + + # The request object for POST /categories + # Prevent user from submitting any system created fields in a POST request + createCategoryRequestObject: + type: object + additionalProperties: false + x-internal: true # Don't display in schemas section of docs + properties: + name: + type: string + nullable: false + description: "The name of the new category. Must be between 1 and 100 characters.\nMust not match the name of any existing categories or category groups." + minLength: 1 + maxLength: 100 + description: + type: string + nullable: true + default: + description: The description of the category. Must not exceed 200 characters. + maxLength: 200 + is_income: + type: boolean + nullable: false + default: false + description: If true, the transactions in this category will be treated as income. + exclude_from_budget: + type: boolean + nullable: false + default: false + description: If true, the transactions in this category will be excluded from the budget. + exclude_from_totals: + type: boolean + nullable: false + default: false + description: If true, the transactions in this category will be excluded from totals. + is_group: + type: boolean + nullable: false + default: false + description: If true, the category is a group that can be a parent to other categories, but may not be assigned directly to transactions. + group_id: + type: integer + format: int64 + nullable: true + default: + description: If set to the ID of an existing category group, this new category will be assigned to that group. Cannot be set if `is_group` is true. + archived: + type: boolean + default: false + description: If true, the category is archived and not displayed in relevant areas of the Lunch Money app. + order: + type: number + nullable: true + description: An index specifying the position in which the category is displayed on the categories page in the Lunch Money GUI. For categories within a category group the order index is relative to the other categories within the group. + children: + type: array + default: [] + nullable: false + description: The list of category objects, or category IDs to add to the new category group. This attribute should only be set if "group_id" is set to true.
The categories or IDs specified must all be or belong to existing categories that are not already part of a category group or are themselves category groups.
It is permissible to provide both full category objects and IDs. + items: + oneOf: + - type: integer + - $ref: "#/components/schemas/childCategoryObject" + required: + - name + + # Request object for a PUT /categories/:id request + # Tolerate a request object that includes system created fields from a + # previous GET request, but are essentially ignored + updateCategoryRequestObject: + type: object + x-internal: true # Don't display in schemas section of docs + additionalProperties: false + properties: + name: + type: string + nullable: false + description: If set the new name of the category. Must be between 1 and 100 characters. + minLength: 1 + maxLength: 100 + description: + type: string + nullable: true + description: If set the new description of the category. Must not exceed 200 characters. + maxLength: 200 + is_income: + type: boolean + nullable: false + description: If set will indicate if this category will be treated as income. + exclude_from_budget: + type: boolean + nullable: false + description: If set will indicate if this category will be excluded from budgets. + exclude_from_totals: + type: boolean + nullable: false + description: If set will indicate if this category will be excluded from totals. + archived: + type: boolean + description: If set will indicate if this category is archived. + group_id: + type: integer + format: int64 + nullable: true + description: If set to the ID of an existing category group, and this category is not itself a category group, this category will be a child of the specified group. + order: + type: number + nullable: true + description: If set the index of the category's position in the Lunch Money GUI. + is_group: + type: boolean + nullable: true + default: false + description: If set, this attribute may not be set to a value that is different than the current status of the category or category group. In other words, this API may not be used to convert a category to a category group or vice versa. + children: + type: array + nullable: false + description: If set the list of categories or category IDs to set as children of this category group. This attribute should only be set if the category is already a group.
The categories or IDs specified must all be or belong to existing categories that are not already part of a category group or are themselves category groups.
It is permissible to provide both full category objects and IDs. + items: + oneOf: + - type: integer + - $ref: "#/components/schemas/childCategoryObject" + id: + type: integer + format: int64 + description: System defined unique identifier for the category. Ignored if set. + archived_at: + type: string + nullable: true + description: System set date and time of when the category was last archived (in the ISO 8601 extended format). Ignored if set. + updated_at: + type: string + nullable: true + description: System set date and time of when the category was last updated (in the ISO 8601 extended format). Ignored if set. + created_at: + type: string + nullable: true + description: System set date and time of when the category was created (in the ISO 8601 extended format). Ignored if set. + + # The response object for a DELETE /category request with dependencies + deleteCategoryResponseWithDependencies: + type: object + x-internal: true # Don't display in schemas section of docs + additionalProperties: false + properties: + category_name: + type: string + description: The name of the category + dependents: + type: object + properties: + budget: + type: number + description: The number of budgets depending on the category + category_rules: + type: number + description: The number of category rules depending on the category + transactions: + type: number + description: The number of transactions depending on the category + children: + type: number + description: The number of child categories in the category group + recurring: + type: number + description: The number of recurring transactions depending on the category + plaid_cats: + type: number + description: The number of auto created categories based on Plaid categories + required: + - budget + - category_rules + - transactions + - children + - recurring + - plaid_cats + required: + - category_name + - dependents + + # The primary object that represents a transaction + transactionObject: + type: object + additionalProperties: false + properties: + id: + type: integer + format: int64 + description: System created unique identifier for transaction + date: + type: string + format: date + description: Date of transaction in ISO 8601 format + amount: + type: string + description: Amount of the transaction in numeric format to 4 decimal places + currency: + description: Three-letter lowercase currency code of the transaction in ISO 4217 format + allOf: + - $ref: "#/components/schemas/currencyEnum" + to_base: + type: number + format: double + description: The amount converted to the user's primary currency. If the multi-currency feature is not being used, to_base and amount will be the same. + recurring_id: + type: integer + format: int64 + nullable: true + description: The unique identifier of the associated recurring item that this transaction matched. If the recurring item changed properties of this transaction, an `overrides` property with details on what was overridden will be include in the transaction object. If no `overrides` property exists when there is a `recurring_id` it means that the recurring_item is still in the suggested state, or that it does not contain any rules to override transaction properties. + overrides: + $ref: "#/components/schemas/transactionOverridesObject" + payee: + type: string + description: | + Name of payee set by the user, the financial institution, or by + a matched recurring item. This will match the value + displayed in payee field on the transactions page in the GUI. + minLength: 0 + maxLength: 140 + category_id: + type: integer + format: int64 + nullable: true + description: Unique identifier of associated category set by the user or by a matched recurring_item.
Category details can be obtained by passing the value of this property to the [Get A Single Category](../operations/getCategoryById) API + notes: + type: string + nullable: true + description: | + Any transaction notes set by the user or by + a matched recurring item. This will match the value + displayed in notes field on the transactions page in the GUI. + minLength: 0 + maxLength: 350 + status: + type: string + description: | + Status of the transaction: + - `reviewed`: User has reviewed the transaction, or it was automatically marked as reviewed due to reviewed recurring_item logic + - `unreviewed`: User has not reviewed the transaction and it does not match any reviewed recurring_items. + - `delete_pending`: The synced account deleted this transaction after it was updated by the user. Requires manual intervention. + - `pending`: Transaction is still pending with the synced institution (not posted). + enum: + - reviewed + - unreviewed + - delete_pending + - pending + is_pending: + type: boolean + description: Denotes if the transaction is pending (not posted). Applies only to transactions in synced accounts and will always be false for transactions associated with manual accounts. + created_at: + type: string + format: date-time + description: The date and time of when the transaction was created (in the ISO 8601 extended format). + updated_at: + type: string + format: date-time + description: The date and time of when the transaction was last updated (in the ISO 8601 extended format). + is_parent: + type: boolean + description: If true this transaction has been split into two or more other transactions. By default parent transactions are not returned in call to `GET /transactions` but they can be queried directly by their ID. + children: + type: array + description: Exists only for transactions which are the parent of a split transaction, and contains a list of the associated transactions that it was split into. By default parent transactions are not returned in a `GET /transactions` API call, but can be examined via a subsequent call to `GET /transactions{id}`, where the value of `parent_id` field of a split transaction is the requested transaction. + parent_id: + type: integer + format: int64 + nullable: true + description: A transaction ID if this is a split transaction. Denotes the transaction ID of the original, or parent, transaction. Is null if this is not a split transaction + items: + type: number + is_group: + type: boolean + description: True if this transaction represents a group of transactions. If so, amount and currency represent the totalled amount of transactions bearing this transaction’s id as their group_id. Amount is calculated based on the user’s primary currency. + group_id: + type: integer + format: int64 + nullable: true + description: Is set if this transaction is part of a group. Denotes the ID of the grouped transaction this is now included in. By default the transactions that were grouped are not returned in a call to `GET /transactions` but they can be queried directly by calling the `GET /transactions/group/{id}`, where the id passed is associated with a transaction where the `is_group` attribute is true + manual_account_id: + type: integer + format: int64 + nullable: true + description: The unique identifier of the manual account associated with this transaction. This will always be null if this transaction is associated with a synced account or if this transaction has no associated account and appears as a "Cash Transaction" in the Lunch Money GUI. + plaid_account_id: + type: integer + format: int64 + nullable: true + description: The unique identifier of the plaid account associated with this transaction. This will always be null if this transaction is associated with a manual account or if this transaction has no associated account and appears as a "Cash Transaction" in the Lunch Money GUI. + tag_ids: + type: array + description: A list of tag_ids for the tags associated with this transaction. If the transaction has no tags this will be an empty list.
Tag details can be obtained by passing the value of this attribute as the `ids` query parameter to the [List Tags](../operations/getTags) API + items: + type: integer + format: int64 + source: + type: string + nullable: true + description: | + Source of the transaction: + - `api`: Transaction was added by a call to the [POST /transactions](../operations/createTransaction) API + - `csv`: Transaction was added via a CSV Import + - `manual`: Transaction was created via the "Add to Cash" button on the Transactions page + - `merge`: Transactions were originally in an account that was merged into another account + - `plaid`: Transaction came from a Financial Institution synced via Plaid + - `recurring`: Transaction was created from the Recurring page + - `rule`: Transaction was created by a rule to split a transaction + - `split`: This is a transaction created by splitting another transaction + - `user`: This is a legacy value and is replaced by either csv or manual + enum: + - api + - csv + - manual + - merge + - plaid + - recurring + - rule + - split + - user + external_id: + type: string + nullable: true + description: A user-defined external ID for any transaction that was added via csv import, `POST /transactions` API call, or manually added via the Lunch Money GUI. No external ID exists for transactions associated with synced accounts, and they cannot be added. For transactions associated with manual accounts, the external ID must be unique as attempts to add a subsequent transaction with the same external_id and manual_account_id will be flagged as duplicates and fail. + minLength: 0 + maxLength: 75 + plaid_metadata: + type: object + description: If requested, the transaction's plaid_metadata that came when this transaction was obtained. This will be a json object, but the schema is variable. This will only be present for transactions associated with a plaid account. + custom_metadata: + type: object + description: If requested, the transaction's custom_metadata that was included when the transaction was inserted via the API. This will be a json object, but the schema is variable. This will only be present for transactions associated with a manual account. + required: + - id + - date + - amount + - currency + - to_base + - recurring_id + - overrides + - payee + - category_id + - notes + - status + - is_pending + - created_at + - updated_at + - parent_id + - is_group + - group_id + - manual_account_id + - plaid_account_id + - tag_ids + - source + - external_id + + # The object that represents a new transaction to be inserted + insertTransactionObject: + type: object + x-internal: true # Don't display in schemas section of docs + additionalProperties: false + properties: + date: + type: string + format: date + description: Date of transaction in ISO 8601 format + amount: + oneOf: + - type: number + format: double + - type: string + pattern: ^-?\d+(\.\d{1,4})?$ + description: Numeric value of amount. i.e. $4.25 should be denoted as 4.25. Can be a string or a number in double format. + currency: + description: Three-letter lowercase currency code of the transaction in ISO 4217 format. Must match one of the [supported currencies](). If not set defaults to the user account's primary currency. + allOf: + - $ref: "#/components/schemas/currencyEnum" + payee: + type: string + description: Name of payee for the transaction. + minLength: 0 + maxLength: 140 + category_id: + type: integer + format: int64 + nullable: true + description: The ID of the category associated with the transactions. If set, the category ID must exist for the user's account and it cannot be a category group. + notes: + type: string + nullable: true + description: | + Any transaction notes set by the user or by + a matched recurring item. This will match the value + displayed in notes field on the transactions page in the GUI. + minLength: 0 + maxLength: 350 + manual_account_id: + type: integer + format: int64 + nullable: true + description: The Unique identifier for the associated manually managed account. If set, this must match an existing manual account id associated with the user's account. If not set, and `plaid_account_id` is also not set, no account is associated with the transaction and it will appear as a "Cash Transaction" in the Lunch Money GUI. It is an error if this, and `plaid_account_id` is also set on the same transaction. + plaid_account_id: + type: integer + format: int64 + nullable: true + description: The Unique identifier for the associated plaid synced account. If set, this must match an existing plaid account id associated with the user's account. If not set, and `manual_account_id` is also not set, no account is associated with the transaction and it will appear as a "Cash Transaction" in the Lunch Money GUI. It is an error if this, and `manual_account_id` is also set on the same transaction. In addition the specified plaid account must have the "Allow Modifications To Transactions" property set (which is enabled by default), or the insert will fail. + recurring_id: + type: integer + format: int64 + nullable: true + description: Unique identifier for associated recurring expense. Recurring expense must be associated with the same account. + status: + type: string + description: If set must be either `reviewed` or `unreviewed`. If not set, defaults to `unreviewed`. + enum: + - reviewed + - unreviewed + tag_ids: + type: array + description: A list of IDs for the tags associated with this transaction. Each ID must match an existing tag associated with the user's account. If not set, no tags will be associated with the created transaction. + items: + type: integer + format: int64 + external_id: + type: string + nullable: true + description: A user-defined external ID for the transaction. If set, and `manual_account_id` is set, the creation of the new transaction will fail if a transaction with this id already exists for the specified manual account. + minLength: 0 + maxLength: 75 + custom_metadata: + type: object + description: An optional JSON object that includes additional data related to this transaction. This must be a valid JSON object and, when stringified, must not exceed 4096 characters. This data may be available in the future for processing by rules. + additionalProperties: true + required: + - date + - amount + + splitTransactionObject: + type: object + additionalProperties: false + x-internal: true # Don't display in schemas section of docs + description: The object representing a split transaction + properties: + amount: + oneOf: + - type: number + format: double + - type: string + pattern: ^-?\d+(\.\d{1,4})?$ + description: Individual amount of split. Currency will inherit from parent transaction. All amounts must sum up to parent transaction amount. + payee: + type: string + maxLength: 140 + description: The payee for the child transaction. Will inherit the original payee from the parent if not defined. + date: + type: string + format: date + description: Must be in ISO 8601 format (YYYY-MM-DD). Will inherit from the parent if not defined. + category_id: + type: number + format: int64 + description: Unique identifier for associated category_id. Category must already exist for the account. Will inherit category from the parent if not defined. + notes: + type: string + maxLength: 350 + description: Will inherit notes from parent if not defined. + required: + - amount + + # The object returned when a requested external_id already exists + skippedExistingExternalIdObject: + type: object + x-internal: true # Don't display in schemas section of docs + additionalProperties: false + description: The object returned when a new transaction has an external_id that already exists + properties: + request_transaction_index: + type: number + format: int64 + description: The index of the transaction in the request that was skipped. + external_id: + type: string + minLength: 0 + maxLength: 75 + description: The `external_id` specified in the duplicate skipped transaction. + manual_account_id: + type: number + format: int64 + description: The `manual_account_id` in the duplicate skipped transaction. + existing_transaction_id: + type: number + format: int64 + description: The id of the existing transactions with the same `manual_account_id` and `external_id`. + + manualAccountObject: + type: object + additionalProperties: false + description: An object containing information about a manual account + properties: + id: + type: integer + format: int64 + description: The unique identifier of this account + name: + type: string + description: Name of the account + minLength: 1 + maxLength: 45 + type: + description: Primary type of the account + allOf: + - $ref: "#/components/schemas/AccountTypeEnum" + subtype: + type: string + nullable: true + description: Optional account subtype. Examples include
- retirement - checking - savings - prepaid credit card + display_name: + type: string + nullable: true + description: Optional display name for the account set by the user + balance: + type: string + pattern: ^-?\d+(\.\d{0,4})?$ + description: Current balance of the account in numeric format to 4 decimal places. + balance_as_of: + type: string + format: date-time + description: Date balance was last updated in ISO 8601 extended format + closed_on: + type: string + format: date + nullable: true + description: The date this account was closed. Will be null if the account has not been marked as closed + currency: + type: string + minLength: 3 + maxLength: 3 + description: Three-letter lowercase currency code of the account balance + institution_name: + type: string + nullable: true + minLength: 1 + maxLength: 50 + description: Name of institution holding the account + external_id: + type: string + nullable: true + minLength: 0 + maxLength: 75 + description: An optional external_id that may be set or updated via the API + exclude_from_transactions: + type: boolean + description: If true, this account will not show up as an option for assignment when creating transactions manually + created_at: + type: string + format: date-time + description: Date/time the account was created in ISO 8601 extended format + updated_at: + type: string + format: date-time + description: Date/time the account was created in ISO 8601 extended format + required: + - id + - name + - type + - subtype + - display_name + - balance + - balance_as_of + - closed_on + - currency + - institution_name\ + - external_id + - exclude_from_transactions + - created_at + - updated_at + + # The request object for POST /manual_accounts + # Prevent user from submitting any system created fields in a POST request + createManualAccountRequestObject: + type: object + additionalProperties: false + x-internal: true # Don't display in schemas section of docs + properties: + name: + type: string + description: Name of the manual account + minLength: 1 + maxLength: 45 + example: My Savings Account + type: + description: >- + The type of account. + allOf: + - $ref: "#/components/schemas/AccountTypeEnum" + subtype: + type: string + description: Optional account subtype + minLength: 1 + maxLength: 25 + example: prepaid credit card + display_name: + type: string + description: Display name of the account as set by user. + example: Savings + balance: + type: string + example: "195.50" + description: Numeric value of the current balance of the account as a string. Do not include any special characters aside from a decimal point. + balance_as_of: + type: string + format: date + example: "2024-09-15" + description: Date/time the balance was last updated in ISO 8601 extended format. + closed_on: + type: string + format: date + nullable: true + example: "2024-10-01" + description: The date this account was closed in YYYY-MM-DD format. + currency: + description: Three-letter lowercase currency code of the transaction in ISO 4217 format + allOf: + - $ref: "#/components/schemas/currencyEnum" + institution_name: + type: string + example: Bank of the West + description: Name of institution holding the asset + minLength: 1 + maxLength: 50 + external_id: + type: string + nullable: true + minLength: 0 + maxLength: 75 + description: An optional external_id that may be set or updated via the API + exclude_from_transactions: + type: boolean + description: If true, this asset will not show up as an option for assignment when creating transactions manually. + default: false + required: + - name + - type + - balance + + # Request object for a PUT /manual_accounts/:id request + # Tolerate a request object that includes system created fields from a + # previous GET request, but are essentially ignored + # No properties are listed as required, but the implementation must check + # for at least one of the user settable properties + updateManualAccountRequestObject: + type: object + x-internal: true # Don't display in schemas section of docs + additionalProperties: false + properties: + id: + type: integer + format: int64 + description: System defined unique identifier of this account. Ignored if set. + name: + type: string + description: If set the new name of the account. + minLength: 1 + maxLength: 45 + type: + description: If set the new primary type of the account. + allOf: + - $ref: "#/components/schemas/AccountTypeEnum" + subtype: + type: string + description: If set an optional account subtype. Examples include
- retirement - checking - savings - prepaid credit card + display_name: + type: string + nullable: true + description: If set, an optional display name for the account. + balance: + type: string + description: If set, the new balance of the account. This is a string in numeric format to 4 decimal places. + balance_as_of: + type: string + format: date-time + description: If set to a date-time string in ISO 8601 extended format, the new date that balance was last updated at. This property is ignored if `balance` is not also set. If `balance` is set and this property is not set the current time is used. + closed_on: + type: string + format: date + nullable: true + description: If set, the date this account was closed in YYYY-MM-DD format. + currency: + description: If set, the new three-letter lowercase currency code of the account balance. + allOf: + - $ref: "#/components/schemas/currencyEnum" + institution_name: + type: string + nullable: true + description: If set, the name of institution holding the account. + minLength: 1 + maxLength: 50 + external_id: + type: string + nullable: true + minLength: 0 + maxLength: 75 + description: An optional external_id that may be set or updated via the API + exclude_from_transactions: + type: boolean + description: If set, this will indicate if this account will not show up as an option for assignment when creating transactions manually. + created_at: + type: string + format: date-time + description: System defined date/time the account was created in ISO 8601 extended format. Ignored if set. + updated_at: + type: string + format: date-time + description: System defined date/time the account was created in ISO 8601 extended format. Ignored if set. + + plaidAccountObject: + type: object + additionalProperties: false + description: An object containing information about an account synced via Plaid + properties: + id: + type: integer + format: int64 + description: The unique identifier of this account + date_linked: + type: string + format: date + description: Date account was first linked in ISO 8601 format + name: + type: string + description: Name of the account. This field is set by Plaid and cannot be altered. + display_name: + type: string + nullable: true + description: Optional display name for the account set by the user. If not set it will return a concatenated string of institution and account name. + type: + type: string + description: Primary type of the account, for example credit, depository, etc. This field is set by Plaid and cannot be altered. + subtype: + type: string + description: Optional account subtype. This field is set by Plaid and cannot be altered. + mask: + type: string + description: Mask (last 3 to 4 digits of account) of account. This field is set by Plaid and cannot be altered. + institution_name: + type: string + description: Name of institution holding the account. This field is set by Plaid and cannot be altered. + status: + type: string + description: >- + Denotes the current status of the account within Lunch Money. Must be one of
+ - `active`: Account is active and in good state
+ - `inactive`: Account marked inactive from user. No transactions fetched or balance update for this account.
+ - `relink`: Account needs to be relinked with Plaid.
+ - `syncing`: Account is awaiting first import of transactions.
+ - `not found`: Account cannot be found with Plaid
+ - `not supported`: Account is not supported with Plaid
+ - `error`: Account is in error with Plaid.
+ enum: + - active + - inactive + - relink + - syncing + - not found + - not supported + - error + allow_transaction_modifications: + type: boolean + description: Is false if the "Allow Modification To Transactions" property for this account has been toggled off. Otherwise it is set to true. + limit: + type: number + nullable: true + description: Optional credit limit of the account. This field is set by Plaid and cannot be altered + balance: + type: string + description: Current balance of the account in numeric format to 4 decimal places. This field is set by Plaid and cannot be altered. + currency: + type: string + minLength: 3 + maxLength: 3 + description: Three-letter lowercase currency code of the account balance + balance_last_update: + type: string + format: date-time + description: Date balance was last updated in ISO 8601 extended format. This field is set by Plaid and cannot be altered. + import_start_date: + type: string + format: date + nullable: true + description: Date of earliest date allowed for importing transactions. Transactions earlier than this date are not imported. + last_import: + type: string + format: date-time + nullable: true + description: Timestamp in ISO 8601 extended format of the last time Lunch Money imported new data from Plaid for this account. + last_fetch: + type: string + format: date-time + nullable: true + description: Timestamp in ISO 8601 extended format of the last successful request from Lunch Money for updated data or timestamps from Plaid in ISO 8601 extended format (not necessarily date of last successful import) + plaid_last_successful_update: + type: string + format: date-time + description: Timestamp in ISO 8601 extended format of the last time Plaid successfully connected with institution for new transaction updates, regardless of whether any new data was available in the update. + required: + - id + - date_linked + - name + - display_name + - type + - subtype + - mask + - institution_name + - status + - allow_transaction_modifications + - limit + - balance + - currency + - balance_last_update + - import_start_date + - last_import + - last_fetch + - plaid_last_successful_update + + tagObject: + type: object + additionalProperties: false + properties: + id: + type: integer + format: int64 + description: Unique identifier for the tag. + name: + type: string + description: Name of the tag. + description: + type: string + nullable: true + description: Description of the tag. + updated_at: + type: string + format: date-time + nullable: false + description: The date and time of when the tag was last updated (in the ISO 8601 extended format). + created_at: + type: string + format: date-time + nullable: false + description: The date and time of when the tag was created (in the ISO 8601 extended format). + archived: + type: boolean + description: If true, the tag will not show up when creating or updating transactions in the Lunch Money app. **Can it be assigned via the API** + archived_at: + type: string + format: date-time + nullable: true + description: The date and time of when the tag was last archived or null if not archived + required: + - id + - name + - description + - created_at + - updated_at + - archived + - archived_at + + # The request object for POST /tags + # Prevent user from submitting any system created fields in a POST request + createTagRequestObject: + type: object + additionalProperties: false + x-internal: true # Don't display in schemas section of docs + properties: + name: + type: string + nullable: false + description: "The name of the new tag. Must be between 1 and 100 characters.\nMust not match the name of any existing tags." + minLength: 1 + maxLength: 100 + description: + type: string + nullable: true + default: + description: The description of the tag. Must not exceed 200 characters. + maxLength: 200 + archived: + type: boolean + default: false + description: If true, the tag is archived and not displayed in relevant areas of the Lunch Money app. + required: + - name + + # Request object for a PUT /tags/:id request + # Tolerate a request object that includes system created fields from a + # previous GET request, but are essentially ignored + updateTagRequestObject: + type: object + x-internal: true # Don't display in schemas section of docs + additionalProperties: false + properties: + id: + type: integer + format: int64 + description: System defined unique identifier for the category. Ignored if set. + name: + type: string + nullable: false + description: If set the new name of the category. Must be between 1 and 100 characters. + minLength: 1 + maxLength: 100 + description: + type: string + nullable: true + description: If set the new description of the category. Must not exceed 200 characters. + maxLength: 200 + archived: + type: boolean + description: If set will indicate if this category is archived. + + # The response object for a DELETE /category request with dependencies + deleteTagResponseWithDependencies: + type: object + x-internal: true # Don't display in schemas section of docs + additionalProperties: false + properties: + tag_name: + type: string + description: The name of the tag + dependents: + type: object + properties: + tag_rules: + type: number + description: The number of rules depending on the tag + transactions: + type: number + description: The number of transactions with the tag + required: + - tag_rules + - transactions + required: + - tag_name + - dependents + + recurringObject: + type: object + properties: + id: + type: integer + description: The unique identifier of this recurring item + description: + type: string + description: An optional description of this recurring item. This is not written into the transactions. + status: + type: string + description: The status of this recurring item. `suggested` recurring items are generated by Lunch Money, but only `reviewed` recurring items will be applied to matching transactions. + enum: + - suggested + - reviewed + transaction_criteria: + type: object + description: The set of properties used to identify matching transactions. + properties: + start_date: + type: string + format: date + nullable: true + description: The beginning of the date range for matching transactions. If null, any transactions before end_date may be considered. + end_date: + type: string + format: date + nullable: true + description: The end of the date range for matching transactions. If null, any transactions after start_date may be considered. + granularity: + type: string + description: The unit of time used to define the cadence of the recurring item. + enum: + - day + - week + - month + - year + quantity: + type: integer + description: The number of granularity units between each recurrence. + anchor_date: + type: string + format: date + nullable: false + description: The date used in conjunction with the `quantity` and `granularity` properties to calculate expected occurrences of recurring transactions. + payee: + type: string + nullable: true + description: If any, represents the original transaction payee name that triggered this recurring item's creation. + amount: + type: string + pattern: ^-?\d+(\.\d{1,4})?$ + description: The expected amount for a transaction that will match this recurring item. For recurring items that have a flexible amount this is the average of the specified min and max amounts. + currency: + type: string + nullable: false + description: Three-letter lowercase currency code of the recurring item. + to_base: + type: number + format: double + description: The base amount of the recurring item. + plaid_account_id: + type: integer + format: int64 + nullable: true + description: The Plaid account ID associated with the recurring item, if any. + manual_account_id: + type: integer + format: int64 + nullable: true + description: The manual account ID associated with the recurring item, if any. + overrides: + type: object + description: The values that will be applied to matching transactions. + properties: + payee: + type: string + nullable: false + description: If present, the payee name that will be displayed for any matching transactions. + notes: + type: string + nullable: false + description: If present, the notes that will be displayed for any matching transactions. + category_id: + type: integer + nullable: false + description: If present, the id of the category that matching transactions will be assigned to. + matches: + type: object + nullable: true + description: Details on expected, found and missing transactions for the specified range. This will be `null` for recurring items with a `status` of `suggested`. + properties: + request_start_date: + type: string + format: date + description: The beginning of the date range that this request used to find matching transactions. + request_end_date: + type: string + format: date + description: The beginning of the date range that this request used to find matching transactions. + expected_occurrence_dates: + type: array + items: + type: string + format: date + description: A list of dates within the specified range where a recurring transactions is expected. + found_transactions: + type: array + description: A list with the dates and IDs of matching transactions. + items: + type: object + properties: + date: + type: string + format: date + description: The date for a matching transaction within the specified range. + transaction_id: + type: integer + description: The ID of a matching transaction within the specified range. + missing_transaction_dates: + type: array + items: + type: string + format: date + description: A list of dates within the range of where a recurring transaction was expected but none was found. + created_by: + type: integer + nullable: false + description: The ID of the user who created the recurring item. + created_at: + type: string + format: date-time + nullable: false + description: Date/time the recurring item was created in ISO 8601 extended format. + updated_at: + type: string + format: date-time + nullable: false + description: Date/time the recurring item was updated in ISO 8601 extended format. + source: + type: string + description: | + This can be one of four values: + - `manual`: User created this recurring item manually from the Recurring Items page + - `transaction`: User created this by converting a transaction from the Transactions page + - `system`: Recurring item was created by the system on transaction import + - `null`: Some older recurring items may not have a source. + enum: + - manual + - transaction + - system + - + required: + - id + - description + - status + - transaction_criteria + - overrides + - matches + - created_by + - created_at + - updated_at + - source + + transactionOverridesObject: + type: object + x-internal: true # Don't display in schemas section of docs + additionalProperties: false + nullable: true + description: This object will be included in the transaction if it matched a recurring item causing one or more transaction properties to be automatically overridden. The object will include data on the original fields values prior to the override.
In cases where no recurring item matched, or when no transaction properties were overridden, this field will be null. + properties: + original_payee: + type: string + description: The value of the payee field prior to the recurring rule taking effect. Will not exist if the payee field was not previously populated or was not changed by the recurring item. + original_category_id: + type: integer + format: int64 + nullable: true # This could change, pending discussion with Jen + description: The id of the transaction's category prior to the recurring rule taking effect. Will not exist if the transaction was not previously categorized or was not changed by the recurring item. + original_notes: + type: string + description: The value of the notes field prior to the recurring rule taking effect. Will not exist if the notes field was not previously populated or was not changed by the recurring recurring_item. + + errorResponseObject: + type: object + properties: + message: + type: string + description: overall error message + errors: + type: array + items: + # This is currently an open ended object but we may want to standardize + # We may wish to enumerate error codes + type: object + required: + - message + - errors + + # Define the allowed types for a manual account + AccountTypeEnum: + type: string + enum: + - cash + - credit + - cryptocurrency + - employee compensation + - investment + - loan + - other liability + - other asset + - real estate + - vehicle + # Define the allowed types for the 3 letter currency codes + currencyEnum: + type: string + description: | + Supported Currency codes: + - `aed`: United Arab Emirates Dirham + - `afn`: Afghan Afghani + - `all`: Albanian Lek + - `amd`: Armenian Dram + - `ang`: Netherlands Antillean Guilder + - `aoa`: Angolan Kwanza + - `ars`: Argentine Peso + - `aud`: Australian Dollar + - `awg`: Aruban Florin + - `azn`: Azerbaijani Manat + - `bam`: Bosnia-Herzegovina Convertible Mark + - `bbd`: Barbadian Dollar + - `bdt`: Bangladeshi Taka + - `bgn`: Bulgarian Lev + - `bhd`: Bahraini Dinar + - `bif`: Burundian Franc + - `bmd`: Bermudian Dollar + - `bnd`: Brunei Dollar + - `bob`: Bolivian Boliviano + - `brl`: Brazilian Real + - `bsd`: Bahamian Dollar + - `btc`: Bitcoin + - `btn`: Bhutanese Ngultrum + - `bwp`: Botswanan Pula + - `byn`: Belarusian Ruble + - `bzd`: Belize Dollar + - `cad`: Canadian Dollar + - `cdf`: Congolese Franc + - `chf`: Swiss Franc + - `clp`: Chilean Peso + - `cny`: Chinese Yuan + - `cop`: Colombian Peso + - `crc`: Costa Rican Colón + - `cuc`: Cuban Convertible Peso + - `cup`: Cuban Peso + - `cve`: Cape Verdean Escudo + - `czk`: Czech Republic Koruna + - `djf`: Djiboutian Franc + - `dkk`: Danish Krone + - `dop`: Dominican Peso + - `dzd`: Algerian Dinar + - `egp`: Egyptian Pound + - `ern`: Eritrean Nakfa + - `etb`: Ethiopian Birr + - `eur`: Euro + - `fjd`: Fijian Dollar + - `fkp`: Falkland Islands Pound + - `gbp`: British Pound Sterling + - `gel`: Georgian Lari + - `ggp`: Guernsey Pound + - `ghs`: Ghanaian Cedi + - `gip`: Gibraltar Pound + - `gmd`: Gambian Dalasi + - `gnf`: Guinean Franc + - `gtq`: Guatemalan Quetzal + - `gyd`: Guyanaese Dollar + - `hkd`: Hong Kong Dollar + - `hnl`: Honduran Lempira + - `hrk`: Croatian Kuna + - `htg`: Haitian Gourde + - `huf`: Hungarian Forint + - `idr`: Indonesian Rupiah + - `ils`: Israeli New Sheqel + - `imp`: Isle of Man Pound + - `inr`: Indian Rupee + - `iqd`: Iraqi Dinar + - `irr`: Iranian Rial + - `isk`: Icelandic Króna + - `jep`: Jersey Pound + - `jmd`: Jamaican Dollar + - `jod`: Jordanian Dinar + - `jpy`: Japanese Yen + - `kes`: Kenyan Shilling + - `kgs`: Kyrgystani Som + - `khr`: Cambodian Riel + - `kmf`: Comorian Franc + - `kpw`: North Korean Won + - `krw`: South Korean Won + - `kwd`: Kuwaiti Dinar + - `kyd`: Cayman Islands Dollar + - `kzt`: Kazakhstani Tenge + - `lak`: Laotian Kip + - `lbp`: Lebanese Pound + - `lkr`: Sri Lankan Rupee + - `lrd`: Liberian Dollar + - `lsl`: Lesotho Loti + - `ltl`: Lithuanian Litas + - `lvl`: Latvian Lats + - `lyd`: Libyan Dinar + - `mad`: Moroccan Dirham + - `mdl`: Moldovan Leu + - `mga`: Malagasy Ariary + - `mkd`: Macedonian Denar + - `mmk`: Myanma Kyat + - `mnt`: Mongolian Tugrik + - `mop`: Macanese Pataca + - `mro`: Mauritanian Ouguiya + - `mur`: Mauritian Rupee + - `mvr`: Maldivian Rufiyaa + - `mwk`: Malawian Kwacha + - `mxn`: Mexican Peso + - `myr`: Malaysian Ringgit + - `mzn`: Mozambican Metical + - `nad`: Namibian Dollar + - `ngn`: Nigerian Naira + - `nio`: Nicaraguan Córdoba + - `nok`: Norwegian Krone + - `npr`: Nepalese Rupee + - `nzd`: New Zealand Dollar + - `omr`: Omani Rial + - `pab`: Panamanian Balboa + - `pen`: Peruvian Nuevo Sol + - `pgk`: Papua New Guinean Kina + - `php`: Philippine Peso + - `pkr`: Pakistani Rupee + - `pln`: Polish Zloty + - `pyg`: Paraguayan Guarani + - `qar`: Qatari Rial + - `ron`: Romanian Leu + - `rsd`: Serbian Dinar + - `rub`: Russian Ruble + - `rwf`: Rwandan Franc + - `sar`: Saudi Riyal + - `sbd`: Solomon Islands Dollar + - `scr`: Seychellois Rupee + - `sdg`: Sudanese Pound + - `sek`: Swedish Krona + - `sgd`: Singapore Dollar + - `shp`: Saint Helena Pound + - `sll`: Sierra Leonean Leone + - `sos`: Somali Shilling + - `srd`: Surinamese Dollar + - `std`: São Tomé and Príncipe Dobra + - `svc`: Salvadoran Colón + - `syp`: Syrian Pound + - `szl`: Swazi Lilangeni + - `thb`: Thai Baht + - `tjs`: Tajikistani Somoni + - `tmt`: Turkmenistani Manat + - `tnd`: Tunisian Dinar + - `top`: Tongan Paʻanga + - `try`: Turkish Lira + - `ttd`: Trinidad and Tobago Dollar + - `twd`: New Taiwan Dollar + - `tzs`: Tanzanian Shilling + - `uah`: Ukrainian Hryvnia + - `ugx`: Ugandan Shilling + - `usd`: United States Dollar + - `uyu`: Uruguayan Peso + - `uzs`: Uzbekistan Som + - `vef`: Venezuelan Bolívar + - `vnd`: Vietnamese Dong + - `vuv`: Vanuatu Vatu + - `wst`: Samoan Tala + - `xaf`: CFA Franc BEAC + - `xcd`: East Caribbean Dollar + - `xof`: CFA Franc BCEAO + - `xpf`: CFP Franc + - `yer`: Yemeni Rial + - `zar`: South African Rand + - `zmw`: Zambian Kwacha + - `zwl`: Zimbabwean Dollar + enum: + - aed + - afn + - all + - amd + - ang + - aoa + - ars + - aud + - awg + - azn + - bam + - bbd + - bdt + - bgn + - bhd + - bif + - bmd + - bnd + - bob + - brl + - bsd + - btc + - btn + - bwp + - byn + - bzd + - cad + - cdf + - chf + - clp + - cny + - cop + - crc + - cuc + - cup + - cve + - czk + - djf + - dkk + - dop + - dzd + - egp + - ern + - etb + - eur + - fjd + - fkp + - gbp + - gel + - ggp + - ghs + - gip + - gmd + - gnf + - gtq + - gyd + - hkd + - hnl + - hrk + - htg + - huf + - idr + - ils + - imp + - inr + - iqd + - irr + - isk + - jep + - jmd + - jod + - jpy + - kes + - kgs + - khr + - kmf + - kpw + - krw + - kwd + - kyd + - kzt + - lak + - lbp + - lkr + - lrd + - lsl + - ltl + - lvl + - lyd + - mad + - mdl + - mga + - mkd + - mmk + - mnt + - mop + - mro + - mur + - mvr + - mwk + - mxn + - myr + - mzn + - nad + - ngn + - nio + - nok + - npr + - nzd + - omr + - pab + - pen + - pgk + - php + - pkr + - pln + - pyg + - qar + - ron + - rsd + - rub + - rwf + - sar + - sbd + - scr + - sdg + - sek + - sgd + - shp + - sll + - sos + - srd + - std + - svc + - syp + - szl + - thb + - tjs + - tmt + - tnd + - top + - try + - ttd + - twd + - tzs + - uah + - ugx + - usd + - uyu + - uzs + - vef + - vnd + - vuv + - wst + - xaf + - xcd + - xof + - xpf + - yer + - zar + - zmw + - zwl + + responses: + # errors + unauthorizedToken: + description: Unauthorized. This error occurs when an invalid API token is passed to the request. + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Unauthorized + errors: + - errMsg: Access token does not exist. + rateLimited: + description: Too Many Requests. Retry your request after the number of seconds specified in the retry-after header. + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Too Many Requests + errors: + - errMsg: Too many requests, please try again later. + serverError: + description: Internal Server Error. Contact support. + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Internal Server Error + errors: + - errMsg: Currently in maintenance mode. Please try again in a few minutes. + + securitySchemes: + bearerSecurity: + type: http + description: The Lunch Money API uses API keys to authenticate requests. To use the v1 API you can view and manage your API keys on the [developers page in the Lunch Money app](https://my.lunchmoney.app/developers).

To interact with the Static Mock Server simply enter an API key of 11 characters or more.

To interact with the v2 service implemented on top of the v1 API paste in a real API token associated with a Lunch Money Budget. + scheme: bearer + bearerFormat: JWT + cookieAuth: + type: apiKey + in: cookie + name: _lm_access_token + +paths: + /me: + get: + tags: + - me + summary: Get current user + description: >- + Get details about the user associated with the supplied + authorization token. + operationId: getMe + parameters: [] + responses: + "200": + description: The User Object associated with the authorized token. + content: + application/json: + schema: + $ref: "#/components/schemas/userObject" + example: + name: User 1 + email: user-1@lunchmoney.dev + id: 18328 + account_id: 18221 + budget_name: \U0001F3E0 Family budget + primary_currency: usd + api_key_label: Side project dev key + "401": + $ref: "#/components/responses/unauthorizedToken" + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + /categories: + get: + tags: + - categories + summary: Get all categories + description: Retrieve a list of all categories associated with the user's account. + operationId: getAllCategories + parameters: + - name: format + in: query + description: If `nested`, returns top-level categories (either category groups or categories not part of a category group) in alphabetical order. Grouped categories are nested within the category group under the property `children`. A `flattened`, response is similar but it also includes grouped categories at the top level of this.
Categories are sorted by their `order`. When `order` is null, they are listed below other categories with an `order` in alphabetical order. + required: false + schema: + type: string + default: nested + enum: + - nested + - flattened + - name: is_group + in: query + description: If set to `false`, just the list of assignable categories is returned.
If set to `true`, only category groups are returned.
When set the `format` parameter is ignored. + required: false + schema: + type: boolean + default: not set + enum: + - false + - true + responses: + "200": + description: A list of Category Objects + content: + application/json: + schema: + type: object + properties: + categories: + type: array + items: + $ref: "#/components/schemas/categoryObject" + examples: + nested response: + value: + categories: + - id: 86 + name: Automobile + description: Auto related categories + is_income: false + exclude_from_budget: false + exclude_from_totals: false + updated_at: "2024-02-28T09:49:03.238Z" + created_at: "2024-01-28T09:49:03.238Z" + is_group: true + order: 2 + archived: false + group_id: + archived_at: + children: + - id: 315174 + name: Fuel + description: Fuel and gas expenses + updated_at: "2024-02-28T09:49:03.238Z" + created_at: "2024-01-28T09:49:03.238Z" + is_group: false + order: 1 + archived: false + group_id: 86 + archived_at: + - id: 315175 + name: Maintenance + description: Car maintenance and repairs + updated_at: "2024-02-28T09:49:03.238Z" + created_at: "2024-01-28T09:49:03.238Z" + is_group: false + order: 2 + archived: false + group_id: 86 + archived_at: + - id: 83 + name: Rent + description: Monthly Rent + is_income: false + exclude_from_budget: false + exclude_from_totals: false + updated_at: "2024-02-28T09:49:03.225Z" + created_at: "2024-01-28T09:49:03.225Z" + is_group: false + order: 0 + archived: false + group_id: + archived_at: + - id: 88 + name: W2 Income + description: + is_income: true + exclude_from_budget: false + exclude_from_totals: true + updated_at: "2024-02-28T09:49:03.238Z" + created_at: "2024-01-28T09:49:03.238Z" + is_group: false + order: 3 + archived: false + group_id: + archived_at: + flattened response: + value: + categories: + - id: 86 + name: Automobile + description: Auto related categories + is_income: false + exclude_from_budget: false + exclude_from_totals: false + updated_at: "2024-02-28T09:49:03.238Z" + created_at: "2024-01-28T09:49:03.238Z" + is_group: true + order: 1 + archived: false + group_id: + archived_at: + children: + - id: 315174 + name: Fuel + description: Fuel and gas expenses + updated_at: "2024-02-28T09:49:03.238Z" + created_at: "2024-01-28T09:49:03.238Z" + is_group: false + order: 1 + archived: false + group_id: 86 + archived_at: + - id: 315175 + name: Maintenance + description: Car maintenance and repairs + updated_at: "2024-02-28T09:49:03.238Z" + created_at: "2024-01-28T09:49:03.238Z" + is_group: false + order: 2 + archived: false + group_id: 86 + archived_at: + - id: 315174 + name: Fuel + description: Fuel and gas expenses + is_income: false + exclude_from_budget: false + exclude_from_totals: false + updated_at: "2024-02-28T09:49:03.238Z" + created_at: "2024-01-28T09:49:03.238Z" + is_group: false + order: 1 + archived: false + group_id: 86 + archived_at: + - id: 315175 + name: Maintenance + description: Car maintenance and repairs + is_income: false + exclude_from_budget: false + exclude_from_totals: false + updated_at: "2024-02-28T09:49:03.238Z" + created_at: "2024-01-28T09:49:03.238Z" + is_group: false + order: 2 + archived: false + group_id: 86 + archived_at: + - id: 83 + name: Rent + description: Monthly Rent + is_income: false + exclude_from_budget: false + exclude_from_totals: false + updated_at: "2024-02-28T09:49:03.225Z" + created_at: "2024-01-28T09:49:03.225Z" + is_group: false + order: 2 + archived: false + group_id: + archived_at: + - id: 88 + name: W2 Income + description: + is_income: true + exclude_from_budget: false + exclude_from_totals: true + updated_at: "2024-02-28T09:49:03.238Z" + created_at: "2024-01-28T09:49:03.238Z" + is_group: false + order: 3 + archived: false + group_id: + archived_at: + "400": + description: Invalid request parameters + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Request Validation Failure + errors: + - errMsg: must be equal to one of the allowed values + instancePath: /query/format + schemaPath: "#/properties/query/properties/format/enum" + keyword: enum + params: + allowedValues: + - flattened + - nested + "401": + $ref: "#/components/responses/unauthorizedToken" + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + post: + tags: + - categories + summary: Create a new category or category group + description: Creates a new category with the given name.
If the `is_group` attribute is set to true, a category group is created. In this case the `children` attribute may also be set to an array of existing category IDs to add to the newly created category group. + operationId: createCategory + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/createCategoryRequestObject" + examples: + category: + value: + name: API Created Category + description: Test description of created category + is_income: false + exclude_from_budget: true + exclude_from_totals: false + is_group: false + category group: + value: + name: API Created Category Group + description: Test description of Category Group + is_income: false + exclude_from_budget: false + exclude_from_totals: false + is_group: true + children: + - 83 + responses: + "201": + description: Category or Category Group Object with the successfully created category or category group. + content: + application/json: + schema: + $ref: "#/components/schemas/categoryObject" + examples: + category: + value: + id: 90 + name: API Created Category + description: Test description of created category + is_income: false + exclude_from_budget: true + exclude_from_totals: false + updated_at: 2024-05-26T19:56:52.699000Z + created_at: 2024-05-26T19:56:52.699000Z + is_group: false + group_id: + archived: false + archived_at: + order: + category group: + value: + id: 91 + name: API Created Category Group + description: Test description of Category Group + is_income: false + exclude_from_budget: false + exclude_from_totals: false + updated_at: "2024-05-27T19:59:45.053Z" + created_at: "2024-05-27T19:59:45.053Z" + is_group: true + group_id: + archived: false + archived_at: + order: + children: + - id: 83 + name: Rent + description: Monthly Rent + updated_at: "2024-02-28T09:49:03.225Z" + created_at: "2024-01-28T09:49:03.225Z" + is_group: false + order: 1 + archived: false + group_id: + archived_at: + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Invalid Request Body + errors: + - errMsg: Cannot specify a 'group_id' in request body if 'is_group' is also true + "401": + $ref: "#/components/responses/unauthorizedToken" + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + /categories/{id}: + get: + tags: + - categories + summary: Get a single category + description: Retrieve details of a specific category or category group by its ID. + operationId: getCategoryById + parameters: + - name: id + in: path + description: ID of the category to retrieve + required: true + schema: + type: integer + examples: + category: + summary: Example of a category's id + value: 315174 + category group: + summary: Example of a category group's id + value: 86 + id not found: + summary: Example of an id that doesn't exist + value: 543210 + responses: + "201": + description: Category Object with the requested category or category group. + content: + application/json: + schema: + $ref: "#/components/schemas/categoryObject" + examples: + category: + value: + id: 315174 + name: Fuel + description: Fuel and gas expenses + is_income: false + exclude_from_budget: false + exclude_from_totals: false + updated_at: "2024-02-28T09:49:03.238Z" + created_at: "2024-01-28T09:49:03.238Z" + group_id: 86 + is_group: false + archived: false + archived_at: + order: 1 + category group: + value: + id: 86 + name: Automobile + description: Auto related categories + is_income: false + exclude_from_budget: false + exclude_from_totals: false + updated_at: "2024-02-28T09:49:03.238Z" + created_at: "2024-01-28T09:49:03.238Z" + is_group: true + order: 2 + archived: false + group_id: + archived_at: + children: + - id: 315174 + name: Fuel + description: Fuel and gas expenses + updated_at: "2024-02-28T09:49:03.238Z" + created_at: "2024-01-28T09:49:03.238Z" + group_id: 86 + is_group: false + archived: false + archived_at: + order: 1 + - id: 315175 + name: Maintenance + description: Car maintenance and repairs + updated_at: "2024-02-28T09:49:03.238Z" + created_at: "2024-01-28T09:49:03.238Z" + group_id: 86 + is_group: false + archived: false + archived_at: + order: 2 + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Request Validation Failure + errors: + - errMsg: must be a valid integer + instancePath: /query/ids/0 + schemaPath: "#/properties/query/properties/ids/items/type" + keyword: type + params: + type: integer + "401": + $ref: "#/components/responses/unauthorizedToken" + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Not Found + errors: + - errMsg: There is no category with the id:'543210'` + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + put: + tags: + - categories + summary: Update an existing category or category group + description: "Updates an existing category or category group.\n\nYou may submit the response from a `GET /categories/{id}` as the request body which includes system created attributes such as `id` or `created_at`, however only the `name`, `description`, `is_income`, `exclude_from_budget`, `exclude_from_totals`, `archived`, `group_id`, `order` and `children` can be updated using this API.\n\nIt is also possible to provide only the attribute(s) to be updated in the request body, as long as the request includes at least one of the attributes listed above. For example a request body that contains only a `name` attribute is valid.\nIt is not possible to use this API to convert a category to a category group, or a vice versa, so while submitting a request body with the `is_group` attribute is tolerated, it will result in an error response if the value is changed.\n\nIt is possible to modify the children of an existing category group with this API by setting the `children` attribute. If this is set it will replace the existing children with the newly specified children, so if the intention is to add or remove a single category, it is more straightforward to update the child category by specifying the new `group_id` attribute. If the goal is to add multiple new children or remove multiple existing children, it is recommended to first call the `GET /categories/:id` endpoint to get the existing children and then modify the list as desired." + operationId: updateCategory + parameters: + - name: id + in: path + description: ID of the category to update + required: true + schema: + type: integer + examples: + category: + summary: Example of a category's id + value: 83 + category group: + summary: Example of a category group's id + value: 86 + child category: + summary: Example of a category belonging to a group + value: 315164 + not found: + summary: Example of a category id that does not exist + value: 543210 + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/updateCategoryRequestObject" + examples: + Update some category attributes: + value: + name: Updated Category Name + description: Updated description of the category + Update same attributes with full object: + value: + id: 83 + name: Updated Category Name + description: Updated description of the category + is_income: false + exclude_from_budget: true + exclude_from_totals: false + updated_at: 2020-01-28T09:49:03.225000Z + created_at: 2020-01-28T09:49:03.225000Z + is_group: false + group_id: + archived: false + archived_at: + order: 0 + Invalid attempt to convert to category group: + value: + id: 83 + name: Old Category is now a group! + is_group: true + Remove category from a group: + value: + id: 86 + name: Automobile + description: API Removed a sub category + children: + - 315174 + responses: + "200": + description: Category or Category Group updated successfully + content: + application/json: + schema: + $ref: "#/components/schemas/categoryObject" + examples: + category: + value: + id: 83 + name: Updated Category Name + description: Updated description of the category + is_income: false + exclude_from_budget: false + exclude_from_totals: true + updated_at: 2024-05-26T20:41:18.406000Z + created_at: 2024-01-28T09:49:03.225000Z + is_group: false + order: 0 + archived: false + archived_at: + group_id: + category group: + value: + id: 86 + name: Automobile + description: API Removed a sub category + is_income: false + exclude_from_budget: false + exclude_from_totals: false + updated_at: "2024-06-22T19:54:30.921Z" + created_at: "2024-01-28T09:49:03.238Z" + is_group: true + order: 2 + archived: false + group_id: + archived_at: + children: + - id: 315174 + name: Fuel + description: Fuel and gas expenses + updated_at: "2024-02-28T09:49:03.238Z" + created_at: "2024-01-28T09:49:03.238Z" + group_id: 86 + is_group: false + archived: false + archived_at: + order: 1 + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Invalid Request Body + errors: + - errMsg: Cannot modify the 'group_id' attribute of an existing category or category group + "401": + $ref: "#/components/responses/unauthorizedToken" + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Not Found + errors: + - errMsg: There is no category with the id:'543210'` + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + delete: + tags: + - categories + summary: Delete a category or category group + description: Attempts to delete the single category or category group specified on the path. By default his will only work if there are no dependencies, such as existing budgets for the category, categorized transactions, children categories for a category group, categorized recurring items, etc. If there are dependents, this endpoint will return and object that describes each of the possible dependencies are and how many there are. + operationId: deleteCategory + parameters: + - in: path + name: id + description: ID of the category to delete + required: true + schema: + type: integer + examples: + delete category: + summary: Simple category delete + value: 83 + delete category group: + summary: Attempt to delete category with dependencies + value: 84 + id not found: + summary: Example of an id that doesn't exist + value: 543210 + - in: query + name: force + description: Set to true to force deletion even if there are dependencies + required: false + schema: + type: boolean + default: false + responses: + "204": + description: No Content + "422": + description: Unprocessable Entity + content: + application/json: + schema: + $ref: "#/components/schemas/deleteCategoryResponseWithDependencies" + examples: + delete category with dependencies: + summary: Response to an attempt to delete category with dependencies + value: + category_name: Category to be Deleted + dependents: + budget: 0 + category_rules: 1 + transactions: 10 + children: 0 + recurring: 0 + plaid_cats: 0 + delete category group: + summary: Response to attempt to delete a category group with children + value: + category_name: Category Group to be Deleted + dependents: + budget: 0 + category_rules: 0 + transactions: 0 + children: 3 + recurring: 0 + plaid_cats: 0 + "401": + $ref: "#/components/responses/unauthorizedToken" + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Not Found + errors: + - errMsg: There is no category with the id:'543210'` + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + /manual_accounts: + get: + tags: + - manual_accounts + summary: Get all manual accounts + description: Retrieve a list of all manually-managed accounts associated with the user's account. + operationId: getAllManualAccounts + responses: + "200": + description: A list of manual accounts + content: + application/json: + schema: + type: object + properties: + manual_accounts: + type: array + items: + $ref: "#/components/schemas/manualAccountObject" + example: + manual_accounts: + - id: 119807 + name: Individual Brokerage + type: investment + subtype: brokerage + display_name: + balance: "41211.8000" + balance_as_of: "2024-06-25T17:00:04.000Z" + closed_on: + currency: usd + institution_name: Fidelity + exclude_from_transactions: false + created_at: "2024-06-25T17:00:04.414Z" + updated_at: "2024-06-26T19:03:38.312Z" + - id: 119909 + name: Euro Travel Card + type: credit + subtype: credit card + display_name: + balance: "1004.8000" + balance_as_of: "2023-06-25T17:00:04.000Z" + closed_on: + currency: usd + institution_name: WeBank + exclude_from_transactions: false + created_at: "2024-06-25T17:00:04.414Z" + updated_at: "2024-06-26T19:03:38.312Z" + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Request Validation Failure + errors: + - errMsg: must NOT have additional properties + instancePath: /query + schemaPath: "#/properties/query/additionalProperties" + keyword: additionalProperties + params: + additionalProperty: foo + "401": + $ref: "#/components/responses/unauthorizedToken" + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + post: + tags: + - manual_accounts + summary: Create a manual account + description: Create a new manually-managed account. + operationId: createManualAccount + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/createManualAccountRequestObject" + examples: + minimum request body: + summary: Minimum required fields for creating a manual account + value: + name: API created Account + type: cash + balance: "100" + full example: + summary: Full example with all fields + value: + name: API created loan + type: vehicle + subtype: loan + display_name: Car loan + balance: "9999.99" + balance_as_of: "2024-10-12" + closed_on: + currency: usd + institution_name: Bank of America + exclude_from_transactions: false + responses: + "201": + description: Successfully created manual account + content: + application/json: + schema: + $ref: "#/components/schemas/manualAccountObject" + examples: + minimum request response: + value: + id: 119999 + name: API created Account + type: cash + subtype: + balance: "100" + balance_as_of: "2024-10-06T18:55:08.599Z" + closed_on: + currency: usd + institution_name: + external_id: + exclude_from_transactions: false + created_at: "2024-10-06T18:55:08.599Z" + updated_at: "2024-10-06T18:55:08.599Z" + complete request response: + value: + id: 119999 + name: API created loan + type: vehicle + subtype: loan + balance: "9999.99" + balance_as_of: "2024-10-12" + closed_on: + currency: usd + institution_name: Bank of America + external_id: + exclude_from_transactions: false + created_at: "2024-10-06T18:57:12.029Z" + updated_at: "2024-10-06T18:57:12.029Z" + "400": + description: Invalid request body + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Request Validation Failure + errors: + - errMsg: must have required property 'name' + instancePath: /requestBody + schemaPath: "#/properties/requestBody/required" + keyword: required + params: + missingProperty: name + "401": + $ref: "#/components/responses/unauthorizedToken" + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + /manual_accounts/{id}: + get: + tags: + - manual_accounts + summary: Get a single manual account + description: Retrieve the details of the manual account with the specified ID. + operationId: getManualAccountById + parameters: + - name: id + in: path + description: ID of the manual account to retrieve + required: true + schema: + type: integer + examples: + basic manual account: + summary: Basic manual account by id request + value: 119807 + id not found: + summary: Example of an id that doesn't exist + value: 9999999999999 + responses: + "200": + description: Manual Account Object with the requested account. + content: + application/json: + schema: + $ref: "#/components/schemas/manualAccountObject" + example: + id: 119807 + name: Individual Brokerage + type: investment + subtype: brokerage + display_name: + balance: "41211.8000" + balance_as_of: "2024-06-25T17:00:04.000Z" + closed_on: + currency: usd + institution_name: Fidelity + external_id: + exclude_from_transactions: false + created_at: "2024-06-25T17:00:04.414Z" + updated_at: "2024-06-26T19:03:38.312Z" + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Request Validation Failure + errors: + - errMsg: must be integer + instancePath: /path/id + schemaPath: "#/properties/path/properties/ids/items/type" + keyword: type + params: + type: integer + "401": + $ref: "#/components/responses/unauthorizedToken" + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Not Found + errors: + - errMsg: There is no manual account with the id:'9999999999999'` + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + put: + tags: + - manual_accounts + summary: Update an existing manual account + description: "Updates an existing manual account.\n\nYou may submit the response from a `GET /manual_accounts/{id}` as the request body which includes system created attributes such as `id` or `created_at`, however only the `name`, `type`, `subtype`, `display_name`, `balance`, `balance_as_of`, `closed_on`, `currency`, `institution_name`, `external_id`, and `exclude_from_transactions` can be updated using this API.\n\nIt is also possible to provide only the attribute(s) to be updated in the request body, as long as the request includes at least one of the attributes listed above. For example a request body that contains only a `name` attribute is valid." + operationId: updateManualAccount + parameters: + - name: id + in: path + description: ID of the manual account to update + required: true + schema: + type: integer + examples: + category: + summary: Example of a manual account's id + value: 119807 + not found: + summary: Example of a manual account ID that does not exist + value: 999999999 + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/updateManualAccountRequestObject" + examples: + minimum request body: + summary: type change + value: + type: credit + close account: + summary: close and exclude + value: + closed_on: "2024-10-15" + exclude_from_transactions: true + use get request: + summary: Only display name has changed + value: + id: 119909 + name: Euro Travel Card + type: credit + subtype: credit card + display_name: New Display Name + balance: "1004.8000" + balance_as_of: "2023-06-25T17:00:04.000Z" + closed_on: + currency: usd + institution_name: WeBank + exclude_from_transactions: false + created_at: "2024-06-25T17:00:04.414Z" + updated_at: "2024-06-26T19:03:38.312Z" + responses: + "200": + description: Manual Account updated successfully + content: + application/json: + schema: + $ref: "#/components/schemas/manualAccountObject" + examples: + type changed to credit: + value: + id: 119807 + name: Individual Brokerage + type: investment + subtype: brokerage + display_name: + balance: "41211.8000" + balance_as_of: "2024-06-25T17:00:04.000Z" + closed_on: + currency: usd + external_id: + institution_name: Fidelity + exclude_from_transactions: false + created_at: "2024-06-25T17:00:04.414Z" + updated_at: "2024-06-26T19:03:38.312Z" + closed account: + value: + id: 119807 + name: Individual Brokerage + type: investment + subtype: brokerage + display_name: + balance: "41211.8000" + balance_as_of: "2024-06-25T17:00:04.000Z" + closed_on: "2024-10-06" + currency: usd + external_id: + institution_name: Fidelity + exclude_from_transactions: true + created_at: "2024-06-25T17:00:04.414Z" + updated_at: "2024-10-06T19:03:09.506Z" + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Invalid Request Body + errors: + - errMsg: "A request to update a manual account must include at least one of the following properties: name, type, subtype, display_name, balance, balance_as_of, closed_on, currency, institution_name, exclude_from_transactions" + "401": + $ref: "#/components/responses/unauthorizedToken" + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Not Found + errors: + - errMsg: There is no manual account with the id:'543210'` + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + delete: + tags: + - manual_accounts + summary: Delete a manual account + description: Deletes the single manual account with the ID specified on the path. If any transactions exist with the `manual_account_id` property set to this account's ID they will appear with a warning when displayed in the web view. + operationId: deleteManualAccount + parameters: + - in: path + name: id + description: ID of the manual account to delete + required: true + schema: + type: integer + examples: + delete manual account: + summary: Account ID to delete + value: 119807 + id not found: + summary: Example of an id that doesn't exist + value: 543210 + responses: + "204": + description: No Content + "401": + $ref: "#/components/responses/unauthorizedToken" + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Not Found + errors: + - errMsg: There is no manual account with the id:'543210'` + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + /plaid_accounts: + get: + tags: + - plaid_accounts + summary: Get all accounts synced via Plaid + description: Retrieve a list of all synced accounts associated with the user's account. + operationId: getAllPlaidAccounts + responses: + "200": + description: A list of accounts synced via Plaid + content: + application/json: + schema: + type: object + properties: + plaid_accounts: + type: array + items: + $ref: "#/components/schemas/plaidAccountObject" + example: + plaid_accounts: + - id: 119804 + date_linked: "2020-01-28" + name: 401k + display_name: "" + type: brokerage + subtype: 401k + mask: "7468" + institution_name: Vanguard + status: inactive + allow_transaction_modifications: false + limit: + balance: "12345.6700" + currency: usd + balance_last_update: "2020-01-27T01:38:11.862Z" + import_start_date: "2023-01-01" + last_import: "2019-09-04T12:57:09.190Z" + last_fetch: "2020-01-28T01:38:11.862Z" + plaid_last_successful_update: "2020-01-27T01:38:11.862Z" + - id: 119805 + date_linked: "2020-01-28" + name: Freedom + display_name: Penny's Visa + type: credit + subtype: credit card + mask: "1973" + institution_name: Chase + status: active + allow_transaction_modifications: true + limit: 15000 + balance: "0.0000" + currency: usd + balance_last_update: "2023-01-27T01:38:07.460Z" + import_start_date: "2023-01-01" + last_import: "2023-01-24T12:57:03.250Z" + last_fetch: "2023-01-28T01:38:11.862Z" + plaid_last_successful_update: "2023-01-27T01:38:11.862Z" + - id: 119806 + date_linked: "2020-01-28" + name: Checking + display_name: Penny's Checking + type: cash + subtype: checking + mask: "2046" + institution_name: Western Bank + status: active + allow_transaction_modifications: true + limit: + balance: "5498.2800" + currency: usd + balance_last_update: "2023-01-27T01:38:07.460Z" + import_start_date: "2023-01-01" + last_import: "2023-01-24T12:57:03.250Z" + last_fetch: "2023-01-28T01:38:11.862Z" + plaid_last_successful_update: "2023-01-27T01:38:11.862Z" + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Request Validation Failure + errors: + - errMsg: must NOT have additional properties + instancePath: /query + schemaPath: "#/properties/query/additionalProperties" + keyword: additionalProperties + params: + additionalProperty: foo + "401": + $ref: "#/components/responses/unauthorizedToken" + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + /plaid_accounts/{id}: + get: + tags: + - plaid_accounts + summary: Get a single account that is synced via Plaid + description: Retrieve the details of the plaid account with the specified ID. + operationId: getPlaidAccountById + parameters: + - name: id + in: path + description: ID of the plaid account to retrieve + required: true + schema: + type: integer + examples: + basic manual account: + summary: Basic plaid account by id request + value: 119805 + id not found: + summary: Example of an id that doesn't exist + value: 9999999999999 + responses: + "200": + description: Plaid Account Object with the requested account. + content: + application/json: + schema: + $ref: "#/components/schemas/plaidAccountObject" + example: + id: 119805 + date_linked: "2020-01-28" + name: Freedom + display_name: Penny's Visa + type: credit + subtype: credit card + mask: "1973" + institution_name: Chase + status: active + allow_transaction_modifications: true + limit: 15000 + balance: "0.0000" + currency: usd + balance_last_update: "2023-01-27T01:38:07.460Z" + import_start_date: "2023-01-01" + last_import: "2023-01-24T12:57:03.250Z" + last_fetch: "2023-01-28T01:38:11.862Z" + plaid_last_successful_update: "2023-01-27T01:38:11.862Z" + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Request Validation Failure + errors: + - errMsg: must be integer + instancePath: /path/id + schemaPath: "#/properties/path/properties/ids/items/type" + keyword: type + params: + type: integer + "401": + $ref: "#/components/responses/unauthorizedToken" + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Not Found + errors: + - errMsg: There is no manual account with the id:'9999999999999'` + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + /plaid_accounts/fetch: + post: + tags: + - plaid_accounts + summary: Trigger Fetch from Plaid + description: "Use this endpoint to trigger a fetch for latest data from Plaid.\n\nEligible accounts are those who last_fetch value is over 1 minute ago. (Although the limit is every minute, please use this endpoint sparingly!)\nNote that fetching from Plaid is a background job. This endpoint simply queues up the job. You may track the `plaid_last_successful_update`, `last_fetch` and `last_import` properties to verify the results of the fetch. The `last fetch` property is updated when Plaid accepts a request to fetch data. The `plaid_last_successful_update`is updated when it successfully contacts the associated financial institution. The `last_import` field is updated only when new transactions have been imported." + operationId: triggerPlaidAccountFetch + parameters: + - name: start_date + in: query + schema: + type: string + format: date + description: >- + Denotes the beginning of the time period to fetch transactions for. + If omitted, the most recent transactions will be returned.
+ Required if end_date exists.
+ - name: end_date + in: query + schema: + type: string + format: date + description: >- + Denotes the end of the time period you'd like to get transactions + for. Required if start_date exists. + - name: plaid_account_id + in: query + description: Specific ID of a plaid account to fetch. If not set the endpoint will trigger a fetch for all eligible accounts. + schema: + type: integer + examples: + basic manual account: + summary: Basic manual account by id request + value: 119807 + id not found: + summary: Example of an id that doesn't exist + value: 9999999999999 + responses: + "200": + description: A value of true is returned if Plaid acknowledged the fetch request. This indicates that it is possible that query the `GET /plaid_accounts` endpoint to determine if the request was successful (`plaid_last_successful_update` is more recent than `last_fetch), or if new transactions were synced (`last_import` is more recent than `last_fetch`).
If false is returned the request failed. This can occur if the requested account does not exist, if there are no Plaid accounts associated with the user, or if a request was already made within the last minute. + content: + application/json: + schema: + type: boolean + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Request Validation Failure + errors: + - errMsg: must be integer + instancePath: /path/id + schemaPath: "#/properties/path/properties/ids/items/type" + keyword: type + params: + type: integer + "401": + $ref: "#/components/responses/unauthorizedToken" + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Not Found + errors: + - errMsg: There is no manual account with the id:'9999999999999'` + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + /transactions: + get: + tags: + - transactions (bulk) + summary: Get all transactions + description: Retrieve a list of all transactions associated with a user's account.
If called with no parameters this endpoint will return up to 100 of the most recent transactions. + operationId: getAllTransactions + parameters: + - name: start_date + in: query + schema: + type: string + format: date + description: >- + Denotes the beginning of the time period to fetch transactions for. + If omitted, the most recent transactions will be returned. See `limit`. + Required if end_date exists.
+ - name: end_date + in: query + schema: + type: string + format: date + description: >- + Denotes the end of the time period you'd like to get transactions + for. Required if start_date exists. + - name: manual_account_id + in: query + schema: + type: integer + format: int64 + description: Filter transactions to those associated with specified manual account ID or set this to 0 to omit any transactions from manual accounts. Setting both this and `synched_account_id` to 0 will return transactions with no account. These are listed as "Cash Transactions" in the Lunch Money GUI. + examples: + euro travel card: + value: 219909 + no manual accounts: + value: 0 + - name: plaid_account_id + in: query + schema: + type: integer + format: int64 + description: Filter transactions to those associated with specified plaid account ID or set this to 0 to omit any transactions from plaid accounts. Setting both this and `manual_account_id` to 0 will return transactions with no account. These are listed as "Cash Transactions" in the Lunch Money GUI. + examples: + brokerage account: + value: 119807 + no synched accounts: + value: 0 + - name: recurring_id + in: query + schema: + type: integer + format: int64 + description: > + Filter transactions to those associated with specified Recurring + Item ID + examples: + paychecks: + value: 994069 + rent: + value: 994079 + - name: category_id + in: query + schema: + type: integer + format: int64 + description: Filter transactions to those associated with the specified category ID. Will also match category groups. + examples: + rent: + value: 83 + food category group: + value: 84 + - name: is_group + in: query + schema: + type: boolean + description: Filter by group (returns only grouped transactions if set to true) + - name: status + in: query + schema: + type: string + enum: + - reviewed + - unreviewed + - delete_pending + - pending + description: >- + Filter transactions to those with the specified status:
+ - `reviewed`: Only user reviewed transactions or those that were automatically marked as reviewed due to reviewed recurring_item logic
+ - `unreviewed`: Only transactions that need to be reviewed
+ - `delete_pending`: Only transactions that require manual intervention because the plaid account deleted this transaction after it was updated by the user.
+ - `pending`: Only pending transactions from synced accounts. Must also set `include_pending` to true. + examples: + needs review: + value: unreviewed + needs deletion: + value: delete_pending + - name: tag_id + in: query + schema: + type: integer + format: int64 + description: Filter transactions to those that have a tag with the specified Tag ID + - name: include_pending + in: query + schema: + type: boolean + default: false + description: >- + Pass in true if you’d like to include imported transactions with a + pending status. + - name: include_custom_metadata + in: query + schema: + type: boolean + default: false + description: >- + Pass in true if you’d like the returned transactions objects to include any custom + metadata that was previously added via the API. + - name: limit + in: query + schema: + type: integer + minimum: 1 + maximum: 1000 + default: 100 + description: Sets the maximum number of transactions to return. If more match the filter criteria, the response will include a `has_more` attribute set to `true`. See [pagination](foo) + - name: offset + in: query + schema: + type: integer + description: Sets the offset for the records returned. This is typically set automatically in the header. See [Pagination](/foo) + responses: + "200": + description: >- + Returns an array of transactions.

The `has_more` property + is set to `true` if more transactions are available. See + [Pagination](/foo) + content: + application/json: + schema: + properties: + transactions: + items: + $ref: "#/components/schemas/transactionObject" + type: array + has_more: + type: boolean + description: Set to true if more transactions are available + error: + type: string + required: + - transactions + - has_more + examples: + default response: + summary: Default response + value: + transactions: + - id: 2112150655 + date: "2024-07-28" + amount: "1250.8400" + currency: usd + to_base: 1250.84 + recurring_id: 994069 + overrides: + - original_payee: Penny Lane + payee: Paycheck + category_id: 88 + notes: + status: reviewed + is_pending: false + created_at: "2024-07-28T17:00:06.192Z" + updated_at: "2024-07-28T17:00:06.733Z" + is_parent: false + parent_id: + is_group: false + group_id: + manual_account_id: + plaid_account_id: 119806 + tag_ids: [94317] + source: plaid + external_id: + - id: 2112150655 + date: "2024-07-24" + amount: "21.9800" + currency: usd + to_base: 21.98 + recurring_id: + overrides: + payee: Noodle House + category_id: + notes: + status: unreviewed + is_pending: false + created_at: "2024-07-24T17:00:06.192Z" + updated_at: "2024-07-24T17:00:06.192Z" + is_parent: false + parent_id: + is_group: false + group_id: + manual_account_id: + plaid_account_id: 119805 + tag_ids: [94317] + source: plaid + external_id: + - id: 2112150653 + date: "2024-07-22" + amount: "-847.2200" + currency: usd + to_base: -847.22 + recurring_id: + overrides: + payee: Credit Card Payment + category_id: 82 + is_pending: false + status: reviewed + notes: + created_at: "2024-07-22T17:00:06.192Z" + updated_at: "2024-07-22T17:00:06.733Z" + original_name: Credit Card Payment + is_parent: false + parent_id: + is_group: false + group_id: + manual_account_id: + plaid_account_id: 119804 + tag_ids: [] + source: plaid + external_id: + - id: 2112150651 + date: "2024-07-22" + amount: "250.0000" + currency: usd + to_base: 250.0 + recurring_id: + overrides: + payee: Fidelity + category_id: 82 + notes: Transfer from Checking to Fidelity + status: reviewed + is_pending: false + created_at: "2024-07-22T17:00:06.192Z" + updated_at: "2024-07-22T17:00:06.733Z" + is_parent: false + parent_id: + is_group: false + group_id: + manual_account_id: 119807 + plaid_account_id: + tag_ids: [] + source: csv + external_id: + has_more: false + recurring paychecks: + summary: recurring paychecks + value: + transactions: + - id: 2112150655 + date: "2024-07-28" + amount: "1250.8400" + currency: usd + to_base: 1250.84 + recurring_id: 994069 + overrides: + - original_payee: Penny Lane + payee: Paycheck + category_id: 88 + notes: + status: reviewed + is_pending: false + created_at: "2024-07-28T17:00:06.192Z" + updated_at: "2024-07-28T17:00:06.733Z" + is_parent: false + parent_id: + is_group: false + group_id: + manual_account_id: + plaid_account_id: 119806 + tag_ids: [94317] + source: plaid + external_id: + - id: 2112150653 + date: "2024-07-14" + amount: "1250.8400" + currency: usd + to_base: 1250.84 + recurring_id: 994069 + overrides: + original_payee: Penny Lane + original_category_id: 82 + original_notes: Yippee! + payee: Paycheck + category_id: 88 + notes: + status: reviewed + is_pending: false + created_at: "2024-07-14T17:00:06.192Z" + updated_at: "2024-07-14T17:00:06.733Z" + is_parent: false + parent_id: + is_group: true + group_id: + manual_account_id: + plaid_account_id: 119806 + tag_ids: [94317] + source: plaid + external_id: + has_more: false + limit 2 - paginated response: + summary: Limit 2 paginated response + value: + transactions: + - id: 2112150655 + date: "2024-07-28" + amount: "1250.8400" + currency: usd + to_base: 1250.84 + recurring_id: 994069 + overrides: + - original_payee: Penny Lane + payee: Paycheck + category_id: 88 + notes: + status: reviewed + is_pending: false + created_at: "2024-07-28T17:00:06.192Z" + updated_at: "2024-07-28T17:00:06.733Z" + is_parent: false + parent_id: + is_group: false + group_id: + manual_account_id: + plaid_account_id: 119806 + tag_ids: [94317] + source: plaid + external_id: + - id: 2112150654 + date: "2024-07-24" + amount: "21.9800" + currency: usd + to_base: 21.98 + recurring_id: + overrides: + payee: Noodle House + category_id: + notes: + status: unreviewed + is_pending: false + created_at: "2024-07-24T17:00:06.192Z" + updated_at: "2024-07-24T17:00:06.192Z" + is_parent: false + parent_id: + is_group: false + group_id: + manual_account_id: + plaid_account_id: 119805 + tag_ids: [94317] + source: plaid + external_id: + has_more: true + "400": + description: Invalid request parameters + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Request Validation Failure + errors: + - errMsg: must be integer + instancePath: /query/category_id + schemaPath: "#/properties/query/properties/category_id/type" + keyword: type + params: + type: integer + "401": + $ref: "#/components/responses/unauthorizedToken" + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + post: + tags: + - transactions (bulk) + summary: Insert one or more transactions. + description: "Use this endpoint to add transactions to a budget.\n\nThe request body for this endpoint must include a list of transactions with at least one transaction and not more than 500 transactions to insert." + operationId: createNewTransactions + requestBody: + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + transactions: + type: array + maxLength: 500 + description: List of transactions to insert. + items: + $ref: "#/components/schemas/insertTransactionObject" + apply_rules: + type: boolean + default: false + description: If set to true, any rules associated with the account specified by the `manual_account_id` property for each transaction will be applied. + skip_duplicates: + type: boolean + default: false + description: If set to true, the system will flag new transactions that have the same `date`, `payee`, `amount`, and `manual_account_id`, as a duplicate. Not that deduplication based on `external_id` and `manual_account_id` will always occur regardless of how this property is set. + # debit_as_negative: + # type: boolean + # default: false + # description: If set to true, negative amount values will be interpreted as expenses and positive amount values will be interpreted as credits. + skip_balance_update: + type: boolean + default: false + description: If set to true, and new transactions include a `manual_account_id`, the balances of these accounts will not be updated, when the transactions are inserted. + required: + - transactions + examples: + categorized cash transaction: + value: + transactions: + - date: "2024-12-01" + amount: "42.89" + payee: Food Town + category_id: 315163 + status: reviewed + bare minimum new transaction: + value: + transactions: + - date: "2024-11-01" + amount: "99.9900" + two new cash transactions: + value: + transactions: + - date: "2024-11-01" + amount: "15.00" + payee: Lunch with James + notes: Cash Transaction + category_id: 315163 + - date: "2024-11-01" + amount: "-9.99" + payee: me + notes: Interest from Investment Account Cash + status: unreviewed + with external_id and custom_metadata: + value: + transactions: + - date: "2024-12-01" + amount: "19.99" + payee: Test Payee 3 + manual_account_id: 219807 + external_id: A658214 + notes: API Test created Transaction + custom_metadata: + note: API Test Added Custom MetaData + testNumber: 42 + testBool: false + testArray: + - 1 + - foo + - false + - 42.42 + testObject: + foo: bar + responses: + "201": + description: Transactions successfully inserted + content: + application/json: + schema: + properties: + transactions: + items: + $ref: "#/components/schemas/transactionObject" + type: array + skipped_existing_external_ids: + items: + $ref: "#/components/schemas/skippedExistingExternalIdObject" + type: array + required: + - transactions + examples: + categorized cash transaction: + value: + transactions: + - id: 123456789 + date: "2024-12-01" + amount: "42.89" + currency: usd + to_base: 42.89 + recurring_id: + overrides: {} + payee: Food Town + category_id: 315163 + notes: + status: reviewed + is_pending: false + created_at: "2024-12-18T04:05:58.072Z" + updated_at: "2024-12-18T04:05:58.072Z" + parent_id: + is_group: false + group_id: + manual_account_id: + plaid_account_id: + tag_ids: [] + source: api + external_id: + custom_metadata: {} + bare minimum request: + value: + transactions: + - id: 123456789 + date: "2024-11-01" + amount: "99.99" + currency: usd + to_base: 99.99 + recurring_id: + overrides: {} + payee: + category_id: + notes: + status: unreviewed + is_pending: false + created_at: "2024-11-20T16:09:11.544Z" + updated_at: "2024-11-20T16:09:11.544Z" + parent_id: + is_group: false + group_id: + manual_account_id: + plaid_account_id: + tag_ids: [] + source: api + external_id: + custom_metadata: {} + two new cash transactions: + value: + transactions: + - id: 123456789 + date: "2024-11-01" + amount: "15.00" + currency: usd + to_base: 15 + recurring_id: + overrides: {} + payee: Lunch with James + category_id: + notes: Cash Transaction + status: unreviewed + is_pending: false + created_at: "2024-11-20T16:10:23.395Z" + updated_at: "2024-11-20T16:10:23.395Z" + parent_id: + is_group: false + group_id: + manual_account_id: + plaid_account_id: + tag_ids: [] + source: api + external_id: + custom_metadata: {} + - id: 123456790 + date: "2024-11-01" + amount: "-9.99" + currency: usd + to_base: -9.99 + recurring_id: + overrides: {} + payee: me + category_id: + notes: Interest from Investment Account Cash + status: unreviewed + is_pending: false + created_at: "2024-11-20T16:10:23.395Z" + updated_at: "2024-11-20T16:10:23.395Z" + parent_id: + is_group: false + group_id: + manual_account_id: + plaid_account_id: + tag_ids: [] + source: api + external_id: + custom_metadata: {} + with external_id and custom_metadata: + value: + transactions: + - id: 123456789 + date: "2024-12-01" + amount: "19.99" + currency: usd + to_base: 19.99 + recurring_id: + overrides: {} + payee: Test Payee 3 + category_id: + notes: API Test created Transaction + status: unreviewed + is_pending: false + created_at: "2024-11-20T16:15:19.475Z" + updated_at: "2024-11-20T16:15:19.475Z" + parent_id: + is_group: false + group_id: + manual_account_id: 219807 + plaid_account_id: + tag_ids: [] + source: api + external_id: A658214 + custom_metadata: + note: API Test Added Custom MetaData + testNumber: 42 + testBool: false + testArray: + - 1 + - foo + - false + - 42.42 + testObject: + foo: bar + duplicate_external_ids_ignored: + value: + transactions: + - id: 123456789 + date: "2024-11-01" + amount: "-9.99" + currency: usd + to_base: -9.99 + recurring_id: + overrides: {} + payee: Test Payee 2 + category_id: + notes: API Test created Transaction + status: unreviewed + is_pending: false + created_at: "2024-11-20T16:24:20.028Z" + updated_at: "2024-11-20T16:24:20.028Z" + parent_id: + is_group: false + group_id: + manual_account_id: + plaid_account_id: + tag_ids: [] + source: api + external_id: + custom_metadata: {} + skipped_existing_external_ids: + - request_transaction_index: 0 + external_id: "12345" + manual_account_id: 219807 + existing_transaction_id: 2112150651 + - request_transaction_index: 2 + external_id: "67890" + manual_account_id: 219909 + existing_transaction_id: 2112150723 + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + examples: + invalid ids in new transactions: + value: + message: Invalid Request Body + errors: + - errMsg: "Transaction 0 manual account ID does not belong to your account. ID: 899999999999999" + transaction_index: 0 + error: Invalid Manual Account ID + invalid_property: manual_account_id + category_id: 899999999999999 + - errMsg: "Transaction 1 manual account ID does not belong to your account. ID: 999999999999999" + transaction_index: 1 + error: Invalid Manual Account ID + invalid_property: manual_account_id + category_id: 999999999999999 + - errMsg: "Transaction 2 recurring ID does not belong to your account. ID: 899999999999999" + transaction_index: 2 + error: Invalid Recurring ID + invalid_property: recurring_id + category_id: 899999999999999 + duplicate external_ids within request: + value: + message: Invalid Request Body + errors: + - errMsg: Duplicate External IDs found in the request body + error: Duplicate External ID + transaction_property: external_id + external_id: "12345" + transaction_indices: + - 0 + - 1 + - errMsg: Duplicate External IDs found in the request body + error: Duplicate External ID + transaction_property: external_id + external_id: "54321" + transaction_indices: + - 2 + - 3 + "401": + $ref: "#/components/responses/unauthorizedToken" + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + delete: + tags: + - transactions (bulk) + summary: Bulk delete existing transactions + description: "Deletes the transaction with the IDs specified in the request body.
\nIf any of the specified transactions are a split transaction or a split parent, or if any are a grouped transactions or part of a transaction group, the request will fail with a suggestion on how to unsplit or ungroup the transaction(s) prior to deletion. This will also fail if any of the specified transaction IDs do not exist.
\nOtherwise, the specified transactions are deleted. This action is not reversible!" + operationId: deleteTransactions + requestBody: + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + ids: + type: array + description: Array of existing Transaction IDs to delete + maxLength: 500 + items: + type: number + format: int64 + required: + - ids + examples: + delete three transactions: + value: + ids: + - 2112150653 + - 2112150654 + - 2112150655 + duplicate ids: + value: + ids: + - 2112150653 + - 2112150653 + - 2112150654 + - 2112150654 + invalid ids: + value: + ids: + - 2112150653 + - 9999999999 + - 2112150654 + + responses: + "204": + description: No Content + "400": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Invalid Request Body + errors: + - errMsg: Duplicate Transaction ID + transaction_id: 2112150653 + ids_indices: + - 0 + - 1 + - errMsg: Duplicate Transaction ID + transaction_id: 2112150654 + ids_indices: + - 2 + - 3 + "401": + $ref: "#/components/responses/unauthorizedToken" + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Invalid Request Body + errors: + - errMsg: Transaction ID Not Found + ids_index: 0 + transaction_id: 8888888888 + - errMsg: Transaction ID Not Found + ids_index: 1 + transaction_id: 9999999999 + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + /transactions/{id}: + get: + tags: + - transactions + summary: Get a single transaction + description: | + Retrieve details of a specific transaction by its ID.

+ + It the requested transaction is the parent of split transactions, the transaction + returned in the response will include a `children` property which will contain a list of the + split transactions.

+ + Similarly, if the requested transaction is transaction group, the transaction + returned in the response will include a `children` property which will contain a list of the + original transactions that make up the transaction group. + operationId: getTransactionById + parameters: + - name: id + in: path + description: ID of the transaction to retrieve + required: true + schema: + type: integer + examples: + basic transaction: + summary: Basic transaction by id request + value: 2112140359 + id not found: + summary: Example of an id that doesn't exist + value: 9999999999999 + - name: include_metadata + in: query + description: "Set to true to have the metadata objects associated with this transaction returned as part of the result.\nA `plaid_metatdata` object will always exist for transactions associated with an account that is synced via plaid. A `custom_metadata` object may exist for transactions that were inserted or updated via the API." + required: false + schema: + type: boolean + default: false + + responses: + "200": + description: Transaction Object with the requested transaction. + content: + application/json: + schema: + $ref: "#/components/schemas/transactionObject" + examples: + transaction: + value: + id: 2112150654 + date: "2024-07-24" + amount: "21.9800" + currency: usd + to_base: 21.98 + recurring_id: + overrides: + payee: Noodle House + category_id: + notes: + status: unreviewed + is_pending: false + created_at: "2024-07-24T17:00:06.192Z" + updated_at: "2024-07-24T17:00:06.192Z" + parent_id: + children: [] + is_group: false + group_id: + manual_account_id: + plaid_account_id: 119805 + tag_ids: [] + source: csv + external_id: + category group: + value: + id: 84 + name: Test Category Group + description: + is_income: true + exclude_from_budget: false + exclude_from_totals: true + updated_at: "2020-01-28T09:49:03.238Z" + created_at: "2020-01-28T09:49:03.238Z" + is_group: false + group_id: + order: 1 + archived: false + archived_at: + children: + - 315162 + - 315163 + - 315164 + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Request Validation Failure + errors: + - errMsg: must be integer + instancePath: /path/id + schemaPath: "#/properties/path/properties/id/type" + keyword: type + params: + type: integer + "401": + $ref: "#/components/responses/unauthorizedToken" + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Not Found + errors: + - errMsg: There is no transaction with the id:'543210'` + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + delete: + tags: + - transactions + summary: Delete a transaction + description: "Deletes the transaction with the ID specified on the path.
\nIf the specified transaction is a split transaction or a split parent, or if it is a grouped transactions or part of a transaction group, the request will fail with a suggestion on how to unsplit or ungroup the transaction(s) prior to deletion. Otherwise, the specified transaction is deleted.
\nThis action is not reversible!" + operationId: deleteTransactionById + parameters: + - in: path + name: id + description: ID of the transaction to delete + required: true + schema: + type: integer + examples: + delete transaction: + summary: Simple transaction delete + value: 2112140361 + delete split transaction: + value: 2112140459 + delete transaction group: + value: 2112140959 + id not found: + summary: Example of an id that doesn't exist + value: 543210 + responses: + "204": + description: No Content + "401": + $ref: "#/components/responses/unauthorizedToken" + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Not Found + errors: + - errMsg: There is no transaction with the id:'543210'` + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + /transactions/group: + post: + tags: + - transactions (group) + summary: Create a transaction group + description: | + Specify a set of existing transaction IDs to group together as a single grouped transaction. + The new transaction will have an amount equal to the sum of the grouped transaction amounts. If the + grouped transactions have different currencies, the new group transaction will be set in the user's + default currency.

+ After a transaction has been grouped the original transactions are no longer shown on the + transactions page or returned by a `GET /transactions` request. The newly created grouped + transaction is returned instead. + + To see the details of the original transactions that were used to create a transaction group, use the + `GET /transactions/{id}` endpoint, passing the ID of the grouped transaction. The grouped transactions will + be included in the `children` property of the transaction returned in the response + operationId: groupTransactions + requestBody: + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + ids: + type: array + maxLength: 500 + description: List of existing transaction IDs to group. Split and recurring transactions may not be grouped. Transactions that are already grouped must be ungrouped before being regrouped. + items: + type: integer + date: + type: string + format: date + description: Date for the new grouped transaction in ISO 8601 format. + payee: + type: string + description: | + The payee for the new grouped transaction. + minLength: 0 + maxLength: 140 + category_id: + type: integer + format: int64 + nullable: true + description: The ID of an existing category to assign to the grouped transaction. If not set and all the grouped transactions have the same category, the grouped transaction will inherit the category, otherwise the new transaction will have no category. + notes: + type: string + nullable: true + description: | + Notes for the grouped transaction. + minLength: 0 + maxLength: 350 + status: + type: string + description: If set must be either `reviewed` or `unreviewed`. If not set, defaults to `reviewed`. + enum: + - reviewed + - unreviewed + tag_ids: + type: array + description: A list of IDs for the tags associated with the grouped transaction. Each ID must match an existing tag associated with the user's account. If not set, no tags will be associated with the created transaction. + items: + type: integer + format: int64 + required: + - ids + - date + - payee + examples: + group inherits category: + value: + ids: + - 2112140365 + - 2112140361 + payee: Home Entertainment Transactions + date: "2024-12-10" + responses: + "201": + description: The new grouped parent transaction with populated children attribute + content: + application/json: + schema: + properties: + transactions: + items: + $ref: "#/components/schemas/transactionObject" + type: array + examples: + group inherits category: + value: + transactions: + - id: 123456789 + date: "2024-12-10" + amount: "375.0000" + currency: usd + to_base: 375 + recurring_id: + overrides: {} + payee: Home Entertainment Transactions + category_id: 315628 + notes: + status: reviewed + is_pending: false + created_at: "2024-12-18T14:45:03.366Z" + updated_at: "2024-12-18T14:45:03.366Z" + parent_id: + is_group: true + group_id: + manual_account_id: + plaid_account_id: + tag_ids: [] + source: api + external_id: + custom_metadata: {} + children: + - id: 2112140365 + date: "2024-11-10" + amount: "75.00" + currency: usd + to_base: 75 + recurring_id: + overrides: + payee: Target + category_id: 315628 + notes: Household items + status: reviewed + is_pending: false + created_at: "2024-11-10T17:00:06.192Z" + updated_at: "2024-11-10T17:00:06.733Z" + is_parent: false + parent_id: + is_group: false + group_id: 123456789 + manual_account_id: + plaid_account_id: 119809 + tag_ids: [] + source: plaid + external_id: + custom_metadata: + - id: 2112140361 + date: "2024-11-09" + amount: "300.00" + currency: usd + to_base: 300 + recurring_id: + overrides: + payee: Best Buy + category_id: 315628 + notes: Electronics + status: reviewed + is_pending: false + created_at: "2024-11-09T17:00:06.192Z" + updated_at: "2024-11-09T17:00:06.733Z" + is_parent: false + parent_id: + is_group: false + group_id: 123456789 + manual_account_id: + plaid_account_id: 119810 + tag_ids: [] + source: plaid + external_id: + custom_metadata: + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + examples: + bad math: + value: + message: Invalid Request Body + errors: + - errMsg: Sums of split transactions do not add up to the original transaction amount! + split recurring: + value: + message: Invalid Request Body + errors: + - errMsg: You cannot split a recurring transaction! + split group: + value: + message: Invalid Request Body + errors: + - errMsg: You cannot split a grouped transaction! + split split: + value: + message: Invalid Request Body + errors: + - errMsg: You cannot split an already split transaction!" + + "401": + $ref: "#/components/responses/unauthorizedToken" + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + /transactions/group/{id}: + delete: + tags: + - transactions (group) + summary: Delete a transaction group + description: "Deletes the transaction group with the ID specified on the path.
\nThe transactions within the group are not removed and will subsequently be treated as \"normal\" ungrouped transactions." + operationId: ungroupTransactions + parameters: + - in: path + name: id + description: ID of the transaction group to delete + required: true + schema: + type: integer + examples: + # TODO Update examples include non group + delete transaction group: + summary: Simple transaction group delete + value: 2112140959 + delete non group transaction: + summary: ID is not a transaction group + value: 2112150649 + id not found: + summary: Example of an id that doesn't exist + value: 543210 + responses: + "204": + description: No Content + "401": + $ref: "#/components/responses/unauthorizedToken" + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Not Found + errors: + - errMsg: "There is no transaction with the id: 543210" + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + /transactions/split/{id}: + post: + tags: + - transactions (split) + summary: Split a transaction + description: "Splits an existing transaction into a set of smaller child transactions.

After a transaction has been split the original transaction is no longer shown on the transactions page or returned by a `GET /transactions` request. The newly created child transactions are returned instead.\nTo see the details of the original parent transaction after it has been split use the `GET /transactions/{id}` endpoint, passing the value of the `parent_id` of one of the children." + operationId: splitTransaction + parameters: + - name: id + in: path + description: ID of the transaction to spit + required: true + schema: + type: integer + examples: + spit transaction: + summary: Basic transaction by id request + value: 2112150650 + already split transaction: + summary: Attempt to split a transaction that has already been split + value: 2112140459 + id not found: + summary: Example of an id that doesn't exist + value: 9999999999999 + requestBody: + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + child_transactions: + type: array + maxLength: 500 + description: List of child transactions to create. The sum of the `amounts` must match the split transaction amount. + items: + $ref: "#/components/schemas/splitTransactionObject" + required: + - child_transactions + examples: + split 88.45 Transaction: + value: + child_transactions: + - amount: 44.23 + payee: Food Town - Lenny + - amount: 44.22 + payee: Food Town - Penny + invalid math on 88.45 Transaction: + value: + child_transactions: + - amount: 1.50 + payee: Food Town - Lenny + - amount: 1.50 + payee: Food Town - Penny + responses: + "201": + description: The new split parent transaction with populated children attribute + content: + application/json: + schema: + properties: + transactions: + items: + $ref: "#/components/schemas/transactionObject" + type: array + examples: + split 88.45 Transaction: + value: + transactions: + - id: 2112150650 + date: "2024-10-19" + amount: "88.4500" + currency: usd + to_base: 88.45 + recurring_id: + overrides: + payee: Food Town + category_id: 315162 + notes: + status: reviewed + is_pending: false + created_at: "2024-10-19T17:00:06.192Z" + updated_at: "2024-11-30T22:25:53.232Z" + parent_id: + is_parent: true + is_group: false + group_id: + manual_account_id: + plaid_account_id: 119805 + tag_ids: [] + source: plaid + external_id: + children: + - id: 2112150750 + date: "2024-10-19" + amount: "44.2300" + currency: usd + to_base: 44.23 + recurring_id: + overrides: + payee: Food Town - Lenny + category_id: 315162 + notes: + status: reviewed + is_pending: false + created_at: "2024-11-30T22:25:53.232Z" + updated_at: "2024-11-30T22:25:53.232Z" + is_parent: false + parent_id: + is_group: false + group_id: + manual_account_id: + plaid_account_id: 119805 + tag_ids: [] + source: plaid + external_id: + - id: 2112150751 + date: "2024-10-19" + amount: "44.2200" + currency: usd + to_base: 44.22 + recurring_id: + overrides: + payee: Food Town - Penny + category_id: 315162 + notes: + status: reviewed + is_pending: false + created_at: "2024-11-30T22:25:53.232Z" + updated_at: "2024-11-30T22:25:53.232Z" + is_parent: false + parent_id: + is_group: false + group_id: + manual_account_id: + plaid_account_id: 119805 + tag_ids: [] + source: plaid + external_id: + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + examples: + bad math: + value: + message: Invalid Request Body + errors: + - errMsg: Sums of split transactions do not add up to the original transaction amount! + split recurring: + value: + message: Invalid Request Body + errors: + - errMsg: You cannot split a recurring transaction! + split group: + value: + message: Invalid Request Body + errors: + - errMsg: You cannot split a grouped transaction! + split split: + value: + message: Invalid Request Body + errors: + - errMsg: You cannot split an already split transaction!" + + "401": + $ref: "#/components/responses/unauthorizedToken" + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + delete: + tags: + - transactions (split) + summary: Unsplit a previously split transactions + description: "Deletes the split children of a previously split transactions and restores the parent transactions to the normal unsplit state.

\nUse the value of the `parent_id`property of a split transaction to specify the parent ID." + operationId: unsplitTransaction + parameters: + - in: path + name: id + description: ID of the previously split transaction to delete. + required: true + schema: + type: integer + examples: + # TODO Update examples include non group + unsplit a transaction: + value: 2112140459 + invalid parent id: + value: 2112140361 + id not found: + value: 543210 + responses: + "204": + description: No Content + "400": + # TODO Update example + description: Invalid request parameters + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Invalid Request Body + errors: + - errMsg: "parent_ids 0 transaction ID does not exist. ID: 2112140458" + error: Invalid Transaction ID + invalid_property: parent_ids + index: 0 + id: 2112140458 + "401": + $ref: "#/components/responses/unauthorizedToken" + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + /tags: + get: + tags: + - tags + summary: Get All Tags + description: Retrieve a list of all tags associated with the user's account. + operationId: getAllTags + responses: + "200": + description: A list of tags + content: + application/json: + schema: + type: object + properties: + tags: + type: array + items: + $ref: "#/components/schemas/tagObject" + example: + tags: + - id: 94317 + name: Penny's + description: For transactions not related to Lenny + updated_at: "2024-02-28T09:49:03.238Z" + created_at: "2024-01-28T09:49:03.238Z" + archived: false + archived_at: + - id: 94318 + name: Road Trip + description: "" + updated_at: "2024-02-28T09:50:03.238Z" + created_at: "2024-01-28T09:50:03.238Z" + archived: false + archived_at: + - id: 94319 + name: Date Night + description: "" + updated_at: "2024-02-28T09:59:03.238Z" + created_at: "2024-01-28T10:02:03.238Z" + archived: false + archived_at: + "400": + # TODO is there any circumstance that this would happen? + description: Invalid request parameters + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Request Validation Failure + errors: + - errMsg: must be equal to one of the allowed values + instancePath: /query/format + schemaPath: "#/properties/query/properties/format/enum" + keyword: enum + params: + allowedValues: + - flattened + - nested + "401": + $ref: "#/components/responses/unauthorizedToken" + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + post: + tags: + - tags + summary: Create a new tag + description: Creates a new tag with the given name + operationId: createTag + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/createTagRequestObject" + examples: + name only: + value: + name: API Created Tag with no description + with description: + value: + name: API Created Tag + description: Description of tag created via API + responses: + "201": + description: Tag Object with the successfully created tag + content: + application/json: + schema: + $ref: "#/components/schemas/tagObject" + examples: + name only: + value: + id: 94350 + name: API Created Tag with no description + description: + archived: false + with description: + value: + id: 94351 + name: API Created Tag + description: Description of tag created via API + archived: false + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Invalid Request Body + errors: + - errMsg: Tag with name 'New Tag' already exists + "401": + $ref: "#/components/responses/unauthorizedToken" + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + /tags/{id}: + get: + tags: + - tags + summary: Get a single tags + description: Retrieve the details of a specific tag with the specified ID. + operationId: getTagById + parameters: + - name: id + in: path + description: ID of the tag to retrieve + required: true + schema: + type: integer + examples: + tag: + summary: Example of a tags's id + value: 94319 + not found: + summary: Example of a tag id that does not exist + value: 543210 + responses: + "200": + description: Tag Object with the requested Tag ID + content: + application/json: + schema: + $ref: "#/components/schemas/tagObject" + example: + id: 94319 + name: Date Night + description: "" + updated_at: "2024-02-28T09:59:03.238Z" + created_at: "2024-01-28T10:02:03.238Z" + archived: false + archived_at: + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Request Validation Failure + errors: + - errMsg: must be a valid integer + instancePath: /query/ids/0 + schemaPath: "#/properties/query/properties/ids/items/type" + keyword: type + params: + type: integer + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Not Found + errors: + - errMsg: There is no tag with the id:'543210' + "401": + $ref: "#/components/responses/unauthorizedToken" + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + put: + tags: + - tags + summary: Update an existing tag + description: "Updates an existing tag.\n\nYou may submit the response from a `GET /tags/{id}` as the request body which includes system created attributes such as `id`, however only the `name`, `description`, and `archived`, can be updated using this API.\n\nIt is also possible to provide only the attribute(s) to be updated in the request body, as long as the request includes at least one of the attributes listed above. For example a request body that contains only a `name` attribute is valid." + operationId: updateTag + parameters: + - name: id + in: path + description: ID of the tag to update + required: true + schema: + type: integer + examples: + tag: + summary: Example of a tags's id + value: 94319 + not found: + summary: Example of a tag id that does not exist + value: 543210 + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/updateTagRequestObject" + examples: + Update tag name: + value: + name: Updated Tag Name + description: Updated description of the category + Update with full object: + value: + id: 94319 + name: Updated Tag Name + description: API Updated Description + archived: false + responses: + "200": + description: Category or Category Group updated successfully + content: + application/json: + schema: + $ref: "#/components/schemas/tagObject" + examples: + new name: + value: + id: 94319 + name: Updated Tag Name + description: + updated_at: "2024-02-28T09:59:03.238Z" + created_at: "2024-01-28T10:02:03.238Z" + archived: false + archived_at: + new name and description: + value: + id: 94319 + name: Updated Tag Name + description: API Updated Description + updated_at: "2024-02-28T09:59:03.238Z" + created_at: "2024-01-28T10:02:03.238Z" + archived: false + archived_at: + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Invalid Request Body + # TODO update this with a relevant message + errors: + - errMsg: Cannot modify the 'group_id' attribute of an existing category or category group + "401": + $ref: "#/components/responses/unauthorizedToken" + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Not Found + errors: + - errMsg: There is no tag with the id:'543210'` + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + delete: + tags: + - tags + summary: Delete a tag + description: "Deletes the tag with the ID specified on the path.
\nIf transaction or rules exist with the tag a dependents object is returned and the tag is not deleted. This behavior can be overridden by setting the `force` param to `true`." + operationId: deleteTag + parameters: + - in: path + name: id + description: ID of the tag to delete + required: true + schema: + type: integer + examples: + delete tag: + summary: Simple tag delete + value: 94319 + delete tag with dependents: + summary: Tag request with dependents + value: 94317 + id not found: + summary: Example of an id that doesn't exist + value: 543210 + - in: query + name: force + description: Set to true to force deletion even if there are dependencies + required: false + schema: + type: boolean + default: false + responses: + "204": + description: No Content + "422": + description: Unprocessable Entity + content: + application/json: + schema: + $ref: "#/components/schemas/deleteTagResponseWithDependencies" + example: + tag_name: Tag to be Deleted + dependents: + rules: 1 + transactions: 10 + "401": + $ref: "#/components/responses/unauthorizedToken" + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Not Found + errors: + - errMsg: There is no tag with the id:'543210'` + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + /recurring: + get: + tags: + - recurring + summary: Get a all recurring items + description: Get info about the recurring items for a specified time frame + operationId: getAllRecurring + parameters: + - name: start_date + in: query + schema: + type: string + format: date + description: >- + Denotes the beginning of the range used to populate the `matching` object in the + recurring items. If omitted, the current month will be used as the range.
+ Required if end_date exists. + - name: end_date + in: query + schema: + type: string + format: date + description: >- + Denotes the end of the the range used to populate the `matching` object in the + recurring items. Required if start_date exists. + - name: include_suggested + in: query + schema: + type: boolean + description: When set to true will include recurring items that have been suggested by the system, but have not been reviewed and are not actively updating transactions. + responses: + "200": + description: A list of recurring items + content: + application/json: + schema: + type: object + properties: + recurring_items: + type: array + items: + $ref: "#/components/schemas/recurringObject" + example: + recurring: + - id: 994069 + description: Income + status: reviewed + transaction_criteria: + start_date: "2024-09-01" + end_date: "2024-10-31" + anchor_date: "2024-09-14" + granularity: month + quantity: 1 + payee: Penny Lane + amount: "1250.8400" + currency: usd + to_base: 1250.84 + plaid_account_id: 119806 + manual_account_id: + overrides: + payee: Paycheck + category_id: 88 + matches: + request_start_date: "2024-10-01" + request_end_date: "2024-10-31" + expected_occurrence_dates: + - "2024-10-14" + - "2024-10-28" + found_transactions: + - date: "2024-10-14" + transaction_id: 2212150658 + missing_transaction_dates: + - "2024-10-28" + created_by: 18328 + created_at: "2024-07-28T01:01:38.716Z" + updated_at: "2024-07-28T01:01:38.716Z" + source: manual + - id: 994079 + description: Monthly rent payable to Mrs Smith + status: reviewed + transaction_criteria: + start_date: "2024-09-01" + end_date: "2024-10-31" + anchor_date: "2024-09-01" + granularity: month + quantity: 1 + payee: + amount: "850.0000" + currency: usd + to_base: 850 + plaid_account_id: 119806 + manual_account_id: + overrides: + payee: Rent + notes: Monthly rent payable to Mrs Smith + category_id: 83 + matches: + request_start_date: "2024-10-01" + request_end_date: "2024-10-31" + expected_occurrence_dates: + - "2024-10-01" + found_transactions: + - date: "2024-10-01" + transaction_id: 2212150656 + missing_transaction_dates: [] + created_by: 18328 + created_at: "2024-06-28T01:01:38.195Z" + updated_at: "2024-06-28T01:01:38.195Z" + source: manual + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Request Validation Failure + errors: + - errMsg: must be a valid integer + instancePath: /query/ids/0 + schemaPath: "#/properties/query/properties/ids/items/type" + keyword: type + params: + type: integer + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Not Found + errors: + - errMsg: There is no tag with the id:'543210' + "401": + $ref: "#/components/responses/unauthorizedToken" + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + /recurring/{id}: + get: + tags: + - recurring + summary: Get a single recurring item + description: Retrieve the details of a specific recurring item with the specified ID. + operationId: getRecurringById + parameters: + - name: id + in: path + description: ID of the recurring item to retrieve + required: true + schema: + type: integer + examples: + tag: + summary: Example of a recurring ID + value: 994069 + not found: + summary: Example of a recurring ID that does not exist + value: 543210 + - name: start_date + in: query + schema: + type: string + format: date + description: >- + Denotes the beginning of the range used to populate the `matching` object in the + recurring items. If omitted, the current month will be used as the range.
+ Required if end_date exists. + - name: end_date + in: query + schema: + type: string + format: date + description: >- + Denotes the end of the the range used to populate the `matching` object in the + recurring items. Required if start_date exists. + responses: + "200": + description: Tag Object with the requested Tag ID + content: + application/json: + schema: + $ref: "#/components/schemas/recurringObject" + example: + id: 994069 + description: Income + status: reviewed + transaction_criteria: + start_date: "2024-09-01" + end_date: "2024-10-31" + anchor_date: "2024-09-14" + granularity: month + quantity: 1 + payee: Penny Lane + amount: "1250.8400" + currency: usd + to_base: 1250.84 + plaid_account_id: 119806 + manual_account_id: + overrides: + payee: Paycheck + category_id: 88 + matches: + request_start_date: "2024-10-01" + request_end_date: "2024-10-31" + expected_occurrence_dates: + - "2024-10-14" + - "2024-10-28" + found_transactions: + - date: "2024-10-14" + transaction_id: 2212150658 + missing_transaction_dates: + - "2024-10-28" + created_by: 18328 + created_at: "2024-07-28T01:01:38.716Z" + updated_at: "2024-07-28T01:01:38.716Z" + source: manual + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Request Validation Failure + errors: + - errMsg: must be a valid integer + instancePath: /query/ids/0 + schemaPath: "#/properties/query/properties/ids/items/type" + keyword: type + params: + type: integer + "404": + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/errorResponseObject" + example: + message: Not Found + errors: + - errMsg: There is no tag with the id:'543210' + "401": + $ref: "#/components/responses/unauthorizedToken" + "429": + $ref: "#/components/responses/rateLimited" + "500": + $ref: "#/components/responses/serverError" + +security: + - bearerSecurity: [] + - cookieAuth: []