PatchCustomerRequest
Partial update of a customer (RFC 5789). Only the fields present in the body are touched: - **field omitted** → the current value is kept; - **field sent with a value** → replaced; - **field sent as `null`** → cleared (only where documented as nullable below). The resulting customer goes through the same validation as `PUT` (AEAT census check for Spanish NIFs, duplicate identifier check excluding this customer, field formats). The census check matches `legal_name` only for individuals; for a company the name is **not verified** and only the CIF decides.
Properties
| Name | Type | Description |
|---|---|---|
| nif | object | New Spanish Tax ID. Mutually exclusive with `alternative_id`. Omit to keep the current identifier; it cannot be cleared. |
| alternative_id | object | New alternative identifier (non-Spanish customers). Mutually exclusive with `nif`. Omit to keep the current identifier. |
| legal_name | string | Customer legal name. Cannot be cleared. Matched against the AEAT census only for individuals; for a company the name is **not verified**. |
| trade_name | stringnull | Customer trade name. Send `null` to clear it. |
| address | object | Full address. Replaced as a whole (the address itself is not patched field by field) and cannot be cleared. |
| phone | object | Phone number. Send `null` to clear it. |
| stringnull | Main contact address. Invoice emails go here only when the customer has no `billing_emails`. Send `null` to clear it. | |
| website | stringnull | Website URL. Send `null` to clear it. |
| billing_emails | arraynull | Addresses that receive the customer's invoice emails. When the send request names no `recipients` and the invoice has no `email_config` recipients, invoices go to these addresses, and not to `email`; |
| contact_person | stringnull | Contact person name. Send `null` to clear it. |
| notes | stringnull | Additional notes. Send `null` to clear it. |
| preferred_payment_method | object | Default payment method. Replaced as a whole; omit it to keep the current one. |
| general_discount | numbernull | General discount percentage. Send `null` to clear it. |
| active | boolean | Whether the customer is active or inactive. |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/beel-es/json-schema/beel-es-patch-customer-request-schema.json",
"title": "PatchCustomerRequest",
"description": "Partial update of a customer (RFC 5789). Only the fields present in the\nbody are touched:\n\n- **field omitted** → the current value is kept;\n- **field sent with a value** → replaced;\n- **field sent as `null`** → cleared (only where documented as nullable\n below).\n\nThe resulting customer goes through the same validation as `PUT`\n(AEAT census check for Spanish NIFs, duplicate identifier check\nexcluding this customer, field formats). The census check matches\n`legal_name` only for individuals; for a company the name is\n**not verified** and only the CIF decides.\n",
"x-generated": "2026-11-10",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/beel-es-companycustomers-api-openapi.yml#/components/schemas/PatchCustomerRequest",
"type": "object",
"properties": {
"nif": {
"allOf": [
{
"$ref": "#/$defs/NIF"
}
],
"description": "New Spanish Tax ID. Mutually exclusive with `alternative_id`.\nOmit to keep the current identifier; it cannot be cleared.\n"
},
"alternative_id": {
"allOf": [
{
"$ref": "#/$defs/AlternativeIdentifier"
}
],
"description": "New alternative identifier (non-Spanish customers). Mutually\nexclusive with `nif`. Omit to keep the current identifier.\n"
},
"legal_name": {
"type": "string",
"minLength": 1,
"maxLength": 120,
"description": "Customer legal name. Cannot be cleared. Matched against the AEAT census only\nfor individuals; for a company the name is **not verified**.\n"
},
"trade_name": {
"type": [
"string",
"null"
],
"maxLength": 120,
"description": "Customer trade name. Send `null` to clear it."
},
"address": {
"allOf": [
{
"$ref": "#/$defs/Address"
}
],
"description": "Full address. Replaced as a whole (the address itself is not\npatched field by field) and cannot be cleared.\n"
},
"phone": {
"allOf": [
{
"$ref": "#/$defs/PhoneInput"
}
],
"description": "Phone number. Send `null` to clear it."
},
"email": {
"type": [
"string",
"null"
],
"format": "email",
"minLength": 5,
"maxLength": 255,
"description": "Main contact address. Invoice emails go here only when the customer has no\n`billing_emails`. Send `null` to clear it.\n"
},
"website": {
"type": [
"string",
"null"
],
"maxLength": 255,
"pattern": "^(https?://.+|)$",
"description": "Website URL. Send `null` to clear it."
},
"billing_emails": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/$defs/Email"
},
"description": "Addresses that receive the customer's invoice emails. When the send request names no\n`recipients` and the invoice has no `email_config` recipients, invoices go to these\naddresses, and not to `email`; `email` is used only when `billing_emails` is empty.\nReplaced as a whole; send `null` or `[]` to remove them all.\n"
},
"contact_person": {
"type": [
"string",
"null"
],
"maxLength": 200,
"description": "Contact person name. Send `null` to clear it."
},
"notes": {
"type": [
"string",
"null"
],
"description": "Additional notes. Send `null` to clear it."
},
"preferred_payment_method": {
"allOf": [
{
"$ref": "#/$defs/PaymentInfo"
}
],
"description": "Default payment method. Replaced as a whole; omit it to keep the\ncurrent one.\n"
},
"general_discount": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 100,
"description": "General discount percentage. Send `null` to clear it."
},
"active": {
"type": "boolean",
"description": "Whether the customer is active or inactive."
}
},
"$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"
}
}
},
"AlternativeIdentifier": {
"type": [
"object",
"null"
],
"required": [
"type",
"number"
],
"description": "Alternative identifier for customers without Spanish Tax ID.\n\n### VeriFactu rules (checked when you send it, `422` on violation)\n- `country_code` is required, except for `PASSPORT` (03) and `NOT_REGISTERED` (07), the two\n types AEAT accepts with `ES`: omitted, `ES` applies. Missing for any other type, the\n identifier is rejected with `ALTERNATIVE_ID_COUNTRY_REQUIRED`, and `error.details` names\n the field where it was sent: `alternative_id.country_code` on a customer,\n `recipient.alternative_id.country_code` on an invoice recipient. Same code in both.\n- If `country_code = ES`, then `type` **must** be `PASSPORT` (03) or `NOT_REGISTERED` (07)\n (`ALTERNATIVE_ID_SPAIN_INVALID_TYPE`).\n- If `type = NOT_REGISTERED` (07), then `country_code` **must** be `ES`\n (`ALTERNATIVE_ID_REQUIRES_SPAIN`), and `number` **must** be a Spanish DNI or NIE: a\n Spanish company is always registered (`RECIPIENT_UNREGISTERED_ID_MUST_BE_DNI_OR_NIE`).\n That DNI or NIE must not be one the AEAT census identifies: if it is, the identifier is\n rejected with `ALTERNATIVE_ID_ACTUALLY_IN_CENSUS` and has to be sent as `nif`. A customer\n is checked when it is saved; an invoice recipient, when the invoice is issued with\n VeriFactu. If the census does not answer, the identifier is not rejected.\n- If `type = NIF_IVA` (02), `country_code` **must** be an EU member state other than Spain\n (`ALTERNATIVE_ID_VAT_REQUIRES_EU_COUNTRY`), and `number` **must** have that country's\n EU VAT number structure as AEAT defines it: the country prefix (`EL` for Greece) followed\n by the national number, e.g. `FR40303265045`, `DE123456789`, `EL094014201`\n (`ALTERNATIVE_ID_VAT_INVALID_FORMAT`). Lowercase letters are accepted and stored in\n uppercase. A customer from outside the EU is identified with another type, such as\n `OTHER_DOCUMENT` or `COUNTRY_ID`.\n\nA `number` that is blank once trimmed is rejected with `ALTERNATIVE_ID_INVALID`.\n\nWell-formed is not the same as registered: an EU VAT number that is not in the VIES\ncensus is still rejected by VeriFactu after the invoice is issued.\n\nAn identifier returned in a response is the one stored. A customer saved before a rule\nexisted keeps its identifier and can still be read; issuing an invoice to it with an\nidentifier that breaks these rules is rejected with the same code, before a number is used.\n\n### Matrix of allowed combinations\n| `type` | `country_code = ES` | `country_code ≠ ES` |\n|------------------------|:-------------------:|:-------------------:|\n| `NIF_IVA` (02) | ✗ | EU member states only |\n| `PASSPORT` (03) | ✓ | ✓ |\n| `COUNTRY_ID` (04) | ✗ | ✓ |\n| `RESIDENCE_CERTIFICATE` (05) | ✗ | ✓ |\n| `OTHER_DOCUMENT` (06) | ✗ | ✓ |\n| `NOT_REGISTERED` (07) | ✓ | ✗ |\n",
"properties": {
"type": {
"type": "string",
"enum": [
"NIF_IVA",
"PASSPORT",
"COUNTRY_ID",
"RESIDENCE_CERTIFICATE",
"OTHER_DOCUMENT",
"NOT_REGISTERED",
"02",
"03",
"04",
"05",
"06",
"07"
],
"description": "Identifier type. Use descriptive names:\n- **NIF_IVA**: EU VAT number (intra-community) — *only for an EU member state other than Spain, with that country's VAT number structure*\n- **PASSPORT**: Passport — *allowed for any country*\n- **COUNTRY_ID**: Country of residence ID — *not allowed when `country_code = ES`*\n- **RESIDENCE_CERTIFICATE**: Residence certificate — *not allowed when `country_code = ES`*\n- **OTHER_DOCUMENT**: Other supporting document — *not allowed when `country_code = ES`*\n- **NOT_REGISTERED**: Not registered in AEAT — *requires `country_code = ES`*\n\n**⚠️ DEPRECATED numeric codes** (will be removed in v2):\n02, 03, 04, 05, 06, 07 — use the descriptive names above instead.\n"
},
"number": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"description": "Identifier number. For `NIF_IVA`, the full EU VAT number with its country prefix\n(e.g. `FR40303265045`); see the VeriFactu rules on the parent schema.\n"
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"minLength": 2,
"maxLength": 2,
"description": "ISO 3166-1 alpha-2 code of the country that issued the document. Required except for\n`PASSPORT` and `NOT_REGISTERED`, where omitting it means `ES`. Constrains the allowed\n`type` values; see the VeriFactu rules on the parent schema.\n"
}
}
},
"Email": {
"type": "string",
"format": "email",
"minLength": 5,
"maxLength": 255,
"description": "Email address (minimum valid email is 5 chars, e.g. a@b.co)"
},
"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"
},
"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"
},
"PaymentInfo": {
"type": "object",
"properties": {
"method": {
"allOf": [
{
"$ref": "#/$defs/PaymentMethod"
}
],
"description": "Preferred payment method. Omitted, `BANK_TRANSFER` applies.\nIf NONE is selected, no payment information will be shown on the invoice.\n"
},
"iban": {
"$ref": "#/$defs/IBAN"
},
"swift": {
"$ref": "#/$defs/SWIFT"
},
"payment_term_days": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 365,
"description": "Payment term in days. When marking an invoice as paid, every field of this object\nthat travels replaces the stored one and every omitted field keeps its current value.\n"
}
}
},
"PaymentMethod": {
"type": "string",
"description": "Payment method shown on invoices and recurring invoices.\n\n- `NONE`: no payment information is shown.\n- `BANK_TRANSFER`: bank transfer to the IBAN of the payment details; the only method\n that requires an IBAN.\n- `CARD`: card payment.\n- `CASH`: cash payment.\n- `CHECK`: payment by cheque.\n- `DIRECT_DEBIT`: direct debit from the customer's bank account.\n- `BIZUM`: payment through Bizum.\n- `OTHER`: any other method.\n",
"enum": [
"NONE",
"BANK_TRANSFER",
"CARD",
"CASH",
"CHECK",
"DIRECT_DEBIT",
"BIZUM",
"OTHER"
]
},
"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-patch-customer-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.