NAV
Lunch Money
Developer API

Getting Started

Welcome to the Lunch Money developer API! We created this to enable the user and the community to build rich plug-ins to complement their Lunch Money experience.

Current Status

The developer API is officially in open public beta. During this time, please continue to heed caution and use this API at your own risk as any and all changes are irreversible.

We welcome feedback via email (support@lunchmoney.app). These docs are also on Github, so if you see a mistake or something that could be improved, feel free to open a pull request!

Connecting to the Lunch Money API

Connect to the server

The Lunch Money API endpoint is: https://dev.lunchmoney.app

Authentication

Use Bearer Tokens in your requests like this:

Recommended

https://dev.lunchmoney.app/v1/categories

with the Authorization header field set to Bearer YOURACCESSTOKEN

Not Recommended

https://dev.lunchmoney.app/v1/categories?access_token=YOURACCESSTOKEN

Lunch Money API requests are authenticated using the Bearer Token authentication method.

Getting an access token

Get your access token by going to the developers page in the Lunch Money app.

What should I build?

Great question! We’ve tried to expose the minimum endpoints needed to enable you to build powerful products and extensions.

Here are a few ideas of what you can build:

Basic use cases

Integration with your bank

Does your bank offer an API? You can build a bridge between Lunch Money and your bank to import transactions automatically.

Sync Lunch Money data to your personal interface

If you have your own spreadsheet or other interface, use the API to sync data for personalized viewing and analytics.

Specific use cases with high demand:

Amazon receipt matcher

Do you make a lot of Amazon purchases? I'm sure by now you know how frustrating it is to try to identify exactly what the expense is for! Build an Amazon receipt matcher that pulls in your Amazon purchase history and matches on transactions in Lunch Money and updates the notes.

Venmo integration via email

The lack of a Venmo and Plaid integration is frustrating for many of our users and is largely out of our control. Since Venmo sends an email notification every time you send or receive money, build a service that enables users to forward their Venmo notification emails for parsing and insertion into Lunch Money!

Companion mobile app

Build a simple mobile app that allows quick insertion of transactions into your Lunch Money account or quick reviewing.

Zillow integration

Create an integration that automatically updates the value of a real estate property in Lunch Money.

Awesome Projects

This is a list of awesome open-sourced projects created by the Lunch Money community!

Auto-importers

Source Made by Git repo
Monzo transactions @joehoyle Link
bunq transactions @markjongkind Link
Delta cryptocurrency portfolio balance @markjongkind Link
Amazon transaction notes @samwelnella Link
Investing.com security prices @DouweM Link
Venmo emails to transactions @billycao Link
Wealthsimple Invest, Trade, and Cash balances @jamiepinheiro Link
Vehicle & House Prices using KBB, Redfin, and Zillow. @mike_bianco Link
Categorize Amazon Transactions @mike_bianco Link
Splitwise transactions @juftin Link
Rust CLI to sync Venmo transactions @emersonford Link
Another Amazon transaction notes updater @juftin Link

API clients

Language Made by Git repo
JavaScript with TypeScript support @joehoyle Link
Go @icco Link
Python @juftin Link
Async client in Kotlin for JVM-based languages @smaugfm Link
Ruby @mmenanno Link

Other

Description Made by Git repo
React Native app (WIP) @yuanhaochiang Link
Singer target to sync asset balances from arbitrary sources @DouweM Link
iOS shortcut for categorizing transactions @jamiepinheiro Link
Milk Money: mobile web quick add @dareiff Link
Scritable iOS Widget for Lunch Money status updates @amanb014 Link
Import transaction history from Mint. @mike_bianco Link
Pushover Push Notifications @juftin Link

Changelog

A log of changes. Breaking changes will be denoted with 🚨

March 27, 2024

Updated

January 18, 2024

New

December 20, 2023

New

October 8, 2023

Updated

June 22, 2022

New

June 4, 2022

New

August 31, 2021

Updated

June 9, 2021

New

Updated

May 27, 2021

New

Updated

March 28, 2020

New

Updated

FAQ

The endpoint I need is not listed. Can you add it?

If you would like a specific endpoint which is not currently supported, please let us know by emailing support@lunchmoney.app and stating your use case.

What currencies are supported?

Check here for a list of all the currencies we currently support. If a currency is missing, let us know via email and we’ll try to get it added!

I’ve built something! Now what?

Awesome! Please share with us via email about what you built! If you are willing to share your code, we encourage you to open-source your tool/plug-in so others in the Lunch Money community can benefit and we'll add it to our Awesome Projects page.

Where can I get support?

Join our Discord community and chat with us in the 💻-developer-api channel! For account-specific issues, email us at support@lunchmoney.app.

User

User Object

Attribute Name Type Nullable Description
user_id number false Unique identifier for user
user_name string false User's' name
user_email string false User's email
account_id number false Unique identifier for the associated budgeting account
budget_name string false Name of the associated budgeting account
api_key_label string true User-defined label of the developer API key used. Returns null if nothing has been set.

Get User

Use this endpoint to get details on the current user.

{
  "user_name": "User 1",
  "user_email": "user-1@lunchmoney.dev",
  "user_id": 18328,
  "account_id": 18221,
  "budget_name": "🏠 Family budget",
  "api_key_label": "Side project dev key"
}

HTTP Request

GET https://dev.lunchmoney.app/v1/me

Categories

Categories Object

