ESPIDCard Fields and Validations · Mobbeel for developers

Introduction

In this document we present the fields that we extract from the Spanish ID Card in its three different versions: ESPIDCardV1, ESPIDCardV2 and ESPIDCardV3. We also present a brief description of each type, as well as the validations applied to them.

Types of documents

Document Type	Front	Back
ESPIDCardV1
ESPIDCardV2
ESPIDCardV3
ESPIDCardV4

Parts of the documents

Side	Image
Front
Back

Fields extracted from the documents

`documentType`

The documentType field details the type of document. Depending on the document type, we can have the following values: ESPIDCardV1, ESPIDCardV2 and ESPIDCardV3.

The document is classified based on the appearance of the document (eg: position of the image of the face, the distribution of defining elements, colour histogram...), and based on its contents, using an analysis of the text blocks.

`firstSurname`

The firstSurname field returns the first surname. In Spain, every person has two surnames, the first one being the first surname of the father, and the second being the first surname of the mother. More information on Spanish naming customs here.

By default, the selected surname will always be the one present at the back of the card (ie: in the MRZ) and, if it cannot be read, the one at the front will be selected. If both of the sides are successfully scaned, both will be analysed and considered in order to complete the surnames or correct them, according to the following considerations:

If the surname has been detected on both sides and the one at the front has a Ñ, the surname will be corrected to include this character, since the MRZ does not allow for special characters.
If the surname is too long and is, therefore, truncated in the MRZ, it will be completed with the data from the surname at the front, after checking that the surname is the same on both sides.

`secondSurname`

The secondSurname field returns the second surname (see information on Spanish naming customs here).

If the surname has been detected on both sides and the one at the front has a Ñ, the surname will be corrected to include this character, since the MRZ does not allow for special characters.
If the surname is too long and is, therefore, truncated in the MRZ, it will be completed with the data from the surname at the front, after checking that the surname is the same on both sides.

`surname`

The surname field returns the concatenation of firstSurname and secondSurname.

Regarding the logic of the extraction, it's the same as applied in firstSurname and secondSurname.

`name`

The name field returns the name present on the back of the document (ie: the one in the MRZ) by default. If the names at the front and the back don't match due to the name being too long and, therefore, being truncated, or due to the name having special characters, it will be completed or modified according to the following:

If the name has been detected on both sides and the one at the front has a Ñ, the surname will be corrected to include this character, since the MRZ does not allow for special characters.
If the name is too long and is, therefore, truncated in the MRZ, it will be completed with the data from the surname at the front, after checking that the surname is the same on both sides.

`gender`

The gender field, which returns the gender of the document holder, is present at the front and the back of all document types except for ESPIDCardV1, where it is not shown at the front.

There are three possible scenarios regarding the gender field:

Both sides are valid: in this case, the back side is the one that's considered since the MRZ is more reliable. If the gender field doesn't match on both sides, there will be a validation, associated to the matching of this field, between both sides, which will be returned as invalid, eg: validationGenderBothSideMatch=NOT_VALID.

Both sides are not valid: no value is returned.
One of the sides is valid: the valid value will be returned. In this case, there is no validation associated to the field that's being returned as invalid, eg: validationGender = NOT_VALID.

`nationality`

The nationality field, which returns the nationality of the document holder, is present at the front and the back of all document types except for ESPIDCardV1, where it is not shown at the front.

There are three possible scenarios regarding the nationality field:

Both sides are valid: in this case, the back side is the one that's considered since the MRZ is more reliable. If the nationality field doesn't match on both sides, there will be a validation, associated to the matching of this field, between both sides, which will be returned as invalid, eg: validationNationalityBothSidesMatch=NOT_VALID.
Both sides are not valid: no value is returned.
One of the sides is valid: the valid value will be returned. In this case, there is no validation associated to the field that's being returned as invalid, eg: validationNationality = NOT_VALID.

