Verification data retrieval

warning

Important Note on Data Retrieval Endpoints:

Please use the additional data retrieval endpoints only if the webhooks are not functioning, have missed some information, or only after the verification process is finished. These endpoints are intended for individual cases and not for regular integration use. Reliance on webhooks ensures efficient and streamlined processing. If you encounter issues or have questions, please contact technical support.

All of the endpoints below accept only one JSON parameter scanRef and require a POST request with basic auth header API key and API secret that can be retrieved by contacting iDenfy's technical support or iDenfy's sales team:

• sales@idenfy.com
• via Dashboard

danger

Avoid using the /api/v2/status endpoint as part of your main integration. This endpoint is designed to supplement webhooks only in individual cases where the webhook is not working or missing some data. Regular or extensive use of this endpoint to check verification status is not recommended and may lead to inefficiencies, and your account may be blocked. For any issues or questions, please contact technical support.

note

Some of the data fields may be missing simply because they are not contained in the specific document, or the data may be unreadable due to a low-quality image.

Verification status

The endpoint returns an overall status of the verification https://ivs.idenfy.com/api/v2/status.

Example JSON for the request body:

{
  "scanRef": "scan-ref"
}

Response structure

JSON key	Type	Constraints	Explanation
status	String	- Max length 30	An overall status of the verification. Possible values: - APPROVED - DENIED - SUSPECTED * - REVIEWING - ACTIVE - EXPIRED - EXPIRED-DELETED - DELETED - ARCHIVED * Overall status of the verification. It depends on auto or manual webhook, but if face status:autoFace, manualFace is FACE_MATCH and document status autoDocument, manualDocument is DOC_VALIDATED, then the verification is approved. If other statuses exist, for example: DOC_NOT_FOUND, FACE_MISMATCH, then verification is declined. If any fraudTags or mismatchTags exist for the verification, then status can be set as SUSPECTED, because the identification caught some discrepancies. If verification is approved(FACE_MATCH and DOC_VALIDATED) but overall status SUSPECTED it should be decided on your end to allow or decline this client. For value explanations refer to status vocabulary
scanRef	String	- Max length 36	A unique string to trace back a verification on iDenfy’s side.
clientId	String	- Max length 100	A unique string to trace back a client on your side.
fraudTags	List	-	A list of fraud tags (strings) indicating why verification was SUSPECTED. Possible values: - FACE_SUSPECTED - FACE_BLACKLISTED - DOC_FACE_BLACKLISTED - DOC_MOBILE_PHOTO - DEV_TOOLS_OPENED - DOC_PRINT_SPOOFED - FAKE_PHOTO - AML_SUSPECTION - AML_FAILED - LID_SUSPECTION - LID_FAILED - UTILITY_ADDRESS_CHECK_FAILURE - VIRTUAL_CAMERA - FACE_IN_BLACKLIST - DOC_FACE_IN_BLACKLIST - DUPLICATE_FACE - DUPLICATE_DOC_FACE For value explanations refer to status vocabulary.
mismatchTags	List	-	A list of mismatch tags (strings) indicating where partner provided document information does not match with the read information. Verification overall status was SUSPECTED if any mismatchTags exist. Possible values: -NAME -SURNAME -DOCUMENT_NUMBER -PERSONAL_CODE -EXPIRY_DATE -DATE_OF_BIRTH -DATE_OF_ISSUE -FULL_NAME -UNDER_AGE -UNKNOWN_AGE -SEX -NATIONALITY -INVALID_ADDITIONAL_STEP -ADDITIONAL_STEP_NOT_FOUND -DOC_INFO_MISMATCH -ADDITIONAL_STEP_INFORMATION_MISMATCH -EXPIRED_ADDITIONAL_STEP_INFORMATION For value explanations refer to status vocabulary.
manualFace	String	- Max length 30	A Final face analysis result (decision made by a automatic system and human). Possible values: - FACE_MATCH - FACE_MISMATCH - NO_FACE_FOUND - TOO_MANY_FACES - FACE_UNCERTAIN - FAKE_FACE For value explanations refer to status vocabulary.
autoDocument	String	- Max length 30	An automatic document analysis result (decision made by an automated platform). Possible values: - DOC_VALIDATED - DOC_INFO_MISMATCH - DOC_NOT_FOUND - DOC_NOT_FULLY_VISIBLE - DOC_NOT_SUPPORTED - DOC_FACE_NOT_FOUND - DOC_TOO_BLURRY - DOC_GLARED - DOC_FACE_GLARED - MRZ_NOT_FOUND - MRZ_OCR_READING_ERROR - BARCODE_NOT_FOUND - DOC_EXPIRED - COUNTRY_MISMATCH - DOC_TYPE_MISMATCH - DOC_SIDE_MISMATCH - DOC_DAMAGED - DOC_FAKE - DOC_ERROR - AUTO_UNVERIFIABLE - DOC_NOT_ANALYSED - DOC_NAME_ERROR - DOC_SURNAME_ERROR - DOC_EXPIRY_ERROR - DOC_DOB_ERROR - DOC_PERSONAL_NUMBER_ERROR - DOC_NUMBER_ERROR - DOC_DATE_OF_ISSUE_ERROR - DOC_SEX_ERROR - DOC_NATIONALITY_ERROR - COUNTRY_NOT_SUPPORTED - DOC_PERSONAL_CODE_INVALID - DOC_SPOOF_DETECTED - MRZ_INVALID - DOC_NOT_ALLOWED For value explanations refer to status vocabulary.
manualDocument	String	- Max length 30	A Final document analysis result (decision made by a automatic system and human). Possible values: - DOC_VALIDATED - DOC_NOT_FULLY_VISIBLE - DOC_NOT_SUPPORTED - DOC_EXPIRED - DOC_DAMAGED - DOC_FAKE - DOC_PERSONAL_CODE_INVALID - MRZ_INVALID For value explanations refer to status vocabulary.

