# List businesses, or find one by external_id

Returns your platform's businesses, a page at a time. Pass the previous page's `next_cursor` as
`cursor` to get the next page; [Pagination](https://developers.lazyinvoice.co.il/embedded/pagination/) explains the rules.

To find one business by your own ID, pass `external_id` instead. The response is then a page with
that business, or an empty page when no business of your platform has that `external_id`. Its
`next_cursor` is always null.

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

## Parameters

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `external_id` | string | No | Return only the business with this external ID: a page of zero or one, with no next page. Cannot be combined with `cursor`. |
| `cursor` | string | No | The `next_cursor` of the previous page. |
| `limit` | integer | No | Businesses per page, 1 to 100. Minimum 1. Maximum 100. Default `20`. |

## Responses

### 200 OK

A page of businesses. The body has these fields.

| Name | Type | Description |
| --- | --- | --- |
| `businesses` | array of [Business object](https://developers.lazyinvoice.co.il/embedded/objects/businesses/) | The businesses on this page. |
| `next_cursor` | string or null | Pass as `cursor` to get the next page; null on the last page. |

## 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`: an unknown query parameter, a `limit` that is not an integer from 1 to 100, an invalid `cursor`, an empty `external_id`, or `cursor` combined with `external_id`. Fix the request; `param` names the field at fault when there is one. |

## Retry safety

Safe to retry. It changes nothing.

## Async behavior and events

None. This endpoint only reads.

## Examples

### List businesses

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

Response: `200 OK`

```json
{
  "businesses": [
    {
      "biz_id": "biz_3TnWx7RcV1a8fKq2LmZp",
      "external_id": "customer-1043",
      "name": "Noa Cohen Studio",
      "created_at": "2026-10-02T09:15:41.208113+00:00"
    },
    {
      "biz_id": "biz_8fKq2LmZp4TnWx7RcV1a",
      "external_id": "customer-1042",
      "name": "Dana Levi Design",
      "created_at": "2026-10-02T09:14:03.512874+00:00"
    }
  ],
  "next_cursor": "eyJiaXpfaWQiOiAiYml6XzhmS3EyTG1acDRUbld4N1JjVjFhIn0="
}
```

### Find a business by your external ID

```bash
curl https://embedded-api.lazyinvoice.co.il/v1/businesses?external_id=customer-1042 \
  -H "Authorization: Bearer $LAZY_API_KEY"
```

Response: `200 OK`

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

### No business has that external ID

```bash
curl https://embedded-api.lazyinvoice.co.il/v1/businesses?external_id=customer-9999 \
  -H "Authorization: Bearer $LAZY_API_KEY"
```

Response: `200 OK`

```json
{
  "businesses": [],
  "next_cursor": null
}
```

### A limit out of range

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

Response: `400 Bad Request`

```json
{
  "error": {
    "code": "validation_error",
    "message": "limit must be at most 100",
    "param": "limit",
    "request_id": "q8Zr1Ndk2vLp0Xw7HcYt3Rb9Fs6Mj4Ge5Ua1Ki8Oy2Wn0Tz7Ql3Px=="
  }
}
```

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