canonical: https://jentic.com/apis/lumabill.ch/lumabill

# Lumabill Ch Lumabill API

The Lumabill API gives Pro and Lifetime subscribers programmatic access to Swiss invoicing and bookkeeping: it issues invoices, offers, credit notes, and recurring invoices, records payments, and posts journal entries against a chart of accounts. It also tracks clients, vendors, expenses, and reusable product items, imports bank statements and reconciles each transaction against invoices or expenses, and generates accounting reports for a fiscal year. Invoices support CHF, EUR, USD, and GBP with per-line VAT rates, and an account with several companies can target one profile per request with the X-Profile-Id header.

## For AI agents

Create and send Swiss invoices, record payments, log expenses, post journal entries, reconcile imported bank transactions, and generate accounting reports in Lumabill. Authenticates with an lmb_ bearer API key.

## Scope

Does not process card payments, run payroll, or file VAT returns with the tax authority. Use for Swiss invoicing, expenses, bookkeeping, and bank reconciliation in Lumabill only.

## Capabilities

- Issue invoices with line items, per-line vat_rate, and CHF, EUR, USD, or GBP currency via POST /invoices, then fetch a public share link
- Record a payment against an invoice through POST /payments and undo it with POST `/invoices/{id}/unpay`
- Create a credit note (Gutschrift) for an issued invoice and settle it against open invoices (Verrechnung)
- Post balanced journal entries with account_number, debit, and credit lines, and reverse a manual entry with a Storno
- Import a bank statement file and reconcile each transaction as MATCHED, CATEGORIZED, or IGNORED against invoices or expenses
- Schedule monthly, quarterly, or yearly recurring invoices from an invoice template
- Generate accounting reports for a fiscal year or date range via GET `/reports/{type}`

## Use cases

### Bookkeeping assistant through Jentic

An agent handles a freelancer's invoicing from a chat request. It searches Jentic for 'create a Lumabill invoice', receives POST /invoices with its lines, currency, and vat_rate fields, looks up the client with GET /clients, and creates the invoice with status sent. When the money arrives it records the payment with POST /payments against the invoice_id and a paidDate.

Example prompt: Call GET /clients with q 'Muster AG', then POST /invoices with that client_id, currency CHF, status sent, and one line of description 'Consulting March', quantity 10, price 150, vat_rate 8.1

### Bank reconciliation

Close the month by matching bank movements to the books. POST /bank-imports uploads a statement file for a bank_account_id, GET `/bank-imports/{id}/transactions` lists what came in, and PUT `/bank-transactions/{id}` marks each transaction MATCHED to an invoice or expense, CATEGORIZED to an account, or IGNORED.

Example prompt: Call GET `/bank-imports/{id}/transactions` with status UNMATCHED, find the transaction matching an open invoice amount, and call PUT `/bank-transactions/{id}` with status MATCHED and matchedInvoiceId

### Credit notes and settlements

Correct an issued invoice the Swiss way. POST `/invoices/{id}/credit-note` creates a Gutschrift for an issued invoice, and POST `/invoices/{id}/credit-allocations` settles the credit note against one or more open invoices (Verrechnung) by invoiceId and amount, with DELETE `/credit-allocations/{id}` to undo a settlement.

Example prompt: Call POST `/invoices/{id}/credit-note` for the disputed invoice, then POST `/invoices/{id}/credit-allocations` on the new credit note with allocations naming the open invoiceId and amount

### Expense capture and reporting

Log costs as they happen and report on them later. POST /expenses records an expense with description, amount, currency, date, and an optional receipt_url, POST `/expenses/{id}/pay` records the payment from a paymentAccountId, and GET `/reports/{type}` generates a report for a fiscal_year_id or date range.

