### Get All Assets - Example Response Source: https://github.com/lunch-money/developers/blob/main/source/includes/_assets.md This JSON object represents a successful response (200 OK) when fetching all assets. It contains an array of asset objects, each detailing properties like ID, type, name, balance, and currency. ```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" } ] } ``` -------------------------------- ### Create Category Response Examples Source: https://github.com/lunch-money/developers/blob/main/source/includes/_categories.md Examples of successful and error responses when creating a new category via the POST endpoint. ```json { "category_id": 26213 } ``` ```json { "error": "Missing category name." } ``` -------------------------------- ### Example 200 Response - Budget Summary Data Source: https://github.com/lunch-money/developers/blob/main/source/includes/_budget.md This JSON object represents a successful response (200 OK) from the Get Budget Summary endpoint. It illustrates the structure of the returned data, including category details, monthly spending, and budget configurations. ```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 } ] ``` -------------------------------- ### Create Category Group Response Examples Source: https://github.com/lunch-money/developers/blob/main/source/includes/_categories.md Examples of successful and error responses when creating a new category group via the POST endpoint. ```json { "category_id": 26213 } ``` ```json { "error": "A category with the same name (sample_duplicate_name) already exists." } ``` -------------------------------- ### Get Budget Summary - HTTP Request Source: https://github.com/lunch-money/developers/blob/main/source/includes/_budget.md This snippet demonstrates the HTTP GET request to retrieve budget summaries. It includes the base URL and the required query parameters for specifying the date range. ```http GET https://dev.lunchmoney.app/v1/budgets?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD ``` -------------------------------- ### Get All Assets - HTTP Request Source: https://github.com/lunch-money/developers/blob/main/source/includes/_assets.md This snippet shows the HTTP GET request to retrieve a list of all manually-managed assets associated with a user's account. It requires no specific input parameters beyond the base URL. ```HTTP GET https://dev.lunchmoney.app/v1/assets ``` -------------------------------- ### GET /v1/recurring_expenses Source: https://github.com/lunch-money/developers/blob/main/source/includes/_recurring_expenses.md Retrieves a list of recurring expenses expected for a specific month based on the provided start date. ```APIDOC ## GET /v1/recurring_expenses ### Description Retrieves a list of recurring expenses expected for a specific month. Note: This endpoint is deprecated; use /v1/recurring_items instead. ### Method GET ### Endpoint https://dev.lunchmoney.app/v1/recurring_expenses ### Parameters #### Query Parameters - **start_date** (string) - Optional - Accepts ISO-8601 format (YYYY-MM-DD). Returns expenses for the month containing this date. - **debit_as_negative** (boolean) - Optional - If true, returns expenses as negative and credits as positive. ### Request Example GET https://dev.lunchmoney.app/v1/recurring_expenses?start_date=2020-01-01 ### Response #### Success Response (200) - **recurring_expenses** (array) - List of recurring expense objects. #### Response Example { "recurring_expenses": [ { "id": 264, "start_date": "2020-01-01", "cadence": "twice a month", "payee": "Test 5", "amount": "-122.0000", "currency": "cad", "billing_date": "2020-01-01" } ] } ``` -------------------------------- ### GET /v1/assets Source: https://github.com/lunch-money/developers/blob/main/source/includes/_assets.md Retrieves a list of all manually-managed assets associated with the user's account. ```APIDOC ## GET /v1/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. #### Response Example { "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" } ] } ``` -------------------------------- ### Create Asset - Example Response Source: https://github.com/lunch-money/developers/blob/main/source/includes/_assets.md This JSON object represents a successful response (200 OK) after creating a new asset. It includes the details of the newly created asset, such as its ID, name, balance, and creation timestamp. ```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 } ``` -------------------------------- ### GET /v1/me Source: https://context7.com/lunch-money/developers/llms.txt Retrieve information about the currently authenticated user, including their primary currency and budget name. ```APIDOC ## GET /v1/me ### Description Retrieve details about the authenticated user including their primary currency and budget name. ### Method GET ### Endpoint https://dev.lunchmoney.app/v1/me ### Parameters None ### Response #### Success Response (200) - **user_name** (string) - Name of the user - **user_email** (string) - Email address of the user - **user_id** (integer) - Unique identifier for the user - **primary_currency** (string) - The user's primary currency code #### Response Example { "user_name": "John Doe", "user_email": "john@example.com", "user_id": 18328, "primary_currency": "usd" } ``` -------------------------------- ### Get Budget Summary - Bash Source: https://context7.com/lunch-money/developers/llms.txt Fetches a summary of budget performance for all budgetable categories over a specified date range. The data is aggregated monthly, providing insights into spending versus budgeted amounts. ```bash curl -X GET "https://dev.lunchmoney.app/v1/budgets?start_date=2024-01-01&end_date=2024-03-31" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` -------------------------------- ### Unsplit Transactions Response Examples Source: https://github.com/lunch-money/developers/blob/main/source/includes/_transactions.md Examples of responses from the unsplit transactions endpoint. The 200 response returns an array of transaction IDs that were successfully unsplit. The 404 response indicates an error, listing transaction IDs that are not valid for unsplitting. ```json [ 84389, 23212, 43333 ] ``` ```json { "error": "The following transaction ids are not valid to unsplit: 1232, 1233, 1234" } ``` -------------------------------- ### Update Asset Example (JSON Response) Source: https://github.com/lunch-money/developers/blob/main/source/includes/_assets.md This JSON object represents a successful response when updating an asset. It includes details of the updated asset such as its ID, type, name, balance, and associated currency. It also shows timestamps for creation and balance updates. ```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" } ``` -------------------------------- ### Get All Categories (Bash) Source: https://context7.com/lunch-money/developers/llms.txt Retrieve all categories associated with the user's account. Supports both flattened (default) and nested formats. Requires an Authorization header. ```bash curl -X GET "https://dev.lunchmoney.app/v1/categories" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ```bash curl -X GET "https://dev.lunchmoney.app/v1/categories?format=nested" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` -------------------------------- ### GET /v1/plaid_accounts Source: https://context7.com/lunch-money/developers/llms.txt Retrieve all bank accounts synced via Plaid integration. ```APIDOC ## GET /v1/plaid_accounts ### Description Retrieve all bank accounts synced via Plaid integration. ### Method GET ### Endpoint https://dev.lunchmoney.app/v1/plaid_accounts ### Response #### Success Response (200) - **plaid_accounts** (array) - List of synced bank accounts. #### Response Example { "plaid_accounts": [ { "id": 91, "name": "401k", "balance": "125000.6700", "currency": "usd" } ] } ``` -------------------------------- ### GET /v1/crypto Source: https://github.com/lunch-money/developers/blob/main/source/includes/_crypto.md Retrieves a list of all cryptocurrency assets associated with the user's account, including both synced and manual sources. ```APIDOC ## GET /v1/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) - List of crypto asset objects. #### Response Example { "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" } ] } ``` -------------------------------- ### Handle Recurring Expenses Error Response Source: https://github.com/lunch-money/developers/blob/main/source/includes/_recurring_expenses.md Example JSON 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" } ``` -------------------------------- ### GET /v1/budgets Source: https://github.com/lunch-money/developers/blob/main/source/includes/_budget.md Retrieve full details on budgets for all budgetable categories within a specified time period. ```APIDOC ## GET /v1/budgets ### Description Use this endpoint to get full details on the budgets for all budgetable categories between a certain time period. The budgeted and spending amounts will be broken down by month. ### Method GET ### Endpoint https://dev.lunchmoney.app/v1/budgets ### Parameters #### Query Parameters - **start_date** (string) - Required - Start date for the budget period (e.g., 2021-04-01). - **end_date** (string) - Required - End date for the budget period (e.g., 2021-04-30). - **currency** (string) - Optional - Currency for the budgeted amount. Defaults to primary currency if empty. ### Request Example GET https://dev.lunchmoney.app/v1/budgets?start_date=2020-07-01&end_date=2020-09-01 ### Response #### Success Response (200) - **category_name** (string) - Name of the category. - **data** (object) - Monthly breakdown of spending and budget data. - **config** (object) - Budget configuration settings. #### Response Example [ { "category_name": "Food", "category_id": 34476, "data": { "2020-09-01": { "num_transactions": 23, "spending_to_base": 373.51, "budget_amount": 376.08 } }, "config": { "cadence": "monthly", "amount": 300 } } ] ``` -------------------------------- ### Get Budget Summary API Source: https://context7.com/lunch-money/developers/llms.txt Retrieves a summary of budget details for all budgetable categories within a specified date range, broken down by month. ```APIDOC ## GET /v1/budgets ### Description Retrieve budget details for all budgetable categories within a specified time period, broken down by month. ### Method GET ### Endpoint /v1/budgets ### Parameters #### Query Parameters - **start_date** (string) - Required - The start date for the budget summary (YYYY-MM-DD). - **end_date** (string) - Required - The end date for the budget summary (YYYY-MM-DD). ### Request Example ```bash curl -X GET "https://dev.lunchmoney.app/v1/budgets?start_date=2024-01-01&end_date=2024-03-31" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ### Response #### Success Response (200) - **budgets** (array) - A list of budget summary objects for each category. - **category_name** (string) - The name of the category. - **category_id** (integer) - The ID of the category. - **category_group_name** (string) - The name of the parent category group. - **group_id** (integer) - The ID of the parent category group. - **is_group** (boolean) - Indicates if the category is a group. - **is_income** (boolean) - Indicates if the category is for income. - **exclude_from_budget** (boolean) - Indicates if the category is excluded from budget calculations. - **exclude_from_totals** (boolean) - Indicates if the category is excluded from total calculations. - **data** (object) - Monthly budget data. - **YYYY-MM-DD** (object) - Data for a specific month. - **num_transactions** (integer) - Number of transactions in the month. - **spending_to_base** (number) - Total spending in the month, converted to the base currency. - **budget_to_base** (number) - Budgeted amount in the month, converted to the base currency. - **budget_amount** (number) - The budgeted amount for the month. - **budget_currency** (string) - The currency of the budget. - **is_automated** (boolean) - Indicates if the budget is automated. - **config** (object) - Budget configuration details. - **config_id** (integer) - The ID of the budget configuration. - **cadence** (string) - The budget cadence (e.g., 'monthly'). - **amount** (number) - The budgeted amount. - **currency** (string) - The currency of the budget. - **to_base** (number) - The amount converted to the base currency. - **auto_suggest** (string) - The auto-suggestion strategy for the budget. - **order** (integer) - The display order of the category. - **archived** (boolean) - Indicates if the category is archived. - **recurring** (object) - Information about recurring items associated with the budget. - **list** (array) - List of recurring items. - **payee** (string) - The payee for the recurring item. - **amount** (string) - The amount of the recurring item. - **currency** (string) - The currency of the recurring item. - **to_base** (number) - The amount converted to the base currency. ### Response Example ```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": { "2024-01-01": { "num_transactions": 23, "spending_to_base": 373.51, "budget_to_base": 400.00, "budget_amount": 400.00, "budget_currency": "usd", "is_automated": false }, "2024-02-01": { "num_transactions": 19, "spending_to_base": 285.92, "budget_to_base": 400.00, "budget_amount": 400.00, "budget_currency": "usd" }, "2024-03-01": { "num_transactions": 21, "spending_to_base": 328.66, "budget_to_base": 400.00, "budget_amount": 400.00, "budget_currency": "usd" } }, "config": { "config_id": 9, "cadence": "monthly", "amount": 400, "currency": "usd", "to_base": 400, "auto_suggest": "fixed-rollover" }, "order": 0, "archived": false, "recurring": { "list": [ { "payee": "Grocery Store", "amount": "150.000", "currency": "usd", "to_base": 150 } ] } } ] ``` ``` -------------------------------- ### Get All Tags Source: https://github.com/lunch-money/developers/blob/main/source/includes/_tags.md Retrieves a list of all tags associated with the user's account. Note: This v1 API is not recommended for new projects; use v2 instead. ```APIDOC ## GET /v1/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 ### Parameters None ### Request Example None ### Response #### Success Response (200) - **id** (number) - Unique identifier for tag - **name** (string) - User-defined name of tag - **description** (string) - User-defined description of tag - **archived** (boolean) - If true, the tag will not show up when creating or updating transactions in the Lunch Money app #### 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 Crypto Assets (JSON) Source: https://github.com/lunch-money/developers/blob/main/source/includes/_crypto.md Retrieves a list of all cryptocurrency assets associated with the user's account, including both synced and manual balances. This endpoint returns a JSON object containing an array of crypto assets. ```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" } ] } ``` -------------------------------- ### Get All Tags - Bash Source: https://context7.com/lunch-money/developers/llms.txt Retrieves a list of all tags available in your account. Tags are used for organizing transactions and can be filtered or used in various API operations. ```bash curl -X GET "https://dev.lunchmoney.app/v1/tags" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` -------------------------------- ### Retrieve All Categories JSON Response Source: https://github.com/lunch-money/developers/blob/main/source/includes/_categories.md An example of the JSON response structure returned when fetching all categories. It demonstrates both standard categories and category groups containing nested children. ```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" } ] } ] } ``` -------------------------------- ### Upsert Budget API Source: https://context7.com/lunch-money/developers/llms.txt Creates or updates a budget for a specific category and month. Requires category ID, start date, amount, and currency. ```APIDOC ## PUT /v1/budgets ### Description Create or update a budget for a specific category and month. ### Method PUT ### Endpoint /v1/budgets ### Parameters #### Request Body - **start_date** (string) - Required - The start date of the budget period (YYYY-MM-01). - **category_id** (integer) - Required - The ID of the category to set the budget for. - **amount** (number) - Required - The budget amount. - **currency** (string) - Required - The currency of the budget (e.g., 'usd'). ### Request Example ```bash curl -X PUT "https://dev.lunchmoney.app/v1/budgets" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "start_date": "2024-04-01", "category_id": 34476, "amount": 450, "currency": "usd" }' ``` ### Response #### Success Response (200) - **category_group** (object) - Details of the updated or created budget. - **category_id** (integer) - The ID of the category. - **amount** (number) - The updated budget amount. - **currency** (string) - The currency of the budget. - **start_date** (string) - The start date of the budget period. #### Error Response (400 Bad Request) - **error** (string) - Error message indicating why the budget could not be updated (e.g., "Budget must be greater than or equal to the sum of sub-category budgets ($10.01)."). ### Response Example ```json { "category_group": { "category_id": 34476, "amount": 450, "currency": "usd", "start_date": "2024-04-01" } } ``` ``` -------------------------------- ### Create New Asset Source: https://context7.com/lunch-money/developers/llms.txt Creates a new manual account for tracking balances. Requires a JSON payload with account details such as name, type, and balance. ```bash curl -X POST "https://dev.lunchmoney.app/v1/assets" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type_name": "cash", "subtype_name": "savings", "name": "Emergency Fund", "display_name": "Rainy Day Fund", "balance": "10000.00", "balance_as_of": "2024-01-15T00:00:00.000Z", "currency": "usd", "institution_name": "Ally Bank", "exclude_transactions": false }' ``` -------------------------------- ### Get Transaction Group 404 Response Example Source: https://github.com/lunch-money/developers/blob/main/source/includes/_transactions.md This JSON object represents an error response when attempting to retrieve a transaction group that does not exist or is not part of a group. The error message specifies the transaction ID and the reason for the failure. ```json { "error": [ "Transaction 35360525 is not a transaction group, or part of a transaction group." ] } ``` -------------------------------- ### POST /v1/assets Source: https://context7.com/lunch-money/developers/llms.txt Create a new manually-managed account for tracking balances. ```APIDOC ## POST /v1/assets ### Description Create a new manually-managed account for tracking balances. ### Method POST ### Endpoint https://dev.lunchmoney.app/v1/assets ### Request Body - **type_name** (string) - Required - Type of asset (e.g., cash) - **name** (string) - Required - Name of the asset - **balance** (string) - Required - Current balance ### Response #### Success Response (200) - **id** (integer) - The ID of the created asset #### Response Example { "id": 34061, "name": "Emergency Fund", "balance": "10000.0000" } ``` -------------------------------- ### Get Transaction Group 200 Response Example Source: https://github.com/lunch-money/developers/blob/main/source/includes/_transactions.md This JSON object represents a successful response when retrieving a transaction group. It includes the parent transaction's details and an array of its associated child transactions, each with their respective details like payee, amount, and date. ```json { "id": 481307164, "date": "2023-11-29", "amount": "0", "currency": "usd", "to_base": 0, "payee": "Walmart+", "category_id": 315174, "category_name": "General", "category_group_id": 315362, "category_group_name": "Shopping", "is_income": false, "exclude_from_budget": false, "exclude_from_totals": false, "created_at": "2023-11-30T23:59:56.584Z", "updated_at": "2023-11-30T23:59:56.584Z", "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": null, "has_children": null, "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": null, "plaid_account_name": null, "plaid_account_mask": null, "institution_name": null, "plaid_account_display_name": null, "plaid_metadata": null, "plaid_category": null, "source": null, "display_name": "Walmart+", "display_notes": null, "account_display_name": " ", "tags": [], "children": [ { "id": 480887173, "payee": "Walmart", "amount": "-14.1800", "currency": "usd", "date": "2023-11-29", "formatted_date": "2023-11-29", "notes": null, "asset_id": null, "plaid_account_id": 54174, "to_base": -14.18 }, { "id": 480887180, "payee": "Walmart", "amount": "14.1800", "currency": "usd", "date": "2023-11-28", "formatted_date": "2023-11-28", "notes": null, "asset_id": null, "plaid_account_id": 54174, "to_base": 14.18 } ], "external_id": null } ``` -------------------------------- ### Lunch Money API Overview Source: https://context7.com/lunch-money/developers/llms.txt This section provides an overview of the Lunch Money API, its common use cases, and essential integration best practices. ```APIDOC ## Lunch Money API Overview ### Description The Lunch Money API provides comprehensive tools for building personal finance integrations. Common use cases include: importing transactions from banks without native Plaid support, syncing financial data to custom spreadsheets or dashboards, building receipt matchers for e-commerce platforms like Amazon, creating Venmo/PayPal integrations via email parsing, and automating real estate or investment value tracking. The API supports full CRUD operations on transactions, categories, tags, assets, and budgets, enabling developers to build complete financial management workflows. ### Best Practices When integrating with the Lunch Money API, best practices include: - Using the Bearer token authentication header rather than query parameters. - Implementing proper error handling for the various error response formats. - Respecting the 500 transaction limit per insert request. - Using the `external_id` field to prevent duplicate imports. - For Plaid-synced accounts, use the experimental fetch endpoint sparingly (minimum 1-minute intervals) and track the `last_import` and `plaid_last_successful_update` fields to verify data freshness. - The API supports multi-currency operations with automatic conversion to the user's primary currency via the `to_base` field. ``` -------------------------------- ### GET /v1/transactions/:transaction_id Source: https://github.com/lunch-money/developers/blob/main/source/includes/_transactions.md Retrieves the details of a specific transaction by its unique ID. ```APIDOC ## GET /v1/transactions/:transaction_id ### Description Use this endpoint to retrieve details about a specific transaction by ID. ### Method GET ### Endpoint https://dev.lunchmoney.app/v1/transactions/:transaction_id ### Parameters #### Path Parameters - **transaction_id** (integer) - Required - The unique identifier of the transaction. #### Query Parameters - **debit_as_negative** (boolean) - Optional - Pass in true if you’d like expenses to be returned as negative amounts and credits as positive amounts. Defaults to false. ### Request Example GET https://dev.lunchmoney.app/v1/transactions/480887173 ### Response #### Success Response (200) - **id** (integer) - Transaction ID - **date** (string) - Date of transaction - **amount** (string) - Transaction amount #### Response Example { "id": 480887173, "date": "2023-11-29", "amount": "-14.1800" } ``` -------------------------------- ### Create Asset - HTTP Request Source: https://github.com/lunch-money/developers/blob/main/source/includes/_assets.md This snippet demonstrates the HTTP POST request to create a new manually-managed asset. The request body should contain the necessary asset details such as name, type, and balance. ```HTTP POST https://dev.lunchmoney.app/v1/assets ``` -------------------------------- ### Get Transaction Group Source: https://github.com/lunch-money/developers/blob/main/source/includes/_transactions.md Retrieves transaction group information using a transaction ID. ```APIDOC ## GET /v1/transactions/group ### Description Retrieves transaction group information using a transaction ID. ### Method GET ### Endpoint /v1/transactions/group ### Parameters #### Query Parameters - **transaction_id** (number) - Required - Transaction ID of either the parent or any of the children in the transaction group ### Response #### Success Response (200) - **transaction_group_id** (number) - The ID of the transaction group #### Response Example ```json 84389 ``` ``` -------------------------------- ### Retrieve All Assets Source: https://context7.com/lunch-money/developers/llms.txt Fetches a list of all manually-managed accounts associated with the user's account. Requires a valid Bearer token in the Authorization header. ```bash curl -X GET "https://dev.lunchmoney.app/v1/assets" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` -------------------------------- ### GET /transactions Source: https://github.com/lunch-money/developers/blob/main/source/includes/_transactions.md Retrieve a list of transactions with various filtering, pagination, and formatting options. ```APIDOC ## GET /transactions ### Description Retrieves a list of transactions based on provided filters. Supports filtering by tags, accounts, categories, and date ranges. ### Method GET ### Endpoint /transactions ### Parameters #### Query Parameters - **tag_id** (number) - Optional - Filter by tag ID. - **recurring_id** (number) - Optional - Filter by recurring expense ID. - **plaid_account_id** (number) - Optional - Filter by Plaid account ID. - **category_id** (number) - Optional - Filter by category ID. - **asset_id** (number) - Optional - Filter by asset ID. - **is_group** (boolean) - Optional - Filter by group. - **status** (string) - Optional - Filter by status (cleared or uncleared). - **start_date** (string) - Optional - Start date (YYYY-MM-DD). - **end_date** (string) - Optional - End date (YYYY-MM-DD). - **debit_as_negative** (boolean) - Optional - Return expenses as negative amounts. - **pending** (boolean) - Optional - Include pending transactions. - **offset** (number) - Optional - Offset for records. - **limit** (number) - Optional - Max records to return (default 1000). ### Request Example GET /transactions?start_date=2023-01-01&end_date=2023-01-31 ### Response #### Success Response (200) - **transactions** (array) - List of transaction objects. #### Response Example { "transactions": [ { "id": 12345, "date": "2023-01-15", "amount": 50.00, "payee": "Grocery Store" } ] } ``` -------------------------------- ### POST /v1/assets Source: https://github.com/lunch-money/developers/blob/main/source/includes/_assets.md Creates a new manually-managed asset in the user's account. ```APIDOC ## POST /v1/assets ### Description Use this endpoint to create a single (manually-managed) asset. ### Method POST ### Endpoint https://dev.lunchmoney.app/v1/assets ### Response #### Success Response (200) - **id** (number) - Unique identifier for the created asset. - **name** (string) - Name of the asset. #### Response Example { "id": 34061, "type_name": "depository", "name": "My Test Asset", "balance": "67.2100", "currency": "cad" } ``` -------------------------------- ### Authenticate API Requests Source: https://context7.com/lunch-money/developers/llms.txt Demonstrates how to authenticate requests to the Lunch Money API using a Bearer token in the Authorization header. ```bash curl -X GET "https://dev.lunchmoney.app/v1/me" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` -------------------------------- ### GET /v1/transactions/{id} Source: https://context7.com/lunch-money/developers/llms.txt Retrieve detailed information about a specific transaction by its unique ID. ```APIDOC ## GET /v1/transactions/{id} ### Description Retrieve detailed information about a specific transaction by its ID. ### Method GET ### Endpoint https://dev.lunchmoney.app/v1/transactions/{id} ### Parameters #### Path Parameters - **id** (integer) - Required - The unique ID of the transaction ### Response #### Success Response (200) - **id** (integer) - Transaction ID - **amount** (string) - Transaction amount - **payee** (string) - Payee name #### Response Example { "id": 480887173, "amount": "-14.1800", "payee": "Walmart" } ``` -------------------------------- ### GET /v1/transactions Source: https://context7.com/lunch-money/developers/llms.txt Retrieve a list of transactions with support for date filtering and other query parameters. ```APIDOC ## GET /v1/transactions ### Description Retrieve all transactions within a specified date range with optional filtering by category, tag, account, or status. ### Method GET ### Endpoint https://dev.lunchmoney.app/v1/transactions ### Parameters #### Query Parameters - **start_date** (string) - Optional - Start date for transactions (YYYY-MM-DD) - **end_date** (string) - Optional - End date for transactions (YYYY-MM-DD) - **category_id** (integer) - Optional - Filter by category ID - **status** (string) - Optional - Filter by status (e.g., cleared) ### Response #### Success Response (200) - **transactions** (array) - List of transaction objects - **has_more** (boolean) - Indicates if more results are available #### Response Example { "transactions": [ { "id": 246946944, "date": "2024-01-18", "amount": "53.1900", "payee": "Amazon" } ], "has_more": true } ``` -------------------------------- ### Config Object Structure Source: https://github.com/lunch-money/developers/blob/main/source/includes/_budget.md Details the attributes and their types within the Config Object, used for setting budget configurations. ```APIDOC ## Config Object | Attribute Name | Type | Nullable | Description | | -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | config_id | number | false | Unique identifier for config | | cadence | string | false | One of: | | amount | number | false | Amount in numeric format | | currency | string | false | Three-letter lowercase currency code for the recurring expense in ISO 4217 format | | to_base | number | false | The amount converted to the user's primary currency. | | auto_suggest | string | false | One of: | **Note:** The `config` property in the Budget Object can be `null`. When `config` is `null`, it means the category has no budget configuration set. When `config` is present (not null), all properties listed above are required and not nullable. ```