End your management of an account you provisioned
Scopeaccounts:writeEnds 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 account holder keeps the account, its NIFs and its invoices, and becomes responsible for their own subscription; nothing is deleted or anonymised.
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 its management has already ended.
Reversible only while the account stays unclaimed. If the holder has not claimed the account, provisioning the same email again reactivates it (see POST /v1/accounts). Once they claim it, the account is theirs and provisioning returns 409 PROVISIONING_ACCOUNT_CLAIMED: getting the management back then requires their consent, not just their email address. Only the manager who ended the relationship can reactivate it.
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
uuidResponse Body
application/json
application/json
application/json
application/json
curl -X DELETE "https://app.beel.es/api/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/management"{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication required"
},
"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"
}
}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.
Create a company POST
Creates a new NIF/company under the authenticated account. Invoice series are created automatically with default values. This endpoint only **creates**. A NIF that already exists in your account returns `409` with `error.code=NIF_ALREADY_REGISTERED` and the existing `error.details.company_id` — it is never turned into a silent environment activation on the existing company. Switching an environment on for a company you already have is a separate act (explicit confirmation in Live, and it is what gets billed): `POST /v1/companies/{company_id}/activations`. Send `activate: false` to create only the NIF profile, without switching it on anywhere — no series, no charge, nothing to undo. Otherwise the `aeat_environment` field decides the creation flow: * **`TEST`** — created immediately, free. `201` + `CompanyCreatedData`. * **`PROD` + account already production-active** (billing set up) — created immediately as a production NIF. Real emission stays blocked until the AEAT representation is signed for this NIF. `201` + `CompanyCreatedData`. * **`PROD` + account with no card on file** — no company is created. Returns `402` with `error.code=CHECKOUT_REQUIRED` and **no checkout URL**: this endpoint never starts a charge (a production charge always hangs off activating an existing, user-signalled company in Live), and an API key has no browser to return from a checkout with. Create the company (with `activate: false`, or in `TEST`) and activate it in Live via `POST /v1/companies/{company_id}/activations`. * **`PROD` + account past due** — no company is created. Returns `402` with `error.code=PAYMENT_REQUIRED`. Nothing to sign up for here: the outstanding invoice has to be settled first. The company is created under the account the request resolves to — your own account, or the account the `BeeL-Active-Company` header points at when you manage it. The NIF is always registered in the name of that account's holder, never in the name of the caller. An account provisioned for someone who has not signed in yet already has a holder, so companies can be created for it right away.