CustomerValidationUnifiedResult
Unified format for customer validation results. Used for bulk validation (JSON), CSV import and Holded Excel import. One shape for every bulk and import outcome, so a caller reads a batch creation, a CSV import and a Holded import the same way.
Properties
| Name | Type | Description |
|---|---|---|
| metadata | object | |
| customers_validation | array | List of processed customers with their validation status |
| statistics | object |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/beel-es/json-schema/beel-es-customer-validation-unified-result-schema.json",
"title": "CustomerValidationUnifiedResult",
"description": "Unified format for customer validation results.\nUsed for bulk validation (JSON), CSV import and Holded Excel import.\n\nOne shape for every bulk and import outcome, so a caller reads a batch creation, a CSV\nimport and a Holded import the same way.\n",
"x-generated": "2026-11-10",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/beel-es-companycustomerimports-api-openapi.yml#/components/schemas/CustomerValidationUnifiedResult",
"type": "object",
"required": [
"metadata",
"customers_validation",
"statistics"
],
"properties": {
"metadata": {
"$ref": "#/$defs/CustomerValidationMetadata"
},
"customers_validation": {
"type": "array",
"items": {
"$ref": "#/$defs/CustomerValidationItem"
},
"description": "List of processed customers with their validation status"
},
"statistics": {
"$ref": "#/$defs/CustomerValidationStatistics"
}
},
"$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"
}
}
},
"CustomerEcho": {
"type": "object",
"required": [
"legal_name"
],
"description": "A customer as it was submitted, once parsed and validated. Same fields as `Customer` minus\nthe ones only a stored customer has (`id`, `created_at`, `updated_at`): a rehearsal writes\nnothing, so it has none of them to report. The identifier of a customer that WAS created is\nreported next to this object, in `customer_id`.\n\n`Customer` itself is untouched — many endpoints return it and it does require an `id`.\n",
"properties": {
"legal_name": {
"type": "string"
},
"trade_name": {
"type": "string"
},
"nif": {
"$ref": "#/$defs/NIF"
},
"alternative_id": {
"$ref": "#/$defs/AlternativeIdentifier"
},
"address": {
"$ref": "#/$defs/Address"
},
"phone": {
"$ref": "#/$defs/Phone"
},
"email": {
"type": [
"string",
"null"
],
"format": "email",
"minLength": 5,
"maxLength": 255,
"description": "Main contact address (minimum valid email is 5 chars, e.g. a@b.co). Invoice emails go\nhere only when the customer has no `billing_emails`.\n"
},
"website": {
"type": [
"string",
"null"
],
"maxLength": 255,
"description": "Website URL",
"pattern": "^(https?://.+|)$"
},
"billing_emails": {
"type": "array",
"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.\n"
},
"contact_person": {
"type": "string"
},
"notes": {
"type": "string",
"maxLength": 1000
},
"preferred_payment_method": {
"$ref": "#/$defs/PaymentInfo"
},
"general_discount": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"active": {
"type": "boolean"
}
}
},
"CustomerValidationError": {
"type": "object",
"required": [
"field",
"value",
"message",
"code"
],
"description": "Field-specific validation error",
"properties": {
"field": {
"type": "string",
"description": "Field that failed validation"
},
"value": {
"type": "string",
"description": "Value that caused the error"
},
"message": {
"type": "string",
"description": "Human-readable text, already resolved to the language of the request. It is never a raw\ni18n key — a key neither reads nor is stable against a rename.\n"
},
"code": {
"type": "string",
"description": "Stable, uppercase, never translated — this is what an integration compares. Present\non every row error. When the same failure exists on the single\n`POST /v1/companies/{company_id}/customers`, it is the SAME code, so the single and the\nbulk route never disagree about the same customer (`CLIENT_DUPLICATE`,\n`NIF_NOT_IN_CENSUS`, `NIF_REVOCADO`, `CUSTOMER_IDENTIFIER_REQUIRED`,\n`NIF_INVALID_FORMAT`, …). Failures\nthat only an import has carry their own: `CUSTOMER_DUPLICATED_IN_BATCH`,\n`CUSTOMER_DUPLICATED_IN_FILE`, `CUSTOMER_FIELD_REQUIRED`,\n`CUSTOMER_FIELD_INVALID_FORMAT`, `CUSTOMER_FIELD_INVALID_CHARACTERS`,\n`CUSTOMER_ADDRESS_INVALID`, `CUSTOMER_NOT_SAVED`,\n`CUSTOMER_ROW_NOT_PROCESSED`. An address field of a file row that the JSON contract\nwould have capped carries the address code, blank after trimming or over its length:\n`STREET_EMPTY`, `POSTAL_CODE_EMPTY`, `CITY_EMPTY`, `PROVINCE_EMPTY`,\n`STREET_MAX_LENGTH` (255), `NUMBER_MAX_LENGTH` (20), `CITY_MAX_LENGTH` (100),\n`PROVINCE_MAX_LENGTH` (100). A reason with no specific code yet answers\n`VALIDATION_ERROR`.\n"
}
}
},
"CustomerValidationItem": {
"type": "object",
"required": [
"index",
"status",
"errors",
"warnings"
],
"description": "Individual customer validation result.\nWorks for bulk JSON, CSV import and Holded Excel import.\n",
"properties": {
"index": {
"type": "integer",
"description": "Customer index in the submitted list (0-based for bulk, 1-based for files).\nFor CSV/Excel, represents the row number in the file.\n"
},
"customer": {
"allOf": [
{
"$ref": "#/$defs/CustomerEcho"
}
],
"description": "**Echo of what was submitted**, parsed and validated. Absent when the row could not be\nparsed at all.\n\nIt is deliberately NOT a `Customer`: the same operation also runs as a rehearsal\n(`dry_run=true`), where nothing is written and there is no `id` nor `created_at` to\nreport. Typing it as `Customer` — which requires both — made the contract impossible to\nhonour in one of its two modes, and it was in fact honoured in neither. **The identifier\nof what was created travels in `customer_id`**, at row level, and only when the row\nactually created something.\n"
},
"customer_id": {
"allOf": [
{
"$ref": "#/$defs/UUID"
}
],
"description": "Identifier of the customer this row created. **Present only when the row actually\ncreated something**: absent in a rehearsal (`dry_run=true`), absent on a row that was\nrejected, and absent on a batch that was rejected as a whole.\n\nAfter a `201`, every row carries it, and\n`GET /v1/companies/{company_id}/customers/{customer_id}` answers `200`.\n"
},
"status": {
"type": "string",
"enum": [
"VALID",
"WARNING",
"ERROR",
"DUPLICATE",
"NIF_INVALID"
],
"description": "Customer validation status:\n- VALID: Completely valid customer\n- WARNING: Valid customer but with non-critical warnings\n- ERROR: Invalid customer, cannot be processed\n- DUPLICATE: Duplicate customer (in batch/CSV or database)\n- NIF_INVALID: the identifier does not match the AEAT census: a NIF the census does not\n identify, or a type 07 (not registered) whose DNI or NIE the census does identify\n"
},
"errors": {
"type": "array",
"description": "List of errors found (block import)",
"items": {
"$ref": "#/$defs/CustomerValidationError"
}
},
"warnings": {
"type": "array",
"description": "List of warnings (do not block import)",
"items": {
"$ref": "#/$defs/CustomerValidationWarning"
}
},
"row_number": {
"type": [
"integer",
"null"
],
"description": "Row number in the file (CSV or Excel depending on source_type)"
}
}
},
"CustomerValidationMetadata": {
"type": "object",
"required": [
"total_customers",
"is_dry_run",
"processing_time_ms",
"source_type"
],
"description": "Metadata about the validation operation.\nCompatible with bulk JSON, CSV import and Holded Excel import.\n",
"properties": {
"total_customers": {
"type": "integer",
"description": "Total number of customers submitted"
},
"is_dry_run": {
"type": "boolean",
"description": "Whether it was validation (true) or import (false)"
},
"processing_time_ms": {
"type": "integer",
"description": "Processing time in milliseconds"
},
"source_type": {
"type": "string",
"enum": [
"BULK_JSON",
"CSV_IMPORT",
"HOLDED_EXCEL"
],
"description": "Data source type:\n- BULK_JSON: Data sent as JSON to bulk endpoint\n- CSV_IMPORT: Data parsed from CSV file\n- HOLDED_EXCEL: Data parsed from Holded Excel file\n"
},
"filename": {
"type": [
"string",
"null"
],
"description": "File name (CSV or Excel depending on source_type)"
},
"file_size_bytes": {
"type": [
"integer",
"null"
],
"description": "File size in bytes"
},
"total_rows": {
"type": [
"integer",
"null"
],
"description": "Total file rows excluding headers"
}
}
},
"CustomerValidationStatistics": {
"type": "object",
"required": [
"total_processed",
"valid",
"with_warnings",
"with_errors",
"duplicates",
"invalid_nifs",
"imported",
"success_rate"
],
"description": "Aggregated validation statistics.\nCompatible with all source types (bulk JSON, CSV and Holded Excel).\n\nEvery field except `imported` counts rows of the submitted file/payload, classified by\noutcome: each row falls into exactly one of `valid`, `with_warnings`, `with_errors`,\n`duplicates` and `invalid_nifs`, so those five add up to `total_processed`.\n`imported` is the only field that counts writes to the database, so it is the field to\nread to know whether an import worked.\n",
"properties": {
"total_processed": {
"type": "integer",
"description": "Total customers processed"
},
"valid": {
"type": "integer",
"description": "Completely valid customers (no warnings or errors)"
},
"with_warnings": {
"type": "integer",
"description": "Valid customers but with warnings"
},
"with_errors": {
"type": "integer",
"description": "Customers with errors (not importable)"
},
"duplicates": {
"type": "integer",
"description": "Customers with duplicate NIFs"
},
"invalid_nifs": {
"type": "integer",
"description": "Customers with NIFs not valid in AEAT"
},
"imported": {
"type": "integer",
"description": "Customers actually created in the database by this request.\nAlways `0` when `is_dry_run=true` (a preview writes nothing). On a real import it is\nthe number of rows that reached the database — normally `importable`, and lower when a\nrow was rejected on write (it is then reported under `duplicates` or `with_errors`).\n"
},
"success_rate": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 1,
"description": "Success rate (valid + with_warnings) / total_processed"
},
"importable": {
"type": "integer",
"description": "Total customers that can be imported (valid + with_warnings)"
},
"not_importable": {
"type": "integer",
"description": "Total customers that CANNOT be imported (with_errors + duplicates + invalid_nifs)"
}
}
},
"CustomerValidationWarning": {
"type": "object",
"required": [
"field",
"message"
],
"description": "Validation warning (does not block import)",
"properties": {
"field": {
"type": "string",
"description": "Field with warning"
},
"message": {
"type": "string",
"description": "Warning message"
}
}
},
"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"
]
},
"Phone": {
"type": "string",
"maxLength": 20,
"description": "A phone number, as the record holds it: digits, spaces, dashes, parentheses and an\noptional leading `+`, up to 20 characters.\n\nThis is the schema a **response** carries, and the length above is the only rule it\nstates. It deliberately does not repeat the character rule, because a number can reach a\nrecord through a path that predates that rule or never passed through this API at all —\na payment provider's customer data, a bulk import. Read the field defensively and do not\nassume it parses.\n\nWhat a **request** has to satisfy is `PhoneInput`, which adds the rules this API enforces\non the way in.\n"
},
"SWIFT": {
"type": "string",
"pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$",
"minLength": 8,
"maxLength": 11,
"description": "SWIFT/BIC code"
},
"UUID": {
"type": "string",
"format": "uuid",
"description": "Universally Unique Identifier (UUID v4)"
}
}
}
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-customer-validation-unified-result"
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.