# Advisors (your accountant) (https://docs.getbeel.com/en/api/advisors)

Invite a commercialista with read-only access, list who has access, revoke an invitation or remove them.

An **advisor** is the company's commercialista: a team member with the read-only role `auditor` (shown as **Accountant** in the app). Once they accept the invitation they can read and export issued and received invoices, bank movements and the Taxes section, and change nothing. It is the same invitation as [Invite your accountant](/en/guide/report-e-commercialista#invite-your-accountant) in the app.

Scopes: `advisors:read` to list, `advisors:write` to invite and remove. Inviting or removing someone gives a real person access to real data, so it needs a **live key** (`403 livemode_required` with a test key). `advisors:write` is never selected by default when you create a key: tick it on purpose.

The key's member must be allowed to do the same in the app: `invites.manage` to invite or revoke an invitation, `members.manage` to remove a member (never the primary owner or themselves). Otherwise `403 invite_not_allowed` or `remove_not_allowed`.

## Invite [#invite]

```bash
curl https://www.getbeel.com/api/v1/advisors \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "email": "studio@commercialista.it" }'
```

`201` with the advisor, `status: "invited"`. The invitation email is sent right away and expires after 7 days (`expires_at`). An address that already has a pending advisor invitation gets that invitation back with `200` and no second email, so retries are safe; revoke it to send a new one. An address already in the team answers `409 already_member`; one invited to another role `409 already_invited`. A refused invitation policy answers `403 invite_not_allowed` with the reason.

```json
{
  "id": "inv_42",
  "object": "advisor",
  "email": "studio@commercialista.it",
  "name": null,
  "role": "auditor",
  "status": "invited",
  "invited_at": "2026-11-09T10:00:00.000Z",
  "expires_at": "2026-11-16T10:00:00.000Z",
  "joined_at": null
}
```

## List [#list]

`GET /v1/advisors` returns the active advisors (`id` `mem_…`, `status: "active"`, `joined_at`) and the pending invitations (`inv_…`). Other team members are not listed. The list is not paginated (`has_more` is always `false`).

## Remove [#remove]

`DELETE /v1/advisors/{id}`: `inv_…` revokes the invitation, `mem_…` removes the commercialista from the team, who loses access at once. Returns `{ "id", "object": "advisor", "deleted": true }`.

## Client companies [#client-companies]

With the `Getbeel-Company` header a parent account invites the commercialista of one of its client companies, with the same rules.

To invite the same commercialista to several companies at once (this account and its client companies), send them in `company_ids` (at most 25):

```bash
curl https://www.getbeel.com/api/v1/advisors/invitations \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "email": "studio@commercialista.it", "company_ids": ["<this account id>", "<client company id>"] }'
```

`POST /v1/advisors/invitations` answers `200` with one result per company, in the order sent: `invited`, `already_invited` (the pending invitation, no second email) or `failed` with the reason (`company_not_found` for an id that is not this account or a client company you manage, `already_member`, `invite_not_allowed`, `subscription_required`, `credits_exhausted`, `rate_limited`). Each company is invited exactly like `POST /v1/advisors`; one failing never stops the others. Without `company_ids` it invites to the company of the `Getbeel-Company` header, else this account. A test key gets `403 livemode_required`. In the app: **Client companies → Invite your accountant**.

## MCP and SDKs [#mcp-and-sdks]

- MCP: `list_advisors`, `invite_advisor`, `invite_accountant` (several companies) and `remove_advisor`. The assistant must confirm the email address with you before inviting.
- TypeScript: `getbeel.advisors.list()`, `getbeel.advisors.invite('studio@commercialista.it')`, `getbeel.advisors.remove('inv_42')`.
- Python: `client.advisors.list()`, `client.advisors.invite("studio@commercialista.it")`, `client.advisors.remove("inv_42")`.
