{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/beel-es/json-schema/beel-es-update-company-request-schema.json",
  "title": "UpdateCompanyRequest",
  "description": "Editable fields of a company.\n`entity_type`, `nif` and `legal_form` are immutable once set;\n`legal_name` can only be corrected together with a successful\nAEAT census re-validation of the NIF. For a company that\nre-validation checks the CIF only — the name is **not verified**,\nso it can never fail because of the name you send.\n\n**Everything here reads back.** The `200` of the update — and every later\n`GET /v1/companies/{company_id}` — returns `CompanyData`, which carries each of these\nfields under the same name and the same type. No need to keep your own copy to\nreconcile: write it, read it back. Five of them also have a read of their own,\n`logo_url`, `invoice_template_type`, `invoice_accent_color`, `invoice_language` and\n`email_language`, all returned by\n`GET /v1/companies/{company_id}/invoice-customization`.\n\nA field you never set is **absent** from the read, which means \"nothing stored\" — not\n\"hidden from you\", and not a default. What varies by caller is what you may *write*\n(see the Test-credential rule below), never what comes back.\n\n**From Test, on a company activated in Live, only six of these fields are writable**:\n`logo_url`, `invoice_accent_color`, `invoice_template_type`, `invoice_language`,\n`email_language` and `additional_info` — what the invoice *looks like* and the free\nnote it carries. Everything else describes the real business and answers\n`422 FISCAL_IDENTITY_LIVE_ONLY` unless the call is made with a live credential.\n",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/beel-es-company-api-openapi.yml#/components/schemas/UpdateCompanyRequest",
  "type": "object",
  "properties": {
    "entity_type": {
      "allOf": [
        {
          "$ref": "#/$defs/EntityType"
        },
        {
          "description": "Entity type. IMMUTABLE once set."
        }
      ]
    },
    "legal_name": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 255,
      "description": "Legal/fiscal name. Changing it triggers AEAT census re-validation of the NIF.\nFor a self-employed individual the census matches NIF and name together, so a\nname it does not recognise is rejected. For a legal entity the name is\n**not verified**: the re-validation only confirms the CIF, and the business\nname held by the census is the only thing to contrast yours against.\n"
    },
    "nif": {
      "allOf": [
        {
          "$ref": "#/$defs/NIF"
        },
        {
          "description": "NIF/CIF. IMMUTABLE once set."
        }
      ]
    },
    "legal_form": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 100,
      "description": "Legal form (SL, SA, ...). IMMUTABLE once set. Only for LEGAL_ENTITY."
    },
    "trade_name": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 255,
      "description": "Commercial/trade name for the company"
    },
    "address": {
      "$ref": "#/$defs/Address"
    },
    "legal_representative": {
      "$ref": "#/$defs/LegalRepresentative"
    },
    "phone": {
      "allOf": [
        {
          "$ref": "#/$defs/PhoneInput"
        }
      ]
    },
    "email": {
      "allOf": [
        {
          "$ref": "#/$defs/Email"
        },
        {}
      ]
    },
    "website": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 500,
      "description": "Website"
    },
    "logo_url": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 500,
      "description": "Logo URL"
    },
    "additional_info": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 500,
      "description": "Free note printed on the invoice. It is presentation, not fiscal identity, so a\ntest credential may change it even on a company activated in Live. Read it back in\n`CompanyData.additional_info` (`GET /v1/companies/{company_id}`).\n"
    },
    "default_iban": {
      "allOf": [
        {
          "$ref": "#/$defs/IBAN"
        },
        {}
      ]
    },
    "default_swift": {
      "allOf": [
        {
          "$ref": "#/$defs/SWIFT"
        },
        {}
      ]
    },
    "account_holder": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 255,
      "description": "Bank account holder"
    },
    "iae": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 20,
      "description": "IAE code"
    },
    "activity_start_date": {
      "type": [
        "string",
        "null"
      ],
      "format": "date",
      "description": "Activity start date"
    },
    "default_payment_term": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0,
      "maximum": 365,
      "description": "Default payment term in days"
    },
    "invoice_template_type": {
      "allOf": [
        {
          "$ref": "#/$defs/InvoiceTemplateType"
        }
      ],
      "description": "Invoice PDF template type"
    },
    "invoice_accent_color": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^#[0-9A-Fa-f]{6}$",
      "description": "Invoice PDF accent color (#RRGGBB)"
    },
    "invoice_language": {
      "allOf": [
        {
          "$ref": "#/$defs/Language"
        },
        {
          "description": "Language for invoice PDFs"
        }
      ]
    },
    "email_language": {
      "allOf": [
        {
          "$ref": "#/$defs/Language"
        },
        {
          "description": "Language for emails"
        }
      ]
    }
  },
  "$defs": {
    "Address": {
      "description": "Address you send when you create or update a company, a customer or an onboarding.\n\nA required field made only of whitespace passes the length checks below but leaves the\naddress without that part, so it is rejected with `422`: `STREET_EMPTY`,\n`POSTAL_CODE_EMPTY`, `CITY_EMPTY` or `PROVINCE_EMPTY`.\n\nAddresses you read back are described by their own schema.\n",
      "type": "object",
      "required": [
        "street",
        "postal_code",
        "city"
      ],
      "properties": {
        "street": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "pattern": "^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$",
          "description": "Full address (street, number, floor, etc.) - Latin characters only"
        },
        "number": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20,
          "description": "Street number. Optional: omit it when the address has none, or when `street` already\ncarries the address in full.\n"
        },
        "floor": {
          "type": "string",
          "maxLength": 10,
          "description": "Floor or level"
        },
        "door": {
          "type": "string",
          "maxLength": 10,
          "description": "Door or apartment"
        },
        "postal_code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20,
          "description": "Postal code (5 digits for Spain, free format for other countries)"
        },
        "city": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "pattern": "^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$",
          "description": "City or town - Latin characters only"
        },
        "province": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "pattern": "^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$",
          "description": "Province or state - Latin characters only. Required for an address in Spain\n(`country_code` `ES`, or no country at all); optional elsewhere, where many addresses\nhave none. A Spanish address without it is rejected with a `422`.\n"
        },
        "country": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "pattern": "^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$",
          "description": "Country of the address, as its ISO 3166-1 alpha-2 code (`GB`) or its official name\nin Spanish, English or Catalan (`Reino Unido`, `United Kingdom`, `Regne Unit`;\ncase and accents are ignored). Anything else, such as `UK`, is rejected with\n`422 COUNTRY_CODE_REQUIRED`: send `country_code` instead. If it names a different\ncountry than `country_code`, `422 COUNTRY_CODE_MISMATCH` (`España` alone yields to\na foreign `country_code`: it was the old default). What is stored and\nreturned is always the Spanish name derived from the resulting code, never the\ntext sent. With neither field present, the address is Spanish (`España`).\n"
        },
        "country_code": {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "minLength": 2,
          "maxLength": 2,
          "description": "ISO 3166-1 alpha-2 country code: the canonical field that decides the country of\nthe address. It must be a real country code (`GB`, not `UK`); otherwise\n`422 COUNTRY_CODE_REQUIRED`. When it is omitted, the code comes from `country`\n(see there). With neither field present, the address is stored as `ES`.\n"
        }
      }
    },
    "Email": {
      "type": "string",
      "format": "email",
      "minLength": 5,
      "maxLength": 255,
      "description": "Email address (minimum valid email is 5 chars, e.g. a@b.co)"
    },
    "EntityType": {
      "type": "string",
      "description": "Taxpayer type.\nINDIVIDUAL: Natural person (individual self-employed).\nLEGAL_ENTITY: Legal entity (company with legal form: SL, SA, etc.).\n",
      "enum": [
        "INDIVIDUAL",
        "LEGAL_ENTITY"
      ]
    },
    "IBAN": {
      "type": "string",
      "pattern": "^[A-Z]{2}\\d{2}[A-Z0-9]{1,30}$",
      "minLength": 15,
      "maxLength": 34,
      "description": "IBAN (International Bank Account Number).\nRequired when payment method is BANK_TRANSFER.\n"
    },
    "InvoiceTemplateType": {
      "type": "string",
      "description": "Invoice PDF template. `MODERN_TABLE` is a structured table layout for\nproduct/service lines; `PROFESSIONAL_SERVICE` is a text-based layout.\n",
      "enum": [
        "MODERN_TABLE",
        "PROFESSIONAL_SERVICE"
      ]
    },
    "Language": {
      "type": "string",
      "description": "Supported languages: `es` Spanish, `en` English, `ca` Catalan.\n",
      "enum": [
        "es",
        "en",
        "ca"
      ]
    },
    "LegalRepresentative": {
      "type": "object",
      "required": [
        "full_name",
        "nif",
        "address"
      ],
      "description": "Legal representative data for a legal entity.\nOnly used when entity_type = LEGAL_ENTITY.\n",
      "properties": {
        "full_name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Full name of the legal representative"
        },
        "nif": {
          "type": "string",
          "pattern": "^(\\d{8}[A-Z]|[ABCDEFGHJKLMNPQRSUVW]\\d{7}[A-Z0-9]|[XYZ]\\d{7}[A-Z])$",
          "minLength": 9,
          "maxLength": 9,
          "description": "Tax ID of the legal representative (DNI/CIF/NIE)"
        },
        "address": {
          "allOf": [
            {
              "$ref": "#/$defs/Address"
            },
            {
              "description": "Address of the legal representative"
            }
          ]
        }
      }
    },
    "NIF": {
      "type": "string",
      "pattern": "^(\\d{8}[A-Z]|[ABCDEFGHJKLMNPQRSUVW]\\d{7}[A-Z0-9]|[XYZ]\\d{7}[A-Z])$",
      "minLength": 9,
      "maxLength": 9,
      "description": "Spanish Tax ID (9 characters, uppercase only). Structural validation:\n- DNI: 8 digits + 1 letter (e.g., 12345678A)\n- NIE: X/Y/Z + 7 digits + 1 letter (e.g., X1234567A)\n- CIF: Organization letter + 7 digits + 1 control digit/letter (e.g., B12345674)\n"
    },
    "PhoneInput": {
      "type": "string",
      "minLength": 9,
      "maxLength": 20,
      "pattern": "^[+]?[0-9\\s\\-\\(\\)]+$",
      "description": "A phone number as this API accepts it: 9 to 20 characters, and only digits, spaces,\ndashes, parentheses and an optional leading `+`. Every request that takes a phone number\nuses this schema.\n\nIt is `Phone` plus the rules enforced on input. A value this schema accepts always\nsatisfies `Phone`, so anything you send here is something a response can return.\n"
    },
    "SWIFT": {
      "type": "string",
      "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$",
      "minLength": 8,
      "maxLength": 11,
      "description": "SWIFT/BIC code"
    }
  }
}