`dateOfBirth`

The dateOfBirth field returns the document holder's date of birth.

There are three possible scenarios regarding the dateOfBirth field:

Both sides are valid: in this case, the back side is the one that's considered since the MRZ is more reliable. If the dateOfBirth field doesn't match on both sides, there will be a validation, associated to the matching of this field, between both sides, which will be returned as invalid, eg: validationDateOfBirthBothSidesMatch=NOT_VALID.
Both sides are not valid: no value is returned.
One of the sides is valid: the valid value will be returned. In this case, there is no validation associated to the field that's being returned as invalid, eg: validationDateOfBirth = NOT_VALID.

`dateOfExpiry`

The dateOfExpiry field returns the document's date of expiry.

There are three possible scenarios regarding the dateOfExpiry field:

Both sides are valid: in this case, the back side is the one that's considered since the MRZ is more reliable. If the dateOfExpiry field doesn't match on both sides, there will be a validation, associated to the matching of this field, between both sides, which will be returned as invalid, eg: validationDateOfExpiryBothSidesMatch=NOT_VALID.
Both sides are not valid: no value is returned.
One of the sides is valid: the valid value will be returned. In this case, there is no validation associated to the field that's being returned as invalid, eg: validationDateOfExpiry = NOT_VALID.

`documentNumber`

The documentNumber field returns the document's physical support number. This number changes each time that the document holder renews the document.

There are three possible scenarios regarding the documentNumber field:

Both sides are valid: in this case, the back side is the one that's considered since the MRZ is more reliable. If the documentNumber field doesn't match on both sides, there will be a validation, associated to the matching of this field, between both sides, which will be returned as invalid, eg: validationDocumentNumberBothSidesMatch=NOT_VALID.
Both sides are not valid: no value is returned.
One of the sides is valid: the valid value will be returned. In this case, there is no validation associated to the field that's being returned as invalid, eg: validationDocumentNumber = NOT_VALID.

`personalNumber`

The personalNumber field returns the document holder's personal identity number. This number does not change if the holder renews the document, and it's always present on the bottom-left corner of the document.

There are three possible scenarios regarding the personalNumber field:

Both sides are valid: in this case, the back side is the one that's considered since the MRZ is more reliable. If the personalNumber field doesn't match on both sides, there will be a validation, associated to the matching of this field, between both sides, which will be returned as invalid, eg: validationPersonalNumberBothSidesMatch=NOT_VALID.
Both sides are not valid: no value is returned.
One of the sides is valid: the valid value will be returned. In this case, there is no validation associated to the field that's being returned as invalid, eg: validationPersonalNumber = NOT_VALID.

Location of the fields within the document

The following table details where all the fields extracted from the Spanish ID Card have been obtained.

Field Name	Details	Present at the Front	Present at the Back
`documentType`	Type of document	Yes	Yes
`firstSurname`	First surname	Yes	Yes
`secondSurname`	Second surname	Yes	Yes
`surname`	Concatenation of `firstSurname` and `secondSurname`	Yes	Yes
`name`	Name	Yes	Yes
`gender`	Gender	Yes	Yes
`nationality`	Nationality	Yes	Yes
`dateOfBirth`	Date of birth	Yes	Yes
`dateOfExpiry`	Date of expiry	Yes	Yes
`documentNumber`	Document number	Yes	Yes
`personalNumber`	Document number	Yes	Yes
`cityOfBirth`	City or place of birth	No	Yes
`regionOfBirth`	Region or country of birth	No	Yes
`parents`	Name of the parents	No	Yes
`address`	Home address	No	Yes
`city`	City of domicile	No	Yes
`region`	Region of domicile	No	Yes
`issuingState`	Three digit code of the country of issue following the ISO 3166-1	No	Yes
`mrz`	Three lines of text belonging to the machine-readable zone (MRZ)	No	Yes

Side	Image
Front
Back

Validations extracted from the documents

