Invitations

To add a person to an account you create an invitation — its own resource, separate from members. It is a single-use, expiring token that carries the target role and, for a MEMBER, the initial company grants. The person becomes a member only when they accept; a revoked or expired invitation never produces one.

Invitations hang off the account — /v1/accounts/{account_id}/invitations — and require OWNER or ADMIN plus members:read / members:write.

Invite a person

POST /v1/accounts/{account_id}/invitations — members:write. Full field list and types: Invite a person to the account.

curl -X POST https://app.beel.es/api/v1/accounts/3fa85f64-5717-4562-b3fc-2c963f66afa6/invitations \
  -H "Authorization: Bearer beel_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "invited_email": "colleague@example.com",
    "account_role": "MEMBER",
    "send_email": false,
    "grants": [
      { "company_id": "550e8400-e29b-41d4-a716-446655440000", "access_level": "OPERATE" }
    ]
  }'

Three things about the body are easy to get wrong:

• grants is required, even when empty. Send [] to invite somebody with no NIF access yet and grant it after they accept. An explicit null is rejected with 400 — the API will not guess whether you meant "none" or "forgot".
• Grants only make sense for account_role: "MEMBER". An OWNER or ADMIN reaches every NIF implicitly; sending grants with either is 422 GRANTS_ONLY_FOR_MEMBER. A grant naming a NIF outside the account is 422 GRANT_COMPANY_NOT_IN_ACCOUNT.
• Inviting as OWNER requires you to be OWNER. An ADMIN cannot mint one.

Copy-link or email

• Copy-link (default, send_email: false) — you get a ready-to-share invitation_url plus the raw token, and deliver it however you like: your own email, chat, in-app. Full control over the message and the branding.
• Email (send_email: true) — BeeL. also sends the invitation email for you. You still receive the token and URL in the response, so you can follow up yourself.

Both mint the same single-use token; invitation_url is just that token wrapped in the acceptance link for the current environment, so you never assemble /aceptar?token= by hand.

Acceptance happens outside the API

The invitee opens the link and accepts on BeeL. — setting a password if they are new. There is no public endpoint for you to call: acceptance is a session action on BeeL.'s side, the same way a provisioned account is claimed. You observe the result, you do not drive it: the invitation flips to ACCEPTED and the person shows up in GET /v1/accounts/{account_id}/members.

Track and revoke

GET /v1/accounts/{account_id}/invitations — members:read, paginated with page and limit. Every invitation stays readable for its whole life:

DELETE /v1/accounts/{account_id}/invitations/{invitation_id} — members:write, 204. Only a PENDING invitation can be revoked; one already accepted, revoked or expired returns 404 rather than disclosing which of the three it is. See Revoke a member invitation.

Next steps