Response example

{
  "fraudTags": [],
  "mismatchTags": [],
  "autoDocument": "DOC_VALIDATED",
  "autoFace": "FACE_MATCH",
  "manualDocument": "DOC_VALIDATED",
  "manualFace": "FACE_MATCH",
  "scanRef": "328c6766-934e-11ed-bb9b-025ad99a18e7",
  "clientId": "W2GL2K333Y",
  "status": "APPROVED"
}

Verification data

The following endpoint returns the data of the verification: https://ivs.idenfy.com/api/v2/data.

note

Any of the specified fields below can be null. Also, some fields in original language could have symbols encoded in UTF-16.

Response structure

JSON key	Type	Constraints	Explanation
docFirstName	String	- Max length 100	Client's name parsed from the document.
docLastName	String	- Max length 100	Client's surname parsed from the document.
docNumber	String	- Max length 100	Client's document number parsed from the document.
docPersonalCode	String	- Max length 30	Client's personal code parsed from the document.
docExpiry	String	- Format: YYYY-MM-DD	Expiration date parsed from the client's document.
docDob	String	- Format: YYYY-MM-DD	Date of birth parsed from the client's document.
docDateOfIssue	String	- Format: YYYY-MM-DD	Date of issue parsed from the client's document.
docType	String	- Max length 30	Document type of the completed verification. Possible values: ID_CARD PASSPORT RESIDENCE_PERMIT DRIVER_LICENSE AADHAAR PAN_CARD VISA BORDER_CROSSING ASYLUM NATIONAL_PASSPORT VOTER_CARD OLD_ID_CARD TRAVEL_CARD PHOTO_CARD MILITARY_CARD PROOF_OF_AGE_CARD DIPLOMATIC_ID
docSex	String	- Max length 9	Client's sex parsed from the document. Possible values: - MALE - FEMALE - UNDEFINED
docNationality	String	- Max length 2	Client's nationality parsed from the document. Returned value is an alpha-2 country code.
docIssuingCountry	String	- Max length 2	Document's issuing country parsed from the document. Returned value is an alpha-2 country code.
docTemporaryAddress	String	- Max length 100	Clients temporary address parsed from the document.
docBirthName	String	- Max length 100	Clients birth name parsed from the document.
birthPlace	String	- Max length 60	Client's birth place parsed from the document.
authority	String	- Max length 60	Client's document authority parsed from the document.
address	String	- Max length 80	Client's address parsed from the document.
driverLicenseCategory	String	- Max length 30	Client driving license categories (classes) parsed from the document.
mothersMaidenName	String	- Max length 80	Clients mothers maiden name parsed from the document.
manuallyDataChanged	Bool	-	Defines if data was manually changed after the automatic process.
fullName	String	- Max length 60	The full name of the client parsed from the document.
selectedCountry	String	- Any country in alpha-2 code	Country which was selected in verification process.
orgFirstName	String	- Max length 60	Client's name parsed from the document in original language.
orgLastName	String	- Max length 60	Client's surname parsed from the document in original language.
orgNationality	String	- Max length 30	Client's nationality parsed from the document in original language.
orgBirthPlace	String	- Max length 60	Client's birth place parsed from the document in original language.
orgBirthName	String	- Max length 500	Client birth name parsed from the document in original language.
orgAuthority	String	- Max length 60	Client's document authority categories parsed from the document in original language.
orgAddress	String	- Max length 60	Client's address parsed from the document in original language.
orgTemporaryAddress	String	- Max length 500	Client temporary address parsed from the document in original language.
orgMothersMaidenName	String	- Max length 500	Clients mothers maiden name parsed from the document in original language.
clientIpProxyRiskLevel	String	- Max length 11	Client's IP address proxy risk level. If this feature isn't enabled or this is not the final callback with overall status APPROVED - this field will be null. Possible values: - VERY_LOW - LOW - MEDIUM - HIGH - VERY_HIGH - NOT_CHECKED
ageEstimate	String	- Max length 10	Client age detected from selfie when liveness is on. Possible values: - UNDER_13 - OVER_13 - OVER_18 - OVER_22 - OVER_25 - OVER_30
duplicateFaces	List	-	Indicates scanRefs of other clients which selfie faces were matched with this one's verification. If list is empty, a value is null.
duplicateDocFaces	List	-	Indicates scanRefs of other clients which document faces were matched with this one's verification. If list is empty, a value is null.
scanRef	String	- Max length 40	Unique identifier of the client's verification.
clientId	String	- Max length 100	Client's unique identifier.
additionalData	JSON object	Must be used with additionalSteps	Additional data that was provided alongside any additionalSteps, for example - Social Security Number in UTILITY_BILL. Must be used with additionalSteps

