# LUCA External API v1

> Token-authenticated, entity-scoped external API for payment reconciliation, AI bill import, and management-account reports. Live integrations call the production base URL **https://api.luca.pro**; the Try-It console on this reference targets a mock sandbox that returns documented example responses and never touches real data.

Base URL: https://api.luca.pro

## Authentication

Create a token in LUCA under **Settings → API Tokens → Create token**. Give it a name and a (mandatory) expiry - the token string is shown once, so copy it immediately.

- **Bound to one company.** A token can only ever touch the company that was active when it was created. For another company, create a separate token while that company is active.
- **Acts as you.** It carries the permissions of the LUCA user who created it; each endpoint needs the same permission the web app uses. (Tip: create a least-privilege integration user for the token.)
- **Expires / revocable.** An expired or revoked token returns `401`.

Send it on every request as the header `Authorization: Bearer <token>`.

## Using an AI app

An AI app that speaks MCP (Claude, ChatGPT, Cursor) can connect to https://api.luca.pro/mcp and use these actions as ready-made tools instead of calling the API itself. How to connect: https://developer.luca.pro/mcp

## Income

### Customers

Fields, examples and responses: https://developer.luca.pro/llms/customers.md

- GET /api/v1/customers: List customers
- POST /api/v1/customers: Create a customer
- GET /api/v1/customers/{customer}/invoices: List a customer's open invoices
- GET /api/v1/customers/{id}: Retrieve a customer
- PUT /api/v1/customers/{id}: Update a customer
- DELETE /api/v1/customers/{id}: Delete a customer
- POST /api/v1/customers/{id}/contacts: Add a contact to a customer
- PUT /api/v1/customers/{id}/contacts/{contactId}: Update a customer's contact
- DELETE /api/v1/customers/{id}/contacts/{contactId}: Delete a customer's contact

### Products & services

Fields, examples and responses: https://developer.luca.pro/llms/products-services.md

- GET /api/v1/product-services: List products & services
- POST /api/v1/product-services: Create a product/service
- GET /api/v1/product-services/{id}: Retrieve a product/service
- PUT /api/v1/product-services/{id}: Update a product/service
- DELETE /api/v1/product-services/{id}: Delete a product/service

### Quotations

Fields, examples and responses: https://developer.luca.pro/llms/quotations.md

- GET /api/v1/quotations: List quotations
- POST /api/v1/quotations: Create a quotation
- GET /api/v1/quotations/{id}: Retrieve a quotation
- PUT /api/v1/quotations/{id}: Update a quotation
- DELETE /api/v1/quotations/{id}: Delete a quotation
- POST /api/v1/quotations/{id}/send: Send a quotation
- PUT /api/v1/quotations/{id}/mark-as-sent: Mark a quotation as sent
- GET /api/v1/quotations/{id}/pdf: Download a quotation PDF
- POST /api/v1/quotations/{id}/convert: Convert a quotation to an invoice

### Cash sales

Fields, examples and responses: https://developer.luca.pro/llms/cash-sales.md

- GET /api/v1/cash-sales: List cash sales
- POST /api/v1/cash-sales: Create a cash sale
- GET /api/v1/cash-sales/{id}: Retrieve a cash sale
- PUT /api/v1/cash-sales/{id}: Update a cash sale
- DELETE /api/v1/cash-sales/{id}: Delete a cash sale
- GET /api/v1/cash-sales/{id}/pdf: Download a cash sale PDF

### Credit sales

Fields, examples and responses: https://developer.luca.pro/llms/credit-sales.md

- GET /api/v1/credit-sales: List credit sales
- POST /api/v1/credit-sales: Create a credit sale
- GET /api/v1/credit-sales/{id}: Retrieve a credit sale
- PUT /api/v1/credit-sales/{id}: Update a credit sale
- DELETE /api/v1/credit-sales/{id}: Delete a credit sale
- POST /api/v1/credit-sales/{id}/pay: Record a payment against a credit sale
- GET /api/v1/credit-sales/{id}/pdf: Download a credit sale PDF

### Invoices

Fields, examples and responses: https://developer.luca.pro/llms/invoices.md

