Core concepts
The Lazy Embedded API is built around four levels. Your platform owns businesses, one per customer. Each business has transactions, and each transaction groups one or more documents.
flowchart TD
Platform["Your platform"]
Platform --> B1["Business (tenant): customer-1042"]
Platform --> B2["Business (tenant): customer-1043"]
B1 --> T1["Transaction: one payment"]
B1 --> T2["Transaction: another payment"]
T1 --> D1["Document: tax invoice"]
T1 --> D2["Document: receipt"]
T2 --> D3["Document: utility bill"]
Platform
Section titled “Platform”Your platform is your company’s account with Lazy. It holds your API keys and your contract with Lazy. The contract sets each business’s limits and prices. Lazy bills your platform once a month for all its businesses and for the extras bought for them.
Business
Section titled “Business”A business is a tenant: one of your customers inside Lazy. Each business’s documents, transactions, settings and usage are isolated from every other business, including the other businesses of your platform. Create one business per customer, and never share a business between customers.
A business has two IDs:
| ID | Who chooses it | Used for |
|---|---|---|
biz_id |
Lazy | The path of every request about the business, such as /v1/businesses/{biz_id}. |
external_id |
Your platform | Linking the business to your own customer record, and finding it again. |
The external_id is unique within your platform. Creating a second business with the same
external_id fails with 409 business_exists, and the error names the existing business’s
biz_id. You can change a business’s external_id later with
Update a business.
A business also has tax info: its tax profile, such as its business type and whether it is registered for VAT. See the tax info object.
Deleting a business is permanent: there is no way to restore it.
Usage and limits
Section titled “Usage and limits”Each business has a monthly document allowance and a limit on how far back Lazy scans its email. The usage object shows both, along with how many documents the business used in the current period. You can raise either limit for one business:
- Top up documents adds documents to the current month.
- Extend the scan period makes Lazy scan further back, permanently.
Both purchases are billed to your platform in its next monthly bill.
Documents and transactions
Section titled “Documents and transactions”A document is one financial document of the business. Lazy reads these types:
- tax invoice
- tax invoice-receipt
- receipt
- proforma invoice
- credit note
- utility bill
- fine
- order confirmation
Documents reach Lazy in three ways:
- Email sync: Lazy scans the business’s connected mailbox.
- WhatsApp: the business sends documents to Lazy on WhatsApp.
- Manual upload: the business uploads a file.
A transaction is one payment, either revenue or expense, with the other side of the payment as its party: a supplier for an expense, a customer for revenue. Lazy groups the documents of one payment into its transaction. For example, the tax invoice and the receipt for the same purchase belong to one transaction. Every document belongs to exactly one transaction.
The API does not expose documents and transactions yet. The changelog announces them when it does.