Attribute Name Type Nullable Description
id number false A unique identifier for the category.
name string false The name of the category. Must be between 1 and 40 characters.
description string true The description of the category. Must not exceed 140 characters.
is_income boolean false If true, the transactions in this category will be treated as income.
exclude_from_budget boolean false If true, the transactions in this category will be excluded from the budget.
exclude_from_totals boolean false If true, the transactions in this category will be excluded from totals.
archived boolean true If true, the category is archived and not displayed in relevant areas of the Lunch Money app.
archived_on string true The date and time of when the category was last archived (in the ISO 8601 extended format).
updated_at string true The date and time of when the category was last updated (in the ISO 8601 extended format).
created_at string true The date and time of when the category was created (in the ISO 8601 extended format).
is_group boolean false If true, the category is a group that can be a parent to other categories.
group_id number true The ID of a category group (or null if the category doesn't belong to a category group).
order number true Numerical ordering of categories
children array of objects true For category groups, this will populate with the categories nested within and include id, name, description and created_at fields.
group_category_name string true For grouped categories, the name of the category group

Get All Categories

Use this endpoint to get a flattened list of all categories in alphabetical order associated with the user's account.

{
  "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": true,
      "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": false,
      "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"
        }
      ]
    }
  ]
}

HTTP Request

GET https://dev.lunchmoney.app/v1/categories

Query Parameters

Parameter Type Required Default Description
format string false flattened 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.

Get Single Category

Use this endpoint to get hydrated details on a single category. Note that if this category is part of a category group, its properties (is_income, exclude_from_budget, exclude_from_totals) will inherit from the category group.

{
  "id": 315358,
  "name": "Food & Drink",
  "description": null,
  "is_income": false,
  "exclude_from_budget": false,
  "exclude_from_totals": false,
  "archived": false,
  "archived_on": null,
  "is_group": true,
  "group_id": null,
  "order": 5,
  "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"
    }
  ]
}

HTTP Request

GET https://dev.lunchmoney.app/v1/categories/:category_id

Create Category

Use this endpoint to create a single category

Example 200 Response

Returns the ID of the newly-created category

{
  "category_id": 26213
}

Example Error Response (sends as 200)

{ "error": "Missing category name." }

{ "error": "Category name must be less than 40 characters." }

{ "error": "Category description must be less than 140 characters." }

{
  "error": "Operation error occurred. Please try again or contact support@lunchmoney.app for assistance."
}

HTTP Request

POST https://dev.lunchmoney.app/v1/categories

Parameter Type Required Default Description
name string true - Name of category. Must be between 1 and 40 characters.
description string false - Description of category. Must be less than 140 categories.
is_income boolean false false Whether or not transactions in this category should be treated as income.
exclude_from_budget boolean false false Whether or not transactions in this category should be excluded from budgets.
exclude_from_totals boolean false false Whether or not transactions in this category should be excluded from calculated totals.
archived boolean false false Whether or not category should be archived.
group_id number false - Assigns the newly-created category to an existing category group.

Create Category Group

Use this endpoint to create a single category group

Example 200 Response

Returns the ID of the newly-created category group

{
  "category_id": 26213
}

Example Error Response (sends as 200)

{ "error": "Missing category name." }

{
  "error": "A category with the same name (sample_duplicate_name) already exists."
}

{
  "error": "The following category id(s) could not be added as a group because you do not have permissions for this category, or it is already a category group: 3893"
}

HTTP Request

POST https://dev.lunchmoney.app/v1/categories/group

Parameter Type Required Default Description
name string true - Name of category. Must be between 1 and 40 characters.
description string false - Description of category. Must be less than 140 categories.
is_income boolean false false Whether or not transactions in this category should be treated as income.
exclude_from_budget boolean false false Whether or not transactions in this category should be excluded from budgets.
exclude_from_totals boolean false false Whether or not transactions in this category should be excluded from calculated totals.
category_ids array of numbers false - Array of category_id to include in the category group.
new_categories array of strings false - Array of strings representing new categories to create and subsequently include in the category group.

Update Category

Use this endpoint to update the properties for a single category or category group

Example 200 Response

If successfully updated, returns true

true

Example Error Response (sends as 200)

{ "error": "No valid fields to update for this category." }

{ "error": "You may not set the is_group property for an existing category." }

{
  "error": "This category cannot be assigned a group because it is a category group."
}

{
  "error": "Operation error occurred. Please try again or contact support@lunchmoney.app for assistance."
}

HTTP Request

PUT https://dev.lunchmoney.app/v1/categories/:category_id

Parameter Type Required Default Description
name string false - Name of category. Must be between 1 and 40 characters.
description string false - Description of category. Must be less than 140 categories.
is_income boolean false false Whether or not transactions in this category should be treated as income.
exclude_from_budget boolean false false Whether or not transactions in this category should be excluded from budgets.
exclude_from_totals boolean false false Whether or not transactions in this category should be excluded from calculated totals.
archived boolean false false Whether or not category should be archived.
group_id number false false For a category, set the group_id to include it in a category group

Add to Category Group

Use this endpoint to add categories (either existing or new) to a single category group

Example 200 Response

Returns the hydrated object for the category group

{
  "id": 315358,
  "name": "Food & Drink",
  "description": null,
  "is_income": false,
  "exclude_from_budget": false,
  "exclude_from_totals": false,
  "is_group": true,
  "group_id": null,
  "children": [
    {
      "id": 315162,
      "name": "Alcohol, Bars",
      "description": null,
      "created_at": "2022-03-06T20:11:36.066Z"
    },
    {
      "id": 315164,
      "name": "Coffee Shops",
      "description": null,
      "created_at": "2022-03-06T20:11:36.082Z"
    },
    {
      "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"
    }
  ]
}

Example Error Response (sends as 200)

{
  "error": "The following category id(s) could not be added as a group because you do not have permissions for this category, or it is already a category group: 3280"
}

{
  "error": "Operation error occurred. Please try again or contact support@lunchmoney.app for assistance."
}

HTTP Request

POST https://dev.lunchmoney.app/v1/categories/group/:group_id/add