- GET /api/v1/invoices/payment-status: Retrieve an invoice's payment status
- GET /api/v1/invoices/detail: Retrieve invoice details
- GET /api/v1/invoices/pdf: Download an invoice PDF
- GET /api/v1/invoices: List invoices
- POST /api/v1/invoices: Create an invoice
- POST /api/v1/invoices/renew: Renew an invoice
- GET /api/v1/invoices/{id}: Retrieve an invoice
- PUT /api/v1/invoices/{id}: Update an invoice
- DELETE /api/v1/invoices/{id}: Delete an invoice
- POST /api/v1/invoices/{id}/send: Send an invoice
- POST /api/v1/invoices/{id}/send-reminder: Send a payment reminder for an invoice

### Credit notes

Fields, examples and responses: https://developer.luca.pro/llms/credit-notes.md

- GET /api/v1/credit-notes: List credit notes
- POST /api/v1/credit-notes: Create a credit note
- GET /api/v1/credit-notes/{id}: Retrieve a credit note
- PUT /api/v1/credit-notes/{id}: Update a credit note
- DELETE /api/v1/credit-notes/{id}: Delete a credit note
- POST /api/v1/credit-notes/{id}/send: Send a credit note
- PUT /api/v1/credit-notes/{id}/mark-as-sent: Mark a credit note as sent
- GET /api/v1/credit-notes/{id}/pdf: Download a credit note PDF

### Sale receipts

Fields, examples and responses: https://developer.luca.pro/llms/sale-receipts.md

- GET /api/v1/sale-receipts: List sale receipts
- POST /api/v1/sale-receipts: Create a sale receipt
- GET /api/v1/sale-receipts/{id}: Retrieve a sale receipt
- PUT /api/v1/sale-receipts/{id}: Update a sale receipt
- DELETE /api/v1/sale-receipts/{id}: Delete a sale receipt
- GET /api/v1/sale-receipts/{id}/pdf: Download a sale receipt PDF

## Expense

### Vendors

Fields, examples and responses: https://developer.luca.pro/llms/vendors.md

- GET /api/v1/vendors: List vendors
- POST /api/v1/vendors: Create a vendor
- GET /api/v1/vendors/{vendor}/bills: List a vendor's open (payable) bills
- GET /api/v1/vendors/{id}: Retrieve a vendor
- PUT /api/v1/vendors/{id}: Update a vendor
- DELETE /api/v1/vendors/{id}: Delete a vendor

### Purchase orders

Fields, examples and responses: https://developer.luca.pro/llms/purchase-orders.md

- GET /api/v1/purchase-orders: List purchase orders
- POST /api/v1/purchase-orders: Create a purchase order
- GET /api/v1/purchase-orders/{id}: Retrieve a purchase order
- PUT /api/v1/purchase-orders/{id}: Amend a purchase order
- DELETE /api/v1/purchase-orders/{id}: Delete a purchase order
- POST /api/v1/purchase-orders/{id}/send: Send a purchase order
- PUT /api/v1/purchase-orders/{id}/mark-as-sent: Mark a purchase order as sent
- GET /api/v1/purchase-orders/{id}/pdf: Download a purchase order PDF
- POST /api/v1/purchase-orders/{id}/convert: Convert a purchase order to a bill

### Delivery orders

Fields, examples and responses: https://developer.luca.pro/llms/delivery-orders.md

- GET /api/v1/delivery-orders: List delivery orders
- POST /api/v1/delivery-orders: Record a delivery order
- GET /api/v1/delivery-orders/{id}: Retrieve a delivery order
- PUT /api/v1/delivery-orders/{id}: Amend a delivery order
- DELETE /api/v1/delivery-orders/{id}: Delete a delivery order
- PUT /api/v1/delivery-orders/{id}/mark-as-reviewed: Mark a delivery order as reviewed
- GET /api/v1/delivery-orders/{id}/file: Download a delivery order's scan

### Bills

Fields, examples and responses: https://developer.luca.pro/llms/bills.md

- GET /api/v1/bills/lookup: Retrieve a bill by reference
- GET /api/v1/bills: List bills
- POST /api/v1/bills: Create a bill
- GET /api/v1/bills/{id}: Retrieve a bill
- PUT /api/v1/bills/{id}: Amend a bill
- DELETE /api/v1/bills/{id}: Delete a bill
- POST /api/v1/bills/{id}/pay: Pay a bill
- GET /api/v1/bills/{id}/attachment: Download the vendor's uploaded document
- POST /api/v1/bills/{id}/attachment: File the supplier's document against a bill

