canonical: https://jentic.com/apis/example.ilucca.net/lucca-cleemy-expenses

# Example Ilucca Cleemy Expenses

Cleemy Expenses is Lucca's expense management API for submitting, approving, and reporting on employee expenses. Agents can list and create temporary expense items, attach receipts, and assemble them into expense claims that follow the company approval workflow. The spec covers expense capture and claim lifecycle, while users, departments, and absence data live in sibling Lucca APIs.

## For AI agents

Capture employee expense items, build expense claims, and move them through Lucca's approval workflow.

## Scope

Does not handle payroll, user directories, or organization structures - use for expense item capture and claim submission only.

## Capabilities

- List temporary expense items by owner, purchase date, or paging cursor
- Create a new temporary expense entry with purchase metadata for later claim assembly
- Retrieve a specific temporary expense item by id for review or editing
- Initiate a new expense claim that bundles approved temporary items
- Look up an existing expense claim and the items attached to it
- Filter expense data with date-range comparators such as since, until, and between

## Use cases

### Monthly expense claim submission

At the end of each month, an employee or assistant agent sweeps all unattached temporary expense items, attaches them to a new expense claim, and submits the claim for manager approval. Cleemy handles the claim numbering, totals, and routing through Lucca's approval workflow, so the agent only needs to call list, create-claim, and attach operations.

Example prompt: List all temporary expense items for user 1234 with purchasedOn between 2026-05-01 and 2026-05-31, then create an expense claim that includes them and submit it for approval.

### Card-feed expense capture

When a corporate card transaction lands in a finance system, an integration agent creates a corresponding temporary expense item in Cleemy with the merchant, amount, and purchase date. This pre-populates the employee's Cleemy inbox so they only need to attach a receipt and categorise the spend, cutting manual data entry from the expense process.

Example prompt: Create a temporary expense item for owner 1234 with amount 87.50 EUR and purchasedOn 2026-06-08 representing a corporate card transaction at a hotel.

### Reimbursement reconciliation

A finance agent pulls the list of expense claims for a given period and reconciles them against payment runs, ensuring every approved claim has been paid out. Because the Cleemy spec exposes claim ids, owners, and item totals, the agent can match claims to payroll lines without manual export.

Example prompt: Retrieve expense claim 987 and compare its total amount to the corresponding reimbursement line in this month's payroll run.

### AI agent expense assistant via Jentic

An employee-facing AI assistant integrated through Jentic answers questions like 'what did I expense last week?' and 'submit all my pending lunches'. Jentic handles credential isolation and operation discovery, so the assistant calls Cleemy's list and create endpoints without ever seeing the raw API key.

Example prompt: Use Jentic to search for 'list employee expenses', load the Cleemy list-temp-items operation, and return all items for the current user purchased in the last 7 days.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /api/v3/expenseTempItems | List temporary expense items with optional filters |
| POST | /api/v3/expenseTempItems | Create a new temporary expense item |
| GET | /api/v3/expenseTempItems/{expenseTempItemId} | Retrieve a specific temporary expense item |
| POST | /api/v3/expenseClaims/creation | Start a new expense claim |
| GET | /api/v3/expenseClaims | List expense claims |

## Key resources

- **Expenses** — Temporary expense items captured before being assembled into a claim
- **ExpenseClaims** — Submitted claims that group expense items for approval and reimbursement

## Why Jentic

- **Setup:** Wiring Cleemy Expenses by hand means learning its header API key auth on your Lucca tenant host, tracking the /api/v3 expense-item and claim endpoints, and handling errors yourself. Through Jentic you install once, import Cleemy Expenses from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** Cleemy puts the item id in the URL path (/api/v3/expenseTempItems/{expenseTempItemId}), so a rule can pin your agent to one expense item and the read paths around it. You choose the operations it may call, so claim creation via /expenseClaims/creation is not included unless you add it.
- **Credential handling:** Your Cleemy 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 'list employee expenses' or 'create an expense claim', and Jentic returns the matching Cleemy operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Lucca Directory** — Provides the user records that own Cleemy expense items
- **Ramp** — US-focused corporate card and expense platform with built-in card issuing
- **Expensify** — Standalone expense management platform with receipt scanning
- **Brex** — Corporate card whose transaction feed can populate Cleemy expense items

## FAQ

### What authentication does the Cleemy Expenses API use?

Cleemy Expenses uses an API key passed in the Authorization header. Through Jentic, the key is stored encrypted in your Jentic One instance and never enters the agent's context - the agent receives a scoped token that is exchanged at call time.

### Can I create expense claims through the Cleemy Expenses API?

Yes. POST /api/v3/expenseClaims/creation starts a new claim, and GET /api/v3/expenseClaims lists existing claims so an agent can verify status before bundling temporary items into a submission.

### How do I filter Cleemy expense items by date?

The purchasedOn query parameter on /api/v3/expenseTempItems supports comparators: ?purchasedOn=since,2026-01-01, ?purchasedOn=until,2026-01-31, and ?purchasedOn=between,2026-01-01,2026-01-31. This lets an agent pull exactly the items it needs without post-filtering.

### What are the rate limits for the Cleemy Expenses API?

The OpenAPI spec does not publish explicit rate limits. Lucca enforces per-tenant throttling at the platform level, so agents should handle 429 responses with exponential backoff and respect any Retry-After header returned by the gateway.

### How do I list a user's expenses through Jentic?

Run pip install jentic, then search for 'list employee expenses', load the Expenses_listTempItems operation, and execute it with ownerId set to the target user. Jentic returns the input schema so the agent can supply purchasedOn ranges without reading the spec directly.

### Does Cleemy Expenses cover users and departments too?

No. The Cleemy Expenses spec covers only expense items and claims. For user records use the Lucca Directory API, and for department structures use the Lucca Organization API - both are available in the Jentic API Directory.

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

Yes. Because you run Jentic One yourself, your own rules decide which Cleemy operations and credentials the agent may use. Since the expense item id sits in the URL path (/api/v3/expenseTempItems/{expenseTempItemId}), you can pin the agent to a single expense item and the read paths around it. You also choose the operation set, so claim creation via /api/v3/expenseClaims/creation stays off unless you explicitly allow it.