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

List the account's invitations

Scopemembers:read

Lists the invitations sent to join the account, whatever their status. Accepted, revoked and expired invitations stay in the list: the record is the trail of who was granted access to the account's fiscal data.

GET
/v1/accounts/{account_id}/invitations

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

Query Parameters

page?integer

Page number, starting at 1. The response echoes it back as pagination.current_page.

Default1
Range1 <= value
limit?integer

How many items to return per page. The response echoes it back as pagination.items_per_page.

Default20
Range1 <= value <= 100

Response Body

application/json

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"
{
  "success": true,
  "data": {
    "invitations": [
      {
        "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"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 87,
      "items_per_page": 20,
      "has_next": true,
      "has_previous": true
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The parameter 'invoice_id' has an invalid type. Expected: UUID.",
    "details": {
      "field": "invoice_id",
      "invalid_value": "deliveries",
      "expected_format": "UUID"
    }
  },
  "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": "VALIDATION_ERROR",
    "message": "Validation constraint violation.",
    "details": {
      "limit": "must be greater than or equal to 1"
    }
  },
  "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"
  }
}

Set the account owner PUT

Makes the member in the body the account's `OWNER` and steps the calling owner down to `ADMIN`, so the account always keeps exactly one owner. - **Repeatable:** it states the desired owner rather than performing a transfer, so repeating the same call once that member already owns the account returns the same `204` instead of failing. - **Credentials:** unlike the rest of this API, this operation is available only from a signed-in dashboard session. No API key, live or test, can perform it, whatever scopes it holds. - **From an integration:** to hand an account over to its holder, issue a claim token with `POST /v1/accounts/{account_id}/claim-tokens` instead.

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.