# Lili MCP - Quickstart

> 💡 **Need Help?** For any issues, questions, or integration support with the Lili MCP, please contact us at [dev@lili.co](mailto:dev@lili.co).


# Introduction

The Lili MCP (Model Context Protocol) server lets AI assistants — like Claude, Cursor, or any MCP-compatible client — securely access Lili business banking data on behalf of your users.

With the Lili MCP, an AI assistant can answer questions like:

- *"What's my current account balance?"*
- *"Show me all expenses over $500 last quarter"*
- *"How much have I set aside in my Tax Bucket?"*
- *"List my unpaid invoices"*


# Connection Details

| Property | Value |
|  --- | --- |
| MCP Server URL | `https://mcp.lili.co/mcp` |
| Transport | HTTP (Streamable HTTP, MCP spec 2025-03-26) |
| Authentication | OAuth 2.0 (Authorization Code flow) |


# Installation

## Claude Desktop

Add the following to your Claude Desktop configuration (`claude_desktop_config.json`):


```json
{
  "mcpServers": {
    "lili": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.lili.co/mcp"
      ]
    }
  }
}
```

On first use, you will be prompted to authorize via your Lili account credentials.

## Cursor

Install in Cursor

To open Cursor and automatically add the Lili MCP, click the button above. Alternatively, go to **Settings → MCP** and add:


```json
{
  "lili": {
    "url": "https://mcp.lili.co/mcp",
    "transport": "http"
  }
}
```

## VS Code

Install in VS Code

To open VS Code and automatically add the Lili MCP, click the button above. Alternatively, add the following to your `.vscode/mcp.json` file in your workspace:


```json
{
  "servers": {
    "lili": {
      "type": "http",
      "url": "https://mcp.lili.co/mcp"
    }
  }
}
```

To learn more, see the VS Code [documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).

## OpenClaw

OpenClaw is a container-isolated, self-hosted AI agent platform. To connect OpenClaw to the Lili MCP server, add the server details under the `mcpServers` section of your configuration file (typically `~/.openclaw/mcp.json` or `openclaw.json`):


```json
{
  "mcpServers": {
    "lili": {
      "url": "https://mcp.lili.co/mcp",
      "transport": "streamable-http"
    }
  }
}
```

Restart the OpenClaw gateway to apply the configuration:


```bash
openclaw gateway restart
```

## NanoClaw

NanoClaw is a secure, lightweight AI agent framework optimized for containerized workflows. To connect NanoClaw to the Lili MCP, configure the server in your NanoClaw configuration file (typically `nanoclaw.json` or `~/.config/nanoclaw.json`):


```json
{
  "mcpServers": {
    "lili": {
      "url": "https://mcp.lili.co/mcp",
      "transport": "http"
    }
  }
}
```

NanoClaw will launch and mount the Lili MCP integration automatically into the agent's container environment upon startup.

## Other MCP Clients

Any MCP client that supports HTTP transport and OAuth 2.0 can connect. Point the client at `https://mcp.lili.co/mcp` and follow the OAuth flow.

# Authentication

The Lili MCP uses OAuth 2.0 Authorization Code flow. When a user first connects:

1. The MCP client opens a browser window to the Lili authorization page
2. The user logs in with their Lili credentials
3. The user grants the requested permissions
4. The client receives an access token and begins making requests


Access tokens are scoped to the authenticated user. Accountants who manage multiple clients can switch between clients using the `list_customers` and `select_customer` tools.

# User Types

The Lili MCP supports two user types:

**Business Users** — owners of a Lili business bank account. They can access their own account data directly without specifying a `businessUserId`.

**Accountants** — professionals managing multiple client accounts. They must provide `businessUserId` in most tool calls. Use `list_customers` to enumerate accessible clients and `select_customer` to work with a specific one.

# Tools Reference

## Accountant Tools

These tools are only available to users authenticated as accountants.

### `list_customers`

Retrieve a list of all client business accounts that have granted access to you as their accountant. For each client, it returns their business name, contact details, connection status, and external ID.

