Company

Update a company

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.

patch/v1/companies/{company_id}

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/companies/{company_id}
  • Auth: HTTP bearer

Request body

entity_type'INDIVIDUAL' | 'LEGAL_ENTITY' nullable

Entity type. IMMUTABLE once set.

legal_namestring nullable

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.

nifstring nullable

NIF/CIF. IMMUTABLE once set.

legal_formstring nullable

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

trade_namestring nullable

Commercial/trade name for the company

phonestring

A phone number as this API accepts it: 9 to 20 characters, and only digits, spaces, dashes, parentheses and an optional leading +. Every request that takes a phone number uses this schema.

It is Phone plus the rules enforced on input. A value this schema accepts always satisfies Phone, so anything you send here is something a response can return.

emailstring email nullable

Email address (minimum valid email is 5 chars, e.g. a@b.co)

websitestring nullable

Website

logo_urlstring nullable

Logo URL

additional_infostring nullable

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}).

default_ibanstring nullable

IBAN (International Bank Account Number). Required when payment method is BANK_TRANSFER.

default_swiftstring nullable

SWIFT/BIC code

account_holderstring nullable

Bank account holder

iaestring nullable

IAE code

activity_start_datestring date nullable

Activity start date

default_payment_terminteger nullable

Default payment term in days

invoice_template_type'MODERN_TABLE' | 'PROFESSIONAL_SERVICE'

Invoice PDF template. MODERN_TABLE is a structured table layout for product/service lines; PROFESSIONAL_SERVICE is a text-based layout.

invoice_accent_colorstring nullable

Invoice PDF accent color (#RRGGBB)

invoice_language'es' | 'en' | 'ca' nullable

Language for invoice PDFs

email_language'es' | 'en' | 'ca' nullable

Language for emails

Example request

{
  "entity_type": "INDIVIDUAL",
  "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"
  },
  "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",
  "default_iban": "ES1234567890123456789012",
  "default_swift": "ABCDESMMXXX",
  "invoice_template_type": "MODERN_TABLE",
  "invoice_accent_color": "#fc481d",
  "invoice_language": "es",
  "email_language": "es"
}

Response

Company updated. The body is CompanyData, which echoes every field this request accepts — the stored value, not the one you sent, so it is also the confirmation of what a partial update left untouched.

successboolean

Example response

{
  "data": {
    "entity_type": "INDIVIDUAL",
    "environment": "PROD",
    "aeat_environment": "PROD",
    "account_state": "TEST_ONLY",
    "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",
    "default_iban": "ES1234567890123456789012",
    "default_swift": "ABCDESMMXXX",
    "invoice_template_type": "MODERN_TABLE",
    "invoice_accent_color": "#fc481d",
    "invoice_language": "es",
    "email_language": "es"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.