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

Change your access over a managed account

Scopeaccounts:write

Updates the access_level you keep over an account you provisioned.

  • Raising it: only possible while the account is unclaimed. Once its holder has taken ownership you may keep or lower your access, but only they can raise it.
  • Billing: the level never affects it — you pay for the account's subscription at any level.
  • OPERATE: issuing invoices on the holder's behalf additionally requires a signed fiscal representation from them.
  • Entitlement: requires manage_accounts.
PATCH
/v1/accounts/{account_id}/access-level

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

Identifier (UUID) of an account you manage. An account you do not manage answers exactly like one that does not exist, so its existence is never disclosed.

Formatuuid

Request Body

access_levelstring

How much access an actor has to an account or a company. The same three values are used everywhere access is granted or reported — whether the actor is a member of the account or a provisioner managing it on someone's behalf.

NONE — no access to the data. VIEW — read invoices, customers, products, series and fiscal data. OPERATE — everything in VIEW, plus creating and editing them. Issuing invoices for an account you manage additionally requires a signed fiscal representation from the account holder (see /v1/accounts/{account_id}/companies/{company_id}/representation).

Access level never affects billing: whoever provisioned an account pays for its subscription regardless of the level they keep over it.

Value in"NONE" | "VIEW" | "OPERATE"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://app.beel.es/api/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/access-level" \  -H "Content-Type: application/json" \  -d '{    "access_level": "VIEW"  }'
Empty
{
  "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 is required to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "MANAGED_SCOPE_ELEVATION_REQUIRES_OWNER",
    "message": "Only the account holder can raise management access over their account once it has been claimed"
  },
  "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"
  }
}

Get your provisioning usage GET

Returns how many accounts you have provisioned and the billable count that follows from them — the figure behind your offline B2B invoice. - **Billable unit:** the provisioned account, not the real NIF. Every account you provision counts as one, empty and unclaimed ones included. - **`account_id`:** your own account. Usage is a property of the provisioner, not of each provisioned account, so any other id returns `404`. - **Entitlement:** requires `manage_accounts`.

End your management of an account DELETE

Ends the management relationship over an account you provisioned: you lose access to it, and its NIFs stop counting towards your billable usage from the next billing cycle. - **The holder:** keeps the account, its NIFs and its invoices, and becomes responsible for their own subscription. Nothing is deleted or anonymised. - **Reversible:** only while the account stays unclaimed. Provisioning the same email again reactivates it (see `POST /v1/accounts`), and only the manager who ended the relationship can do so. Once the holder claims the account it is theirs, and getting the management back needs their consent, not just their email address. - **Entitlement:** requires `manage_accounts`.