**Request Parameters:** None

### `select_customer`

Establish an active session with a specific client account. This returns a confirmation with the selected client's external ID, which you can use to perform tasks on their behalf.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `customerExternalId` | string | Yes | External ID of the customer to select |


### `lili_get_accountant_profile`

Retrieve your registered accountant profile details, including your name, firm name, primary email address, and unique partner referral code.

**Request Parameters:** None

### `lili_list_accountant_clients`

Search and view your connected clients using a paginated query. You can filter results by business name or owner name to quickly locate a specific account.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `search` | string | No | Filter by business name or owner name |
| `page` | integer | No | Page number (0-based, default 0) |
| `size` | integer | No | Page size (max 50, default 20) |


### `lili_download_client_statement`

Directly download the most recent monthly bank statement PDF for a specified client account.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | Yes | Business user external ID from `lili_list_accountant_clients` |


### `lili_download_all_client_statements`

Download a consolidated ZIP archive containing the latest monthly bank statements for all your connected clients in one action.

**Request Parameters:** None

### `lili_get_client_access_status`

Check your current access status and authorization level for a specific client's business account, including any pending terms of service agreements.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | Required when called by an accountant |


### `lili_search_accountant_referrals`

Search, track, and monitor the status of client referrals you have sent, with full pagination and filters for business names or emails.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `search` | string | No | Filter by business name, owner name, or email |
| `page` | integer | No | Page number (0-based, default 0) |
| `size` | integer | No | Page size (max 50, default 20) |


### `lili_get_referral_invite_url`

Generate a unique, shareable invitation URL for a prospective client referral, allowing them to sign up under your accountant partner profile.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `referralExternalId` | string | Yes | Referral external ID from `lili_search_accountant_referrals` |


## Account

### `lili_get_account_summary`

Retrieve a comprehensive financial overview of a Lili business customer's primary checking account. This includes key details like the routing number, masked account number, and real-time balances in both USD and cents. It also provides the status and balances of any sub-accounts, such as the Tax Bucket or BusinessBuild credit card collateral.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only; from `list_customers`) |


### `lili_list_linked_external_accounts`

Retrieve a list of external bank accounts that the business customer has linked via Plaid. For security, full account numbers are never exposed. Instead, this returns safe metadata for each connected account, including the financial institution's name, a masked account number, account type, connection status, and external ID.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |


## Transactions

### `lili_search_transactions`

Search and filter the customer's transaction history using custom criteria. This tool supports pagination and allows filtering by date range, account number, transaction type (such as purchases or transfers), category, and USD amount. The results include detailed records with transaction IDs, merchant names, exact timestamps, pending status, and category codes.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |
| `startDate` | string | No | Start date (`YYYY-MM-DD`) |
| `endDate` | string | No | End date (`YYYY-MM-DD`) |
| `accountNo` | string | No | Filter by account number |
| `recordCnt` | integer | No | Max records to return (1–100, default 10) |
| `page` | integer | No | Page number (default 1) |
| `pending` | boolean | No | `true` = pending only, `false` = settled only, omit = all |
| `transactionType` | string | No | One of: `PURCHASE`, `FUND_TRANSFER`, `REFUND`, `CHECK_DEPOSIT`, `FEE`, `ATM`, `CACHE_DEPOSIT` |
| `category` | string | No | Category code from `lili_list_transaction_categories` |
| `minAmountUsd` | number | No | Minimum absolute amount in USD |
| `maxAmountUsd` | number | No | Maximum absolute amount in USD |


### `lili_get_transaction`

Retrieve deep, enriched details for a single transaction. By passing the transaction ID, type, account number, and the relevant date window, you'll get comprehensive details such as full merchant information, merchant category codes (MCC), location keys, categorization, and the exact settlement amount.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |
| `accountNo` | string | Yes | Account number from `lili_search_transactions` |
| `transactionType` | string | Yes | Transaction type from `lili_search_transactions` |
| `transactionId` | string | Yes | Transaction ID from `lili_search_transactions` |
| `startDate` | string | Yes | Start of the date window (`YYYY-MM-DD`) |
| `endDate` | string | Yes | End of the date window (`YYYY-MM-DD`) |


