Create a business

View as Markdown

Creates a business, a tenant inside Lazy, for one of your customers. Give it your own ID for that customer as external_id, which must be unique within your platform. The response is the new Business object, with the biz_id that every other request about the business uses.

The business starts with the monthly document allowance and the email scan period your contract with Lazy sets. To start it with more, set top_up_units or scan_years. They are bought together with the business, the same as Top up documents and Extend the scan period, and billed to your platform in its next monthly bill.

Lazy bills your platform for the business from the day it is created, under your contract.

POST https://embedded-api.lazyinvoice.co.il/v1/businesses

Parameters

Body

A JSON object with these fields.

Name	Type	Required	Description
`name`	string	Yes	The business’s display name. Leading and trailing spaces are removed. Cannot be empty.
`external_id`	string	Yes	Your own ID for the business, unique within your platform. Leading and trailing spaces are removed. Cannot be empty.
`top_up_units`	integer	No	Top-up units to buy with the business. A unit is not one document: its size in documents is set in your contract with Lazy. Each unit adds that many documents to this month’s `max_docs`. Minimum 0. Maximum 100. Default `0`.
`scan_years`	integer	No	Years to add to how far back Lazy scans the business’s email. Permanent. Minimum 0. Maximum 10. Default `0`.

Responses

201 Created

The created business. The body is a Business object.

Errors

Every error body is the error envelope. Any endpoint can also return 401, 429 and 500; Errors explains them.

Status	Code, cause and what to do
400	`validation_error`: a body that is not valid JSON or not a JSON object, a missing, empty, mistyped, out-of-range or unknown field, or an unknown query parameter. Fix the request; `param` names the field at fault when there is one.
409	`business_exists`: another business of your platform already has this `external_id`; the error’s `biz_id` names it. Use that business, or choose another `external_id`. `billing_not_ready`: your platform’s billing is not set up yet; contact Lazy.

Retry safety

Safe to retry with the same external_id:

If the first request never created the business, the retry creates it and returns 201 Created.
If the first request created it, the retry returns 409 business_exists. The error’s biz_id names the business the first request created. Any top_up_units and scan_years in the request were bought once, by the first request.

Async behavior and events

None. The change is complete when the response arrives, and Lazy sends no webhook for it.

Added in: October 2026

Examples

curl -X POST https://embedded-api.lazyinvoice.co.il/v1/businesses \
  -H "Authorization: Bearer $LAZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Dana Levi Design", "external_id": "customer-1042"}'

Response: 201 Created

{
  "biz_id": "biz_8fKq2LmZp4TnWx7RcV1a",
  "external_id": "customer-1042",
  "name": "Dana Levi Design",
  "created_at": "2026-10-02T09:14:03.512874+00:00"
}

curl -X POST https://embedded-api.lazyinvoice.co.il/v1/businesses \
  -H "Authorization: Bearer $LAZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Noa Cohen Studio", "external_id": "customer-1043", "top_up_units": 2, "scan_years": 1}'

Response: 201 Created

{
  "biz_id": "biz_3TnWx7RcV1a8fKq2LmZp",
  "external_id": "customer-1043",
  "name": "Noa Cohen Studio",
  "created_at": "2026-10-02T09:15:41.208113+00:00"
}

curl -X POST https://embedded-api.lazyinvoice.co.il/v1/businesses \
  -H "Authorization: Bearer $LAZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Dana Levi Design", "external_id": "customer-1042"}'

Response: 409 Conflict

{
  "error": {
    "code": "business_exists",
    "message": "A business with this external_id already exists",
    "biz_id": "biz_8fKq2LmZp4TnWx7RcV1a",
    "request_id": "q8Zr1Ndk2vLp0Xw7HcYt3Rb9Fs6Mj4Ge5Ua1Ki8Oy2Wn0Tz7Ql3Px=="
  }
}