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

Update a company

Scopecompanies:write

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.

PATCH
/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

Request Body

entity_type?string
Value in"INDIVIDUAL" | "LEGAL_ENTITY"
legal_name?string|null

Legal/fiscal name. Changing it triggers AEAT census re-validation of the NIF. For a self-employed individual the census matches NIF and name together, so a name it does not recognise is rejected. For a legal entity the name is not verified: the re-validation only confirms the CIF, and the business name held by the census is the only thing to contrast yours against.

Length1 <= length <= 255
nif?string
legal_form?string|null

Legal form (SL, SA, ...). IMMUTABLE once set. Only for LEGAL_ENTITY.

Length1 <= length <= 100
trade_name?string|null

Commercial/trade name for the company

Length1 <= length <= 255
address?

Address you send when you create or update a company, a customer or an onboarding. The street number is mandatory here: an address without it is rejected with 422.

Addresses you read back are described by their own schema, and do not guarantee the street number: records registered before it was collected have none.

legal_representative?

Legal representative data for a legal entity. Only used when entity_type = LEGAL_ENTITY.

phone?string
email?string
website?string|null

Website

Length1 <= length <= 500
logo_url?string|null

Logo URL

Length1 <= length <= 500
additional_info?string|null

Free note printed on the invoice. It is presentation, not fiscal identity, so a test credential may change it even on a company activated in Live. Read it back in CompanyData.additional_info (GET /v1/companies/{company_id}).

Lengthlength <= 500
default_iban?string
default_swift?string
account_holder?string|null

Bank account holder

Length1 <= length <= 255
iae?string|null

IAE code

Length1 <= length <= 20
activity_start_date?string|null

Activity start date

Formatdate
default_payment_term?integer|null

Default payment term in days

Range0 <= value <= 365
invoice_template_type?string
Value in"MODERN_TABLE" | "PROFESSIONAL_SERVICE"
invoice_accent_color?string|null

Invoice PDF accent color (#RRGGBB)

Match^#[0-9A-Fa-f]{6}$
invoice_language?string
Value in"es" | "en" | "ca"
email_language?string
Value in"es" | "en" | "ca"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'
{
  "success": true,
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "access_level": "NONE",
    "nif": "string",
    "legal_name": "string",
    "trade_name": "string",
    "entity_type": "INDIVIDUAL",
    "is_primary": true,
    "verifactu_status": "NOT_CONFIGURED",
    "environment": "PROD",
    "in_prod": true,
    "in_test": true,
    "aeat_environment": "PROD",
    "account_state": "TEST_ONLY",
    "address": {
      "street": "string",
      "number": "string",
      "floor": "string",
      "door": "string",
      "postal_code": "string",
      "city": "string",
      "province": "string",
      "country": "string",
      "country_code": "string"
    },
    "legal_form": "string",
    "legal_representative": {
      "full_name": "María García López",
      "nif": "12345678A",
      "address": {
        "street": "Calle Mayor, 123",
        "number": "123",
        "floor": "2º A",
        "door": "A",
        "postal_code": "28001",
        "city": "Madrid",
        "province": "Madrid",
        "country": "España",
        "country_code": "ES"
      }
    },
    "phone": "+34 612 345 678",
    "email": "user@example.com",
    "website": "string",
    "logo_url": "string",
    "additional_info": "string",
    "default_iban": "ES1234567890123456789012",
    "default_swift": "ABCDESMMXXX",
    "account_holder": "string",
    "iae": "string",
    "activity_start_date": "2019-08-24",
    "default_payment_term": 365,
    "invoice_template_type": "MODERN_TABLE",
    "invoice_accent_color": "#fc481d",
    "invoice_language": "es",
    "email_language": "es",
    "default_irpf_rate": 0,
    "created_at": "2019-08-24T14:15:22Z",
    "readiness": {
      "ready": true,
      "blockers": [
        "COMPANY_HAS_NO_NIF"
      ],
      "verifactu": {
        "ready": true,
        "blockers": [
          "ENV_MISMATCH"
        ]
      }
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "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": "FISCAL_IDENTITY_LIVE_ONLY",
    "message": "This company is live. In Test mode you can only change how the invoice looks (logo, colour, template, languages and additional information). Fiscal details are edited in Live mode"
  },
  "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"
  }
}

Get a company GET

Returns the identity and activation state of a company (NIF): its fiscal data, whether it is switched on in Test and in Live, and its VeriFactu registration state. It also returns **every field `PATCH /v1/companies/{company_id}` accepts** — contact details, legal representative, bank details, IAE, activity start date, payment term and the rendering block — so what was written can be read back without keeping a copy of it. A field never set comes back absent: that means "nothing stored", not "hidden". Its invoice series are not part of this response: read them from `GET /v1/companies/{company_id}/series`.

Delete a company DELETE

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