NewThe global rate limit drops to 1000 requests per minute
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Invitations

Invite a person to the account

Scopemembers:write

Creates a single-use invitation for a person to join the account with the given role (and optional initial company grants for MEMBER). Requires OWNER/ADMIN; OWNER cannot be invited — an account has exactly one owner, handed over only through transfer-ownership. Returns the acceptance token once — deliver it to the invitee.

POST
/v1/accounts/{account_id}/invitations

Authorization

AuthorizationBearer <token>

API Key authentication.

Format: Authorization: Bearer beel_sk_<key>

Scopes: API Keys use the same scopes as OAuth2 tokens. Each key is created with specific scopes that limit which endpoints it can access. The required scope for each endpoint is documented in the operation's security section under OAuth2.

Obtaining Keys: API Keys are managed from the BeeL dashboard

Security: API Keys are secret credentials. Do not share them or store them in source code

In: header

Path Parameters

account_idstring

Your own account, or an account you provisioned. It — not the credential — decides which account the operation acts on; a 403 is returned when you do not reach it, the same response an account that does not exist gets.

Formatuuid

Header Parameters

Idempotency-Key?string

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)
  • If the same key is sent twice, the result of the first operation is returned
  • Keys 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 and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.
Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255

Request Body

invited_emailstring

Email address of the invited person.

Formatemail
Length1 <= length
account_rolestring

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

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.

Value in"OWNER" | "ADMIN" | "MEMBER"
send_email?boolean

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

Defaultfalse
grants

Initial grants (only when account_role is MEMBER). Required: send [] to invite with no company access yet (granted later). An explicit null is rejected with 400.

Default[]

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/invitations" \  -H "Content-Type: application/json" \  -d '{    "invited_email": "user@example.com",    "account_role": "OWNER",    "grants": []  }'
{
  "success": true,
  "data": {
    "invitation_id": "a6e6785a-3ea9-406c-b873-17eaf2ed5fc9",
    "invited_email": "user@example.com",
    "account_role": "OWNER",
    "expires_at": "2019-08-24T14:15:22Z",
    "token": "string",
    "invitation_url": "http://example.com"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "LIVE_CREDENTIAL_REQUIRED",
    "message": "This operation changes the real account; it requires a live API key or a dashboard session."
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "CONCURRENT_MODIFICATION",
    "message": "The resource was modified by another request; read it again and retry"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "field": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  },
  "type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
  "title": "INVOICE_NO_LINES",
  "detail": "La factura debe tener al menos una línea",
  "instance": "/v1/invoices/abc-123"
}
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again in 60 seconds."
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Unsupported media type: text/plain. Supported: application/json"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

List the account's member invitations GET

Lists the member invitations of the account with their status (`PENDING`/`ACCEPTED`/`REVOKED`/`EXPIRED`). Requires OWNER/ADMIN. The acceptance token is never exposed (it is shown only once, at creation).

Retrieve a member invitation GET

Retrieves one member invitation of the account. Requires OWNER/ADMIN. The acceptance token is never exposed (it is shown only once, at creation). An invitation stays readable for its whole life: `ACCEPTED`, `REVOKED` and `EXPIRED` invitations are returned with their status, exactly as they appear in the list — the record is the audit trail of who was granted access to the account's fiscal data, and revoking it does not erase it. `404` therefore means only one thing: no member invitation with that id exists in this account.