Skip to main content

Document Validation v2

This API allows the morphological validation process of identity documents.

The process consists of 3 steps:

  1. Start: the information of the document (images, country and type of document) to be analyzed is sent.
  2. Status: the status of the operation is queried to see if it is possible to proceed to obtain the result of the operation. this query must be made n times until the analysis operation has been completed.
  3. Data: the results of the morphological analysis of the document are obtained.

Start​

Morphological validation start request:

curl --location '{IDENTITY_API_BASE_URL}/verify/documentValidation/v2/start' \
--header 'x-api-key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "country": "{COUNTRY_CODE}",
    "idType": "{ID_TYPE}",
    "documentRawImageMimeType": "image/jpeg",
    "documentFrontRawImage": "{FRONTSIDE_IMAGE}",
    "documentBackRawImage": "{BACKSIDE_IMAGE}",
    "merchantIdScanReference": "{SCAN_REFERENCE}"
}'

Request parameters:

FieldRequiredDescription
countryYesISO 3166-1 alpha-3 country code
idTypeYesType of the provided ID. Allowed values: PASSPORT, DRIVING_LICENSE, ID_CARD, RESIDENCE_PERMIT, VISA
documentFrontRawImageYesBase64 encoded image of ID front side
documentBackRawImageYesBase64 encoded image of ID back side. Optional for single-sided documents like PASSPORT
merchantIdScanReferenceNoCustom operation reference. Max. length: 100 characters
documentRawImageMimeTypeNoMime format of image "image/png" or "image/jpeg"

Example response:

200 OK

Content-Type: application/json

{
    "timestamp": "1970-01-01T00:00:00.000Z",
    "scanReference": "fe294c25-17e1-4d98-a958-710edbf00064",
    "type": "1"
}

Response fields:

FieldDescription
timestampTimestamp (UTC) of the response in ISO 8601 format
scanReferenceReference number for each scan
typeDeprecated value. Will be removed in future versions

Status​

Morphological validation status request:

curl --location '{IDENTITY_API_BASE_URL}/verify/documentValidation/v2/status' \
--header 'x-api-key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "scanReference": "{SCAN_REFERENCE}",
    "type": "{TYPE}"
}'

Request parameters:

FieldRequiredDescription
SCAN_REFERENCEYesScan reference number
TYPENoDeprecated value. Will be removed in future versions

Example response:

200 OK

Content-Type: application/json

{
    "timestamp": "1970-01-01T00:00:00.000Z",
    "scanReference": "fe294c25-17e1-4d98-a958-710edbf00064",
    "status": "DONE"
}

Response fields:

FieldDescription
timestampTimestamp (UTC) of the response in ISO 8601 format
scanReferenceScan reference number
statusOperation status. Possible states: PENDING, DONE, FAILED

Data​

Morphological validation data request:

curl --location '{IDENTITY_API_BASE_URL}/verify/documentValidation/v2/data' \
--header 'x-api-key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "scanReference": "{SCAN_REFERENCE}",
    "type": "{TYPE}"
}'

Request parameters:

FieldRequiredDescription
SCAN_REFERENCEYesScan reference number
TYPENoDeprecated value. Will be removed in future versions

Example response:

200 OK

Content-Type: application/json

{
    "status": "success",
    "verification": {
        "scanReference": "12df6045-3846-3e45-946a-14fa6136d79a",
        "code": 9001,
        "person": {
            "gender": null,
            "idNumber": null,
            "lastName": "PEREZ",
            "firstName": "MATIAS",
            "citizenship": null,
            "dateOfBirth": "1973-03-30",
            "nationality": null,
            "yearOfBirth": "1973",
            "placeOfBirth": "MADRID"
        },
        "reason": null,
        "status": "approved",
        "document": {
            "type": "DRIVERS_LICENSE",
            "number": "PEREZ771116SM1AJ",
            "country": "ESP",
            "validFrom": null,
            "validUntil": "2024-04-20",
            "placeOfIssue": "MADRID",
            "firstIssue": "2015-03-21",
            "issueNumber": "01",
            "issuedBy": "ISSUER"
        },
        "reasonCode": null,
        "merchantScanReference": "12345678",
        "decisionTime": "2019-11-06T07:18:36.916Z",
        "acceptanceTime": "2019-11-06T07:15:27.000Z",
    }
}

Response fields:

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