Parameter Type Required Default Description
category_ids array of numbers false - Array of category_id to include in the category group.
new_categories array of strings false - Array of strings representing new categories to create and subsequently include in the category group.

Delete Category

Use this endpoint to delete a single category or category group. This will only work if there are no dependencies, such as existing budgets for the category, categorized transactions, categorized recurring items, etc. If there are dependents, this endpoint will return what the dependents are and how many there are.

Example 200 Response

If successfully deleted, returns true

true

Example Error Response (sends as 200)

{
  "dependents": {
    "category_name": "Food & Drink",
    "budget": 4,
    "category_rules": 0,
    "transactions": 43,
    "children": 7,
    "recurring": 0
  }
}

HTTP Request

DELETE https://dev.lunchmoney.app/v1/categories/:category_id

Force Delete Category

Use this endpoint to force delete a single category or category group and along with it, disassociate the category from any transactions, recurring items, budgets, etc.

Note: it is best practice to first try the Delete Category endpoint to ensure you don't accidentally delete any data. Disassociation/deletion of the data arising from this endpoint is irreversible!

Example 200 Response

If successfully deleted, returns true

true

Example Error Response (sends as 200)

{
  "error": "Operation error occurred. Please try again or contact support@lunchmoney.app for assistance."
}

HTTP Request

DELETE https://dev.lunchmoney.app/v1/categories/:category_id/force

Tags

Tags Object

Attribute Name Type Nullable Description
id number false Unique identifier for tag
name string false User-defined name of tag
description string true User-defined description of tag
archived boolean false If true, the tag will not show up when creating or updating transactions in the Lunch Money app

Get All Tags

Use this endpoint to get a list of all tags associated with the user's account.

[
    {
        "id": 1807,
        "name": "Wedding",
        "description": "All wedding-related expenses",
        "archived": false
    },
    {
        "id": 1808,
        "name": "Honeymoon",
        "description": "All honeymoon-related expenses",
        "archived": true
    }
]

HTTP Request

GET https://dev.lunchmoney.app/v1/tags

Transactions

Transaction Object

Attribute Name Type Nullable Description
id number false Unique identifier for transaction
date string false Date of transaction in ISO 8601 format
payee string false Name of payee. If recurring_id is not null, this field will show the payee of associated recurring expense instead of the original transaction payee
amount string false Amount of the transaction in numeric format to 4 decimal places
currency string false Three-letter lowercase currency code of the transaction in ISO 4217 format
to_base number false The amount converted to the user's primary currency. If the multicurrency feature is not being used, to_base and amount will be the same.
category_id number true Unique identifier of associated category (see Categories)
category_name string true Name of category associated with transaction
category_group_id number true Unique identifier of associated category group, if any
category_group_name string true Name of category group associated with transaction, if any
is_income boolean false Based on the associated category's property, denotes if transaction is treated as income
exclude_from_budget boolean false Based on the associated category's property, denotes if transaction is excluded from budget
exclude_from_totals boolean false Based on the associated category's property, denotes if transaction is excluded from totals
created_at string false The date and time of when the transaction was created (in the ISO 8601 extended format).
updated_at string false The date and time of when the transaction was last updated (in the ISO 8601 extended format).
status string true One of the following:
  • cleared: User has reviewed the transaction
  • uncleared: User has not yet reviewed the transaction
  • pending: Imported transaction is marked as pending. This should be a temporary state.
Note: special statuses for recurring items have been deprecated.
is_pending boolean false Denotes if transaction is pending (not posted)
notes string true User-entered transaction notes If recurring_id is not null, this field will be description of associated recurring expense
original_name string true The transactions original name before any payee name updates. For synced transactions, this is the raw original payee name from your bank.
recurring_id number true Unique identifier of associated recurring item
recurring_payee number true Payee name of associated recurring item
recurring_description number true Description of associated recurring item
recurring_cadence number true Cadence of associated recurring item (one of once a week, every 2 weeks, twice a month, monthly, every 2 months, every 3 months, every 4 months, twice a year, yearly)
recurring_type number true Type of associated recurring (one of cleared, suggested, dismissed)
recurring_amount number true Amount of associated recurring item
recurring_currency number true Currency of associated recurring item
parent_id number true Exists if this is a split transaction. Denotes the transaction ID of the original transaction. Note that the parent transaction is not returned in this call.
has_children boolean false True if this transaction is a parent transaction and is split into 2 or more other transactions
group_id number true Exists if this transaction is part of a group. Denotes the parent’s transaction ID
is_group boolean false 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.
asset_id number true Unique identifier of associated manually-managed account (see Assets) Note: plaid_account_id and asset_id cannot both exist for a transaction
asset_institution_name number true Institution name of associated manually-managed account
asset_name number true Name of associated manually-managed account
asset_display_name number true Display name of associated manually-managed account
asset_status number true Status of associated manually-managed account (one of active, closed)
plaid_account_id number true Unique identifier of associated Plaid account (see Plaid Accounts) Note: plaid_account_id and asset_id cannot both exist for a transaction
plaid_account_name number true Name of associated Plaid account
plaid_account_mask number true Mask of associated Plaid account
institution_name number true Institution name of associated Plaid account
plaid_account_display_name number true Display name of associated Plaid account
plaid_metadata number true Metadata associated with imported transaction from Plaid
source number false Source of the transaction (one of api, csv, manual,merge,plaid,recurring,rule,user)
display_name number false Display name for payee for transaction based on whether or not it is linked to a recurring item. If linked, returns recurring_payee field. Otherwise, returns the payee field.
display_notes number true Display notes for transaction based on whether or not it is linked to a recurring item. If linked, returns recurring_notes field. Otherwise, returns the notes field.
account_display_name number false Display name for associated account (manual or Plaid). If this is a synced account, returns plaid_account_display_name or asset_display_name.
tags Tag[] false Array of Tag objects
children Transaction[] true Array of child Transaction objections, these objects are slimmed down to the more essential fields, and contain an extra field called formatted_date that contains the date of transaction in ISO 8601 format
external_id string true User-defined external ID for any manually-entered or imported transaction. External ID cannot be accessed or changed for Plaid-imported transactions. External ID must be unique by asset_id. Max 75 characters.
original_date string true DEPRECATED
type string true DEPRECATED
subtype string true DEPRECATED
fees string true DEPRECATED
price string true DEPRECATED
quantity string true DEPRECATED

