GetbeelDocs

Advisors (your accountant)

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 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

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.

{
  "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

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

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

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):

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: 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").

On this page