Document Validation Data V2

Gets the morphological analysis results of the document once the validation process has completed successfully.

The response fields will depend on the configured morphology provider.

Endpoint

POST /verify/documentValidation/v2/data

Headers

Name	Type	Required	Description
x-api-key	string	Yes	API key for access authorization.
family	string	No	Value: Onboarding. Required with the tracking service.

All calls to the Tracking Endpoints with Identity Platform must contain the header family.

Request body

Content-Type: application/json

Parameters

Parameter	Type	Required	Description
scanReference	string	Yes	Scan reference number of the scan.
type	string	No	⚠️ Value deprecated. It will be removed in future versions.
tracking	object	No	Object representing the necessary tracking information.
tracking.extraData	string	No	Token generated by the SDK Mobile/Web. Contains tokenized tracking information with the Platform.
tracking.operationId	string	No	Operation identifier generated by the SDK Mobile/Web.

Request example

{
  "scanReference": "fe294c25-17e1-4d98-a958-710edbf00064",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Responses

200 Success

Response parameters — root

Parameter	Type	Description
status	string	Service status. Possible values: success, fail
verification	object	Object with the verification results. See detailed tables below.

Response parameters — verification

Parameter	Type	Nullable	Description
acceptanceTime	string	No	Initial timestamp in format YYYY-MM-DDThh🇲🇲ss.SSSZ.
code	integer	No	Corresponding status code. Possible values: 7001, 7002, 9001, 9102, 9103, 9104, 9121. See Verification Results.
decisionTime	string	No	Timestamp corresponding to the moment of the final decision.
merchantScanReference	string	No	Validation reference number.
scanReference	string	No	Internal reference provided in the start status.
status	string	No	Document validation process status. Possible values: created, started, submitted, inflow_completed, review, approved, declined, resubmission_requested, expired, abandoned. See Verification Results.
reason	string	Yes	Description of the document rejection reason (status or declined or resubmission_requested). Null if the status is approved. See Service Result Code.
reasonCode	integer	Yes	Code associated with the rejection reason. Null if the status is approved. See Reason Codes.
document	object	No	Document information. See table below.
person	object	No	Person information. See table below.

Response parameters — verification.document

Parameter	Type	Nullable	Description
type	string	No	Document type. Possible values: PASSPORT, DRIVING_LICENSE, ID_CARD, VISA, UNSUPPORTED
country	string	No	Issuing country code in ISO 3166-1 alpha-3.
number	string	No	Document number.
validFrom	string	Yes	Document issue date.
validUntil	string	No	Document expiration date.
placeOfIssue	string	No	Place of issue.
firstIssue	string	No	Document first issue date.
issueNumber	string	No	Issue number.
issuedBy	string	No	Issuing authority.

Response parameters — verification.person

Parameter	Type	Nullable	Description
firstName	string	Yes	User's first name.
lastName	string	Yes	User's last name.
idNumber	string	Yes	User document number.
citizenship	string	Yes	Citizenship.
nationality	string	Yes	Nationality.
gender	string	Yes	Gender.
dateOfBirth	string	Yes	Date of birth in format YYYY-MM-DD.
yearOfBirth	string	Yes	Year of birth YYYY.
placeOfBirth	string	Yes	Place of birth.

Service Result Code

The serviceResultCode indicates the overall result of the service execution:

serviceResultCode	Description	HTTP status code
0	The service execution was successful, the module processed the request correctly.	200

Verification Results

The field verification.status in the Document Validation Data response indicates the verification result.

The value of verification.status is returned in lowercase, exactly as it appears in the column status of the following table (for example "status": "declined", "status": "approved"). The resubmission status is transmitted as resubmission_requested, not as Resubmission. Always compare the exact value.

status	Code	Description
started	7001	The validation process has been initiated.
submitted	7002	Sent for validation processing.
approved	9001	Verified and approved successfully.
declined	9102	Validation failed and was permanently rejected.
resubmission_requested	9103	Requires resubmission with corrections or additional information.
expired / abandoned	9104	The validation process has expired or was abandoned.
review	9121	Under manual review for additional verification.

In addition to the above, the process can return the intermediate states created and inflow_completed, which the platform treats as in-progress states together with started, submitted and review.

Reason Codes

The following table contains the reason codes (reasonCode) that can accompany the service result, sorted numerically. The column Associated status indicates the value of verification.status with which each code is published; the codes marked with — correspond to request validation or configuration errors, not a verification decision.

This enumeration follows the official list published by the verification provider and may be expanded in the future. Depending on the configuration of each integration, a specific integration may not receive all listed codes.

• The service transmits the value of reasonCode as-is, without filtering or translating it: any code from this list can reach the client.

• As a general trend, the codes in the 5xx range normally accompany declined and those in the 6xx range to resubmission_requested, but there are exceptions (e.g. 655 is declined and 643 can appear with both statuses). Therefore the decision must always branch always on verification.status, never on the numeric range or on the reason text. See Relationship between reasonCode and the decision.

• The range 900 (901–906) groups registry lookup errors and digital identity provider errors. It must not be confused with the values 9001, 9102, 9103, 9104 and 9121, which correspond to the field verification.code (verification status) and not to reasonCode.

Code	Associated status	Description
101	declined	No physical document has been used
102	declined	Suspicion of document tampering
103	declined	The person presenting the document does not seem to match the photo on the document
104	declined	The name entered does not match the name on the document
105	declined	Suspicious behavior
106	declined	Known fraud
107	declined	Rate/abuse (abusive use of the service)
108	declined	Rate/abuse: duplicate end user
109	declined	Rate/abuse: duplicate device
110	declined	Rate/abuse: duplicate Identity document
111	declined	Fraudulent session access
112	declined	Restricted IP location
113	declined	Suspicious behavior: mass identity creation (identity farming)
120	declined	The portrait person does not seem to match the reference photo
121	declined	User identifier missing
122	declined	No reference found
123	declined	Record checks were not passed
124	declined	The face already exists in the face collection
126	declined	Possible match with a politically exposed person (PEP)
127	declined	Face match against a blocklist
128	declined	The end user's identifier does not match
201	resubmission_requested	The video and/or photos are missing
202	resubmission_requested	The face is not clearly visible
203	resubmission_requested	The document is not fully visible
204	resubmission_requested	Poor image quality
205	resubmission_requested	Damaged document
206	resubmission_requested	Unsupported document type
207	resubmission_requested	Expired document
208	resubmission_requested	Selfie missing
209	resubmission_requested	Document photo missing
210	resubmission_requested	The front side of the document was photographed twice
211	resubmission_requested	The document is not visible in the Identity document image
212	resubmission_requested	Document framing: part of the document is outside the image
213	resubmission_requested	Occluded document: the Identity document is partially occluded (e.g., by fingers)
214	resubmission_requested	Poor-quality selfie: insufficient quality (e.g., too dark or blurry)
215	resubmission_requested	Poor-quality document: the document is unreadable (e.g., too blurry or dark)
216	resubmission_requested	Poor-quality document: reflections
217	resubmission_requested	Custom resubmission
218	resubmission_requested	Upload limit exceeded
501	declined	High likelihood of fraudulent attempt
502	declined	Multiple people present in the session
503	declined	Spoofing attempt
504	declined	Spoofing attempt: device screen use
505	declined	Spoofing attempt: printed copy use
506	declined	Presented document manipulated
507	declined	Presented document manipulated: data cross-check
508	declined	Presented document manipulated: document similarity with a specimen
509	declined	The person presenting the document does not match the photo on the document
510	declined	Unsupported presented document type
511	declined	Presented document expired
512	declined	Presented document canceled or damaged
513	declined	Presented document canceled
514	declined	The presented document is damaged
515	declined	Spoofing attempt: device screen in the face image
516	declined	Spoofing attempt: device screen in the document image
517	declined	Spoofing attempt: device screen in the front-side document image
518	declined	Spoofing attempt: device screen in the back-side document image
519	declined	Injection attack attempt
520	declined	Spoofing attempt: printed copy in the face image
521	declined	Spoofing attempt: printed copy in the document image
522	declined	Spoofing attempt: printed copy in the front-side document image
523	declined	Spoofing attempt: printed copy in the back-side document image
524	declined	Presented document manipulated: the data on the front of the document and the MRZ do not match
525	declined	Presented document manipulated: the data on the front of the document and the barcode do not match
526	declined	Spoofing attempt: photos streamed in streaming
527	declined	The address proof data could not be obtained
528	declined	The issue date of the proof of address is too old
529	declined	The national identity document data could not be validated
530	declined	The person is under 13 years old
531	declined	The person is under 14 years old
532	declined	The person is under 16 years old
533	declined	The person is under 18 years old
534	declined	The person is under 20 years old
535	declined	The person is under 21 years old
536	declined	The person is under 25 years old
537	declined	The document portrait could not be cropped
538	declined	The CIFAS database could not be queried
539	declined	The resubmission limit has been exceeded
540	declined	Low confidence score for the session
541	declined	The document name does not match the name indicated when the session started
542	declined	CPF could not be validated
543	declined	The face reference image has poor quality
544	declined	The registry did not respond
545	declined	The reference image is missing
546	declined	Insufficient face image quality
547	declined	Face missing
548	declined	Spoofing attempt with missing face reference image
549	declined	NFC validation failed
550	declined	The name on the proof of address does not match the name indicated when the session started
551	declined	The document is not recognized
552	declined	The front side of the document is missing
553	declined	The back of the document is missing
554	declined	The front of the document does not appear complete in the image
555	declined	The back of the document does not appear complete in the image
556	declined	The face image is not clear
557	declined	The document data are not visible
558	declined	Could not obtain the surnames
559	declined	Could not obtain the names
560	declined	Could not obtain the date of birth
561	declined	Could not obtain the document number
562	declined	Could not obtain the expiration date
563	declined	Could not obtain the personal number
564	declined	Too many incorrect attempts or incomplete MFA
565	declined	Unsupported driving license category
566	declined	System processing failure
567	declined	Decision criteria not met
568	declined	Invalid input
569	declined	Could not crop the face from the face image
570	declined	Custom rejection
571	declined	Could not identify the country
572	declined	The document number does not match the document number provided at login
573	declined	The document address does not match the address provided at login
574	declined	The provided address is missing required fields
575	declined	Invalid certificate
576	declined	The date of birth on the document does not match the date of birth provided at login
577	declined	The personal number on the document does not match the personal number provided at login
578	declined	The gender on the document does not match the gender provided at login
579	declined	Could not validate the PDF signature
580	declined	Address comparison failed due to regional restrictions
581	declined	The provided face image does not match the face image on record
582	declined	The provided name does not match the name on record
583	declined	The provided date of birth does not match the date of birth on record
584	declined	The provided personal number does not match the personal number on record
585	declined	The document issue date is too old
586	declined	A required entry is missing
587	declined	The occupation on the document does not match the occupation provided at login
602	resubmission_requested	Unsupported presented document type
603	resubmission_requested	Video missing
604	resubmission_requested	Face and/or document images are missing
605	resubmission_requested	The face image is missing
606	resubmission_requested	The face is not clearly visible
607	resubmission_requested	Document missing in the image
608	resubmission_requested	The front side of the document is missing
609	resubmission_requested	The back of the document is missing
610	resubmission_requested	Document obscured
611	resubmission_requested	Front of document obscured
612	resubmission_requested	Back of document obscured
613	resubmission_requested	The document does not appear complete in the image
614	resubmission_requested	The front of the document does not appear complete in the image
615	resubmission_requested	The back of the document does not appear complete in the image
616	resubmission_requested	Document covered by reflections
617	resubmission_requested	Front of document covered by reflections
618	resubmission_requested	Back of document covered by reflections
619	resubmission_requested	The document data are not visible
620	resubmission_requested	Presented document expired
621	resubmission_requested	Voided or damaged document
622	resubmission_requested	Voided document
623	resubmission_requested	Damaged document presented
624	resubmission_requested	The face image on the document is not visible
625	resubmission_requested	Could not obtain the surnames
626	resubmission_requested	Could not obtain the names
627	resubmission_requested	Could not obtain the date of birth
628	resubmission_requested	Could not obtain the issue date
629	resubmission_requested	Could not obtain the expiration date
630	resubmission_requested	Could not obtain the gender
631	resubmission_requested	Could not obtain the document number
632	resubmission_requested	Could not obtain the personal number
633	resubmission_requested	Could not obtain the nationality
634	resubmission_requested	Could not obtain the home address
635	resubmission_requested	The document and face image are missing
636	resubmission_requested	The presented document is not real: screen use
637	resubmission_requested	The presented document is not real: printed copy use
638	resubmission_requested	Could not obtain the place of issue
639	resubmission_requested	Could not obtain the first issue date
640	resubmission_requested	The person did not give consent
641	resubmission_requested	Multiple faces detected
642	resubmission_requested	Multiple documents uploaded
643	declined / resubmission_requested	Could not crop the face image from the front of the document
644	resubmission_requested	Could not obtain the Citizen Identifier (INE)
645	resubmission_requested	Resubmission: could not obtain OCR (IFE)
646	resubmission_requested	Could not estimate age
647	resubmission_requested	The document is not recognized
648	resubmission_requested	Technical issues
649	resubmission_requested	Could not obtain foreigner information
650	resubmission_requested	Could not obtain the process number
651	resubmission_requested	Could not obtain occupation information
652	resubmission_requested	Could not obtain employer information
653	resubmission_requested	Could not obtain the residence permit type
654	resubmission_requested	Could not obtain the driver's license number
655	declined	Could not obtain the additional name
656	resubmission_requested	Multiple people are present in the session
657	resubmission_requested	The image of the open Passport is missing
658	resubmission_requested	Could not obtain the elector number (Elector Number)
659	resubmission_requested	Could not obtain the electoral identifier
660	resubmission_requested	Could not obtain the first surname
661	resubmission_requested	Could not obtain the second surname
662	resubmission_requested	Could not obtain the document remarks
663	resubmission_requested	Could not obtain the place of birth
664	resubmission_requested	Could not obtain category B
665	resubmission_requested	Could not obtain the category B issue date
666	resubmission_requested	Could not obtain the category B expiration date
667	resubmission_requested	Could not obtain category AM
668	resubmission_requested	Could not obtain category A
669	resubmission_requested	Could not obtain the document issue number
670	resubmission_requested	Could not obtain the document issuing authority
671	resubmission_requested	Could not obtain the additional names
672	resubmission_requested	Could not obtain the barcode data
673	resubmission_requested	The face is not centered
674	resubmission_requested	The face is covered by glasses
675	resubmission_requested	The face is not within the rotation limits
676	resubmission_requested	Could not crop the face from the face image
677	resubmission_requested	Uneven lighting on the face
678	resubmission_requested	Blurred face
679	resubmission_requested	Could not obtain hair color
680	resubmission_requested	Could not obtain eye color
681	resubmission_requested	Could not obtain height
682	resubmission_requested	Could not obtain weight
683	resubmission_requested	Incorrect face size relative to the image
684	resubmission_requested	The eyes are not sufficiently open
685	resubmission_requested	Too much digital noise in the image
686	resubmission_requested	Image contrast too low
687	resubmission_requested	Could not obtain the driving license category
688	resubmission_requested	The document number does not match the document number provided at login
689	resubmission_requested	The document address does not match the address provided at login
690	resubmission_requested	The date of birth on the document does not match the date of birth provided at login
691	resubmission_requested	The personal number on the document does not match the personal number provided at login
692	resubmission_requested	The gender on the document does not match the gender provided at login
693	resubmission_requested	The document name does not match the name indicated when the session started
694	resubmission_requested	Could not obtain any name
695	resubmission_requested	Could not identify the document type from the document
696	resubmission_requested	The occupation on the document does not match the occupation provided at login
697	resubmission_requested	Could not validate the PDF signature
901	declined	Record provider error connecting to the record
902	declined	Could not find the person in the record
903	declined	Verification of part of the personal information failed
904	declined	Document reported lost or stolen
905	declined	The digital identity provider session has expired
906	declined	Not all required digital identity fields and documents were shared
1001	—	Request validation error: the query identifier (Query ID) must be between 20 and 40 characters.
1002	— / declined	Request validation error: the query identifier (Query ID) must be a valid UUID v4. In dPAD-enabled integrations it indicates a screen replay attack (Screen Replay Attack), always with status declined. See the note on dPAD after this table.
1003	— / declined	Request validation error: the query identifier (Query ID) must be unique; it has already been used. In dPAD-enabled integrations it indicates a black and white printed copy attack (Black and White Printed Copy Attack), always with status declined. See the note on dPAD after this table.
1005	declined	Only in dPAD-enabled integrations: document photo replacement (Photo Replacement Attack). See the note on dPAD after this table.
1102	—	The request is missing required parameters.
1104	—	The request includes invalid parameters.
1201	—	Invalid timestamp: it must not be more than one hour old.
1202	—	Invalid timestamp format. It must be YYYY-MM-DDTHH:MM:S + timezone offset.
1203	—	Invalid ISO 8601 date: the date must have the format YYYY-MM-DD.
1301	—	The requested features are not supported.
1302	—	Only HTTPS return URLs are allowed.
1303	—	Invalid status.
1304	—	Transition to the indicated state is not possible ($STATUS).
1308	—	Missing identification number (ID number).
1309	—	SSN validation requires firstName + lastName or fullName of the person.
1310	—	SSN validation requires person.dateOfBirth or address data.
1400	—	The image data was not found.
1401	—	The image is not in valid base64.
1402	—	The image context is not supported.
1403	—	An image property is missing.
1500	—	The field vendorData cannot exceed 1000 characters.
1501	—	vendorData must be a string.
2003	—	Date of birth is not a valid date.
2101	—	The document number must be between 6 and 9 characters.
2102	—	The document number can only contain the characters A-Z and 0-9.
2103	—	The document type is not supported.
2104	—	The document of the indicated country is not supported.

Codes with dual meaning (dPAD)

In integrations with passive document presentation attack detection (dPAD) enabled, the codes 1002, 1003 and 1005 are emitted when the validation diagnosis is a spoofing attempt (spoof), always with verification.status = declined:

Code	Meaning with dPAD enabled
1002	Screen replay attack (Screen Replay Attack).
1003	Black and white printed copy (Black and White Printed Copy Attack).
1005	Document photo replacement (Photo Replacement Attack).

In integrations without dPAD, 1002 and 1003 they retain only their meaning as request validation errors and 1005 are not emitted.

Relationship between reasonCode and the decision

The field reasonCode explains why the decision was made, but does not by itself indicate what the decision was. The decision is always determined by verification.status:

verification.status	Meaning
declined	Rejection final. The process has ended; the user cannot correct the result by retrying.
resubmission_requested	Rejection recoverable. The user is asked to resubmit after correcting the indicated problem.

A same reason can appear under different codes depending on the associated decision: there are equivalent pairs in which code 5xx corresponds to declined and code 6xx to resubmission_requested. Some examples: expired document (511 / 620), unsupported document type (510 / 602), front missing (552 / 608), back missing (553 / 609), document data not visible (557 / 619), document not recognized (551 / 647), surnames not obtained (558 / 625) or expiration date not obtained (562 / 629).

Therefore, do not infer the result from the text of reason or from the numeric range of the code: always branch on the exact value of verification.status.

Example response

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

400 Bad Request

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

401 Unauthorized

{
  "message": "Unauthorized"
}

403 Forbidden

{
  "Message": "User is not authorized to access this resource with an explicit deny"
}

502 Bad Gateway

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

504 Gateway Timeout

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