# Fill the sandbox with a demo business

`POST /sandbox/seed`

Requires the `businesses` scope.

For a `bk_test_` key only: creates a demo business with three customers, four issued documents (a paid invoice-receipt, an unpaid tax invoice with a due date, a dollar document in English with zero-rated VAT, a cash receipt), one open draft, one recorded expense and one expense draft, all through the same code path the API uses. Idempotent: a second call finds the seeded business and returns it with `seeded: false`. A live key is refused (`validation`).

## Response

`201`: `{ "ok": true, … }`

| Field | Type | | Description |
|---|---|---|---|
| `ok` | boolean | **required** |  |
| `seeded` | boolean | **required** | true when this call created the fixtures, false when they already existed. |
| `business` | Business | **required** | One Israeli dealer (עוסק), one of your end users. |
| `parties` | array of object |  |  |
| `documents` | array of object |  |  |
| `expenses` | array of object |  |  |

Errors: `400`, `401`, `403`, `429`. Every failure answers `{ "error", "reason", "hint", "param", "doc_url", "retryable", "request_id" }`: branch on `reason`, and read `hint` for what to change (https://docs.billos.co.il/errors.md).

## Examples

### cURL

```bash
curl -X POST "$BASE/sandbox/seed" \
  -H "X-Api-Key: $KEY"
```
### Node

```node
const res = await fetch(`${BASE}/sandbox/seed`, {
  method: 'POST',
  headers: {
    'X-Api-Key': KEY,
  },
})
const data = await res.json()
if (!data.ok) throw new Error(data.reason)
```
### Python

```python
import requests
res = requests.post(
    f"{BASE}/sandbox/seed",
    headers={"X-Api-Key": KEY},
)
data = res.json()
```