UpdateCompanyRequest
Editable fields of a company. `entity_type`, `nif` and `legal_form` are immutable once set; `legal_name` can only be corrected together with a successful AEAT census re-validation of the NIF. For a company that re-validation checks the CIF only — the name is **not verified**, so it can never fail because of the name you send. **Everything here reads back.** The `200` of the update — and every later `GET /v1/companies/{company_id}` — returns `CompanyData`, which carries each of these fields under the same name and the same type. No need to keep your own copy to reconcile: write it, read it back. Five of them also have a read of their own, `logo_url`, `invoice_template_type`, `invoice_accent_color`, `invoice_language` and `email_language`, all returned by `GET /v1/companies/{company_id}/invoice-customization`. A field you never set is **absent** from the read, which means "nothing stored" — not "hidden from you", and not a default. What varies by caller is what you may *write* (see the Test-credential rule below), never what comes back. **From Test, on a company activated in Live, only six of these fields are writable**: `logo_url`, `invoice_accent_color`, `invoice_template_type`, `invoice_language`, `email_language` and `additional_info` — what the invoice *looks like* and the free note it carries. Everything else describes the real business and answers `422 FISCAL_IDENTITY_LIVE_ONLY` unless the call is made with a live credential.
Properties
| Name | Type | Description |
|---|---|---|
| entity_type | object | |
| legal_name | stringnull | 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 |
| nif | object | |
| legal_form | stringnull | Legal form (SL, SA, ...). IMMUTABLE once set. Only for LEGAL_ENTITY. |
| trade_name | stringnull | Commercial/trade name for the company |
| address | object | |
| legal_representative | object | |
| phone | object | |
| object | ||
| website | stringnull | Website |
| logo_url | stringnull | Logo URL |
| additional_info | stringnull | 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 / |
| default_iban | object | |
| default_swift | object | |
| account_holder | stringnull | Bank account holder |
| iae | stringnull | IAE code |
| activity_start_date | stringnull | Activity start date |
| default_payment_term | integernull | Default payment term in days |
| invoice_template_type | object | Invoice PDF template type |
| invoice_accent_color | stringnull | Invoice PDF accent color (#RRGGBB) |
| invoice_language | object | |
| email_language | object |
JSON Schema
{
"$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"
}
}
}
Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
curl "https://apis.io/api/v1/json-schemas/beel-es-update-company-request"
curl "https://apis.io/api/v1/json-schemas?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.