# Multiple companies (multi-company) (https://docs.getbeel.com/en/api/companies)

Software houses, marketplaces and accountants manage their clients' companies from one account, with one API key.

Each company on Getbeel is a separate account, with its own fiscal data, invoices, bank and SDI sending. A **parent** account (your accounting firm, software house or marketplace) can have **client companies**: you create them, work on them in the app by switching between them, and the parent account's API key (or MCP connection) can act on each of them.

## The rules [#the-rules]

- Whoever adds a client company becomes its **owner**. Only a company's members see it: invite colleagues from the company's **Members** page, like the client.
- A parent account's key acts on a client company only if the member who created the key can manage that company (owner or member, not auditor). Otherwise the answer is `404 company_not_found`, the same as for a company that does not exist.
- One level only: a client company cannot have client companies. A client company does not see the parent account or the other client companies.
- If the parent account is deleted, the client companies stay, with their data and members.
- For now each company has its own plan: sending real invoices to SDI from a client company needs the SDI add-on on that company. With a test key the sandbox works on all of them, but only a live key can add companies or change their data (`403 livemode_required`).

## In the app [#in-the-app]

**Client companies** lists each company with its SDI status (fiscal data complete or what is missing, SDI sending on) and **Add company**. A name and VAT number are enough; complete the rest later in **Company data**. To work on a company, use **Open** or the selector at the top of the sidebar.

The **Client companies** entry is in the sidebar of teams that chose **Accountant** when getting started or that already have a client company. Everyone else finds the page in **Settings → Company → Manage client companies**. Inside a client company the entry is not shown: a client company cannot have client companies of its own.

## With the API [#with-the-api]

Create the company (scope `companies:write`, live key). The key's member becomes its owner, so the same key can use it right away:

```bash
curl -X POST https://www.getbeel.com/api/v1/companies \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rossi Srl",
    "vat_number": "01234567890",
    "regime_fiscale": "RF01",
    "address": "Via Roma", "street_number": "1",
    "postal_code": "20121", "city": "Milano", "province": "MI"
  }'
```

The response is the company, with its `id` and `sdi_readiness` (`ready` and the `missing` fields). Then send its `id` in the **`Getbeel-Company`** header on any other endpoint:

```bash
curl https://www.getbeel.com/api/v1/invoices \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Getbeel-Company: $COMPANY_ID"
```

Without the header, requests act on the key's own account. `GET /v1/me` with the header shows the company you are acting on.

| Endpoint                   | Scope             |                                                          |
| -------------------------- | ----------------- | -------------------------------------------------------- |
| `GET /v1/companies`        | `account:read`    | The key's account and the client companies it can act on |
| `POST /v1/companies`       | `companies:write` | Adds a client company                                    |
| `GET /v1/companies/{id}`   | `account:read`    | One company (or the account itself)                      |
| `PATCH /v1/companies/{id}` | `companies:write` | Changes only the fields sent                             |

`/v1/companies` is always relative to the key's account: the `Getbeel-Company` header does not apply there. A client company's key cannot create companies (`409 company_nesting_not_allowed`).

Keys created before this feature do not have the `companies:write` scope: create a new key to add companies over the API. Reading and acting on companies works with existing keys.

## With an AI assistant (MCP) [#with-an-ai-assistant-mcp]

The `list_companies` tool lists the companies, `create_company` adds one and `update_company` changes its data (live key); every other tool takes `company_id` to act on a client company. Ask for example: _"List my client companies and tell me which ones are not ready for SDI"_, or _"Draft an invoice for Rossi Srl…"_. Clients that allow custom headers can also use `Getbeel-Company`.

## Webhooks [#webhooks]

A client company's events go to the endpoints set up **on that company** (the company's Settings → API keys & MCP) and to the parent account's matching endpoints, as long as the member who added the parent's endpoint can still manage the company. The parent's copy carries `company_id` (the company's id, the `Getbeel-Company` value); the company's own copy does not.