The validations can return the following values:

VALID: states that the field to which the validation is referencing to could be extracted and is valid. The conditions which determine if a field is valid are relative to the particular field.
NOT_VALID: states that the field to which the validation is referencing to could be extracted and is not valid. The conditions which determine if a field is valid are relative to the particular field.
NOT_CHECKED: states that either this validation is not supported for the type of document that is being processed or that the field to which the validation is referencing to could not be extracted and, thus, the validation could not be completed.

Types of validations extracted from the documents

`validationSex`

Note: this validation is deprecated and substituted by validationGender. It's still being used for compatibility reasons, but will be removed in version 3.0 of MobbScan.

States whether the letter (M or F) to determine the gender of the document holder is correct and valid. This validation is returned as valid if it has been successfully validated in at least one of the two sides of the document.

`validationGender`

`validationNationality`

States whether the three letter code that represent the nationality of the document holder is correct and valid. This validation is returned as valid if the three extracted letters match one of the ISO 3166-1 alpha-3 codes. More information on the ISO codes here.

`validationDateOfBirth`

States whether the date of birth of the document holder exists and is valid. This validation is returned as valid if it has been successfully validated in at least one of the two sides of the document.

The condition to validate the date is different in each side of the document and, in order to be valid, it fill have to have the following format:

Front: mm-dd-yyyy
Back: yymmdd

If the date is valid on both sides of the document but it's different to the one extracted from the front of the document, the validation validationDateOfBirthBothSidesMatch would be returned as NOT_VALID. More information on the dateOfBirth section.

`validationDateOfExpiry`

States whether the date of expiry of the document exists and is valid. This validation is returned as valid if it has been successfully validated in at least one of the two sides of the document.

The condition to validate the date is different in each side of the document and, in order to be valid, it fill have to have the following format:

Front: mm-dd-yyyy
Back: yymmdd

If the date is valid on both sides of the document but it's different to the one extracted from the front of the document, the validation validationDateOfExpiryBothSidesMatch would be returned as NOT_VALID. More information on the dateOfExpirty section.

`validationDocumentNotExpired`

States whether the document has expired. This validation is returned as valid if it has been successfully validated in at least one of the two sides of the document.

If the validation is extracted as valid only from one of the two sides, there is a validation that will be returned as NOT_VALID: validationDateOfExpiryBothSidesMatch.

`validationPersonalNumber`

States whether the personal identity number of the document holder exists and is valid. This number is the one present on the bottom left corner, and it's the one that's commonly referred to as the "DNI number". This validation is returned as valid if it has been successfully validated in at least one of the two sides of the document.

In order for this number to be valid it will have to be validated by the algorithm that calculates the associated control digit. More information here.

If the validation is extracted as valid only from one of the two sides, there is a validation that will be returned as NOT_VALID: validationPersonalNumberBothSidesMatch.

`validationPersonalNumberFormat`

States whether the format of the personal identity number of the document holder is valid. This format consists of 8 numbers and 1 letter. If the number doesn't have this format, the validation will be returned as NOT_VALID.

`validationDocumentNumber`

States whether the document number exists and is valid. This number changes each time that the document holder renews the document.

If the validation is extracted as valid only from one of the two sides, there is a validation that will be returned as NOT_VALID: validationDocumentNumberBothSidesMatch.

`validationDocumentNumberFormat`

States whether the format of the document number of the document number is valid, which consists of 3 letters and 6 numbers. If the number doesn't have this format, the validation will be returned as NOT_VALID.

`validationNameNotEmpty`

States whether the name field is not empty. If the field is indeed empty, the validation will be returned as NOT_VALID.

`validationSurnameNotEmpty`

States whether the surname field is not empty. If the field is indeed empty, the validation will be returned as NOT_VALID.

`validationIssuingState`

States whether the field associated to the country of issue (issuingState) in the second line of the MRZ in the back of the document is valid.

