### Example 200 Response - Get All Assets Source: https://lunchmoney.dev/ An example of a successful response when retrieving all assets. It includes a list of asset objects, each with detailed financial information. ```json { "assets": [ { "id": 72, "type_name": "cash", "subtype_name": "physical cash", "name": "Test Asset 1", "balance": "1201.0100", "to_base": 1020.85, "balance_as_of": "2020-01-26T12:27:22.000Z", "currency": "cad", "institution_name": "Bank of Me", "exclude_transactions": false, "created_at": "2020-01-26T12:27:22.726Z" }, { "id": 73, "type_name": "credit", "subtype_name": "credit card", "name": "Test Asset 2", "balance": "0.0000", "to_base": 0, "balance_as_of": "2020-01-26T12:27:22.000Z", "currency": "usd", "institution_name": "Bank of You", "exclude_transactions": false, "created_at": "2020-01-26T12:27:22.744Z" }, { "id": 74, "type_name": "vehicle", "subtype_name": "automobile", "name": "Test Asset 3", "balance": "99999999999.0000", "to_base": 657179189.99, "balance_as_of": "2020-01-26T12:27:22.000Z", "currency": "jpy", "institution_name": "Bank of Mom", "exclude_transactions": false, "created_at": "2020-01-26T12:27:22.755Z" }, { "id": 75, "type_name": "loan", "subtype_name": null, "name": "Test Asset 4", "balance": "10101010101.0000", "to_base": 307687460.61, "balance_as_of": "2020-01-26T12:27:22.000Z", "currency": "twd", "institution_name": null, "exclude_transactions": true, "created_at": "2020-01-26T12:27:22.765Z" } ] } ``` -------------------------------- ### Get Budget Summary - Example Response Source: https://lunchmoney.dev/ This JSON object represents a successful response from the GET /budgets endpoint. It provides a breakdown of spending and budget amounts for various categories, aggregated monthly. Note that categories without explicit budget configurations will still appear if they have associated transactions, with null values for budget-related fields. ```json [ { "category_name": "Food", "category_id": 34476, "category_group_name": null, "group_id": null, "is_group": true, "is_income": false, "exclude_from_budget": false, "exclude_from_totals": false, "data": { "2020-09-01": { "num_transactions": 23, "spending_to_base": 373.51, "budget_to_base": 376.08, "budget_amount": 376.08, "budget_currency": "usd", "is_automated": true, }, "2020-08-01": { "num_transactions": 23, "spending_to_base": 123.92, "budget_to_base": 300, "budget_amount": 300, "budget_currency": "usd", }, "2020-07-01": { "num_transactions": 23, "spending_to_base": 228.66, "budget_to_base": 300, "budget_amount": 300, "budget_currency": "usd", } }, "config": { "config_id": 9, "cadence": "monthly", "amount": 300, "currency": "usd", "to_base": 300, "auto_suggest": "fixed-rollover" }, "order": 0, "archived": false, "recurring": null }, { "category_name": "Alcohol & Bars", "category_id": 26, "category_group_name": "Food", "group_id": 34476, "is_group": null, "is_income": false, "exclude_from_budget": false, "exclude_from_totals": false, "data": { "2020-09-01": { "spending_to_base": 270.86, "num_transactions": 14 }, "2020-08-01": { "spending_to_base": 79.53, "num_transactions": 8 }, "2020-07-01": { "spending_to_base": 149.61, "num_transactions": 8 } }, "config": null, "archived": false, "order": 1, "recurring": { "list": [ { "payee": "Recurring Payee", "amount": "20.000", "currency": "cad", "to_base": 20 } ] } }, { "category_name": "Unbudgeted Category", "category_id": 12345, "category_group_name": null, "group_id": null, "is_group": false, "is_income": false, "exclude_from_budget": false, "exclude_from_totals": false, "data": { "2020-09-01": { "spending_to_base": 50.00, "num_transactions": 1, "budget_to_base": null, "budget_amount": null, "budget_currency": null } }, "config": null, "order": 2, "archived": false, "recurring": null } ] ``` -------------------------------- ### Get All Transactions - Example 404 Response Source: https://lunchmoney.dev/ This is an example of an error response (404 Not Found) when the required query parameters are missing. The response body contains an error message indicating the issue. ```json { "error": "Both start_date and end_date must be specified." } ``` -------------------------------- ### Get All Tags - GET Request Example Source: https://lunchmoney.dev/ Illustrates how to retrieve a list of all tags associated with a user's account. The response includes tag ID, name, description, and an archived status. This endpoint does not require any parameters. ```json [ { "id": 1807, "name": "Wedding", "description": "All wedding-related expenses", "archived": false }, { "id": 1808, "name": "Honeymoon", "description": "All honeymoon-related expenses", "archived": true } ] ``` -------------------------------- ### Example 200 Response - Update Asset Source: https://lunchmoney.dev/ An example of a successful response after updating an asset. It returns the updated details of the asset. ```json { "id": 12, "type_name": "cash", "subtype_name": "savings", "name": "TD Savings Account", "balance": "28658.5300", "to_base": 20061.34, "balance_as_of": "2020-03-10T05:17:23.856Z", "currency": "cad", "institution_name": "TD Bank", "exclude_transactions": false, "created_at": "2019-08-10T22:46:19.486Z" } ``` -------------------------------- ### Example 200 Response - Create Asset Source: https://lunchmoney.dev/ An example of a successful response after creating a new asset. It returns the details of the newly created asset, including its ID and properties. ```json { "id": 34061, "type_name": "depository", "subtype_name": null, "name": "My Test Asset", "display_name": null, "balance": "67.2100", "to_base": 47.05, "balance_as_of": "2022-05-29T21:35:36.557Z", "closed_on": null, "created_at": "2022-05-29T21:35:36.564Z", "currency": "cad", "institution_name": null, "exclude_transactions": false } ``` -------------------------------- ### Upsert Budget - Example JSON Body Source: https://lunchmoney.dev/ Example JSON payload for the Upsert Budget endpoint. It includes category_id, amount, currency, and start_date for the budget. ```JSON { "category_group": { "category_id": 34476, "amount": 100, "currency": "usd", "start_date": "2021-06-01" } } ``` -------------------------------- ### Get All Transactions - Example 200 Response Source: https://lunchmoney.dev/ This is an example of a successful response (200 OK) when retrieving transactions. It returns a JSON object containing a list of transaction objects and a boolean indicating if more transactions are available. ```json { "transactions": [ { "id": 246946944, "date": "2023-07-18", "amount": "53.1900", "currency": "usd", "to_base": 53.19, "payee": "Amazon", "category_id": 315172, "category_name": "Restaurants", "category_group_id": 315358, "category_group_name": "Food & Drink", "is_income": false, "exclude_from_budget": false, "exclude_from_totals": false, "created_at": "2023-09-09T08:43:05.875Z", "updated_at": "2023-10-09T06:07:03.105Z", "status": "cleared", "is_pending": false, "notes": null, "original_name": null, "recurring_id": null, "recurring_payee": null, "recurring_description": null, "recurring_cadence": null, "recurring_type": null, "recurring_amount": null, "recurring_currency": null, "parent_id": 225508713, "has_children": false, "group_id": null, "is_group": false, "asset_id": null, "asset_institution_name": null, "asset_name": null, "asset_display_name": null, "asset_status": null, "plaid_account_id": 76602, "plaid_account_name": "Amazon Whole Foods Visa", "plaid_account_mask": "6299", "institution_name": "Chase", "plaid_account_display_name": "Amazon Whole Foods Visa", "plaid_metadata": null, "plaid_category": null, "source": null, "display_name": "Amazon", "display_notes": null, "account_display_name": "Amazon Whole Foods Visa", "tags": [ { "name": "Amazon", "id": 76543 } ], "external_id": null }, { "id": 246946943, "date": "2023-07-18", "amount": "12.2100", "currency": "usd", "to_base": 12.21, "payee": "Frelard Tamales", "category_id": 315172, "category_name": "Restaurants", "category_group_id": 315358, "category_group_name": "Food & Drink", "is_income": false, "exclude_from_budget": false, "exclude_from_totals": false, "created_at": "2023-09-09T08:43:05.818Z", "updated_at": "2023-10-09T06:07:03.529Z", "status": "cleared", "is_pending": false, "notes": null, "original_name": null, "recurring_id": null, "recurring_payee": null, "recurring_description": null, "recurring_cadence": null, "recurring_type": null, "recurring_amount": null, "recurring_currency": null, "parent_id": 225588844, "has_children": false, "group_id": null, "is_group": true, "asset_id": null, "asset_institution_name": null, "asset_name": null, "asset_display_name": null, "asset_status": null, "plaid_account_id": 54174, "plaid_account_name": "Amex -11005", "plaid_account_mask": "1005", "institution_name": "American Express", "plaid_account_display_name": "Amex Plat", "plaid_metadata": null, "plaid_category": null, "source": null, "display_name": "Frelard Tamales", "display_notes": null, "account_display_name": "Amex Plat", "tags": [], "children": [ { "id": 246946948, "payee": "Child Transaction One", "amount": "-33.6000", "currency": "cad", "date": "2023-08-10", "formatted_date": "2023-09-10", "notes": null, "asset_id": 7409, "plaid_account_id": null, "to_base": -33.6 }, { "id": 246946948, "payee": "Child Transaction Two", "amount": "-33.6000", "currency": "cad", "date": "2023-08-10", "formatted_date": "2023-09-10", "notes": null, "asset_id": 7409, "plaid_account_id": null, "to_base": -33.6 } ], "external_id": null } ], "has_more": true } ``` -------------------------------- ### Get Budget Summary - HTTP Request Source: https://lunchmoney.dev/ This demonstrates the HTTP GET request to the /budgets endpoint. It requires 'start_date' and 'end_date' query parameters to define the budget period. An optional 'currency' parameter can be used to filter results by a specific currency. ```http GET https://dev.lunchmoney.app/v1/budgets?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD¤cy=usd ``` -------------------------------- ### Remove Budget - Example Error Response Source: https://lunchmoney.dev/ An example of an error response from the Remove Budget endpoint, indicating an invalid date format. ```JSON { "error": "start_date must be a valid date in format YYYY-MM-01" } ``` -------------------------------- ### Upsert Budget - Example Error Response Source: https://lunchmoney.dev/ An example of an error response that might be returned by the Upsert Budget endpoint, indicating a validation issue with the budget amount. ```JSON { "error": "Budget must be greater than or equal to the sum of sub-category budgets ($10.01)." } ``` -------------------------------- ### Example Error Response - Update Asset Source: https://lunchmoney.dev/ An example of an error response when attempting to update an asset with invalid data. The response indicates the specific validation errors encountered. ```json { "errors": [ "type_name must be one of: cash, credit, investment, other, real estate, loan, vehicle, cryptocurrency, employee compensation" ] } ``` -------------------------------- ### Get All Assets Source: https://lunchmoney.dev/ Retrieves a list of all manually-managed assets associated with the user's account. ```APIDOC ## Get All Assets ### Description Use this endpoint to get a list of all manually-managed assets associated with the user’s account. ### Method GET ### Endpoint https://dev.lunchmoney.app/v1/assets ### Response #### Success Response (200) - **assets** (array) - A list of asset objects. - **id** (integer) - Unique identifier for the asset. - **type_name** (string) - The type of the asset (e.g., "cash", "credit"). - **subtype_name** (string) - The subtype of the asset (e.g., "physical cash", "credit card"). - **name** (string) - The name of the asset. - **balance** (string) - The current balance of the asset. - **to_base** (float) - The balance converted to the user's base currency. - **balance_as_of** (string) - The timestamp when the balance was recorded (ISO 8601 format). - **currency** (string) - The three-letter ISO 4217 currency code. - **institution_name** (string) - The name of the institution holding the asset. - **exclude_transactions** (boolean) - Whether transactions for this asset are excluded from certain views. - **created_at** (string) - The timestamp when the asset was created (ISO 8601 format). ### Response Example ```json { "assets": [ { "id": 72, "type_name": "cash", "subtype_name": "physical cash", "name": "Test Asset 1", "balance": "1201.0100", "to_base": 1020.85, "balance_as_of": "2020-01-26T12:27:22.000Z", "currency": "cad", "institution_name": "Bank of Me", "exclude_transactions": false, "created_at": "2020-01-26T12:27:22.726Z" } ] } ``` ``` -------------------------------- ### Example 200 Response for Single Transaction Source: https://lunchmoney.dev/ This is an example of a successful response (HTTP 200) when retrieving a single transaction. It includes all the details of the transaction, such as ID, date, amount, payee, category, and associated Plaid information. ```JSON { "id": 480887173, "date": "2023-11-29", "amount": "-14.1800", "currency": "usd", "to_base": -14.18, "payee": "Walmart", "category_id": 315295, "category_name": "Health, Medical", "category_group_id": 315357, "category_group_name": "Personal", "is_income": false, "exclude_from_budget": false, "exclude_from_totals": false, "created_at": "2023-11-30T22:10:57.820Z", "updated_at": "2023-11-30T23:59:56.587Z", "status": "cleared", "is_pending": false, "notes": null, "original_name": "Walmart", "recurring_id": null, "recurring_payee": null, "recurring_description": null, "recurring_cadence": null, "recurring_type": null, "recurring_amount": null, "recurring_currency": null, "parent_id": null, "has_children": null, "group_id": 481307164, "is_group": false, "asset_id": null, "asset_institution_name": null, "asset_name": null, "asset_display_name": null, "asset_status": null, "plaid_account_id": 54174, "plaid_account_name": "Amex 1002", "plaid_account_mask": "1005", "institution_name": "American Express", "plaid_account_display_name": "Amex Plat", "plaid_metadata": "{\"account_id\":\"fMKfypkyRXSXvpJor4vPTg6OP7wD4afmEjv6N\",\"account_owner\":\"1005\",\"amount\":-14.18,\"authorized_date\":\"2023-11-28\",\"authorized_datetime\":null,\"category\":[\"Shops\",\"Supermarkets and Groceries\"],\"category_id\":\"19047000\",\"check_number\":null,\"counterparties\":[{\"confidence_level\":\"VERY_HIGH\",\"entity_id\":\"O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM\",\"logo_url\":\"https://plaid-merchant-logos.plaid.com/walmart_1100.png\",\"name\":\"Walmart\",\"type\":\"merchant\",\"website\":\"walmart.com\"}],\"date\":\"2023-11-29\",\"datetime\":null,\"iso_currency_code\":\"USD\",\"location\":{\"address\":null,\"city\":null,\"country\":null,\"lat\":null,\"lon\":null,\"postal_code\":null,\"region\":null,\"store_number\":null},\"logo_url\":\"https://plaid-merchant-logos.plaid.com/walmart_1100.png\",\"merchant_entity_id\":\"O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM\",\"merchant_name\":\"Walmart\",\"name\":\"Walmart\",\"payment_channel\":\"other\",\"payment_meta\":{\"by_order_of\":null,\"payee\":null,\"payer\":null,\"payment_method\":null,\"payment_processor\":null,\"ppd_id\":null,\"reason\":null,\"reference_number\":\"320233330735688096\"},\"pending\":false,\"pending_transaction_id\":null,\"personal_finance_category\":{\"confidence_level\":\"VERY_HIGH\",\"detailed\":\"GENERAL_MERCHANDISE_SUPERSTORES\",\"primary\":\"GENERAL_MERCHANDISE\"},\"personal_finance_category_icon_url\":\"https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png\",\"transaction_code\":null,\"transaction_id\":\"rmQdnefvAndbfHN5mZ4y703C3vdjk7mozCw1OarL\",\"transaction_type\":\"place\",\"unofficial_currency_code\":null,\"website\":\"walmart.com\"}", "plaid_category": "GENERAL_MERCHANDISE_SUPERSTORES", "source": "plaid", "display_name": "Walmart", "display_notes": null, "account_display_name": "Amex Plat", "tags": [], "external_id": null } ``` -------------------------------- ### Get All Assets - HTTP Request Source: https://lunchmoney.dev/ Retrieves a list of all manually-managed assets associated with the user's account. This endpoint is useful for getting an overview of all financial assets. ```http GET https://dev.lunchmoney.app/v1/assets ``` -------------------------------- ### Example Recurring Items Response (JSON) Source: https://lunchmoney.dev/ This JSON object represents a successful response from the 'Get Recurring Items' endpoint. It details a recurring weekly income item, including its occurrences, associated transactions within a range, and missing dates. ```json [ { "id": 940537, "start_date": null, "end_date": null, "payee": "Weekly Income", "currency": "usd", "created_at": "2024-05-27T12:48:33.777Z", "updated_at": "2024-05-27T12:48:33.777Z", "billing_date": "2024-05-01", "original_name": null, "description": null, "plaid_account_id": null, "asset_id": null, "source": "manual", "amount": "-200.0000", "notes": null, "category_id": 911979, "category_group_id": null, "is_income": true, "exclude_from_totals": false, "granularity": "weeks", "quantity": 1, "occurrences": { "2024-05-29": [ { "id": 2178542342, "date": "2024-05-29", "amount": "-200", "currency": "usd", "payee": "Weekly Income", "category_id": 911979, "recurring_id": 940537, "to_base": -200 } ], "2024-06-05": [ { "id": 2178538493, "date": "2024-06-05", "amount": "-200", "currency": "usd", "payee": "Weekly Income", "category_id": 911979, "recurring_id": 940537, "to_base": -200 } ], "2024-06-12": [], "2024-06-19": [], "2024-06-26": [], "2024-07-03": [] }, "transactions_within_range": [ { "id": 2178538493, "date": "2024-06-05", "amount": "-200", "currency": "usd", "payee": "Weekly Income", "category_id": 911979, "recurring_id": 940537, "to_base": -200 } ], "missing_dates_within_range": [ "2024-06-12", "2024-06-19", "2024-06-26" ], "date": "2024-06-04", "to_base": -200 }, { "id": 838965, "start_date": null, "end_date": null, "payee": "Google Fi", "currency": "usd", "created_at": "2024-04-05T20:02:22.698Z", "updated_at": "2024-04-05T20:02:22.698Z", "billing_date": "2024-01-25", "original_name": null, "description": "Cell phone plan", "plaid_account_id": null, "asset_id": 109419, "source": "manual", "amount": "50.0000", "notes": null, "category_id": 911972, "category_group_id": null, "is_income": false, "exclude_from_totals": false, "granularity": "months", "quantity": 1, "occurrences": { "2024-05-25": [ { "id": 21781233, "date": "2024-05-25", "amount": "50.0000", "currency": "usd", "payee": "Google Fi", "category_id": 911972, "recurring_id": 838965, "to_base": 50 } ], "2024-06-25": [], "2024-07-25": [] }, "transactions_within_range": [], "missing_dates_within_range": [ "2024-06-25" ], "date": "2024-06-04", "to_base": 50 }, { "id": 838963, "start_date": null, "end_date": null, "payee": "Geico", "currency": "usd", "created_at": "2024-04-05T20:02:22.244Z", "updated_at": "2024-04-05T20:02:22.244Z" } ] ``` -------------------------------- ### Get All Tags Source: https://lunchmoney.dev/ Retrieves a list of all tags associated with the user's account. ```APIDOC ## Get All Tags ### Description Use this endpoint to get a list of all tags associated with the user’s account. ### Method GET ### Endpoint `https://dev.lunchmoney.app/v1/tags` ### Response #### Success Response (200) An array of tag objects. - **id** (number) - Unique identifier for the tag. - **name** (string) - User-defined name of the tag. - **description** (string) - User-defined description of the tag. - **archived** (boolean) - If true, the tag will not show up when creating or updating transactions. #### Response Example ```json [ { "id": 1807, "name": "Wedding", "description": "All wedding-related expenses", "archived": false }, { "id": 1808, "name": "Honeymoon", "description": "All honeymoon-related expenses", "archived": true } ] ``` ``` -------------------------------- ### Get All Transactions - HTTP Request Source: https://lunchmoney.dev/ This snippet demonstrates how to make an HTTP GET request to retrieve all transactions. It specifies the base URL and the endpoint for transactions. Optional query parameters like start_date and end_date can be added to filter results. ```http GET https://dev.lunchmoney.app/v1/transactions ``` -------------------------------- ### Handle Recurring Expenses API Error Source: https://lunchmoney.dev/ Example of a 404 error response returned when an invalid start_date parameter is provided to the API. ```json { "error": "Invalid start_date. Must be in format YYYY-MM-DD" } ``` -------------------------------- ### Example 404 Response for Single Transaction Source: https://lunchmoney.dev/ This is an example of an error response (HTTP 404) when a requested transaction ID is not found in the system. It indicates that the specified transaction could not be retrieved. ```JSON { "error": "Transaction ID not found." } ``` -------------------------------- ### GET /v1/me Source: https://lunchmoney.dev/ Retrieves the details of the currently authenticated user, including their account information and settings. ```APIDOC ## GET /v1/me ### Description Use this endpoint to get details on the current user. ### Method GET ### Endpoint https://dev.lunchmoney.app/v1/me ### Response #### Success Response (200) - **user_id** (number) - Unique identifier for user - **user_name** (string) - User's name - **user_email** (string) - User's email - **account_id** (number) - Unique identifier for the associated budgeting account - **budget_name** (string) - Name of the associated budgeting account - **primary_currency** (string) - Primary currency from user's settings - **api_key_label** (string) - User-defined label of the developer API key used #### Response Example { "user_name": "User 1", "user_email": "user-1@lunchmoney.dev", "user_id": 18328, "account_id": 18221, "budget_name": "🏠 Family budget", "primary_currency": "usd", "api_key_label": "Side project dev key" } ``` -------------------------------- ### Get All Crypto Assets Source: https://lunchmoney.dev/ Retrieves a list of all cryptocurrency assets associated with the user's account, including both synced and manual crypto balances. ```APIDOC ## Get All Crypto ### Description Use this endpoint to get a list of all cryptocurrency assets associated with the user’s account. Both crypto balances from synced and manual accounts will be returned. ### Method GET ### Endpoint https://dev.lunchmoney.app/v1/crypto ### Response #### Success Response (200) - **crypto** (array) - A list of cryptocurrency assets. - **zabo_account_id** (integer) - The Zabo account ID for synced assets. - **source** (string) - The source of the crypto asset (e.g., "synced", "manual"). - **created_at** (string) - Timestamp of when the asset was created. - **name** (string) - The name of the cryptocurrency. - **display_name** (string) - A custom display name for the asset. - **balance** (string) - The current balance of the cryptocurrency. - **balance_as_of** (string) - Timestamp of when the balance was last updated. - **currency** (string) - The currency symbol of the cryptocurrency (e.g., "doge", "ETH"). - **status** (string) - The status of the asset (e.g., "active"). - **institution_name** (string) - The name of the institution or wallet holding the asset. - **id** (integer) - The unique identifier for manual assets. ### Response Example ```json { "crypto": [ { "zabo_account_id": 544, "source": "synced", "created_at": "2020-07-27T11:53:02.722Z", "name": "Dogecoin", "display_name": null, "balance": "1.902383849000000000", "balance_as_of": "2021-05-21T00:05:36.000Z", "currency": "doge", "status": "active", "institution_name": "MetaMask" }, { "id": 152, "source": "manual", "created_at": "2021-04-03T04:16:48.230Z", "name": "Ether", "display_name": "BlockFi - ETH", "balance": "5.391445130000000000", "balance_as_of": "2021-05-20T16:57:00.000Z", "currency": "ETH", "status": "active", "institution_name": "BlockFi" } ] } ``` ``` -------------------------------- ### Remove Budget - Example Success Response Source: https://lunchmoney.dev/ A successful response from the Remove Budget endpoint, typically returning a boolean true. ```JSON true ``` -------------------------------- ### Get All Categories Source: https://lunchmoney.dev/ Retrieves a flattened list of all categories associated with the user's account. Categories are returned in alphabetical order. ```APIDOC ## GET /v1/categories ### Description Use this endpoint to get a flattened list of all categories in alphabetical order associated with the user’s account. ### Method GET ### Endpoint https://dev.lunchmoney.app/v1/categories ### Query Parameters - **format** (string) - Optional - Can either `flattened` or `nested`. If `flattened`, returns a singular array of categories, ordered alphabetically. If `nested`, returns top-level categories (either category groups or categories not part of a category group) in an array. Subcategories are nested within the category group under the property `children`. ### Response #### Success Response (200) - **categories** (array of objects) - A list of category objects. - **id** (number) - A unique identifier for the category. - **name** (string) - The name of the category. - **description** (string) - The description of the category. - **is_income** (boolean) - If true, the transactions in this category will be treated as income. - **exclude_from_budget** (boolean) - If true, the transactions in this category will be excluded from the budget. - **exclude_from_totals** (boolean) - If true, the transactions in this category will be excluded from totals. - **archived** (boolean) - If true, the category is archived. - **archived_on** (string) - The date and time of when the category was last archived. - **updated_at** (string) - The date and time of when the category was last updated. - **created_at** (string) - The date and time of when the category was created. - **is_group** (boolean) - If true, the category is a group. - **group_id** (number) - The ID of a category group or null. - **order** (number) - Numerical ordering of categories. - **children** (array of objects) - For category groups, this will populate with nested categories. - **group_category_name** (string) - For grouped categories, the name of the category group. ### Response Example ```json { "categories": [ { "id": 83, "name": "Test 1", "description": "Test description", "is_income": false, "exclude_from_budget": true, "exclude_from_totals": false, "updated_at": "2020-01-28T09:49:03.225Z", "created_at": "2020-01-28T09:49:03.225Z", "is_group": false, "group_id": null, "order": 0 }, { "id": 84, "name": "Test 2", "description": null, "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": true, "group_id": 83, "order": 1, "children": [ { "id": 315162, "name": "Alcohol, Bars", "description": null, "created_at": "2022-03-06T20:11:36.066Z" }, { "id": 315169, "name": "Groceries", "description": null, "created_at": "2022-03-06T20:11:36.120Z" }, { "id": 315172, "name": "Restaurants", "description": null, "created_at": "2022-03-06T20:11:36.146Z" } ] } ] } ``` ``` -------------------------------- ### Delete Category - DELETE Request Example Source: https://lunchmoney.dev/ Shows how to delete a single category or category group. This operation is only successful if the category has no dependencies. If dependencies exist, the response will detail them. The endpoint requires a category ID. ```json true ``` ```json { "dependents": { "category_name": "Food & Drink", "budget": 4, "category_rules": 0, "transactions": 43, "children": 7, "recurring": 0 } } ``` -------------------------------- ### GET /v1/recurring_items Source: https://lunchmoney.dev/ Retrieves a list of recurring items. This endpoint replaces the deprecated GET /v1/recurring_expenses. ```APIDOC ## GET /v1/recurring_items ### Description Retrieves a list of recurring items. This endpoint is the successor to the deprecated `GET /v1/recurring_expenses`. ### Method GET ### Endpoint `/v1/recurring_items` ### Parameters #### Query Parameters - **start_date** (string) - Optional - Filter recurring items starting on or after this date (YYYY-MM-DD). - **end_date** (string) - Optional - Filter recurring items ending on or before this date (YYYY-MM-DD). - **status** (string) - Optional - Filter by status (e.g., `active`, `inactive`). ### Response #### Success Response (200) - **recurring_items** (array) - An array of recurring item objects. - **id** (integer) - The unique identifier for the recurring item. - **title** (string) - The title of the recurring item. - **amount** (integer) - The amount of the recurring item. - **currency** (string) - The currency of the amount. - **interval_unit** (string) - The unit of the interval (e.g., `days`, `weeks`, `months`, `years`). - **interval_count** (integer) - The number of interval units. - **start_date** (string) - The start date of the recurring item (YYYY-MM-DD). - **end_date** (string) - The end date of the recurring item (YYYY-MM-DD) or null if it does not end. - **created_at** (string) - The timestamp when the recurring item was created. - **updated_at** (string) - The timestamp when the recurring item was last updated. #### Response Example ```json { "recurring_items": [ { "id": 1, "title": "Monthly Subscription", "amount": 5000, "currency": "USD", "interval_unit": "months", "interval_count": 1, "start_date": "2023-01-01", "end_date": null, "created_at": "2023-01-01T10:00:00Z", "updated_at": "2023-01-01T10:00:00Z" } ] } ``` ``` -------------------------------- ### Create Asset Source: https://lunchmoney.dev/ Creates a single manually-managed asset for the user's account. ```APIDOC ## Create Asset ### Description Use this endpoint to create a single (manually-managed) asset. ### Method POST ### Endpoint https://dev.lunchmoney.app/v1/assets ### Parameters #### Request Body - **type_name** (string) - Required - Must be one of: cash, credit, investment, other, real estate, loan, vehicle, cryptocurrency, employee compensation. - **subtype_name** (string) - Optional - Max 25 characters. - **name** (string) - Required - Max 45 characters. - **display_name** (string) - Optional - Display name of the asset (as set by user). - **balance** (string) - Required - Numeric value of the current balance of the account. Do not include any special characters aside from a decimal point! - **balance_as_of** (string) - Optional - Has no effect if balance is not defined. If balance is defined, but balance_as_of is not supplied or is invalid, current timestamp will be used. Defaults to current timestamp. - **currency** (string) - Optional - Three-letter lowercase currency in ISO 4217 format. The code sent must exist in our database. Defaults to user’s primary currency. - **institution_name** (string) - Optional - Max 50 characters. - **closed_on** (string) - Optional - The date this asset was closed. - **exclude_transactions** (boolean) - Optional - If true, this asset will not show up as an option for assignment when creating transactions manually. Defaults to false. ### Request Example ```json { "type_name": "cash", "name": "My Test Asset", "balance": "67.2100", "currency": "cad" } ``` ### Response #### Success Response (200) - **id** (integer) - Unique identifier for the newly created asset. - **type_name** (string) - The type of the asset. - **subtype_name** (string) - The subtype of the asset. - **name** (string) - The name of the asset. - **display_name** (string) - The display name of the asset. - **balance** (string) - The current balance of the asset. - **to_base** (float) - The balance converted to the user's base currency. - **balance_as_of** (string) - The timestamp when the balance was recorded (ISO 8601 format). - **closed_on** (string) - The date the asset was closed. - **created_at** (string) - The timestamp when the asset was created (ISO 8601 format). - **currency** (string) - The three-letter ISO 4217 currency code. - **institution_name** (string) - The name of the institution holding the asset. - **exclude_transactions** (boolean) - Whether transactions for this asset are excluded. #### Response Example ```json { "id": 34061, "type_name": "depository", "subtype_name": null, "name": "My Test Asset", "display_name": null, "balance": "67.2100", "to_base": 47.05, "balance_as_of": "2022-05-29T21:35:36.557Z", "closed_on": null, "created_at": "2022-05-29T21:35:36.564Z", "currency": "cad", "institution_name": null, "exclude_transactions": false } ``` ``` -------------------------------- ### Config Object Source: https://lunchmoney.dev/ Defines the configuration settings for recurring budget expenses. ```APIDOC ## Config Object ### Description The Config object defines the rules and parameters for a recurring budget. ### Attributes - **config_id** (number) - Required - Unique identifier for the configuration. - **cadence** (string) - Required - Frequency of the budget (e.g., monthly, yearly). - **amount** (number) - Required - The budget amount. - **currency** (string) - Required - ISO 4217 currency code. - **to_base** (number) - Required - Amount converted to primary currency. - **auto_suggest** (string) - Required - Budget strategy type (budgeted, fixed, fixed-rollover, spent). ### Note The `config` property can be `null` if no budget configuration is set for the category. ```