NewTell a voided invoice from a totally rectified one, without a second call
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Accounts

Provisioning usage of your own account

Scopeaccounts:read

Returns how many accounts you have provisioned and how many NIFs (companies) they hold — the billable figure for your offline B2B invoice. Requires the accounts:read scope.

account_id is your own account: usage is a property of the provisioner, not of each provisioned account. Any other id — an account you provisioned, one belonging to someone else, or one that does not exist — returns the same 404, so the endpoint cannot be used to probe which accounts exist.

GET
/v1/accounts/{account_id}/usage

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

Formatuuid

Response Body

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/usage"
{
  "success": true,
  "data": {
    "provisioned_accounts": 1000,
    "nifs": 1000
  },
  "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": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  },
  "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"
  }
}

Get a provisioned account's authoritative status GET

Returns the current lifecycle status and access for one account you provisioned. A `403` is returned when the account was not provisioned by you or does not exist (existence is not disclosed). Requires the `accounts:read` scope.

Change your management access over an account you provisioned PATCH

Updates the access you hold over an account you provisioned: `NONE` (you keep paying for their subscription but cannot see their data), `VIEW` (read their data) or `OPERATE` (issue and edit invoices for them). Issuing on their behalf also requires a signed fiscal representation from the account holder. Privileged: requires the `accounts:write` scope. A `403` is returned when the account was not provisioned by you, when it does not exist (existence is not disclosed), and when you try to RAISE the access level after the account holder has taken ownership of the account — once claimed, only the holder can raise it; you may keep it or lower it.