NewProvince is only required for addresses in Spain
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Invitations

Retrieve an invitation

Scopemembers:read

Returns one invitation of the account, with the same shape the list returns. An invitation stays readable for its whole life: ACCEPTED, REVOKED and EXPIRED ones are returned with their status, because the record is the trail of who was granted access to the account's fiscal data and revoking it does not erase it.

GET
/v1/accounts/{account_id}/invitations/{invitation_id}

Authorization

AuthorizationBearer <token>

Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key short of the scope an operation needs is answered 403. The scope an operation requires is shown next to its title, and the full catalogue lives in the Scopes reference.

Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.

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
invitation_idstring

Identifier (UUID) of an invitation of the account in the path, as returned when it is created or listed. An invitation of another account answers 404, exactly like one that does not exist.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/invitations/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "success": true,
  "data": {
    "invitation_id": "a6e6785a-3ea9-406c-b873-17eaf2ed5fc9",
    "invited_email": "user@example.com",
    "account_role": "OWNER",
    "status": "PENDING",
    "created_at": "2019-08-24T14:15:22Z",
    "expires_at": "2019-08-24T14:15:22Z"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "MEMBER_MANAGEMENT_FORBIDDEN",
    "message": "Only the owner or an admin can manage account members."
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "INVITATION_NOT_FOUND",
    "message": "No invitation with that id in this account."
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "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"
  }
}

Create an invitation POST

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.

Revoke an invitation DELETE

Revokes a `PENDING` invitation, so its acceptance link stops working. - **Already resolved:** an `ACCEPTED`, `REVOKED` or `EXPIRED` invitation cannot be revoked, and answers `404` without disclosing which of the three it is. - **History:** revoking does not remove the invitation from the list.