Get All Transactions

Use this endpoint to retrieve all transactions between a date range.

Example 200 Response

{
  "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
}

Example 404 Response

{ "error": "Both start_date and end_date must be specified." }

Returns list of Transaction objects and a has_more indicator. If no query parameters are set, this endpoint will return transactions for the current calendar month (see start_date and end_date)

HTTP Request

GET https://dev.lunchmoney.app/v1/transactions

Query Parameters

Parameter Type Required Default Description
tag_id number false - Filter by tag. Only accepts IDs, not names.
recurring_id number false - Filter by recurring expense
plaid_account_id number false - Filter by Plaid account
category_id number false - Filter by category. Will also match category groups.
asset_id number false - Filter by asset
is_group boolean false - Filter by group (returns transaction groups)
status string false - Filter by status (Can be cleared or uncleared. Note: special statuses for recurring items have been deprecated.)
start_date string false - Denotes the beginning of the time period to fetch transactions for. Defaults to beginning of current month. Required if end_date exists. Format: YYYY-MM-DD.
end_date string false - Denotes the end of the time period you'd like to get transactions for. Defaults to end of current month. Required if start_date exists. Format: YYYY-MM-DD.
debit_as_negative boolean false false Pass in true if you’d like expenses to be returned as negative amounts and credits as positive amounts. Defaults to false.
pending boolean false false Pass in true if you’d like to include imported transactions with a pending status.
offset number false - Sets the offset for the records returned
limit number false 1000 Sets the maximum number of records to return.
group_id number false - DEPRECATED (Use GET /v1/transactions-group instead)

Get Single Transaction

Use this endpoint to retrieve details about a specific transaction by ID.

Example 200 Response

{
  "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
}

Example 404 Response

{ "error": "Transaction ID not found." }

Returns a single Transaction object

HTTP Request

GET https://dev.lunchmoney.app/v1/transactions/:transaction_id

Query Parameters

Parameter Type Required Default Description
debit_as_negative boolean false false Pass in true if you’d like expenses to be returned as negative amounts and credits as positive amounts. Defaults to false.

Insert Transactions

Use this endpoint to insert many transactions at once.

Example 200 Response

Upon success, IDs of inserted transactions will be returned in an array.

{
  "ids": [54, 55, 56, 57]
}

Example 404 Response

An array of errors will be returned denoting reason why parameters were deemed invalid.

{
  "error": [
    "Transaction 0 is missing date.",
    "Transaction 0 is missing amount.",
    "Transaction 1 status must be either cleared or uncleared: null"
  ]
}

HTTP Request

POST https://dev.lunchmoney.app/v1/transactions

Body Parameters

Parameter Type Required Default Description
transactions array true - List of transactions to insert (see below)
apply_rules boolean false false If true, will apply account’s existing rules to the inserted transactions. Defaults to false.
skip_duplicates boolean false false If true, the system will automatically dedupe based on transaction date, payee and amount. Note that deduping by external_id will occur regardless of this flag.
check_for_recurring boolean false false If true, will check new transactions for occurrences of new monthly expenses. Defaults to false.
debit_as_negative boolean false false If true, will assume negative amount values denote expenses and positive amount values denote credits. Defaults to false.
skip_balance_update boolean false true If true, will skip updating balance if an asset_id is present for any of the transactions.

Transaction Object to Insert

Key Type Required Description
date string true Must be in ISO 8601 format (YYYY-MM-DD).
amount number/string true Numeric value of amount. i.e. $4.25 should be denoted as 4.25.
category_id number false Unique identifier for associated category_id. Category must be associated with the same account and must not be a category group.
payee string false Max 140 characters
currency string false Three-letter lowercase currency code in ISO 4217 format. The code sent must exist in our database. Defaults to user account's primary currency.
asset_id number false Unique identifier for associated asset (manually-managed account). Asset must be associated with the same account.
recurring_id number false Unique identifier for associated recurring expense. Recurring expense must be associated with the same account.
notes string false Max 350 characters
status string false Must be either cleared or uncleared. (Note: special statuses for recurring items have been deprecated.) Defaults to uncleared.
external_id string false User-defined external ID for transaction. Max 75 characters. External IDs must be unique within the same asset_id.
tags Array of numbers and/or strings false Passing in a number will attempt to match by ID. If no matching tag ID is found, an error will be thrown. Passing in a string will attempt to match by string. If no matching tag name is found, a new tag will be created.

Update Transaction

Use this endpoint to update a single transaction. You may also use this to split an existing transaction.

Example 200 Response

If a split was part of the request, an array of newly-created split transactions will be returned.

{
  "updated": true,
  "split": [58, 59]
}

Example 404 Response

An array of errors will be returned denoting reason why parameters were deemed invalid.

{ "error": ["This transaction doesn't exist or you don't have access to it."] }

{
  "error": [
    "You cannot change the amount for this transaction because it was automatically imported.",
    "You cannot assign an asset_id for this transaction because it was automatically imported."
  ]
}

HTTP Request

PUT https://dev.lunchmoney.app/v1/transactions/:transaction_id

Body Parameters