This validation is returned as valid if the three extracted letters match one of the ISO 3166-1 alpha-3 codes. More information on the ISO codes here.

`validationMRZCheckPersonalNumber`

States whether the personal number control digit in the MRZ is valid. In documents from countries other than Spain, this field can have a control digit, whereas in a Spanish document, this field does not have a control digit, so it will have the same content than validationPersonalNumber.

associated to the country of issue (issuingState) in the second line of the MRZ in the back of the document is valid.

`validationMRZCheckDocumentNumber`

States whether the control digit of the document number present in the MRZ is correct.

`validationMRZCheckDateOfBirth`

States whether the control digit of the date of birth present in the MRZ is correct.

`validationMRZCheckDateOfExpiry`

States whether the control digit of the date of expiry present in the MRZ is correct.

`validationMRZCheckComposite`

States whether the global MRZ control digit is correct.

In order for this digit to be correct, the two first lines of the MRZ must be correct. Therefore, all the partial control digits in each line must also be correct:

Line 1:
- validationMRZCheckDocumentNumber
- validationMRZCheckPersonalNumber: this validation must not be valid for ESPIDCardV1
Line 2:
- validationMRZCheckDateOfBirth
- validationMRZCheckDateOfExpiry

This control digit does not verify the information in the third line of the MRZ (surnames and name).

`validationMRZ`

States whether the MRZ is correct. In order to be correct, the previous validations associated to the MRZ must have been returned as valid:

validationMRZCheckPersonalNumber
validationMRZCheckDocumentNumber
validationMRZCheckDateOfBirth
validationMRZCheckDateOfExpiry
validationMRZCheckComposite

`validationMRZNameSurnameSeparator`

States whether the characters (<<) that separate the name from the surnames are correct.

`validationMRZSurnameSeparator`

States whether the character (<) that separate the first surname to the second one is correct.

`validationPersonalNumberBothSidesMatch`

States whether the personal identity number is correct on both sides of the document.

`validationDocumentNumberBothSidesMatch`

States whether the document number is correct on both sides of the document.

`validationNameBothSidesMatch`

States whether the name field matches both sides of the document.

In order to state if the name on both sides match, the special characters on the front side (eg: Ñ, Ç) will not be considered, and will be converted to ASCII characters following the ICAO 9303 standard.

If the name is truncated by the MRZ because it exceeds the maximum number of characters, the validation will be NOT_VALID.

`validationNameBothSidesMatchScore`

States the similarity of the names in both sides of the document with a value from 0 to 100, ie: a percentage. Therefore, a value of 0 states that the names are completely different, and a value of 100 states that the names are exactly the same. The value is calculated intelligently, taking into account the most common deviations of the OCR motor (H/M, U/W...) so that the errors are pondered depending on their nature and frequency. Some examples are:

Reference	Test	Value
MANUEL ENRIQUE	MANUEL ENRIQUE	[`100`]
MANUEL ENRIQUE	HANUEL ENRIQUE	[`96`]
MANUEL ENRIQUE	TANUEL ENRIQUE	[`93`]

Using this value, the integrator will be able to establish thresholds to determine the validity of the match in a personalised way, taking the security requirements and the confidence of the system into account.

`validationSurnameBothSidesMatch`

States whether the surname field matches both sides of the document.

In order to state if the surnames on both sides match, the special characters on the front side (eg: Ñ, Ç) will not be considered, and will be converted to ASCII characters following the ICAO 9303 standard.

If the surname is truncated by the MRZ because it exceeds the maximum number of characters, the validation will be NOT_VALID.

`validationSurnameBothSidesMatchScore`

States the similarity of the surnames in both sides of the document with a value from 0 to 100, ie: a percentage. Therefore, a value of 0 states that the surnames are completely different, and a value of 100 states that the surnames are exactly the same. The value is calculated intelligently, taking into account the most common deviations of the OCR motor (H/M, U/W...) so that the errors are pondered depending on their nature and frequency. Some examples are:

Reference	Test	Value
HERNANDEZ MARTIN	FERNANDEZ MARTIN	[`94`]
HERNANDEZ MARTIN	MERNANDEZ HARTIN	[`91`]
HERNANDEZ MARTIN	LERNANDEZ LARTIN	[`88`]

`validationSexBothSidesMatch`

Note: this validation is deprecated and substituted by validationGender. It's still being used for compatibility reasons, but will be removed in version 3.0 of MobbScan.

States whether the gender field matches both sides of the document. This is not supported for ESPIDCardV1.

`validationGenderBothSidesMatch`

States whether the gender field matches both sides of the document. This is not supported for ESPIDCardV1.

`validationNationalityBothSidesMatch`

States whether the nationality field matches both sides of the document. This is not supported for ESPIDCardV1.

`validationDateOfBirthBothSidesMatch`

States whether the date of birth field matches both sides of the document.

`validationDateOfExpiryBothSidesMatch`

States whether the date of expiry field matches both sides of the document.

`validationBothSidesMatch`

States whether both sides, the front and the back, belong to the same document. The validation is currently based on all the previously described validations, which means that the following fields must match: documentNumber, name, surname, gender, nationality, dateOfBirth and dateOfExpiry.

`validationBothSidesMatchScore`

Returns an integer within the interval of 0-100 regarding the evaluation of how both sides match.

`validationFrontAppearance`

States whether the general appearance of the front side is correct, detecting possible anomalies or modifications, as long as the quality of the image is good enough to proceed with the evaluation (for more details: validationFrontAppearanceScore)

The result provided by this validation is considered in a decision threshold, which can be determined by the integrator considering their security needs, or else use the preestablished one in the platform for an average scenario.

`validationBackAppearance`

States whether the general appearance of the back side is correct, detecting possible anomalies or modifications, as long as the quality of the image is good enough to proceed with the evaluation (for more details: validationBackAppearanceScore)

`validationFrontAppearanceScore`

Returns an integer within the interval of 0-100 regarding the evaluation of the appearance of the front of the document. Some of the elements that are considered in the calculation of this value are:

The presence or absence of distinctive elements.
The presence or absence of the facial image and its appearance.
The detection of photocopied documents or captured from a screen.
The degree of correlation of a photocopied document or captured from a screen to the official model.

From this value, the decision thresholds can be determined to validate the appearance of the document.

`validationBackAppearanceScore`

Returns an integer within the interval of 0-100 regarding the evaluation of the appearance of the back of the document. Some of the elements that are considered in the calculation of this value are:

The presence or absence of distinctive elements.
The presence or absence of the facial image and its appearance.
The detection of photocopied documents or captured from a screen.
The degree of correlation of a photocopied document or captured from a screen to the official model.

From this value, the decision thresholds can be determined to validate the appearance of the document.

`validationFrontNotPhotocopy`

States whether the colour of the front of the document is correct and that it's not a black and white photocopy.

`validationFrontPhotocopyScore`

Returns an integer within the interval of 0-100 stating whether the colour of the front of the document is correct and that it's not a black and white photocopy.

`validationBackNotPhotocopy`

States whether the colour of the back of the document is correct and that it's not a black and white photocopy.

`validationBackPhotocopyScore`

Returns an integer within the interval of 0-100 stating whether the colour of the back of the document is correct and that it's not a black and white photocopy.

`validationDocumentContent`

States whether the general content of the document is valid including, among others, checks of fields and formats.

`validationDocumentForensics`

States whether the document is fraudulent, considering its content and its format, as well as the fraud detecting measures. In other words, it combines the validationDocumentContent and validationDocumentForensics validations.

`validationDocument`

States feather validationDocumentContent and validationDocumentForensics are both valid.

`validationFacialMatchingScore`