### Bill payments

Fields, examples and responses: https://developer.luca.pro/llms/bill-payments.md

- GET /api/v1/bill-payments: List bill payments
- POST /api/v1/bill-payments: Create a bill payment
- GET /api/v1/bill-payments/{id}: Retrieve a bill payment
- PUT /api/v1/bill-payments/{id}: Amend a bill payment
- DELETE /api/v1/bill-payments/{id}: Delete a bill payment

### Debit notes

Fields, examples and responses: https://developer.luca.pro/llms/debit-notes.md

- GET /api/v1/debit-notes: List debit notes
- POST /api/v1/debit-notes: Create a debit note
- GET /api/v1/debit-notes/{id}: Retrieve a debit note
- PUT /api/v1/debit-notes/{id}: Amend a debit note
- DELETE /api/v1/debit-notes/{id}: Delete a debit note

### Luca AI bill import

Fields, examples and responses: https://developer.luca.pro/llms/luca-ai-bill-import.md

- POST /api/v1/luca-ai/bills/imports: Import bills with Luca AI
- GET /api/v1/luca-ai/bills/imports/{batchId}: Check an import's progress
- GET /api/v1/luca-ai/bills/drafts: List bill drafts
- GET /api/v1/luca-ai/bills/drafts/{id}: Retrieve one bill draft
- DELETE /api/v1/luca-ai/bills/drafts/{id}: Discard a bill draft
- POST /api/v1/luca-ai/bills/drafts/{id}/approve: Approve a draft and post the bill

## General ledger

### Journal entries

Fields, examples and responses: https://developer.luca.pro/llms/journal-entries.md

- GET /api/v1/journal-entries: List journal entries
- POST /api/v1/journal-entries: Create a journal entry
- GET /api/v1/journal-entries/{id}: Retrieve a journal entry
- POST /api/v1/journal-entries/{id}/reverse: Reverse a journal entry
- GET /api/v1/journal-entries/{id}/attachment: Download a journal entry's source document
- POST /api/v1/journal-entries/{id}/attachment: Attach a source document to a journal entry

### Journal entry drafts

Fields, examples and responses: https://developer.luca.pro/llms/journal-entry-drafts.md

- GET /api/v1/journal-entry-drafts: List journal entry drafts
- POST /api/v1/journal-entry-drafts: Create a journal entry draft
- GET /api/v1/journal-entry-drafts/{id}: Retrieve a journal entry draft
- PUT /api/v1/journal-entry-drafts/{id}: Amend a journal entry draft
- DELETE /api/v1/journal-entry-drafts/{id}: Discard a journal entry draft
- POST /api/v1/journal-entry-drafts/{id}/reject: Reject a journal entry draft
- POST /api/v1/journal-entry-drafts/{id}/approve: Approve and post a journal entry draft
- GET /api/v1/journal-entry-drafts/{id}/attachment: Download a draft's source document
- POST /api/v1/journal-entry-drafts/{id}/attachment: Attach a source document to a draft

### Bank transfers

Fields, examples and responses: https://developer.luca.pro/llms/bank-transfers.md

- GET /api/v1/bank-transfers: List bank transfers
- POST /api/v1/bank-transfers: Create a bank transfer

### Reporting periods

Fields, examples and responses: https://developer.luca.pro/llms/reporting-periods.md

- GET /api/v1/reporting-periods: List reporting periods
- POST /api/v1/reporting-periods: Open the next reporting period
- PUT /api/v1/reporting-periods/{id}: Change a reporting period's status

### Revaluations

Fields, examples and responses: https://developer.luca.pro/llms/revaluations.md

- GET /api/v1/revaluations/preview: Preview a revaluation
- GET /api/v1/revaluations: List revaluations
- POST /api/v1/revaluations: Post a revaluation
- GET /api/v1/revaluations/{id}: Retrieve a revaluation
- DELETE /api/v1/revaluations/{id}: Delete a revaluation

### Inventory adjustments

Fields, examples and responses: https://developer.luca.pro/llms/inventory-adjustments.md