### `lili_list_transaction_categories`

Retrieve a complete list of Lili's transaction categories, categorized by income and expense types. Each entry provides a machine-readable code and a human-friendly display name. You can use these codes directly to filter transaction searches by category.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |


### `lili_get_transaction_receipt`

Download the digital receipt or document attached to a specific transaction. It returns the file type (such as JPEG or PDF), a suggested filename, and the raw file content encoded in Base64 format, making it easy to display or save.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |
| `transactionId` | string | Yes | Transaction ID from `lili_search_transactions` |


### `lili_get_transaction_locations`

Resolve abstract transaction location keys into full, human-readable address details. By sending up to 10 comma-separated keys, you'll receive precise location data including the street address, city, state, and geographic coordinates.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |
| `locationKeys` | string | Yes | Comma-separated location keys from transaction results (max 10) |


### `lili_export_transactions_csv`

Generate and export transaction data as a downloadable CSV file. It is optimized for short-term transaction exports and returns a Base64-encoded CSV string alongside a recommended filename. For broader date ranges, such as quarterly or annual summaries, we recommend generating a formal expense report instead.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |
| `startDate` | string | Yes | Start date (`YYYY-MM-DD`) |
| `endDate` | string | Yes | End date (`YYYY-MM-DD`) |
| `pending` | boolean | No | Filter by pending state |
| `minAmountUsd` | number | No | Minimum absolute amount in USD |
| `maxAmountUsd` | number | No | Maximum absolute amount in USD |
| `transactionType` | string | No | Transaction type filter |


## Financial Summary

### `lili_get_financial_summary`

Retrieve aggregated financial trends and time-series data for a customer. You can specify whether to fetch income, expenses, or net profit, and configure the time granularity (monthly, quarterly, or yearly) starting from a reference date. It returns a structured series of periods with balances and overall totals.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `customerExternalId` | string | Yes | External ID of the customer (from `select_customer`) |
| `chartType` | string | Yes | One of: `INCOME`, `EXPENSE`, `PROFIT` |
| `startDate` | string | Yes | Reference date within the desired period (`YYYY-MM-DD`) |
| `granularity` | string | No | One of: `MONTH`, `QUARTER`, `YEAR` (default: `MONTH`) |
| `isBusiness` | boolean | No | Filter to business transactions only (`true`/`false`/omit for all). Not applicable to `PROFIT`. |


## Invoices

### `lili_list_invoices`

Query and list the business's invoices, with optional filtering by status (such as unpaid, overdue, paid, or drafted). This returns a paginated list of invoices with their invoice numbers, statuses, due dates, recipient details, and total amounts.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `customerExternalId` | string | Yes | External ID of the customer (from `select_customer`) |
| `status` | string | No | Filter by status (default: `ALL`) |
| `page` | integer | No | Page number (0-based, default 0) |
| `size` | integer | No | Page size (max 100, default 50) |


### `lili_get_invoice`

Retrieve the complete details of a specific invoice. This includes deep-dive data such as the recipient's contact information, itemized line items (with quantities and unit prices), applied discounts, sales tax, payment terms, status, and the secure payment link.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `customerExternalId` | string | Yes | External ID of the customer (from `select_customer`) |
| `invoiceExternalId` | string | Yes | Invoice external ID from `lili_list_invoices` |


### `lili_list_invoice_service_items`

List the merchant's saved invoice item templates. These templates allow merchants to quickly reuse standard line items, returning predefined names, descriptions, and default unit prices.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `customerExternalId` | string | Yes | External ID of the customer (from `select_customer`) |


## Bills & Suppliers

### `lili_list_bills`