Parameter Type Required Default Description
split Split[] see description - Defines the split of a transaction. You may not split an already-split transaction, recurring transaction, or group transaction. (see Split object below). If passing an array of split objects to this parameter, the transaction parameter is not required.
transaction object see description - The transaction update object (see Update Transaction object below). Must include an id matching an existing transaction. If passing a transaction object to this parameter, the split parameter is not required.
debit_as_negative boolean false false If true, will assume negative amount values denote expenses and positive amount values denote credits. Defaults to false.
skip_balance_update boolean false true If false, will skip updating balance if an asset_id is present for any of the transactions.

Update Transaction Object

Key Type Description
date string Must be in ISO 8601 format (YYYY-MM-DD).
category_id number Unique identifier for associated category_id. Category must be associated with the same account and must not be a category group.
payee string Max 140 characters
amount number or string You may only update this if this transaction was not created from an automatic import, i.e. if this transaction is not associated with a plaid_account_id
currency string You may only update this if this transaction was not created from an automatic import, i.e. if this transaction is not associated with a plaid_account_id. Defaults to user account's primary currency.
asset_id number Unique identifier for associated asset (manually-managed account). Asset must be associated with the same account. You may only update this if this transaction was not created from an automatic import, i.e. if this transaction is not associated with a plaid_account_id
recurring_id number Unique identifier for associated recurring expense. Recurring expense must be associated with the same account.
notes string Max 350 characters
status string Must be either cleared or uncleared. Defaults to uncleared. (Note: special statuses for recurring items have been deprecated.) Defaults to uncleared.
external_id string User-defined external ID for transaction. Max 75 characters. External IDs must be unique within the same asset_id. You may only update this if this transaction was not created from an automatic import, i.e. if this transaction is not associated with a plaid_account_id
tags array of numbers and/or strings Input must be an array, or error will be thrown. Passing in a number will attempt to match by ID. If no matching tag ID is found, an error will be thrown. Passing in a string will attempt to match by string. If no matching tag name is found, a new tag will be created. Pass in null to remove all tags.

Split Object

Key Type Required Description
payee string false Max 140 characters. Sets to original payee if none defined
date string false Must be in ISO 8601 format (YYYY-MM-DD). Sets to original date if none defined
category_id number false Unique identifier for associated category_id. Category must be associated with the same account. Sets to original category if none defined
notes string false Sets to original notes if none defined
amount number/string true Individual amount of split. Currency will inherit from parent transaction. All amounts must sum up to parent transaction amount.

Unsplit Transactions

Use this endpoint to unsplit one or more transactions.

Example 200 Response

[84389, 23212, 43333]

Example 404 Response

{
  "error": "The following transaction ids are not valid to unsplit: 1232, 1233, 1234"
}

Returns an array of IDs of deleted transactions

HTTP Request

POST https://dev.lunchmoney.app/v1/transactions/unsplit

Body Parameters

Parameter Type Required Default Description
parent_ids array of numbers true - Array of transaction IDs to unsplit. If one transaction is unsplittable, no transaction will be unsplit.
remove_parents boolean false false If true, deletes the original parent transaction as well. Note, this is unreversable!

Get Transaction Group

Use this endpoint to get the parent transaction and associated children transactions of a transaction group.

Example 200 Response

{
  "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
}

Example 404 Response

{
  "error": [
    "Transaction 35360525 is not a transaction group, or part of a transaction group."
  ]
}

Returns the hydrated parent transaction of a transaction group

HTTP Request

GET https://dev.lunchmoney.app/v1/transactions/group

Query Parameters

Parameter Type Required Description
transaction_id number true Transaction ID of either the parent or any of the children in the transaction group

Create Transaction Group

Use this endpoint to create a transaction group of two or more transactions.

Example 200 Response

84389

Example 404 Response

{
  "error": [
    "Transaction 35360525 is in a transaction group already (35717487) and cannot be added to another transaction group."
  ]
}

Returns the ID of the newly created transaction group

HTTP Request

POST https://dev.lunchmoney.app/v1/transactions/group

Body Parameters

Parameter Type Required Default Description
date string true - Date for the grouped transaction
payee string true - Payee name for the grouped transaction
category_id number false - Category for the grouped transaction
notes string false - Notes for the grouped transaction
tags array false - Array of tag IDs for the grouped transaction
transactions array true - Array of transaction IDs to be part of the transaction group

Delete Transaction Group

Use this endpoint to delete a transaction group. The transactions within the group will not be removed.

Example 200 Response

{ "transactions": [121232, 324324, 545455] }

Example 404 Response

{ "error": ["No transactions found for this group_id 35717487."] }

Returns the IDs of the transactions that were part of the deleted group

HTTP Request

DELETE https://dev.lunchmoney.app/v1/transactions/group/:transaction_id

Recurring Expenses

Recurring Expenses Object

Attribute Type Nullable Description
id number false Unique identifier for recurring expense
start_date string true Denotes when recurring expense starts occurring in ISO 8601 format. If null, then this recurring expense will show up for all time before end_date
end_date string true Denotes when recurring expense stops occurring in ISO 8601 format. If null, then this recurring expense has no set end date and will show up for all months after start_date
cadence string false One of:
  • monthly
  • twice a month
  • once a week
  • every 3 months
  • every 4 months
  • twice a year
  • yearly
payee string false Payee of the recurring expense
amount number false Amount of the recurring expense in numeric format to 4 decimal places
currency string false Three-letter lowercase currency code for the recurring expense in ISO 4217 format
description string true If any, represents the user-entered description of the recurring expense
billing_date string false Expected billing date for this recurring expense for this month in ISO 8601 format
type string false This can be one of two values:
  • cleared: The recurring expense has been reviewed by the user
  • suggested: The recurring expense is suggested by the system; the user has yet to review/clear it
