# Getting started

The Lazy Embedded API lets your platform give each of your customers their own Lazy business. Lazy
collects that business's invoices and receipts, and your platform manages the business over HTTPS.

## Base URL

Every request goes to:

```text
https://embedded-api.lazyinvoice.co.il/v1
```

Requests and responses are JSON. Send every request from your server, never from a browser or a
mobile app, because each request carries your secret API key.

## Before you start

You need an API key. Lazy issues keys on request; see [Authentication](https://developers.lazyinvoice.co.il/embedded/authentication/).
The examples on this page read it from an environment variable:

```bash
export LAZY_API_KEY="<your API key>"
```

## How the API is organized

Your platform owns many businesses. You create one business for each of your customers and give it
your own ID for that customer, the `external_id`. Lazy gives the business its own ID, the `biz_id`.
Every other request about the business uses the `biz_id` in its path. See
[Core concepts](https://developers.lazyinvoice.co.il/embedded/core-concepts/) for the whole model.

## 1. 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"}'
```

Lazy answers `201 Created` with the new [business](https://developers.lazyinvoice.co.il/embedded/objects/businesses/):

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

Store the `biz_id` next to your customer record. If you lose it, find the business again by its
`external_id` with [List businesses](https://developers.lazyinvoice.co.il/embedded/api/businesses/list/).

## 2. Read the business back

```bash
curl https://embedded-api.lazyinvoice.co.il/v1/businesses/biz_8fKq2LmZp4TnWx7RcV1a \
  -H "Authorization: Bearer $LAZY_API_KEY"
```

The response is the same business object as in step 1.

## 3. Read the business's usage

```bash
curl https://embedded-api.lazyinvoice.co.il/v1/businesses/biz_8fKq2LmZp4TnWx7RcV1a/usage \
  -H "Authorization: Bearer $LAZY_API_KEY"
```

The [usage object](https://developers.lazyinvoice.co.il/embedded/objects/usage/) says how many documents the business has used this
month and what its limits are:

```json
{
  "reset_at": "2026-10-02T09:14:03.601127+00:00",
  "used_docs": 0,
  "max_docs": 65,
  "max_email_scan_days": 365
}
```

The limits come from your platform's contract with Lazy, so your numbers may differ.

## Next steps

- Handle failures: [Errors](https://developers.lazyinvoice.co.il/embedded/errors/) and [Retries and idempotency](https://developers.lazyinvoice.co.il/embedded/retries/).
- Page through many businesses: [Pagination](https://developers.lazyinvoice.co.il/embedded/pagination/).
- Stay inside the request limits: [Rate limits](https://developers.lazyinvoice.co.il/embedded/rate-limits/).
- See every endpoint: start with [Create a business](https://developers.lazyinvoice.co.il/embedded/api/businesses/create/).