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

End your management of an account

Scopeaccounts:write

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.
DELETE
/v1/accounts/{account_id}/management

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

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://app.beel.es/api/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/management"
Empty
{
  "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": "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": "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"
  }
}

Change your access over a managed account PATCH

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

Create a company POST

Creates a company under the account the request resolves to. The NIF is registered in the name of that account's holder, never in the name of the caller. - **`activate`:** unless it is `false`, the company is switched on in `aeat_environment` and its three default invoice series (ordinary, simplified, corrective) are seeded there. This endpoint never switches an existing company on: that is `POST /v1/companies/{company_id}/activations`. - **`numbering`:** decides the code, format, counter reset and starting number those series are born with. Only accepted when the request activates the company. - **Billing:** no charge is ever started here. Creating a production NIF requires being the billing subject of the account (`403` otherwise), and an account without billing is rejected with `402`; no checkout is opened in either case. - **Duplicates:** a NIF that already exists in the account is rejected with `409`, and the response carries the existing `error.details.company_id`. - **Addresses:** a Spanish postal code (`country_code` omitted or `ES`) must have 5 digits, in `address` and in `legal_representative.address`; otherwise `422 POSTAL_CODE_INVALID_ES` and nothing is created. Other countries' postal codes are free-form.