Retrieve a list of bills with flexible filtering by status (such as paid or pending) and sorting options (by due date or creation date). It returns key details for each bill including the supplier's name, currency, amount, due date, and payment history.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |
| `status` | string | No | One of: `PAID`, `PENDING`, `CANCELED`, `ALL` (default: `PENDING`) |
| `pageSize` | integer | No | Page size (max 100, default 50) |
| `pageNumber` | integer | No | Page number (0-based, default 0) |
| `sortBy` | string | No | Sort by: `DUE_DATE` or `CREATE_DATE` (default: `DUE_DATE`) |
| `sortDirection` | string | No | `ASC` or `DESC` (default: `ASC`) |


### `lili_get_bill`

Fetch comprehensive information for a specific bill, including its detailed recurring payment rules, historical payment logs, and current settlement status.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `billExternalId` | string | Yes | Bill external ID from `lili_list_bills` |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |


### `lili_get_bill_payment_methods`

Check and verify the available payment options for settling a specific bill. It returns valid payment methods (such as ACH or wire), their eligibility status, any payment limit restrictions, and the estimated fund arrival dates.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `billExternalId` | string | Yes | Bill external ID from `lili_list_bills` |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |


### `lili_download_bill_attachment`

Download the original PDF invoice or attachment associated with a bill. It returns the file type, a suggested filename, and the raw file content encoded in Base64 format.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `documentId` | string | Yes | Document ID from `lili_get_bill` |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |


### `lili_list_suppliers`

Retrieve a list of all saved business suppliers and vendors. This returns basic contact and location details for each supplier, along with their active payment methods.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |


### `lili_get_supplier`

Retrieve complete, structured payment routing instructions for a specific supplier. This covers all configured payment channels, including domestic ACH, domestic wire, international wire (with IBAN and SWIFT), and paper check details. For security, all bank account numbers are securely masked.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `supplierExternalId` | string | Yes | Supplier external ID from `lili_list_suppliers` |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |


## Cards

### `lili_list_cards`

List all debit and credit cards associated with the business account. It returns essential card metadata such as the product type, cardholder name, last 4 digits, status, and shipping date. To maintain PCI-DSS compliance, sensitive card data like CVV, expiration date, and the full PAN are never returned.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |


### `lili_get_businessbuild_card_details`

Retrieve detailed credit limits, balances, and payment terms for the BusinessBuild secured credit card. It returns the account and enrollment status, total credit limit, current usage, remaining spending power (open-to-buy), and the upcoming payment due date.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |


## Tax

### `lili_estimate_taxes`

Estimate the business's annual tax liabilities based on its year-to-date income and categorized tax-deductible expenses. It returns calculated federal income, self-employment, and state tax breakdowns, total estimated taxes owed, tax savings from write-offs, and the marginal tax rate for your next deductible dollar.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `incomeUsd` | number | No | Annual income in USD (uses default income if omitted) |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |


### `lili_get_tax_bucket`

Retrieve the status, balance, and automated configuration of the customer's Tax Bucket. It returns the current balance, active status, whether auto-save is enabled, the configured auto-set-aside percentage, and the estimated tax rate.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |


### `lili_search_tax_bucket_transactions`

Search and view the history of automatic transfers into and out of the Tax Bucket. It returns detailed logs of set-aside transactions, showing amounts, transfer directions (credit or debit), dates, descriptions, and completion statuses.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |
| `startDate` | string | No | Start date (`YYYY-MM-DD`) |
| `endDate` | string | No | End date (`YYYY-MM-DD`) |
| `recordCnt` | integer | No | Max records (default 10, max 100) |
| `page` | integer | No | Page number (default 1) |


## Statements & Documents

### `lili_list_statements`

Retrieve a chronological, most-recent-first list of monthly bank statements available for the checking account and sub-accounts. It provides unique statement IDs, year, month, and creation dates for easy retrieval.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |
| `year` | integer | No | Filter by year (e.g. `2024`) |
| `accountType` | string | No | One of: `MAIN_ACCOUNT`, `TAX_BUCKET`, `SAVING_BUCKET`, `EMERGENCY_BUCKET`, `LOC` |


