Document Pad Diagnostic

Service that allows checking if the support of an identity document is genuine or not by verifying its image, in order to detect presentation attacks aimed at identity theft.

The validation result can return the following values:

Credible: the document is genuine
Doubtful: it cannot be assured if the document is genuine
Spoof: the document appears not to be genuine
Error: the validation process encountered an error

The result is provided in the decision field of the service response, along with the reason field specifying the cause for unsatisfactory validations. This API allows the morphological validation process of identity documents.

Authorizations

All calls to the endpoints must include the following keys in the request header:

Key	Value
x-api-key	[API access authorization] – Required
app-name	[App identifier] – **

** If the request is made directly from a mobile app, the app-name header is required; otherwise, this header is optional.

If the required keys mentioned above are not included, all endpoints will return one of the following response codes:

Response Code

serviceResultCode	Description
401	“message”: “Unauthorized”

Endpoint

Method: POST

curl --location '{IDENTITY_API_BASE_URL}/verify/pad/diagnostic' \
--header 'x-api-key: {API_KEY}'

Requirements

Minimum
- HD images, minimum resolution: 720px.
- Pixels showing the background around the document at least 5% of its width.
- Minimum compression level: JPEG 70.
- The document text must be readable by an OCR.
Recommended
- FullHD images, minimum resolution: 1080px.
- Document centered in the image and filling more than 5% of the document.
- No compression, with formats such as PNG.
- A well-lit photo without blurring or light flares.

Request

Morphological validation request:

Request parameters:

Field	Type	Required	Description
frontSideImage	Base64	Yes	Base64 encoded image of the front side of the document to be validated
backSideImage	Base64	Yes	Base64 encoded image of the back side of the document to be validated
face	Base64	No	Base64 encoded image of the person's face to be validated
tokenized	Boolean	Yes	Defines whether the images are sent in tokenized format or in plain format
countryCode	String	Yes	ISO Alpha-3 code of the country issuing the identity document, e.g., ESP
idType	String	Yes	Type of document to be validated. Possible values: PASSPORT, ID_CARD, RESIDENCE_PERMIT, DRIVERS_LICENSE, DRIVING_LICENSE, VISA

Example request:

curl --location '{IDENTITY_API_BASE_URL}/verify/pad/diagnostic' \
--header 'x-api-key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "frontSideImage": "{FRONTSIDE_IMAGE}",
    "backSideImage": "{BACKSIDE_IMAGE}",
    "face": "{FACE}",
    "tokenized": {TOKENIZED},
    "countryCode": "{COUNTRY_CODE}",
    "idType": "{ID_TYPE}"
}'

Response

Morphological validation data Response:

Successful requests return an HTTP status code 200 OK accompanied by a JSON object containing the information described in the following table:

Response fields:

Field	Type	Description
serviceTransactionId	String	Transaction identifier associated with the request processed by the API
serviceResultCode	Integer	Code indicating the overall result of the service execution
serviceResultLog	String	Description of the execution result
timestamp	String	Timestamp (UTC) of the response in the format: YYYY-MM-DDThh:mm.SSSZ
serviceResult	JSON String	JSON object with the validation result (Table: Validation Result)
serviceDocumentData	JSON String	Dictionary with the data extracted by OCR from the identity document
serviceTtime	String	Processing time in milliseconds

Example response:

200 OK

Content-Type: application/json

{
  "serviceTransactionId": "24f7451f-9bc2-483b-xxxx-a8421d98c664",
  "serviceResultCode": 0,
  "serviceResultLog": "Executed OK",
  "timestamp": "2022-12-15T16:00:00.000Z",
  "serviceResult": "{\"result\":{\"decision\":\"Credible\",\"IQA\":{\"FTA\":\"DOCUMENT_TOO_CLOSE\"}},\"api_version\":\"pad_cards_v1_1_1\"}",
  "serviceDocumentData": "{\"CHECKS\":{\"BIRTH_DATE_SIDE_MATCH\":false,\"SEX_SIDE_MATCH\":true,\"SURNAME_SIDE_MATCH\":true,\"PERSONAL_NUMBER_SIDE_MATCH\":true,\"EXPIRATION_DATE_SIDE_MATCH\":true,\"NAME_SIDE_MATCH\":true,\"NATIONALITY_SIDE_MATCH\":true},\"SUBTYPE\":null,\"BACKSIDE\":{\"FIELD_DATA\":{\"ADDRESS\":[\"\",\"\"],\"CUIL\":\"\"},\"MRZ_DATA\":{\"NATIONALITY\":\"\",\"SERIAL_NUMBER\":\"\",\"SURNAME\":\"\",\"EXPIRATION_DATE\":\"\",\"SEX\":\"\",\"BIRTH_DATE\":\"\",\"ISSUING_COUNTRY\":\"\",\"IDENTITY_NUMBER\":\"\",\"PERSONAL_NUMBER\":\"\",\"NAME\":\"\"}},\"FRONTSIDE\":{\"FIELD_DATA\":{\"NATIONALITY\":\"\",\"SURNAME\":\"\",\"EXPIRATION_DATE\":\"\",\"BARCODES\":[],\"SEX\":\"\",\"BIRTH_DATE\":\"\",\"PERSONAL_NUMBER\":\"\",\"EXPEDITION_DATE\":\"\",\"EXEMPLAR\":\"\",\"NAME\":\"\"}},\"SCORING\":{\"FIELDS_TOTAL\":,\"FIELDS_RETURNED\":,\"OVERALL_RATING\":},\"DOC_MODEL\":\"\"}",
  "serviceTime": "20784"
}

Tables

Table: Validation Result

decision	Description
Credible	The document is genuine
Doubtful	It cannot be assured if the document is genuine
Spoof	The document appears not to be genuine
Error	The validation process encountered an error

Table: Possible Validation Rejection Reasons

reason	Description
Screen_Replay_Attack	An attacker presents an image or video of a document in front of the camera
Black_and_White_Printed_Copy_Attack	Detection of documents printed on paper in grayscale or black and white
Photo_Replacement_Attack	The data region appears genuine but the portrait region has a printed photograph over it. Does not detect digital manipulations.
SECURITY_PHOTO_CHECK	The portrait photo on the identity document is manipulated
SECURITY_DATA_CHECK	Data on the document shows alterations in its content
SECURITY_OCR_CHECK	Comparison of common data between the front and back of the identity document fails
NOT_PROCESSED_OCR	OCR data could not be extracted from the identity document
NOT_PROCESSED_PHOTO_CHECK	Could not perform portrait photo check of the identity document
NOT_PROCESSED_DATA_CHECK	Could not perform field value check of the identity document

Error Codes

For cases of validation errors in input parameters, a response will be obtained according to RFC 9457 Problem Details.

Example response for missing required parameter:

HTTP code: 400 
Content-Type: application/json
Body:

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": [
      "countryCode is required"
  ]
}

Example response for external service communication failure:

HTTP code: 502 
Content-Type: application/json
Body:

{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}

Example response for timeout:

HTTP code: 504 
Content-Type: application/json
Body:

{
  "message": "Endpoint request timed out"
}

Authorizations​

Endpoint​

Requirements​

Request​

Response​

Tables​

Error Codes​