Response example

{
  "docFirstName": "JOHN",
  "docLastName": "SAMPLE PETER",
  "docNumber": "DE4878783",
  "docPersonalCode": null,
  "docExpiry": "2024-03-09",
  "docDob": "1965-03-10",
  "docDateOfIssue": "2014-03-09",
  "docType": "PASSPORT",
  "docSex": "MALE",
  "docNationality": "NL",
  "docIssuingCountry": "NL",
  "docTemporaryAddress": null,
  "docBirthName": null,
  "birthPlace": "LONDON",
  "authority": "BURG",
  "address": null,
  "mothersMaidenName": null,
  "driverLicenseCategory": null,
  "manuallyDataChanged": false,
  "fullName": "JOHN SAMPLE PETER",
  "orgFirstName": "JOHN",
  "orgLastName": "SAMPLE PETER",
  "orgNationality": "NEDERLANDSE",
  "orgBirthPlace": "LONDON",
  "orgAuthority": "BURG",
  "orgAddress": null,
  "orgTemporaryAddress": null,
  "orgMothersMaidenName": null,
  "orgBirthName": null,
  "selectedCountry": "NL",
  "ageEstimate": null,
  "clientIpProxyRiskLevel": null,
  "duplicateFaces": null,
  "duplicateDocFaces": null,
  "addressVerification": null,
  "additionalData": {},
  "scanRef": "328c6766-934e-11ed-bb9b-025ad99a18e7",
  "clientId": "W2GL2K333Y"
}

Verification file URLs

The endpoint returns urls for photos and photos sequence created during verification process https://ivs.idenfy.com/api/v2/files

Response example

{
  "FACE": "https:...",
  "FRONT": "https://...",
  "fileUrls": {
    "FACE": "https://...",
    "FRONT": "https://..."
  },
  "videoUrls": {},
  "additionalStepPdfUrls": {}
}

caution

Please use photo URLs in fileUrls. File urls not in fileUrls or videoUrls could be removed in future.