original_name string true If any, represents the original name of the recurring expense as denoted by the transaction that triggered its creation
source string false This can be one of three values:
  • manual: User created this recurring expense manually from the Recurring Expenses page
  • transaction: User created this by converting a transaction from the Transactions page
  • system: Recurring expense was created by the system on transaction import
  • Some older recurring expenses may not have a source.
plaid_account_id number true If any, denotes the plaid account associated with the creation of this recurring expense (see Plaid Accounts)
asset_id number true If any, denotes the manually-managed account (i.e. asset) associated with the creation of this recurring expense (see Assets)
category_id number true If any, denotes the unique identifier for the associated category to this recurring expense
created_at string false The date and time of when the recurring expense was created (in the ISO 8601 extended format).

Get Recurring Expenses

Use this endpoint to retrieve a list of recurring expenses to expect for a specified period.

Every month, a different set of recurring expenses is expected. This is because recurring expenses can be once a year, twice a year, every 4 months, etc.

If a recurring expense is listed as “twice a month”, then that recurring expense will be returned twice, each with a different billing date based on when the system believes that recurring expense transaction is to be expected. If the recurring expense is listed as “once a week”, then that recurring expense will be returned in this list as many times as there are weeks for the specified month.

In the same vein, if a recurring expense that began last month is set to “Every 3 months”, then that recurring expense will not show up in the results for this month.

Example 200 Response

Returns a list of Recurring Expense objects

{
  "recurring_expenses": [
    {
      "id": 264,
      "start_date": "2020-01-01",
      "end_date": null,
      "cadence": "twice a month",
      "payee": "Test 5",
      "amount": "-122.0000",
      "currency": "cad",
      "created_at": "2020-01-30T07:58:43.944Z",
      "description": null,
      "billing_date": "2020-01-01",
      "type": "cleared",
      "original_name": null,
      "source": "manual",
      "plaid_account_id": null,
      "asset_id": null
    },
    {
      "id": 262,
      "start_date": "2020-01-01",
      "end_date": null,
      "cadence": "monthly",
      "payee": "Test 2",
      "amount": "-32.4500",
      "currency": "usd",
      "created_at": "2020-01-30T07:58:43.921Z",
      "description": "Test description 2",
      "billing_date": "2020-01-03",
      "type": "cleared",
      "original_name": null,
      "source": "manual",
      "plaid_account_id": null,
      "asset_id": null
    },
    {
      "id": 264,
      "start_date": "2020-01-01",
      "end_date": null,
      "cadence": "twice a month",
      "payee": "Test 5",
      "amount": "-122.0000",
      "currency": "cad",
      "created_at": "2020-01-30T07:58:43.944Z",
      "description": null,
      "billing_date": "2020-01-15",
      "type": "cleared",
      "original_name": null,
      "source": "manual",
      "plaid_account_id": null,
      "asset_id": null
    }
  ]
}

Example 404 Response

{ "error": "Invalid start_date. Must be in format YYYY-MM-DD" }

HTTP Request

GET https://dev.lunchmoney.app/v1/recurring_expenses

Parameter Type Required Default Description
start_date string false First day of the current month Accepts a string in ISO-8601 short format. Whatever your start date, the system will automatically return recurring expenses expected for that month. For instance, if you input 2020-01-25, the system will return recurring expenses which are to be expected between 2020-01-01 to 2020-01-31.
debit_as_negative boolean false false Pass in true if you’d like expenses to be returned as negative amounts and credits as positive amounts.

Budget

Budget Object

Attribute Name Type Nullable Description
category_name string false Name of the category, will be "Uncategorized" if no category is assigned
category_id number true Unique identifier for category, can be null when category_name is "Uncategorized"
category_group_name string true Name of the category group, if applicable
group_id number true Unique identifier for category group
is_group boolean true If true, this category is a group
is_income boolean false If true, this category is an income category (category properties are set in the app via the Categories page)
exclude_from_budget boolean false If true, this category is excluded from budget (category properties are set in the app via the Categories page)
exclude_from_totals boolean false If true, this category is excluded from totals (category properties are set in the app via the Categories page)
data Data[] false For each month with budget or category spending data, there is a data object with the key set to the month in format YYYY-MM-DD. For properties, see Data object below.
config object true Object representing the category's budget suggestion configuration
order number false Numerical ordering of budgets
archived boolean false True if the category is archived and not displayed in relevant areas of the Lunch Money app.
recurring object true Returns a list object that contains an array of Recurring Expenses objects (just the payee, amount, currency, and to_base fields) that affect this budget

Data Object

Attribute Name Type Nullable Description
budget_amount number true The budget amount, as set by the user. If empty, no budget has been set.
budget_currency string true The budget currency, as set by the user. If empty, no budget has been set.
budget_to_base number true The budget converted to the user's primary currency. If the multicurrency feature is not being used, budget_to_base and budget_amount will be the same. If empty, no budget has been set.
spending_to_base number false The total amount spent in this category for this time period in the user's primary currency
num_transactions number false Number of transactions that make up "spending_to_base"
is_automated boolean true If true, the budget_amount is only a suggestion based on the set config. If not present, it is false (meaning this is a locked in budget)

Config Object

Attribute Name Type Nullable Description
config_id number false Unique identifier for config
cadence string false One of:
  • monthly
  • twice a month
  • once a week
  • every 3 months
  • every 4 months
  • twice a year
  • yearly
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:
  • budgeted
  • fixed
  • fixed-rollover
  • spent

Get Budget Summary

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.

Example 200 Response

[
    {
        "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
                }
            ]
        }
    }
]

HTTP Request

GET https://dev.lunchmoney.app/v1/budgets

Query Parameters

