--- title: "Spain" url: "https://developer.incode.com/general-reference/spain/" section: "general-reference" group: "eKYB Reference / eKYB Prefill Coverage" version: "v1.1" status: "live" --- # Spain eKYB Prefill in Spain leverages Spain's source of truth to automatically retrieve and populate business information based on a company's CIF or VAT number, including the business name, registered address, entity type, registration status, directors, shareholders, and additional financial and corporate data, without requiring manual input from the user. ## Source | Country | Source | Description | | --- | --- | --- | | Spain | `ES_KYB_PREFILL` | Returns matching Spanish business details from Spain's source of truth for pre-fill. | ## Direct API approach For general integration notes and shared response semantics, see the [eKYB Prefill API Reference](/general-reference/ekyb-prefill-api-reference/). All module configurations and user data can be forwarded directly in the request for performing a Prefill lookup. This overrides existing configuration and data collected about the user. ### Endpoint `POST /omni/externalVerification/ekyb-prefill` ### Request parameters | Parameter | Required | Description | | --- | --- | --- | | plugins | Mandatory | String array. Must be `["ekyb-prefill"]`. Specifies the Prefill flow. | | source | Mandatory | String. Must be `ES_KYB_PREFILL`. Identifies the Prefill source. | | country | Mandatory | String. Two-letter Alpha-2 country code. Must be `ES`. | | taxId | Mandatory | String. Spanish CIF or VAT number. See Tax ID formats for details. | | businessName | Optional | String. Registered name of the business. When provided, adds `nameMatch` to the response. | | address | Optional | String. Business address as a freeform string. When provided, adds `addressMatch` to the response. | ### Tax ID formats The `taxId` field accepts three CIF formats and a VAT number format. Routing between them is determined automatically by the format of the submitted value. | ID Type | Format | Example | | --- | --- | --- | | **CIF — Regular company** | 1 letter + 8 digits | `B12345678` | | **CIF — Sole Trader** | 8 digits + 1 letter | `12345678A` | | **CIF — Foreign Sole Trader** | 1 letter + 7 digits + 1 letter | `X1234567A` | | **VAT number** | `ES` + CIF | `ESB12345678` | Inputs that do not match any of the above formats return a 400 error. ### Sample request ```json { "plugins": ["ekyb-prefill"], "source": "ES_KYB_PREFILL", "country": "ES", "taxId": "B12345678", "businessName": "SECONDOLAB SL", "address": "CALLE ANNA 6 PTA 2, 08620 SANT VICENÇ DELS HORTS" } ``` ### Sample response The Prefill response returns business data retrieved directly from the source of truth. Fields are returned as-is from the source. `nameMatch` and `addressMatch` are only present when `businessName` or `address` were submitted in the request. `otherNames`, `turnover`, `employeeCount`, `companySize`, `shareholders`, and `directors` are only present when available for the company. **Example 1 — SECONDOLAB (Limited Liability Company)** ```json { "kyb-prefill": [ { "tin": "B12345678", "vatNo": "ES12345678", "name": "SECONDOLAB SL", "otherNames": [ { "name": "SECONDOLAB", "businessNameType": "Trade Name" } ], "nameMatch": "Verified", "address": "CALLE ANNA 6 PTA 2, 08620 SANT VICENÇ DELS HORTS", "city": "SANT VICENÇ DELS HORTS", "postalCode": "12345", "entityType": "Limited Liability Company", "registrationStatus": "Active", "registrationDate": "2011-09-15T00:00:00Z", "creditRating": "B", "creditRatingDescription": "Low Risk", "industryDesc": "Retail sale via mail order houses or via Internet", "activityDesc": "Retail sale via mail order houses or via Internet", "turnover": { "currency": "EUR", "value": 120000 }, "employeeCount": "1", "companySize": "Micro-company", "shareholders": [ { "name": "ANA MARIA JIMENEZ", "percentSharesHeld": 100 } ], "directors": [ { "name": "ANA MARIA JIMENEZ", "positionName": "Sole Administrator" } ] } ] } ``` **Example 2 — MARIA MAESTRE ANNA CB (Joint Ownership / Comunidad de Bienes)** ```json { "kyb-prefill": [ { "tin": "E12345678", "vatNo": "ES12345678", "name": "MARIA MAESTRE ANNA CB", "otherNames": [ { "name": "Champús", "businessNameType": "Trade Name" } ], "nameMatch": "Verified", "address": "CALLE Champús PROPI LA OCA 90 LOCAL POSTERIOR, 28041 MADRID", "city": "MADRID", "postalCode": "28041", "entityType": "Joint Ownership", "registrationStatus": "Active", "creditRating": "C", "creditRatingDescription": "Moderate Risk", "industryDesc": "Retail sale of footwear and leather goods in specialised stores", "activityDesc": "Retail sale of footwear and leather goods in specialised stores", "employeeCount": "12", "companySize": "Small company" } ] } ``` ### Response fields | Key | Value | Description | | --- | --- | --- | | tin | CIF number | The Spanish CIF as confirmed by the source of truth. | | vatNo | VAT identifier | The Creditsafe internal company number (`companyNumber`) mapped as the VAT identifier (for example, `ES09166632`). Present for all companies. | | name | Business name | The registered legal name of the business (`registeredCompanyName`) as returned from the source of truth. | | otherNames | Array of `{name, businessNameType}` | Trade names or other business names associated with the company. `businessNameType` is always `"Trade Name"`. Only present when a trade name differs from the registered legal name. | | nameMatch | Verified, Approximate Match, Unverified | Match result comparing the submitted `businessName` against the registered name on file. Only present when `businessName` was submitted in the request. See Name and address match values for details. | | address | Registered address | The primary registered address of the business as returned from the source of truth. | | addressMatch | Verified, Approximate Match, Unverified | Match result comparing the submitted `address` against the registered address on file. Only present when `address` was submitted in the request. See Name and address match values for details. | | city | City | The city of the registered address as returned from the source of truth. | | postalCode | Postal code | The postal code of the registered address as returned from the source of truth. | | entityType | Entity type | The legal form of the business as returned from the source of truth (for example, `Limited Liability Company`, `Joint Ownership`). Defaults to `Unknown` when not available. | | registrationStatus | Registration status | The current company status as returned from the source of truth (for example, `Active`). Defaults to `Unknown` when not available. | | registrationDate | Date | The date the company was registered, as returned from the source of truth. May not be present for all companies. | | creditRating | Credit rating value | The standardized credit rating value (for example, `B`). Defaults to `Unknown` when not available. May not be present for all companies. | | creditRatingDescription | Credit rating description | A human-readable description of the credit rating (for example, `Low Risk`). May not be present for all companies. | | industryDesc | Industry description | The primary activity description as returned from the source of truth (for example, `Retail sale via mail order houses or via Internet`). | | activityDesc | Activity description | The principal activity description as returned from the source of truth. For Spain, this is typically identical to `industryDesc`. | | turnover | `{currency, value}` object | The latest turnover figure as returned from the source of truth. May not be present for all companies. | | employeeCount | String | The latest employee count as returned from the source of truth. Always returned as a string. May not be present for all companies. | | companySize | String | The company size classification as returned from the source of truth (for example, `Micro-company`, `Small company`). May not be present for all companies. | | shareholders | Array of `{name, percentSharesHeld}` | Shareholders associated with the business as returned from the source of truth. Absent for Joint Ownership (`Comunidad de Bienes`) entities — this is expected, not an error. May not be present for all other company types. | | directors | Array of `{name, positionName}` | Current directors and officers as returned from the source of truth. `positionName` reflects the primary position title on file. Absent for Joint Ownership (`Comunidad de Bienes`) entities — this is expected, not an error. May not be present for all other company types. | ### Name and address match values | Status | Description | | --- | --- | | Verified | Exact match found against registry data. | | Approximate Match | Similar match found; may reflect minor differences in naming or address formatting. | | Unverified | No match found in registry data. | ### Registration status values | Status | Description | | --- | --- | | Active | The company is currently active and registered. | | Inactive | The company registration is dissolved, struck off, or no longer active. | | Unknown | The registration status could not be determined. | ## Error responses For standard HTTP response codes, see the API Error Response page. Spain Prefill returns the following country-specific 400 errors. `taxId` is missing, empty, or does not match a supported Spanish identifier format: ```json { "timestamp": 1782851408892, "status": 400, "error": "Bad Request", "message": "taxId must be a valid Spanish CIF (letter + 8 digits, 8 digits + letter, or letter + 7 digits + letter) or VAT number (ES + CIF)", "path": "/omni/externalVerification/ekyb-prefill" } ``` Any mandatory field (`plugins`, `source`, `country`, or `taxId`) is missing: ```json { "timestamp": 1782851468367, "status": 400, "error": "Bad Request", "message": "must not be blank", "path": "/omni/externalVerification/ekyb-prefill" } ``` No business match is found for the submitted `taxId`: ```json { "timestamp": 1782851583695, "status": 200, "message": "No business found matching the provided tax ID.", "path": "/omni/externalVerification/ekyb-prefill" } ``` ## Single Session Dashboard results Prefill results are available on the Business tab in [Single Session view](/dashboard-platform-administration/single-session-view/).