- GET /api/v1/inventory-adjustments: List inventory adjustments
- POST /api/v1/inventory-adjustments: Post an inventory adjustment
- GET /api/v1/inventory-adjustments/{id}: Retrieve an inventory adjustment
- DELETE /api/v1/inventory-adjustments/{id}: Delete an inventory adjustment

### Opening balances

Fields, examples and responses: https://developer.luca.pro/llms/opening-balances.md

- GET /api/v1/opening-balances: Retrieve the opening balances
- PUT /api/v1/opening-balances: Replace the opening balances
- GET /api/v1/opening-balances/invoices: List opening invoices
- POST /api/v1/opening-balances/invoices: Record an opening invoice
- DELETE /api/v1/opening-balances/invoices/{id}: Delete an opening invoice
- GET /api/v1/opening-balances/bills: List opening bills
- POST /api/v1/opening-balances/bills: Record an opening bill
- DELETE /api/v1/opening-balances/bills/{id}: Delete an opening bill

## Reports & reference

### Reports

Fields, examples and responses: https://developer.luca.pro/llms/reports.md

- GET /api/v1/reports/balance-sheet: Retrieve the balance sheet
- GET /api/v1/reports/profit-and-loss: Retrieve the profit and loss
- GET /api/v1/reports/trial-balance: Retrieve the trial balance
- GET /api/v1/reports/general-ledger: Retrieve the general ledger
- GET /api/v1/reports/aged-receivables: Retrieve aged receivables
- GET /api/v1/reports/aged-payables: Retrieve aged payables
- GET /api/v1/reports/bank-register: Retrieve the bank register
- GET /api/v1/reports/gst: Retrieve the GST position
- GET /api/v1/reports/gst/transactions: List the lines behind the GST position
- GET /api/v1/reports/inventory: Retrieve an item's stock movements

### Report files

Fields, examples and responses: https://developer.luca.pro/llms/report-files.md

- POST /api/v1/reports/{report}/files: Request a report file
- GET /api/v1/report-files/{id}: Get a report file
- GET /api/v1/report-files/{id}/download: Download a report file

### Companies

Fields, examples and responses: https://developer.luca.pro/llms/companies.md

- GET /api/v1/entities: List your companies

### Lookups

Fields, examples and responses: https://developer.luca.pro/llms/lookups.md

- GET /api/v1/payment-methods: List payment methods
- POST /api/v1/payment-methods: Create a payment method
- GET /api/v1/accounts: List accounts
- POST /api/v1/accounts: Create an account
- PATCH /api/v1/accounts/{id}: Update an account
- GET /api/v1/tax-codes: List tax codes

### Exchange rates

Fields, examples and responses: https://developer.luca.pro/llms/exchange-rates.md

- GET /api/v1/exchange-rates: List exchange rates
- PUT /api/v1/exchange-rates/{currency_code}: Set a currency's exchange rate

## Financial statements

### Financial statements (UFS)

Fields, examples and responses: https://developer.luca.pro/llms/financial-statements-ufs.md