Example prompt: Call POST /expenses with description 'Office supplies', amount 120, currency CHF, and today's date, then GET /reports to list report types and generate one for the current fiscal year

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/invoices` | Create an invoice |
| GET | `/invoices` | List invoices by status or client |
| POST | `/payments` | Record a payment against an invoice |
| POST | `/expenses` | Create an expense |
| POST | `/journal-entries` | Create a journal entry |
| POST | `/bank-imports` | Import bank transactions |
| PUT | `/bank-transactions/{id}` | Reconcile a bank transaction |
| GET | `/reports/{type}` | Generate a report |

## Key resources

- **Invoices and offers** — Invoices, offers, credit notes, settlements, share links, and recurring invoices
- **Payments** — Payments recorded against invoices and expenses, with undo
- **Clients and vendors** — Customer and supplier records with address and VAT number
- **Expenses** — Costs with VAT lines, receipts, and payment status
- **Ledger** — Chart of accounts and journal entries with Storno reversal
- **Banking** — Bank accounts, statement imports, and transaction reconciliation
- **Reports and profiles** — Fiscal reports and the company profiles an API key can reach

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 70 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 93 / 100
  - Developer Experience & Jentic Compatibility: 76 / 100
  - AI-Readiness & Agent Experience: 53 / 100
  - Agent Usability: 90 / 100
  - Security: 60 / 100
  - AI Discoverability: 66 / 100
- **View full report:** https://jentic.com/apis/lumabill.ch/lumabill/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Lumabill by hand means handling its lmb_ bearer key, sending X-Profile-Id when a key reaches several companies, paging with page and per_page, and backing off on 429 with Retry-After under separate read and write limits. Through Jentic you install once, import Lumabill from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Rules filter by method and path. The company profile travels in the X-Profile-Id header rather than the path, so bound the agent by operations: for example reads of invoices, expenses, and reports. Destructive ones like invoice deletion, bank import deletion, or journal entry withdrawal are not included unless you add them.
- **Credential handling:** Your Lumabill API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Lumabill invoice' or 'reconcile a bank transaction', and Jentic returns the matching Lumabill operation with its input schema, including enums like the reconciliation status, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **bexio API** — Swiss business software for invoicing, accounting, and contacts
- **Xero Accounting API** — Invoices, contacts, bank transactions, and reports in Xero
- **Invoice Ninja API** — Open-source invoicing, quotes, and payments
- **Stripe API** — Online card and wallet payments

## FAQ

### What authentication does the Lumabill API use?

Per its OpenAPI spec, the Lumabill API uses an HTTP bearer API key in the Authorization header, in the form Bearer lmb_..., created in the Lumabill dashboard under Settings, API Keys. Access is for Pro and Lifetime subscribers. If a key reaches several company profiles, add the X-Profile-Id header with the target profile's UUID. Through Jentic, the key is stored encrypted by your own Jentic One instance and injected at execution time.

### Can I reconcile bank transactions with the Lumabill API?

Yes. Upload a statement with POST /bank-imports and a bank_account_id, list its transactions with GET `/bank-imports/{id}/transactions`, and set each one with PUT `/bank-transactions/{id}` to a status such as MATCHED with a matchedInvoiceId or matchedExpenseId, CATEGORIZED with a bookToAccountId, or IGNORED.

### What are the rate limits for the Lumabill API?

The OpenAPI spec states reads (GET) are limited to 60 requests / minute per API key and writes (POST, PUT, DELETE) to 20 requests / minute per API key. Over the limit the API returns 429 Too Many Requests with a Retry-After header in seconds.

### How do I create an invoice in Lumabill through Jentic?

Install Jentic One, add the Lumabill API from the Jentic directory, and store your lmb_ key. Your agent searches for 'create a Lumabill invoice', receives POST /invoices with its input schema, and sends client_id, currency, and lines with description, quantity, price, and vat_rate. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Does the Lumabill API have a sandbox?

Yes. The spec lists a Development / Sandbox server on the api.dev.lumabill.ch host next to the production api.lumabill.ch host, so you can test invoice and journal flows before pointing an agent at live books.

### Is there a Lumabill MCP server?

You don't need an MCP server to give your agent Lumabill. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls it, finding operations by intent rather than loading a long tool list into its context.

### Can I limit what my agent is allowed to do with the Lumabill API?

Yes. For a reporting agent, allow only GET /invoices, GET /expenses, and GET `/reports/{type}`, so it can read figures and produce reports but cannot create invoices, post journal entries, or delete bank imports. The agent's calls are logged for review.