NewThree filters returned the wrong rows
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Companies

Delete a company

Scopecompanies:write

Removes a company (NIF) 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 answers 403 instead of the original 204.
DELETE
/v1/companies/{company_id}

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

company_idstring

NIF (company) the operation acts on. 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 NIF you do not reach answers 403, and so does a NIF that does not exist, so the existence of a NIF in another account is never disclosed.

Formatuuid

Response 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"
Empty
{
  "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": "La factura debe tener al menos una línea",
  "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": "La factura debe tener al menos una línea",
  "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": "La factura debe tener al menos una línea",
  "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 (NIF); the set is the one `UpdateCompanyRequest` declares. - **Immutable fields:** `nif`, `entity_type` and `legal_form`, once set. - **`legal_name`:** changing it requires the NIF to pass an AEAT census re-validation — which for a company checks the CIF only, so it cannot fail because of the name sent. ## 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 (NIF) 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). ## 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.