beel-es · Schema

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.

InvoicingSpainFintechSoftware-as-a-Service

Properties

Name Type Description
metadata object
customers_validation array List of processed customers with their validation status
statistics object
View JSON Schema on GitHub

JSON Schema

beel-es-customer-validation-unified-result-schema.json Raw ↑
{
  "$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.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/beel-es-customer-validation-unified-result"
All schemas
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.