ParameterTypeDescription
statusstringState of the service: Success or Fail
verificationobject
acceptanceTimestringInitial timestamp in the format YYYY-MMDDThh:mm:ss.SSSZ
codeintCorresponding status code. Possible values: Started (7001), Submitted (7002), Approved (9001), Declined (9102), Resubmission (9103), Expired/Abandoned (9104), Review (9121)
decisionTimestringTimestamp corresponding to the moment of the final decision in the format YYYY-MMDDThh:mm:ss.SSSZ
merchantScanReferencestringValidation reference number
ScanReferencestringInternal reference provided in the start status
statusstringStatus of the document validation process. Possible states: Started, Submitted, Approved, Declined, Resubmission, Expired/Abandoned, Review
reasonstringDescription of the reason for document rejection (status declined). Null if status approved
reasonCodeintCode associated with the reason for rejection. Null if status approved
Documentobject
typestringType of document. Possible values: PASSPORT, DRIVING_LICENSE, ID_CARD, VISA, UNSUPPORTED
countrystringIssuing country code in ISO 3166-1 alpha-3 format
numberstringDocument number
validFromstringDocument issue date
validUntilstringDocument expiry date
placeOfIssuestringPlace of issue
firstIssuestringDate of the document's first issue
issueNumberstringIssue number
issuedBystringIssuing authority
personobject
firstNamestringUser's first name
lastNamestringUser's last name
idNumberstringUser's document number
citizenshipstringCitizenship
nationalitystringNationality
genderstringGender
dateOfBirthstringDate of birth in the format YYYY-MM-DD
yearOfBirthstringYear of birth YYYY
placeOfBirthstringPlace of birth

Table: Reason Code

CodeDescription
101Physical document not used
102Suspected document tampering
103Person showing the document does not appear to match document photo
105Suspicious behaviour
106Known fraud
108Velocity/abuse duplicated end-user
109Velocity/abuse duplicated device
110Velocity/abuse duplicated ID
112Restricted IP location
113Suspicious behaviour - Identity Farming
120Person on the portrait does not appear to match reference photo
121User ID missing
122No reference found
123Unable to pass registry checks
126Potential PEP match
127Face match with blocklist
203Full document not visible
502Multiple parties present in session
503Attempted deceit
504Attempted deceit, device screen used
505Attempted deceit, printout used
507Presented document tampered, data cross reference
508Presented document tampered, document similarity to specimen
509Person showing the document does not match document photo
510Presented document type not supported
511Presented document expired
515Attempted deceit, device screen used for face image
526Attempted deceit, photos streamed
527Unable to collect proof of address data
528Proof of address issue date too old
530Person is under 13 years old
531Person is under 14 years old
532Person is under 16 years old
533Person is under 18 years old
534Person is under 20 years old
535Person is under 21 years old
536Person is under 25 years old
537Unable to perform document media portrait cropping
539Resubmission limit exceeded
540Low confidence score for the session
541Name on document does not match with name in session initialisation data
542Unable to validate CPF
543Reference face image has poor quality
544Registry did not respond
545Reference image missing
546Face image quality insufficient
547Face missing
548Attempted deceit, with face reference missing
549NFC validation failed
602Presented document type not supported
603Video missing
605Face image missing
606Face is not clearly visible
608Document front missing
609Document back missing
614Document front not fully in frame
615Document back not fully in frame
619Document data not visible
620Presented document expired
621Document annulled or damaged
625Unable to collect surname
626Unable to collect first names
627Unable to collect date of birth
628Unable to collect issue date
629Unable to collect expiry date
630Unable to collect gender
631Unable to collect document number
632Unable to collect personal number
633Unable to collect nationality
634Unable to collect home address
635Document and face image missing
636Presented document not real, screen used
637Presented document not real, printout used
640Person did not give consent
641Multiple Faces Detected
642Multiple Documents Uploaded
643Unable to crop face image from a document front
644Unable to collect Identificador de Ciudadano (INE)
645Resubmit - Unable to collect OCR (IFE)
646Unable to estimate age
647Document not recognised
648Technical issues
649Unable to collect foreigner information
650Unable to collect process number
651Unable to collect occupation information
652Unable to collect employer information
653Unable to collect residence permit type
654Unable to collect driver's license number
655Unable to collect additional name
657Open passport image missing
662Unable to collect document remarks
1001Query ID must be between 20 and 40 symbols
1002Query ID must be a valid UUID V4
1003Query ID must be unique, it has already been used.
1102Mandatory parameters are missing from the request.
1104Request includes invalid parameters.
1201Invalid timestamp. Timestamp must not be older than one hour.
1202Timestamp format is incorrect. YYYY-MM-DDTHH:MM:S+Timezone Offset
1203Invalid ISO 8601 date. Date needs to be in format YYYY-MM-DD.
1301Requested features are not supported.
1302Only HTTPS return URLs are allowed.
1303Invalid status.
1304Cannot transition to "$STATUS" status.
1308ID number is missing.
1309SSN validation requires person firstName + lastName OR fullName to be provided.
1310SSN validation requires person.dateOfBirth or address data to be provided.
1400Image data not found.
1401Image is not in valid base64.
1402Image context is not supported.
1403Image property is missing.
1500vendorData field cannot be more than 1000 symbols.
1501vendorData must be a string.
2003Date of birth is not a valid date.
2101Document number has to be between 6 and 9 characters.
2102Document number may contain only characters and numbers A-Z, 0-9.
2103Document type is not supported.
2104Document from provided country is not supported.