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

API clients

Language Made by Git repo
JavaScript with TypeScript support @joehoyle Link
Go @icco 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

Changelog

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

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?

If you're a paying member of Lunch Money, join our Slack community and chat with us in the #_api channel! For account-specific issues, email us at support@lunchmoney.app.


Categories

Categories Object

Attribute Name Type Description
id number A unique identifier for the category.
name string The name of the category. Must be between 1 and 40 characters.
description string The description of the category. Must not exceed 140 characters.
is_income boolean If true, the transactions in this category will be treated as income.
exclude_from_budget boolean If true, the transactions in this category will be excluded from the budget.
exclude_from_totals boolean If true, the transactions in this category will be excluded from totals.
updated_at string The date and time of when the category was last updated (in the ISO 8601 extended format).
created_at string The date and time of when the category was created (in the ISO 8601 extended format).
is_group boolean If true, the category is a group that can be a parent to other categories.
group_id number The ID of a category group (or null if the category doesn't belong to a category group).

Get All Categories

Use this endpoint to get a list of all categories 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
    },
    {
      "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
    }
  ]
}

HTTP Request

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

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.

Tags

Tags Object

Attribute Name Type Description
id number Unique identifier for tag
name string User-defined name of tag
description string User-defined description of tag

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"
    },
    {
        "id": 1808,
        "name": "Honeymoon",
        "description": "All honeymoon-related expenses"
    }
]

HTTP Request

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


Transactions

Transaction Object

Attribute Name Type Description
id number Unique identifier for transaction
date string Date of transaction in ISO 8601 format
payee string 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 Amount of the transaction in numeric format to 4 decimal places
currency string Three-letter lowercase currency code of the transaction in ISO 4217 format
notes string User-entered transaction notes If recurring_id is not null, this field will be description of associated recurring expense
category_id number Unique identifier of associated category (see Categories)
asset_id number Unique identifier of associated manually-managed account (see Assets) Note: plaid_account_id and asset_id cannot both exist for a transaction
plaid_account_id number Unique identifier of associated Plaid account (see Plaid Accounts) Note: plaid_account_id and asset_id cannot both exist for a transaction
status string One of the following: cleared: User has reviewed the transaction uncleared: User has not yet reviewed the transaction recurring: Transaction is linked to a recurring expense recurring_suggested: Transaction is listed as a suggested transaction for an existing recurring expense. User intervention is required to change this to recurring.
parent_id number 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.
is_group boolean True if this transaction represents a group of transactions. If so, amount and currency represent the totalled amount of transactions bearing this transaction’s id as their group_id. Amount is calculated based on the user’s primary currency.
group_id number Exists if this transaction is part of a group. Denotes the parent’s transaction ID
tags Tag[] Array of Tag objects
external_id string 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_name string The transactions original name before any payee name updates. For synced transactions, this is the raw original payee name from your bank.
type string (for synced investment transactions only) The transaction type as set by Plaid for investment transactions. Possible values include: buy, sell, cash, transfer and more
subtype string (for synced investment transactions only) The transaction type as set by Plaid for investment transactions. Possible values include: management fee, withdrawal, dividend, deposit and more
fees string (for synced investment transactions only) The fees as set by Plaid for investment transactions.
price string (for synced investment transactions only) The price as set by Plaid for investment transactions.
quantity string (for synced investment transactions only) The quantity as set by Plaid for investment transactions.

Get All Transactions

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

Example 200 Response

{
  "transactions": [
    {
      "id": 602,
      "date": "2020-01-01",
      "payee": "Starbucks",
      "amount": "4.5000",
      "currency": "cad",
      "notes": "Frappuccino",
      "category_id": null,
      "recurring_id": null,
      "asset_id": null,
      "plaid_account_id": null,
      "status": "cleared",
      "is_group": false,
      "group_id": null,
      "parent_id": null,
      "external_id": null,
      "original_name": "STARBUCKS NW 32804",
      "type": null,
      "subtype": null,
      "fees": null,
      "price": null,
      "quantity": null
    },
    {
      "id": 603,
      "date": "2020-01-02",
      "payee": "Walmart",
      "amount": "20.9100",
      "currency": "usd",
      "notes": null,
      "category_id": null,
      "recurring_id": null,
      "asset_id": 153,
      "plaid_account_id": null,
      "status": "uncleared",
      "is_group": false,
      "group_id": null,
      "parent_id": null,
      "external_id": "jf2r3t98o943",
      "original_name": "Walmart Superstore ON 39208",
      "type": null,
      "subtype": null,
      "fees": null,
      "price": null,
      "quantity": null
    }
  ]
}

Example 404 Response

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

Returns list of Transaction objects. 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
group_id number false - Filter by group_id (if the transaction is part of a specific group)
is_group boolean false - Filter by group (returns transaction groups)
status string false - Filter by status (Can be cleared or uncleared. For recurring transactions, use recurring)
offset number false - Sets the offset for the records returned
limit number false - Sets the maximum number of records to return. Note: The server will not respond with any indication that there are more records to be returned. Please check the response length to determine if you should make another call with an offset to fetch more transactions.
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.

Get Single Transaction

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

Example 200 Response

