Delete a company
Scopecompanies:writeRemoves a company from the account: it stops appearing and stops being billed.
- Existing invoices: those already issued are retained, but the company-scoped API can no longer resolve them once the NIF is removed.
- What blocks removal: a NIF activated in Live
(
409 COMPANY_ACTIVE_IN_PRODUCTION), one holding any invoice in Live — issued, draft or proforma (409 COMPANY_HAS_INVOICES) — and the account's primary NIF (400 CANNOT_DELETE_PRIMARY). - Deactivating first: switching off in Live is scheduled to the end of the paid cycle, so the removal only becomes possible once that takes effect.
- Test: NIFs never activated, or activated only in Test, are removed right away, and invoices in Test never block.
Idempotency-Key: without one, a retry after a timeout answers403instead of the original204.
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
Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the BeeL-Active-Company header plays no part. A company you do not reach answers 403, and so does a company that does not exist, so the existence of a company in another account is never disclosed.
uuidResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08"{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The provided data is not valid",
"details": {
"field": "specific error message"
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
},
"type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
"title": "INVOICE_NO_LINES",
"detail": "The invoice must have at least one line",
"instance": "/v1/invoices/abc-123"
}{
"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": "VALIDATION_ERROR",
"message": "The provided data is not valid",
"details": {
"field": "specific error message"
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
},
"type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
"title": "INVOICE_NO_LINES",
"detail": "The invoice must have at least one line",
"instance": "/v1/invoices/abc-123"
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The provided data is not valid",
"details": {
"field": "specific error message"
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
},
"type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
"title": "INVOICE_NO_LINES",
"detail": "The invoice must have at least one line",
"instance": "/v1/invoices/abc-123"
}{
"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"
}
}Update a company PATCH
Updates the editable fields of a company; the set is the one `UpdateCompanyRequest` declares. - **Immutable fields:** `nif`, `entity_type` and `legal_form`, once set. Sending one of them with a different value answers `422` with a code that names the field; sending the value it already has is not a change. - **`legal_name`:** changing it requires the NIF to pass an AEAT census re-validation. For a legal entity (`LEGAL_ENTITY`) the census identifies the company by its NIF alone: the name is not verified, so the name sent cannot make it fail. For an `INDIVIDUAL` the name must match the one the census holds for that NIF. - **Census not answering:** if the AEAT census cannot be reached, the change is not rejected. The response is `200` with the new `legal_name` stored, and BeeL repeats the census check in the background. The outcome of that check is not part of this resource: no field of `CompanyData` carries it. To know what the census says about a NIF and a name, ask `POST /v1/nif/validate`. - **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`. Other countries' postal codes are free-form. ## Test credentials on a Live company Once the company is activated in Live, a test credential may only write the fields that affect how the invoice looks: `logo_url`, `invoice_accent_color`, `invoice_template_type`, `invoice_language`, `email_language` and `additional_info`. Any other field describes the real business — fiscal address, legal representative, bank details, contact data, IAE, activity start date, payment term — and answers `422 FISCAL_IDENTITY_LIVE_ONLY` from Test, since the company is a single record shared by both modes. A company not activated in Live accepts the whole body from Test, and sending a field its current value is never a change. ## What comes back The `200` returns `CompanyData` with **every field this request accepts**, under the same name and the same type — so the response is the confirmation of what was stored, and a later `GET` says the same. A field you never set comes back absent, which means "nothing stored", not "hidden". Two things live outside this body and keep their own reads: the invoice series (`GET /v1/companies/{company_id}/series`) and the rendering block, which is also served on its own by `GET /v1/companies/{company_id}/invoice-customization`.
Switch a company on POST
Switches an existing company on in the mode carried in the body. The mode is always explicit and never taken from the credential's environment, so a Test key can switch a NIF on in Live. ## Modes and billing - **`TEST`:** immediate and free. - **`PROD`:** immediate when the account already has a card on file or an enterprise contract, and the NIF is added to the existing subscription. With no card on file it answers `402 CHECKOUT_REQUIRED`, returning a `checkout_url` when `success_url` and `cancel_url` are supplied. It also requires being the billing subject of the account (`403 NOT_BILLING_OWNER` otherwise). - **`billing_period`:** picks the plan the checkout sells — `MONTHLY` (default) or `ANNUAL`. It only matters when a checkout is opened. Accounts with a negotiated rate or an enterprise contract cannot buy the annual plan (`422 ANNUAL_PLAN_NOT_AVAILABLE`). ## Idempotency and pending switch-offs - **Repeating the call:** opens no second checkout and adds no second subscription item; it returns the existing activation with `already_active: true`. The same `Idempotency-Key` sent to this route and to the nested one it replaces is the same operation, so it is replayed and never charged twice. - **A pending switch-off is cancelled:** while it is pending the NIF is still on — it just carries an effective date — so switching it on again only removes that date, answers `scheduled_deactivation_cancelled: true`, and charges or credits nothing. It does commit the NIF to the next billing cycle, though, so under an agreement capped at a number of Live NIFs it asks for a seat like a new NIF would, and is rejected with `409 NIF_LIMIT_REACHED` when the cap is already full.