# Spain

Spain eKYC verification matches submitted individual data against Spain's Utility - Phone Register as the source of truth. See the [eKYC API Reference](https://developer.incode.com/docs/ekyc-api-reference) for common response semantics that apply across all sources.

## Available sources

| Source                 | API source string | Description                                                       |
| ---------------------- | ----------------- | ----------------------------------------------------------------- |
| Spain Phone Register 2 | `ES_1`            | Verifies submitted data against Spain's Utility - Phone Register. |

{/* TODO: Confirm with PM — existing API documentation identifies the source as `ES_1` with the source of truth described as "Utility - Phone Register," but the Dashboard drop-down shows "Spain Phone Register 2." Confirm whether `ES_1` is still the correct source string in the API request and what the "2" in the Dashboard name indicates. */}

## Spain Phone Register 2

### Request parameters

| Parameter     | Required  | Description                                                         |
| ------------- | --------- | ------------------------------------------------------------------- |
| `source`      | Mandatory | Must be `ES_1`.                                                     |
| `country`     | Mandatory | Must be `ES`.                                                       |
| `taxID`       | Mandatory | Spanish DNI. Nine characters: eight digits followed by a letter.    |
| `firstName`   | Mandatory | First name of the individual.                                       |
| `surName`     | Mandatory | Last name (Apellido2, mother's last name).                          |
| `middleName`  | Optional  | Apellido1 (father's last name).                                     |
| `houseNo`     | Optional  | House or building number.                                           |
| `street`      | Optional  | Street name.                                                        |
| `city`        | Optional  | City of the individual's address (for example, `Madrid`).           |
| `state`       | Optional  | State or autonomous community (for example, `Comunidad de Madrid`). |
| `postalCode`  | Optional  | Postal code.                                                        |
| `dateOfBirth` | Optional  | Format: `yyyy-mm-dd`.                                               |
| `phone`       | Optional  | Phone number.                                                       |

{/* TODO: Confirm with PM — existing API documentation lists taxID, firstName, surName, and country as mandatory, and the documented 400 error message states "taxId, and country are minimum required fields." However, the Dashboard UI only locks Name as required; National ID Number (DNI, which maps to taxID) is not locked. Confirm which set of requirements is accurate for customer-facing documentation. */}

### Response fields

Spain Phone Register 2 anchors verification on the source-of-truth register. See the [eKYC API Reference](https://developer.incode.com/docs/ekyc-api-reference) for common match field definitions and status values.

| Field                | Statuses                              | Description                                                                         |
| -------------------- | ------------------------------------- | ----------------------------------------------------------------------------------- |
| `firstNameMatch`     | `exact`, `fuzzy`, `nomatch`           | Matches first name submitted against the value in the source of truth.              |
| `middleNameMatch`    | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches middle name submitted against the value in the source of truth.             |
| `lastNameMatch`      | `exact`, `fuzzy`, `nomatch`           | Matches last name submitted against the value in the source of truth.               |
| `fullNameMatch`      | `exact`, `fuzzy`, `nomatch`           | Matches full name submitted against the value in the source of truth.               |
| `dobMatch`           | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches date of birth submitted against the value in the source of truth.           |
| `streetMatch`        | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches street submitted against the value in the source of truth.                  |
| `houseNoMatch`       | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches house number submitted against the value in the source of truth.            |
| `streetAddressMatch` | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches street and house number submitted against the value in the source of truth. |
| `cityMatch`          | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches city submitted against the value in the source of truth.                    |
| `stateMatch`         | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches state submitted against the value in the source of truth.                   |
| `postalCodeMatch`    | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches postal code submitted against the value in the source of truth.             |
| `fullAddressMatch`   | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches full address submitted against the value in the source of truth.            |
| `idNumMatch`         | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches DNI submitted against the value in the source of truth.                     |
| `phoneMatch`         | `exact`, `fuzzy`, `nomatch`, `nodata` | Matches phone submitted against the value in the source of truth.                   |
| `overallLevel`       | `low`, `medium`, `high`               | Overall risk level. See below for calculation logic.                                |

### overallLevel calculation

`overallLevel` is calculated based on the risk associated with the submitted full name and DNI:

- `low` when `fullNameMatch` and `idNumMatch` are both `exact`.
- `high` when `fullNameMatch` and `idNumMatch` are both `nomatch`.
- `medium` for all other combinations.

Contact your Incode representative to customize the `overallLevel` calculation for your use case.

### Sample response

```json
{
    "kyc": [
        { "key": "firstNameMatch", "status": "exact" },
        { "key": "middleNameMatch", "status": "exact" },
        { "key": "lastNameMatch", "status": "fuzzy" },
        { "key": "fullNameMatch", "status": "fuzzy" },
        { "key": "dobMatch", "status": "exact" },
        { "key": "streetMatch", "status": "exact" },
        { "key": "cityMatch", "status": "exact" },
        { "key": "stateMatch", "status": "exact" },
        { "key": "postalCodeMatch", "status": "exact" },
        { "key": "fullAddressMatch", "status": "fuzzy" },
        { "key": "idNumMatch", "status": "exact" },
        { "key": "phoneMatch", "status": "nomatch" },
        { "key": "overallLevel", "status": "low" }
    ]
}
```

<br />