# Company groups
> Company groups: which companies a key reaches, the Ocost-Business header, routing by the document’s identifiers, needs_company, and files across the group.
>
> Before: [Keys and scopes](https://ocost.io/docs/en/authentication.md)

A group is the companies one owner runs in Ocost. One API key can send and read for several of them.

## What a key reaches

A key belongs to the company it was made in, its home. Only the owner gives it more companies of the group under [Settings › Developers](https://app.ocost.io/settings/api): a selection, or all, those joining later too. Ocost's support can set them too, each change shown under Settings. A new key reaches its home alone.

Its secret stays the same when its companies change. A company it no longer reaches, or that leaves the group, is refused from the next request.

`GET /public/v1/businesses` lists the companies a key reaches, its home first. Every key may ask it.

```bash
curl -sS https://api.ocost.io/public/v1/businesses \
  -H "Authorization: Bearer $OCOST_KEY"
```

```json
{
  "businesses": [
    { "id": "018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77", "name": "Beispiel Holding GmbH", "own": true },
    { "id": "018f3c2a-9a04-7c21-8e5b-6d2f4c0a9e15", "name": "Beispiel Nord GmbH", "own": false },
    { "id": "018f3c2a-b5e7-7f42-9d13-4a8c2e6f1b09", "name": "Beispiel Süd GmbH", "own": false }
  ]
}
```

## Name the company

Name the company a request acts in with the `Ocost-Business` header, its id. The header decides, and Ocost routes nothing. Without it, a request acts in the key's home.

```bash
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  -H "Ocost-Business: 018f3c2a-9a04-7c21-8e5b-6d2f4c0a9e15" \
  -F "file=@invoice.pdf"
```

A file sent this way has `routed_by: header`. A company the key doesn't reach is refused with `403 urn:ocost:key:business`. A header that isn't an id is a `400`.

## Let the document decide

Send without `Ocost-Business`, and a key that reaches several companies routes the file. Ocost reads it in the key's home and looks for the group's companies on the document before writing anything.

Only an exact identifier of a company counts:

| On the document | `routed_by` |
| --- | --- |
| VAT ID, or another tax or company number, such as an ІПН, NIP, EIN or IDNO | `vat_id` |
| Tax number, such as a Steuernummer | `tax_number` |
| ЄДРПОУ or РНОКПП | `edrpou` |
| Register number with its court | `register` |
| The company's IBAN, as the account to pay into | `iban` |

An incoming invoice names the company as its buyer, an outgoing one as its seller. A contract may name either party. A number read in doubt never counts. Neither does a name or an address.

A party's number may stand outside its block, as in a payment purpose "… для ТОВ «Приклад» 42135797" or a footer. Ocost attaches it to the party it follows. If no party carries a company's number, one anywhere in the text counts, never the seller's company's.

| The document names | The file |
| --- | --- |
| One company by its identifier | Moves there, with `routed_by` as above |
| No company of the group | Stays in the key's home, with `routed_by: home` |
| Two companies, or another one by its name alone | Waits as `needs_company` in the home |

A moved file keeps its id and counts in the month of the company it moved to.

## Assign a waiting file

A waiting file lists its `candidates`, each with `why`. The companies the document names come first, the key's home last.

```json
{
  "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1",
  "status": "needs_company",
  "business_id": "018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77",
  "routed_by": null,
  "candidates": [
    { "business_id": "018f3c2a-9a04-7c21-8e5b-6d2f4c0a9e15", "name": "Beispiel Nord GmbH", "why": "vat_id" },
    { "business_id": "018f3c2a-b5e7-7f42-9d13-4a8c2e6f1b09", "name": "Beispiel Süd GmbH", "why": "vat_id" },
    { "business_id": "018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77", "name": "Beispiel Holding GmbH", "why": "home" }
  ]
}
```

In Ocost, the owner or the accountant answers under Today › Assign. Or answer first with `PATCH /public/v1/files/{file_id}`:

```bash
curl -sS -X PATCH https://api.ocost.io/public/v1/files/$FILE_ID \
  -H "Authorization: Bearer $OCOST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"business_id": "018f3c2a-9a04-7c21-8e5b-6d2f4c0a9e15"}'
```

Either answer sets `routed_by: person`. Both your key and the sending key must reach the company. A file that doesn't wait answers `409`.

## Find files across the group

A key that names no company finds the files it sent in every company it reaches. `GET /public/v1/files/{file_id}`, its content and its document work by the file's id alone. So does `DELETE`.

`GET /public/v1/files` lists the home's files and those the key sent elsewhere. Each file's `business_id` says where it is. The `business_id` query keeps one company's:

```bash
curl -sS -G https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  --data-urlencode "business_id=018f3c2a-9a04-7c21-8e5b-6d2f4c0a9e15"
```

The same bytes already kept in a company of the reach answer that file. Ocost counts them once.

## The MCP in a group

The [MCP server](https://ocost.io/docs/en/mcp.md) takes the same keys and the same header. `send_file` without `Ocost-Business` routes as above. Every other tool acts in the company the header names, else in the key's home.

## See also

- [Keys and scopes](https://ocost.io/docs/en/authentication.md): API keys: how a request carries one, rotating them, their scopes, and the refusals.
- [Statuses and reasons](https://ocost.io/docs/en/statuses.md): A file's statuses and the reasons it wasn't read, and what to do for each.
- [The document](https://ocost.io/docs/en/document.md): The ocost.document.v1 schema in EN 16931 terms (maps to UBL and CII): an example, kind and direction, sources, checks, versions, and every field and value.
- [Connect an assistant](https://ocost.io/docs/en/mcp.md): Connect an assistant to the MCP server (https://api.ocost.io/public/mcp, the same keys): Claude Code, Claude Desktop, Cursor, claude.ai and ChatGPT through OAuth, and any client.
