Companies

Update a company

Scopecompanies:write

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.

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

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.

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.

A required field made only of whitespace passes the length checks below but leaves the address without that part, so it is rejected with 422: STREET_EMPTY, POSTAL_CODE_EMPTY, CITY_EMPTY or PROVINCE_EMPTY.

Addresses you read back are described by their own schema.

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

curl -X PATCH "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+34 910 123 456",
    "email": "facturacion@example.com",
    "default_iban": "ES9121000418450200051332",
    "default_swift": "CAIXESBBXXX",
    "account_holder": "María López Fernández",
    "default_payment_term": 30
  }'

curl -X PATCH "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "phone": "+34 910 123 456",    "email": "facturacion@example.com",    "default_iban": "ES9121000418450200051332",    "default_swift": "CAIXESBBXXX",    "account_holder": "María López Fernández",    "default_payment_term": 30  }'

{
  "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": "The invoice must have at least one line",
  "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: 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 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`.

Update a company

Test credentials on a Live company

What comes back

Authorization

Path Parameters

Request Body

Response Body

200application/json

401application/json

403application/json

422application/json

429application/json

500application/json

defaultapplication/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json