Attaching receipts to expenses

When an expense nature requires a receipt (i.e. the receipt is mandatory), you must follow a three-step process to attach it. You cannot pass a file upload ID directly in the expenseReceipts array — doing so will result in a 403 Forbidden error.

Step 1 — Upload the file

First, upload the receipt file (image, PDF, etc.) using the Files API:

POST /lucca-files/api/uploads HTTP/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Accept: application/json
Content-Type: multipart/form-data; boundary=----FormBoundary

------FormBoundary
Content-Disposition: form-data; name="form"; filename="receipt.pdf"
Content-Type: application/pdf

< ./receipt.pdf
------FormBoundary--

{
  "id": "a24f4279-6bb4-4e1c-9b40-a80a5d44b36d",
  "name": "receipt.pdf",
  "createdAt": "2025-06-15T10:30:00Z",
  "deletedAt": null,
  "contentLength": 95683,
  "contentType": "application/pdf",
  "extension": ".pdf",
  "totalPages": 1
}

Save the returned id — this is your uploadId for the next step.

Step 2 — Create an ExpenseReceipt

Next, create an ExpenseReceipt resource by calling POST /api/v3/expenseReceipts. This step links the uploaded file to the Expenses module:

POST /api/v3/expenseReceipts HTTP/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Content-Type: application/json

{
  "ownerId": 123,
  "requiresOcr": false,
  "sourceId": "WebForm",
  "uploadId": "a24f4279-6bb4-4e1c-9b40-a80a5d44b36d"
}

{
  "id": "f0d01fd0-5f27-4061-8dca-bee6318b0103",
  "originalReceipt": {
    "id": "cb0aae89-56c9-48db-9052-48981660e0f7",
    "name": "receipt-f0d01fd0-5f27-4061-8dca-bee6318b0103.pdf",
    "href": "https://example.ilucca.net/api/v3/ExpenseReceipts/f0d01fd0-5f27-4061-8dca-bee6318b0103/originalReceiptFile",
    "extension": ".pdf"
  }
}

Property	Type	Description
`ownerId`	`integer`	The user ID of the expense owner. Must match the owner of the expense you will create at the next step.
`requiresOcr`	`boolean`	Set to `true` if you want Lucca to run OCR (optical character recognition) on the receipt to automatically extract data.
`sourceId`	`string`	The source of the receipt. Use `"WebForm"` when creating via API.
`uploadId`	`string (uuid)`	The `id` returned by `/lucca-files/api/uploads` in step 1.

Save the returned id (here f0d01fd0-...) — this is the ExpenseReceipt ID you will reference in the expense.

Step 3 — Create the expense with the receipt attached

Finally, create the expense via POST /api/v3/expenseTempItems, referencing the ExpenseReceipt by its id:

POST /api/v3/expenseTempItems HTTP/2
Host: example.ilucca.net
Authorization: lucca application={API_KEY}
Content-Type: application/json

{
  "expenseNatureId": 1,
  "purchasedOn": "2025-06-15",
  "paymentMethodId": 0,
  "quantity": 1,
  "originalTransaction": {
    "currencyId": "EUR",
    "grossAmount": 42.50
  },
  "processedAmounts": {
    "grossAmount": 42.50,
    "currencyId": "EUR"
  },
  "deviceId": "Web",
  "ownerId": 123,
  "merchant": "Restaurant ABC",
  "comment": "Business lunch",
  "expenseReceipts": [
    { "id": "f0d01fd0-5f27-4061-8dca-bee6318b0103" }
  ]
}

Do not pass the file upload ID (from step 1) directly in expenseReceipts. You must create an ExpenseReceipt resource first (step 2) and reference that ID. Passing the upload ID directly will result in a 403 Forbidden error with the message: “Property Id of type CleemyFile is not writable”.

Documentation

Files

Organization Structure API

Core HR API

Recruitment API

Expenses API

Invoices API

Absences API

Office API

Project API

Schedule API

Timesheet API

Mealvouchers API

Compensation API

Training API

Attaching receipts to expenses

Step 1 — Upload the file

Step 2 — Create an ExpenseReceipt

Step 3 — Create the expense with the receipt attached

Summary

​Step 1 — Upload the file

​Step 2 — Create an ExpenseReceipt

​Step 3 — Create the expense with the receipt attached

​Summary

Step 1 — Upload the file

Step 2 — Create an ExpenseReceipt

Step 3 — Create the expense with the receipt attached

Summary