Returns an integer within the interval of 0-100 stating whether the facial matching (ie: comparing the face in the picture in the document to a selfie taken on the spot) is correct.

Note: although this validation is only valid if the integrator has selected the facial verification, the JSON always returns this validation. If the facial verification isn't available, the value will be "validationFacialMatchingScore": -1.0.

JSON example file

The following is a JSON output file resulting from scanning a Spanish National Identity Document:

{

"document":{

  "documentType": "ESPIDCardV3",
  "firstSurname": "ESPAÑOLA",
  "secondSurname": "ESPAÑOLA",
  "surname": "ESPAÑOLA ESPAÑOLA",
  "name": "CARMEN",
  "gender": "F",
  "nationality": "ESP",
  "dateOfBirth": "01/01/1980",
  "dateOfExpiry": "01/01/2025",
  "documentNumber": "BAA000431",
  "personalNumber": "99999999R",

  "regionOfBirth": "MADRID",
  "cityOfBirth": "MADRID",
  "parents": "JUAN / CARMEN",
  "address": "AVDA DE MADRID S-N",
  "city": "MADRID",
  "region": "MADRID",

  "issuingState": "ESP",
  "mrz": "IDESPBAA000431599999999R<<<<<<8001010F2501018ESP<<<<<<<<<<<6ESPANOLA<ESPANOLA<<CARMEN<<<<<",

  "validationSex": "VALID",
  "validationGender": "VALID",
  "validationNationality": "VALID",
  "validationDateOfBirth": "VALID",
  "validationDateOfExpiry": "VALID",
  "validationDocumentNotExpired": "VALID",
  "validationPersonalNumber": "VALID",
  "validationPersonalNumberFormat": "VALID",  
  "validationDocumentNumber": "VALID",
  "validationDocumentNumberFormat": "VALID",

  "validationNameNotEmpty": "VALID",
  "validationSurnameNotEmpty": "VALID",

  "validationIssuingState": "VALID",
  "validationMRZCheckPersonalNumber": "VALID",
  "validationMRZCheckDocumentNumber": "VALID",
  "validationMRZCheckDateOfBirth": "VALID",
  "validationMRZCheckDateOfExpiry": "VALID",
  "validationMRZCheckComposite": "VALID",
  "validationMRZ": "VALID",
  "validationMRZNameSurnameSeparator": "VALID",
  "validationMRZSurnameSeparator": "VALID",
  "validationPersonalNumberBothSidesMatch": "VALID",
  "validationDocumentNumberBothSidesMatch": "VALID",
  "validationNameBothSidesMatch": "VALID",
  "validationNameBothSidesMatchScore": "100",
  "validationSurnameBothSidesMatch": "VALID",
  "validationSurnameBothSidesMatchScore": "100",
  "validationSexBothSidesMatch": "VALID",
  "validationGenderBothSidesMatch": "VALID",
  "validationNationalityBothSidesMatch": "VALID",
  "validationDateOfBirthBothSidesMatch": "VALID",
  "validationDateOfExpiryBothSidesMatch": "VALID",
  "validationBothSidesMatch": "VALID",
  "validationBothSidesMatchScore": "80",

  "validationFrontAppearance": "VALID",
  "validationBackAppearance": "VALID",
  "validationFrontAppearanceScore": "54.0",   
  "validationBackAppearanceScore": "87.0",
  "validationFrontNotPhotocopy": "VALID",
  "validationFrontPhotocopyScore": "0.0",
  "validationBackNotPhotocopy": "VALID",
  "validationBackPhotocopyScore": "0.0",

  "validationDocumentContent": "VALID",
  "validationDocumentForensics": "VALID",
  "validationDocument": "VALID",

  "validationFacialMatchingScore": -1.0
},

"code": "OK",
"description": "SCAN_DOCUMENT_SUCCESS",
"scanId": "b76e62b8-cbdf-4b9c-86fc-4feab4ae9126",
}