Parameter Type Required Default Description
start_date string true - Start date for the budget period. Lunch Money currently only supports monthly budgets, so your date should be the start of a month (eg. 2021-04-01)
end_date string true - End date for the budget period. Lunch Money currently only supports monthly budgets, so your date should be the end of a month (eg. 2021-04-30)
currency string false - Currency for the budgeted amount (optional). If empty, will default to your primary currency

Upsert Budget

Use this endpoint to update an existing budget or insert a new budget for a particular category and date.

Note: Lunch Money currently only supports monthly budgets, so your date must always be the start of a month (eg. 2021-04-01)

Example 200 Response

If this is a sub-category, the response will include the updated category group's budget. This is because setting a sub-category may also update the category group's overall budget.

{
    "category_group": {
        "category_id": 34476,
        "amount": 100,
        "currency": "usd",
        "start_date": "2021-06-01"
    }
}

Example Error Response (sends as 200)

{ "error": "Budget must be greater than or equal to the sum of sub-category budgets ($10.01)." }

HTTP Request

PUT https://dev.lunchmoney.app/v1/budgets

Body Parameters

Parameter Type Required Default Description
start_date string true - Start date for the budget period. Lunch Money currently only supports monthly budgets, so your date must always be the start of a month (eg. 2021-04-01)
category_id number true - Unique identifier for the category
amount number true - Amount for budget
currency string false - Currency for the budgeted amount (optional). If empty, will default to your primary currency

Remove Budget

Use this endpoint to unset an existing budget for a particular category in a particular month.

Example 200 Response

true

Example Error Response (sends as 200)

{ "error": "start_date must be a valid date in format YYYY-MM-01" }

HTTP Request

DELETE https://dev.lunchmoney.app/v1/budgets

Query Parameters

Parameter Type Required Default Description
start_date string true - Start date for the budget period. Lunch Money currently only supports monthly budgets, so your date must always be the start of a month (eg. 2021-04-01)
category_id number true - Unique identifier for the category

Assets

Assets Object

Attribute Name Type Nullable Description
id number false Unique identifier for asset
type_name string false Primary type of the asset. Must be one of:
  • cash
  • credit
  • investment
  • real estate
  • loan
  • vehicle
  • cryptocurrency
  • employee compensation
  • other liability
  • other asset