### `lili_download_statement`

Download a full monthly bank statement in PDF format. It returns a suggested filename and the document content encoded in a Base64 string, allowing immediate downloading or viewing.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |
| `statementId` | string | Yes | Statement ID from `lili_list_statements` |


### `lili_list_tax_statements`

List all available tax statements and Schedule C reports generated for the business. This returns unique statement IDs, the tax year, the quarter (with quarter 5 representing the full-year report), and the document creation date.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |
| `year` | integer | No | Filter by year |


### `lili_download_tax_statement`

Download a selected tax statement or Schedule C report in PDF format as a Base64-encoded string, ready to be saved or reviewed.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |
| `statementId` | string | Yes | Statement ID from `lili_list_tax_statements` |


### `lili_download_expense_report`

Generate and download a comprehensive, beautifully structured expense report in PDF format. It supports custom date ranges or standardized periods (like year-to-date or last year) and handles all background generation and polling automatically, returning the final PDF as a Base64-encoded string.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |
| `periodType` | string | Yes | One of: `BEGINNING_OF_YEAR`, `LAST_YEAR`, `MONTHLY`, `QUARTERLY`, `ALL_TIME`, `CUSTOM` |
| `startDate` | string | No | Required when `periodType` is `CUSTOM` (`YYYY-MM-DD`) |
| `endDate` | string | No | Required when `periodType` is `CUSTOM` (`YYYY-MM-DD`) |
| `detailedReport` | boolean | No | Include detailed breakdown (default `false`) |


### `lili_download_bank_account_letter`

Download an official, signed bank account verification letter in PDF format. You can specify the required variant, including general account verification, ACH routing setup, or domestic/international wire instructions.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |
| `variant` | string | Yes | One of: `GENERAL`, `ACH`, `WIRE_DOMESTIC`, `WIRE_INTERNATIONAL` |


## Identity & Business Profile

### `lili_get_current_user`

Retrieve the personal and business profile details of the currently authenticated user, including their name, email address, and unique external ID.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |


### `lili_get_business_profile`

Fetch key details about the registered business entity, including its legal name, state of incorporation, date of incorporation, and entity type (such as LLC or S-Corp).

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |


### `lili_get_business_addresses`

Retrieve all registered, operational, and mailing addresses associated with the business entity and its primary owner.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |


### `lili_get_business_owners`

List all ultimate beneficial owners (UBOs) and stakeholders of the business, detailing their names, contact emails, specific roles, and ownership percentages.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |


### `lili_get_business_plan`

Check the business's current Lili tier and active benefits, including subscription plans (such as Smart or Premium) and whether they are enrolled in the BusinessBuild program.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |


### `lili_get_duns_details`

Retrieve the business's Dun & Bradstreet (D&B) DUNS number and associated registration details.

**Request Parameters:**

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `businessUserId` | string | No | External ID of the business customer (accountants only) |


# Error Handling

All tool errors return a JSON object:


```json
{
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication is required to use this tool.",
    "httpStatus": 401
  }
}
```

| Error code | Description |
|  --- | --- |
| `AUTHENTICATION_REQUIRED` | User is not authenticated |
| `ACCESS_DENIED` | Caller does not have access to the requested resource |
| `INVALID_PARAMETER` | A required parameter is missing or malformed |
| `NOT_FOUND` | The requested resource does not exist |
| `RATE_LIMITED` | Too many requests; retry after a short delay |
| `INTERNAL_ERROR` | An unexpected server-side error occurred |


# Examples

## Get account balance

**Business user:**


```
lili_get_account_summary
```

Response:


```json
{
  "accountExternalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "accountNumberMasked": "****4321",
  "routingNumber": "123456789",
  "isPrimaryUboChecking": true,
  "availableBalanceCents": 1245000,
  "availableBalanceUsd": "12450.00",
  "subAccounts": [
    { "bucketType": "TAX", "balanceCents": 310000, "balanceUsd": "3100.00" },
    { "bucketType": "BUSINESSBUILD_COLLATERAL", "balanceCents": 500000, "balanceUsd": "5000.00" }
  ]
}
```