{
    "id": 31,
    "date": "2019-02-04",
    "payee": "Shell",
    "amount": "960.0000",
    "currency": "jpy",
    "notes": null,
    "category_id": 22,
    "recurring_id": null,
    "asset_id": null,
    "plaid_account_id": null,
    "status": "cleared",
    "is_group": false,
    "group_id": null,
    "parent_id": null,
    "has_children": null,
    "external_id": null,
    "original_name": "Shell Gas Station",
    "type": null,
    "subtype": null,
    "fees": null,
    "price": null,
    "quantity": 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 false, 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. If recurring_id is provided, the status will automatically be set to recurring or recurring_suggested depending on the type of recurring_id. 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 object false - Defines the split of a transaction. You may not split an already-split transaction, recurring transaction, or group transaction. (see Split object below)
transaction object true - Updates to transaction matching ID (see Update Transaction object below)
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 If recurring_id is provided, the status will automatically be set to recurring or recurring_suggested depending on the type of recurring_id. 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 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.

Split Object

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

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 Description
id number Unique identifier for recurring expense
start_date string 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 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 One of:
  • monthly
  • twice a month
  • once a week
  • every 3 months
  • every 3 months
  • every 4 months
  • twice a year
  • yearly
payee string Payee of the recurring expense
amount number Amount of the recurring expense in numeric format to 4 decimal places
currency string Three-letter lowercase currency code for the recurring expense in ISO 4217 format
description string If any, represents the user-entered description of the recurring expense
billing_date string Expected billing date for this recurring expense for this month in ISO 8601 format
type string 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 If any, represents the original name of the recurring expense as denoted by the transaction that triggered its creation
source string 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 If any, denotes the plaid account associated with the creation of this recurring expense (see Plaid Accounts)
asset_id number If any, denotes the manually-managed account (i.e. asset) associated with the creation of this recurring expense (see Assets)
transaction_id number If any, denotes the unique identifier for the associated transaction matching this recurring expense for the current time period
category_id number If any, denotes the unique identifier for the associated category to this recurring expense

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,
      "transaction_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,
      "transaction_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,
      "transaction_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 Description
category_name string Name of the category
category_id number Unique identifier for category
category_group_name string Name of the category group, if applicable
group_id number Unique identifier for category group
is_group boolean If true, this category is a group
is_income boolean If true, this category is an income category (category properties are set in the app via the Categories page)
exclude_from_budget boolean If true, this category is excluded from budget (category properties are set in the app via the Categories page)
exclude_from_totals boolean If true, this category is excluded from totals (category properties are set in the app via the Categories page)
data Array of data objects 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 Object representing the category's budget suggestion configuration

Data Object

Attribute Name Type Description
budget_amount number The budget amount, as set by the user. If empty, no budget has been set.
budget_currency string The budget currency, as set by the user. If empty, no budget has been set.
budget_to_base number 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 The total amount spent in this category for this time period in the user's primary currency
num_transactions number Number of transactions that make up "spending_to_base"
is_automated boolean 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)

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

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 Description
id number Unique identifier for asset
type_name string Primary type of the asset. Must be one of:
  • employee compensation
  • cash
  • vehicle
  • loan
  • cryptocurrency
  • investment
  • other
  • credit
  • real estate
subtype_name string Optional asset subtype. Examples include:
  • retirement
  • checking
  • savings
  • prepaid credit card
    name string Name of the asset
    display_name string Display name of the asset (as set by user)
    balance string Current balance of the asset in numeric format to 4 decimal places
    balance_as_of string Date/time the balance was last updated in ISO 8601 extended format
    closed_on string The date this asset was closed (optional)
    currency string Three-letter lowercase currency code of the balance in ISO 4217 format
    institution_name string Name of institution holding the asset
    created_at string 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",
                    "status": "active",
                    "institution_name": "Bank of Me",
                    "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",
                "status": "active",
                "institution_name": "Bank of You",
                "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",
                "status": "active",
                "institution_name": "Bank of Mom",
                "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",
                "status": "active",
                "institution_name": null,
                "created_at": "2020-01-26T12:27:22.765Z"
            }
        ]
    }
    

    HTTP Request

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

    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",
        "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
    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 - 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 - Three-letter lowercase currency in ISO 4217 format. The code sent must exist in our database. Defaults to asset's currency.
    institution_name string false - Max 50 characters

    Plaid Accounts

    Plaid Accounts Object

    Attribute Name Type Description
    id number Unique identifier of Plaid account
    date_linked string Date account was first linked in ISO 8601 extended format
    name string Name of the account. Can be overridden by the user. Field is originally set by Plaid
    type string 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 Optional subtype name of account. This field is set by Plaid and cannot be altered
    mask string Mask (last 3 to 4 digits of account) of account. This field is set by Plaid and cannot be altered
    institution_name string Name of institution associated with account. This field is set by Plaid and cannot be altered
    status string 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
      last_import string Date of last imported transaction in ISO 8601 extended format (not necessarily date of last attempted import)
      balance string Current balance of the account in numeric format to 4 decimal places. This field is set by Plaid and cannot be altered
      currency string Currency of account balance in ISO 4217 format. This field is set by Plaid and cannot be altered
      balance_last_update string Date balance was last updated in ISO 8601 extended format. This field is set by Plaid and cannot be altered
      limit number Optional credit limit of the account. This field is set by Plaid and cannot be altered

      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-28T14:15:09.111Z",
            "name": "401k",
            "type": "brokerage",
            "subtype": "401k",
            "mask": "7468",
            "institution_name": "Vanguard",
            "status": "inactive",
            "last_import": "2019-09-04T12:57:09.190Z",
            "balance": "12345.6700",
            "currency": "usd",
            "balance_last_update": "2020-01-27T01:38:11.862Z",
            "limit": null
          },
          {
            "id": 89,
            "date_linked": "2020-01-28T14:15:09.111Z",
            "name": "Freedom",
            "type": "credit",
            "subtype": "credit card",
            "mask": "1973",
            "institution_name": "Chase",
            "status": "active",
            "last_import": "2019-09-04T12:57:03.250Z",
            "balance": "0.0000",
            "currency": "usd",
            "balance_last_update": "2020-01-27T01:38:07.460Z",
            "limit": 15000
          }
        ]
      }
      

      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


      Crypto

      Crypto Object

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

      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.