subtype_name string true Optional asset subtype. Examples include:
  • retirement
  • checking
  • savings
  • prepaid credit card
    name string false Name of the asset
    display_name string true Display name of the asset (as set by user)
    balance string false Current balance of the asset in numeric format to 4 decimal places
    balance_as_of string false Date/time the balance was last updated in ISO 8601 extended format
    closed_on string true The date this asset was closed (optional)
    currency string false Three-letter lowercase currency code of the balance in ISO 4217 format
    institution_name string true Name of institution holding the asset
    exclude_transactions boolean false If true, this asset will not show up as an option for assignment when creating transactions manually
    created_at string false Date/time the asset was created in ISO 8601 extended format

    Get All Assets

    Use this endpoint to get a list of all manually-managed assets associated with the user's account.

    Example 200 Response

    {
  "assets": [
    {
      "id": 72,
      "type_name": "cash",
      "subtype_name": "physical cash",
      "name": "Test Asset 1",
      "balance": "1201.0100",
      "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",
      "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",
      "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",
      "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"
    }
  ]
}

    HTTP Request

    GET https://dev.lunchmoney.app/v1/assets

    Create Asset

    Use this endpoint to create a single (manually-managed) asset.

    Example 200 Response

    {
  "id": 34061,
  "type_name": "depository",
  "subtype_name": null,
  "name": "My Test Asset",
  "display_name": null,
  "balance": "67.2100",
  "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
}

    HTTP Request

    POST https://dev.lunchmoney.app/v1/assets

    Body Parameters

    Parameter Type Required Default Description
    type_name string true - Must be one of: cash, credit, investment, other, real estate, loan, vehicle, cryptocurrency, employee compensation
    subtype_name string false - Max 25 characters
    name string true - Max 45 characters
    display_name string false - Display name of the asset (as set by user)
    balance string true - Numeric value of the current balance of the account. Do not include any special characters aside from a decimal point!
    balance_as_of string false Current timestamp 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.
    currency string false User's primary currency 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 false - Max 50 characters
    closed_on string false - The date this asset was closed
    exclude_transactions boolean false false If true, this asset will not show up as an option for assignment when creating transactions manually

    Update Asset

    Use this endpoint to update a single asset.

    Example 200 Response

    {
  "id": 12,
  "type_name": "cash",
  "subtype_name": "savings",
  "name": "TD Savings Account",
  "balance": "28658.5300",
  "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 Error Response (sends as 200)

    {
  "errors": [
    "type_name must be one of: cash, credit, investment, other, real estate, loan, vehicle, cryptocurrency, employee compensation"
  ]
}

    HTTP Request

    PUT https://dev.lunchmoney.app/v1/assets/:id

    Body Parameters

    Parameter Type Required Default Description
    type_name string false - Must be one of: cash, credit, investment, other, real estate, loan, vehicle, cryptocurrency, employee compensation
    subtype_name string false - Max 25 characters
    name string false - Max 45 characters
    display_name string false - Display name of the asset (as set by user)
    balance string false - Numeric value of the current balance of the account. Do not include any special characters aside from a decimal point!
    balance_as_of string false Current timestamp 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.
    currency string false User's primary currency 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 false - Max 50 characters
    closed_on string false - The date this asset was closed
    exclude_transactions boolean false false If true, this asset will not show up as an option for assignment when creating transactions manually

    Plaid Accounts

    Plaid Accounts Object

    Attribute Name Type Nullable Description
    id number false Unique identifier of Plaid account
    date_linked string false Date account was first linked in ISO 8601 format
    name string false Name of the account. Can be overridden by the user. Field is originally set by Plaid
    display_name string false Display name of the account, if not set it will return a concatenated string of institution and account name.
    type string false Primary type of account. Typically one of:
    • credit
    • depository
    • brokerage
    • cash
    • loan
    • Investment

        • This field is set by Plaid and cannot be altered
    subtype string true Optional subtype name of account. This field is set by Plaid and cannot be altered
    mask string false Mask (last 3 to 4 digits of account) of account. This field is set by Plaid and cannot be altered
    institution_name string false Name of institution associated with account. This field is set by Plaid and cannot be altered
    status string false 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
    • error: Account is in error with Plaid
    • not found: Account is in error with Plaid
    • not supported: Account is in error with Plaid
      balance string false Current balance of the account in numeric format to 4 decimal places. This field is set by Plaid and cannot be altered
      currency string false Currency of account balance in ISO 4217 format. This field is set by Plaid and cannot be altered
      balance_last_update string false Date balance was last updated in ISO 8601 extended format. This field is set by Plaid and cannot be altered
      limit number true Optional credit limit of the account. This field is set by Plaid and cannot be altered
      import_start_date string true Date of earliest date allowed for importing transactions. Transactions earlier than this date are not imported.
      last_import string true Timestamp in ISO 8601 extended format of the last time Lunch Money imported new data from Plaid for this account.
      last_fetch string true Timestamp in ISO 8601 extended format of the last successful check 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 string false 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.

      Get All Plaid Accounts

      Use this endpoint to get a list of all synced Plaid accounts associated with the user's account.

      Example 200 Response

      {
  "plaid_accounts": [
    {
      "id": 91,
      "date_linked": "2020-01-28",
      "name": "401k",
      "display_name": "",
      "type": "brokerage",
      "subtype": "401k",
      "mask": "7468",
      "institution_name": "Vanguard",
      "status": "inactive",
      "limit": null,
      "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": 89,
      "date_linked": "2020-01-28",
      "name": "Freedom",
      "display_name": "Freedom Card",
      "type": "credit",
      "subtype": "credit card",
      "mask": "1973",
      "institution_name": "Chase",
      "status": "active",
      "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",
    }
  ]
}

      Plaid Accounts are individual bank accounts that you have linked to Lunch Money via Plaid. You may link one bank but one bank might contain 4 accounts. Each of these accounts is a Plaid Account.

      HTTP Request

      GET https://dev.lunchmoney.app/v1/plaid_accounts

      Trigger Fetch from Plaid

      This is an experimental endpoint and parameters and/or response may change.

      Use this endpoint to trigger a fetch for latest data from Plaid.

      Example 200 Response

      true

      Returns true if there were eligible Plaid accounts to trigger a fetch for. Eligible accounts are those who last_fetch value is over 1 minute ago. (Although the limit is every minute, please use this endpoint sparingly!)

      Note 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.

      Body Parameters

      Parameter Type Required Default Description
      start_date string false - Start date for fetch (ignored if end_date is null)
      end_date string false - End date for fetch (ignored if start_date is null)
      plaid_account_id number false - Specific ID of a plaid account to fetch. If left empty, endpoint will trigger a fetch for all eligible accounts

      HTTP Request

      POST https://dev.lunchmoney.app/v1/plaid_accounts/fetch

      Crypto

      Crypto Object

      Attribute Name Type Nullable Description
      id number true Unique identifier for a manual crypto account (no ID for synced accounts)
      zabo_account_id number true Unique identifier for a synced crypto account (no ID for manual accounts, multiple currencies may have the same zabo_account_id)
      source string false One of:
      • synced: this account is synced via a wallet, exchange, etc.
      • manual: this account balance is managed manually
      name string false Name of the crypto asset
      display_name string true Display name of the crypto asset (as set by user)
      balance string false Current balance
      balance_as_of string false Date/time the balance was last updated in ISO 8601 extended format
      currency string false Abbreviation for the cryptocurrency
      status string false The current status of the crypto account. Either active or in error.
      institution_name string true Name of provider holding the asset
      created_at string false Date/time the asset was created in ISO 8601 extended format
      to_base number true The balance converted to the user's primary currency.

      Get All Crypto

      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.

      Example 200 Response

      {
    "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"
        },
    ]
}

      HTTP Request

      GET https://dev.lunchmoney.app/v1/crypto

      Update Manual Crypto Asset

      Use this endpoint to update a single manually-managed crypto asset (does not include assets received from syncing with your wallet/exchange/etc). These are denoted by source: manual from the GET call above.

      Example 200 Response

      {
    "id": 1,
    "source": "manual",
    "created_at": "2021-02-10T05:57:34.305Z",
    "name": "Shiba Token",
    "display_name": "SHIB",
    "balance": "12.000000000000000000",
    "currency": "SHIB",
    "status": "active",
    "institution_name": null
}

      Example Error Response (sends as 200)

      { "errors": [ "currency is invalid for crypto: fakecoin. It may not be supported yet. Request to get it supported via the app or support@lunchmoney.app" ] }

      HTTP Request

      PUT https://dev.lunchmoney.app/v1/crypto/manual/:id

      Body Parameters

      Parameter Type Required Default Description
      name string false - Official or full name of the account. Max 45 characters
      display_name string false - Display name for the account. Max 25 characters
      institution_name string false - Name of provider that holds the account. Max 50 characters
      balance number false - Numeric value of the current balance of the account. Do not include any special characters aside from a decimal point!
      currency string false - Cryptocurrency that is supported for manual tracking in our database

      Appendix

      Supported Currencies

      Supported Currencies in Lunch Money

      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

      Here you'll find a list of currently supported currencies in Lunch Money. If your currency is missing, please let us know via email at support@lunchmoney.app and we'll work on getting it added.