**Accountant accessing a client:**


```
lili_get_account_summary businessUserId=abc-123
```

## Search transactions

List all purchases in April 2026 over $100:


```
lili_search_transactions
  startDate=2026-04-01
  endDate=2026-04-30
  transactionType=PURCHASE
  minAmountUsd=100
```

Response:


```json
{
  "page": 1,
  "totalCount": 3,
  "transactions": [
    {
      "transactionId": "txn-001",
      "accountNo": "4321",
      "transactionType": "PURCHASE",
      "amountCents": 24900,
      "amountUsd": "249.00",
      "merchantName": "Amazon Web Services",
      "timestamp": "2026-04-03T14:22:00Z",
      "pending": false,
      "categoryCode": "SOFTWARE",
      "locationKey": null
    }
  ]
}
```

## Get transaction categories


```
lili_list_transaction_categories
```

Response:


```json
[
  { "code": "SOFTWARE", "displayName": "Software & Apps", "transactionType": "EXPENSE" },
  { "code": "OFFICE_SUPPLIES", "displayName": "Office Supplies", "transactionType": "EXPENSE" },
  { "code": "PAYMENT_RECEIVED", "displayName": "Payment Received", "transactionType": "INCOME" }
]
```

Then filter transactions by category:


```
lili_search_transactions startDate=2026-01-01 endDate=2026-12-31 category=SOFTWARE
```

## Get financial summary

Monthly income for Q1 2026:


```
lili_get_financial_summary
  customerExternalId=abc-123
  chartType=INCOME
  startDate=2026-01-01
  granularity=MONTH
```

Response:


```json
{
  "chartType": "INCOME",
  "granularity": "MONTH",
  "totalAmountUsd": "18500.00",
  "totalAmountCents": 1850000,
  "series": [
    { "period": "January 2026", "amountCents": 600000, "amountUsd": "6000.00" },
    { "period": "February 2026", "amountCents": 550000, "amountUsd": "5500.00" },
    { "period": "March 2026", "amountCents": 700000, "amountUsd": "7000.00" }
  ]
}
```

## Estimate taxes


```
lili_estimate_taxes incomeUsd=80000
```

Response:


```json
{
  "estimatedTaxOwedCents": 2134000,
  "estimatedTaxOwedUsd": "21340.00",
  "taxSavingsCents": 42000,
  "taxSavingsUsd": "420.00",
  "incomeCents": 8000000,
  "incomeUsd": "80000.00",
  "deductiblesCents": 150000,
  "deductiblesUsd": "1500.00",
  "isDefaultIncome": false,
  "estimatedRateForNextDeductible": "0.27",
  "breakdown": {
    "federalIncomeTax": { "amountCents": 1280000, "amountUsd": "12800.00" },
    "selfEmploymentTax": { "amountCents": 612000, "amountUsd": "6120.00" },
    "stateTax": { "amountCents": 242000, "amountUsd": "2420.00" }
  }
}
```

## List and view invoices

List all unpaid invoices:


```
lili_list_invoices customerExternalId=abc-123 status=UNPAID
```

Response:


```json
{
  "invoices": [
    {
      "externalId": "inv-001",
      "invoiceNumber": "INV-0042",
      "status": "SENT",
      "amountCents": 500000,
      "amountUsd": "5000.00",
      "dueDate": "2026-06-01",
      "recipientName": "Acme Corp",
      "recipientEmail": "billing@acme.com"
    }
  ],
  "page": 0,
  "pageSize": 50,
  "totalCount": 1,
  "totalPages": 1
}
```

Get full invoice details:


```
lili_get_invoice customerExternalId=abc-123 invoiceExternalId=inv-001
```

Response:


```json
{
  "externalId": "inv-001",
  "invoiceNumber": "INV-0042",
  "status": "SENT",
  "recipient": { "name": "Acme Corp", "email": "billing@acme.com" },
  "description": "Consulting services April 2026",
  "totalAmountCents": 500000,
  "totalAmountUsd": "5000.00",
  "lineItems": [
    { "name": "Strategy consulting", "quantity": 10, "unitPriceCents": 50000, "unitPriceUsd": "500.00" }
  ],
  "paymentTerms": { "dueDate": "2026-06-01", "achPaymentAllowed": true },
  "payUrl": "https://pay.lili.co/inv-001"
}
```

## List bills


```
lili_list_bills status=PENDING sortBy=DUE_DATE sortDirection=ASC
```

Response:


```json
{
  "bills": [
    {
      "billExternalId": "bill-001",
      "billNumber": "BILL-0010",
      "status": "PENDING",
      "amountCents": 120000,
      "amountUsd": "1200.00",
      "currencyCode": "USD",
      "dueDate": "2026-05-30",
      "supplierName": "Office Depot",
      "createdDate": "2026-05-01"
    }
  ],
  "totalCount": 1,
  "pageSize": 50,
  "pageNumber": 0
}
```

## Download a bank statement

List available statements, then download one:


```
lili_list_statements year=2026
```

Response:


```json
{
  "statements": [
    { "statementId": "stmt-001", "year": 2026, "month": 4, "accountType": "MAIN_ACCOUNT", "createdDate": "2026-05-01" }
  ],
  "totalCount": 1
}
```


```
lili_download_statement statementId=stmt-001
```

Response:


```json
{
  "contentType": "application/pdf",
  "base64": "JVBERi0xLjQK...",
  "fileName": "statement-stmt-001.pdf"
}
```

## Download an expense report

Generate a year-to-date expense report:


```
lili_download_expense_report periodType=BEGINNING_OF_YEAR
```

Or for a custom date range:


```
lili_download_expense_report
  periodType=CUSTOM
  startDate=2026-01-01
  endDate=2026-03-31
  detailedReport=true
```

Response:


```json
{
  "contentType": "application/pdf",
  "base64": "JVBERi0xLjQK...",
  "fileName": "expense-report-2026-01-01-to-2026-03-31.pdf"
}
```

## Accountant workflow — access a client


```
list_customers
```

Response:


```json
[
  {
    "externalId": "abc-123",
    "businessName": "Acme LLC",
    "businessType": "LLC",
    "status": "CONNECTED",
    "email": "owner@acmellc.com",
    "firstName": "Jane",
    "lastName": "Smith"
  }
]
```

Select the client, then access their data:


```
select_customer customerExternalId=abc-123

lili_get_account_summary businessUserId=abc-123

lili_search_transactions businessUserId=abc-123 startDate=2026-01-01 endDate=2026-03-31
```

## Get Tax Bucket status


```
lili_get_tax_bucket
```

Response:


```json
{
  "balanceCents": 425000,
  "balanceUsd": "4250.00",
  "isActive": true,
  "isAutoSaveEnabled": true,
  "autoSetAsidePct": 25.0,
  "estimatedTaxRatePct": 27.0,
  "accountId": "tax-acct-001"
}
```

## Get business profile and owners


```
lili_get_business_profile
```

Response:


```json
{
  "legalName": "Acme LLC",
  "incorporationState": "DE",
  "incorporationDate": "2020-03-15",
  "incorporationType": "LLC"
}
```


```
lili_get_business_owners
```

Response:


```json
[
  {
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@acmellc.com",
    "ownershipPercent": 60,
    "role": "PRIMARY_OWNER"
  },
  {
    "firstName": "Bob",
    "lastName": "Jones",
    "email": "bob@acmellc.com",
    "ownershipPercent": 40,
    "role": "UBO"
  }
]
```

## Download a bank account letter

Get ACH routing instructions as a PDF:


```
lili_download_bank_account_letter variant=ACH
```

Response:


```json
{
  "contentType": "application/pdf",
  "base64": "JVBERi0xLjQK...",
  "fileName": "ACH Instructions Document.pdf"
}
```