Invitations

Create an invitation

Creates a single-use invitation for a person to join the account with the given account_role.

  • token: the acceptance secret, returned once and never readable again, so deliver it to the invitee. invitation_url is the ready-to-use link built from that same token.
  • grants: the companies a MEMBER starts with. Omit it, or send [], to invite them with no company access yet; an explicit null is rejected with 422. Grants are only valid for MEMBER, since OWNER and ADMIN reach every company implicitly.
  • account_role: OWNER cannot be invited. An account has exactly one owner, handed over only through PUT /v1/accounts/{account_id}/owner.
  • send_email: defaults to false, so BeeL sends no email and you deliver the token or invitation_url yourself. Set it to true to have the invitation emailed to invited_email as well.
post/v1/accounts/{account_id}/invitations

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/accounts/{account_id}/invitations
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.

Request body

invited_emailstring email required

Email address of the invited person.

account_role'OWNER' | 'ADMIN' | 'MEMBER' required

Who administers the account. Independent of access_level, which says how much access someone has to a given company.

OWNER — full control, including billing, API keys and transferring ownership. Exactly one per account, so it is never an accepted value when you SET a role (inviting a member or changing one's role): both reject it with 422 OWNER_ROLE_NOT_ASSIGNABLE. Ownership moves only through PUT /v1/accounts/{account_id}/owner. ADMIN — everything an OWNER can do, except transferring ownership. MEMBER — no account administration. Access to each company is granted individually and reported as access_level; a member only sees the companies granted to them.

send_emailboolean

If true, an invitation email with the acceptance link is sent to invited_email in addition to returning the token. Defaults to false (you deliver the token/link yourself).

Response

Invitation created successfully

successboolean required

Example response

{
  "success": true,
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.