GetbeelDocs

Multiple companies (multi-company)

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

  • 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

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

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

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:

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.

EndpointScope
GET /v1/companiesaccount:readThe key's account and the client companies it can act on
POST /v1/companiescompanies:writeAdds a client company
GET /v1/companies/{id}account:readOne company (or the account itself)
PATCH /v1/companies/{id}companies:writeChanges 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)

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

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.

On this page