# Create a business

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](https://developers.lazyinvoice.co.il/embedded/objects/businesses/), 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](https://developers.lazyinvoice.co.il/embedded/api/usage/top-up/) and
[Extend the scan period](https://developers.lazyinvoice.co.il/embedded/api/usage/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.

```text
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](https://developers.lazyinvoice.co.il/embedded/objects/businesses/).

## Errors

Every error body is the [error envelope](https://developers.lazyinvoice.co.il/embedded/errors/). Any endpoint can also return 401, 429 and 500; [Errors](https://developers.lazyinvoice.co.il/embedded/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.

## Examples

### Create a business

```bash
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`

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

### Create a business with extras

```bash
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`

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

### The external ID is taken

```bash
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`

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

Added in: [October 2026](https://developers.lazyinvoice.co.il/embedded/changelog/#october-2026)