# Share a business with a person

`POST /businesses/{bid}/access`

Requires the `businesses` scope.

Invite an email address with a role (`accountant`: read everything and generate the regulatory outputs; `bookkeeper`: the same plus recording expenses; `viewer`: read only), or an explicit list of fine scopes (`ocr` cannot be shared). The person sees the business in the console the first time they sign in with that address; an invitation email goes out for a new invite. Re-inviting an active address updates its scopes and answers `200` with `deduped: true`. Up to 20 people per business. Owner only.

## Path parameters

| Name | Type | | Description |
|---|---|---|---|
| `bid` | string | **required** | Business id, from `POST /businesses`. |

## Body

| Field | Type | | Description |
|---|---|---|---|
| `email` | string | **required** | The address the person signs in to the console with (Google). |
| `role` | string |  | A preset. Default `accountant`. One of: `accountant`, `bookkeeper`, `viewer`. |
| `scopes` | array of string |  | Overrides the preset when given. |
| `label` | string |  | Your own note, up to 80 chars. |

## Response

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

| Field | Type | | Description |
|---|---|---|---|
| `ok` | boolean | **required** |  |
| `access` | BusinessAccess | **required** | One person the owner let into a business. |
| `deduped` | boolean |  | An active row for this address already existed and was updated. |
| `emailed` | boolean |  | Whether the invitation email was sent. |

Errors: `400`, `401`, `403`, `404`, `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/businesses/$BID/access" \
  -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dana@example.com"
  }'
```
### Node

```node
const res = await fetch(`${BASE}/businesses/${BID}/access`, {
  method: 'POST',
  headers: {
    'X-Api-Key': KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "dana@example.com"
  }),
})
const data = await res.json()
if (!data.ok) throw new Error(data.reason)
```
### Python

```python
import requests
res = requests.post(
    f"{BASE}/businesses/{BID}/access",
    headers={"X-Api-Key": KEY},
    json={
      "email": "dana@example.com"
    },
)
data = res.json()
```