- GET /api/v1/ufs-drafts: List UFS drafts
- POST /api/v1/ufs-drafts: Start a UFS draft
- GET /api/v1/ufs-drafts/{id}: Retrieve a UFS draft
- GET /api/v1/ufs-drafts/{id}/document: Download the UFS document
- GET /api/v1/ufs-drafts/{id}/trial-balance: Retrieve a UFS draft's trial balance
- GET /api/v1/ufs-drafts/{id}/sfp: Retrieve a UFS draft's statement of financial position
- GET /api/v1/ufs-drafts/{id}/sci: Retrieve a UFS draft's statement of comprehensive income
- GET /api/v1/ufs-drafts/{id}/sce: Retrieve a UFS draft's statement of changes in equity
- GET /api/v1/ufs-drafts/{id}/scf: Retrieve a UFS draft's statement of cash flows
- GET /api/v1/ufs-drafts/{id}/detailed-pl: Retrieve a UFS draft's detailed profit and loss
- GET /api/v1/ufs-drafts/{id}/account-mappings: Retrieve a UFS draft's account mapping
- PUT /api/v1/ufs-drafts/{id}/account-mappings: Map accounts to statement lines
- GET /api/v1/ufs-drafts/{id}/prior-year-comparatives: Retrieve a UFS draft's prior-year comparatives
- PUT /api/v1/ufs-drafts/{id}/prior-year-comparatives: Save a UFS draft's prior-year comparatives
- GET /api/v1/ufs-drafts/{id}/notes: Retrieve a UFS draft's notes
- PATCH /api/v1/ufs-drafts/{id}/notes: Update a UFS draft's notes
- PUT /api/v1/ufs-drafts/{id}/statement-date: Set or clear a UFS draft's statement date
- POST /api/v1/ufs-drafts/{id}/resync-company: Re-read the company into a UFS draft
- POST /api/v1/ufs-drafts/{id}/trial-balance/refresh: Refresh a UFS draft's trial balance
- PUT /api/v1/ufs-drafts/{id}/signing-directors: Choose a UFS draft's signing directors
- POST /api/v1/ufs-drafts/{id}/sections/{section}/review: Mark a UFS draft's section reviewed
- POST /api/v1/ufs-drafts/{id}/generate: Generate a UFS draft's Word document
- PATCH /api/v1/ufs-drafts/{id}/sections/{section}: Change one section of a UFS draft
- POST /api/v1/ufs-drafts/{id}/prior-year-comparatives/lock: Lock a UFS draft's prior-year comparatives
- POST /api/v1/ufs-drafts/{id}/prior-year-comparatives/unlock: Unlock a UFS draft's prior-year comparatives
- POST /api/v1/ufs-drafts/{id}/notes/load: Load a UFS draft's notes
- POST /api/v1/ufs-drafts/{id}/line-notes: Add a custom note to a UFS draft's line
- DELETE /api/v1/ufs-drafts/{id}/line-notes/{key}: Remove a custom note from a UFS draft
- GET /api/v1/ufs-drafts/{id}/preflight: Preflight a UFS draft

## Corporate tax

### Corporate tax computations

Fields, examples and responses: https://developer.luca.pro/llms/corporate-tax-computations.md

- GET /api/v1/tax-computations/available-years: List the years a tax computation can be computed for
- GET /api/v1/tax-computations: List tax computations
- POST /api/v1/tax-computations: Start a tax computation
- GET /api/v1/tax-computations/{id}: Retrieve a tax computation
- DELETE /api/v1/tax-computations/{id}: Delete a tax computation
- GET /api/v1/tax-computations/{id}/trial-balance: Retrieve a tax computation's trial balance
- GET /api/v1/tax-computations/{id}/mappings: Retrieve a tax computation's account treatments
- PUT /api/v1/tax-computations/{id}/mappings: Set account treatments
- GET /api/v1/tax-computations/{id}/schedules: Retrieve a tax computation's Schedule I
- GET /api/v1/tax-computations/{id}/fixed-assets: Retrieve a tax computation's fixed assets
- POST /api/v1/tax-computations/{id}/fixed-assets: Add a fixed asset
- GET /api/v1/tax-computations/{id}/medical: Retrieve a tax computation's medical expense cap
- GET /api/v1/tax-computations/{id}/results: Retrieve a tax computation's figures
- GET /api/v1/tax-computations/{id}/preflight: Check what stops a tax computation's document
- GET /api/v1/tax-computations/{id}/document: Download a tax computation's Word document
- POST /api/v1/tax-computations/{id}/document: Generate a tax computation's Word document
- GET /api/v1/tax-computations/{id}/workbook: Download a tax computation's Excel workbook
- POST /api/v1/tax-computations/{id}/workbook: Generate a tax computation's Excel workbook
- POST /api/v1/tax-computations/{id}/trial-balance/refresh: Refresh a tax computation's trial balance
- PUT /api/v1/tax-computations/{id}/inputs: Record a tax computation's answers
- GET /api/v1/tax-computations/{id}/schedules/{account_id}/ledger: Retrieve an account's ledger lines for Schedule I
- PUT /api/v1/tax-computations/{id}/schedules/{account_id}: Replace an account's Schedule I breakdown
- PUT /api/v1/tax-computations/{id}/fixed-assets/{asset_id}: Update a fixed asset
- DELETE /api/v1/tax-computations/{id}/fixed-assets/{asset_id}: Remove a fixed asset
- POST /api/v1/tax-computations/{id}/compute: Compute a tax computation