Skip to main content

Verification data retrieval

Prioritize Webhooks Over Data Retrieval Endpoints

Webhooks are the recommended method for receiving verification results. They provide information efficiently as events happen.

Use the additional data retrieval endpoints only in these specific fallback scenarios:

  • If you suspect a webhook notification failed or missed some data.
  • To fetch details for a verification after it has already finished.

These endpoints are meant for troubleshooting individual cases, not for routine integration. Relying on webhooks ensures the best performance. If you face issues, please contact technical support.

Critical: Avoid Polling /api/v2/status

Do not use the /api/v2/status endpoint as part of your main integration flow to check verification status.

This endpoint is strictly a supplement for webhooks, intended only for isolated cases where a webhook isn't working correctly or data is missing.

Regularly polling /api/v2/status is not supported. It can lead to system inefficiencies, and your account access may be restricted. Always use webhooks for status updates. For assistance, contact technical support.

Why Data Fields Might Be Missing

You might find that some data fields in the response are empty or null. This typically occurs for one of two reasons:

  • The information was not present on the specific document provided.
  • The data was unreadable due to the quality of the submitted image.

Verification status​

status retrieval endpoint

Authorization: API key pair
Method: POST
Endpoint: https://ivs.idenfy.com/api/v2/status

Status​

For more details on status, see vocabulary

status| Type: String
Explanation:

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.

Constraints:

Max length 30

scanRef| Type: String
Explanation:

A unique string to trace back a verification on iDenfy’s side.

Constraints:

Max length 36

clientId| Type: String
Explanation:

A unique string to trace back a client on your side.

Constraints:

Max length 100

fraudTags| Type: List[String]
Explanation:

A list of fraud tags 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.

Constraints:
mismatchTags| Type: List[String]
Explanation:

A list of mismatch tags indicating where document data doesn't match the provided information. 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.

Constraints:
manualFace| Type: String
Explanation:

Final face analysis result made by system and human. Possible values: FACE_MATCH FACE_MISMATCH NO_FACE_FOUND TOO_MANY_FACES FACE_UNCERTAIN FAKE_FACE.

Constraints:

Max length 30

autoDocument| Type: String
Explanation:

Automatic document analysis result. 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.

Constraints:

Max length 30

manualDocument| Type: String
Explanation:

Final document analysis result made by 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.

Constraints:

Max length 30

Request example​

{
  "scanRef": "scan-ref"
}

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​

data retrieval endpoint

Authorization: API key pair
Method: POST
Endpoint: https://ivs.idenfy.com/api/v2/data

data​

note

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

docFirstName| Type: String
Explanation:

Client's name parsed from the document.

Constraints:
  • Max length 100
docLastName| Type: String
Explanation:

Client's surname parsed from the document.

Constraints:
  • Max length 100
docNumber| Type: String
Explanation:

Client's document number parsed from the document.

Constraints:
  • Max length 100
docPersonalCode| Type: String
Explanation:

Client's personal code parsed from the document.

Constraints:
  • Max length 30
docExpiry| Type: String
Explanation:

Expiration date parsed from the client's document.

Constraints:
  • Format: YYYY-MM-DD
docDob| Type: String
Explanation:

Date of birth parsed from the client's document.

Constraints:
  • Format: YYYY-MM-DD
docDateOfIssue| Type: String
Explanation:

Date of issue parsed from the client's document.

Constraints:
  • Format: YYYY-MM-DD
docType| Type: String
Explanation:

Document type of the completed verification. Possible values:

  • ID_CARD
  • PASSPORT
  • RESIDENCE_PERMIT
  • DRIVER_LICENSE
  • PAN_CARD
  • AADHAAR
  • VISA
  • NATIONAL_PASSPORT
  • PROVISIONAL_DRIVER_LICENSE
  • OLD_ID_CARD
  • MILITARY_CARD
  • BANK_ID_SE
  • ADDRESS_CARD
Constraints:
  • Max length 30
docSex| Type: String
Explanation:

Client's sex parsed from the document. Possible values: MALE FEMALE UNDEFINED

Constraints:
  • Max length 9
docNationality| Type: String
Explanation:

Client's nationality parsed from the document. Returned value is an alpha-2 country code.

Constraints:
  • Max length 2
docIssuingCountry| Type: String
Explanation:

Document's issuing country parsed from the document. Returned value is an alpha-2 country code.

Constraints:
  • Max length 2
docTemporaryAddress| Type: String
Explanation:

Clients temporary address parsed from the document.

Constraints:
  • Max length 100
docBirthName| Type: String
Explanation:

Clients birth name parsed from the document.

Constraints:
  • Max length 100
birthPlace| Type: String
Explanation:

Client's birth place parsed from the document.

Constraints:
  • Max length 60
authority| Type: String
Explanation:

Client's document authority parsed from the document.

Constraints:
  • Max length 60
address| Type: String
Explanation:

Client's address parsed from the document.

Constraints:
  • Max length 80
driverLicenseCategory| Type: String
Explanation:

Client driving license categories (classes) parsed from the document.

Constraints:
  • Max length 30
mothersMaidenName| Type: String
Explanation:

Clients mothers maiden name parsed from the document.

Constraints:
  • Max length 80
manuallyDataChanged| Type: Bool
Explanation:

Defines if data was manually changed after the automatic process.

Constraints:
fullName| Type: String
Explanation:

The full name of the client parsed from the document.

Constraints:
  • Max length 60
selectedCountry| Type: String
Explanation:

Country which was selected in verification process.

Constraints:
  • Any country in alpha-2 code
orgFirstName| Type: String
Explanation:

Client's name parsed from the document in original language.

Constraints:
  • Max length 60
orgLastName| Type: String
Explanation:

Client's surname parsed from the document in original language.

Constraints:
  • Max length 60
orgNationality| Type: String
Explanation:

Client's nationality parsed from the document in original language.

Constraints:
  • Max length 30
orgBirthPlace| Type: String
Explanation:

Client's birth place parsed from the document in original language.

Constraints:
  • Max length 60
orgBirthName| Type: String
Explanation:

Client birth name parsed from the document in original language.

Constraints:
  • Max length 500
orgAuthority| Type: String
Explanation:

Client's document authority categories parsed from the document in original language.

Constraints:
  • Max length 60
orgAddress| Type: String
Explanation:

Client's address parsed from the document in original language.

Constraints:
  • Max length 60
orgTemporaryAddress| Type: String
Explanation:

Client temporary address parsed from the document in original language.

Constraints:
  • Max length 500
orgMothersMaidenName| Type: String
Explanation:

Clients mothers maiden name parsed from the document in original language.

Constraints:
  • Max length 500
clientIpProxyRiskLevel| Type: String
Explanation:

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

Constraints:
  • Max length 11
ageEstimate| Type: String
Explanation:

Client age detected from selfie when liveness is on. Possible values: UNDER_13 OVER_13 OVER_18 OVER_22 OVER_25 OVER_30

Constraints:
  • Max length 10
duplicateFaces| Type: List
Explanation:

Indicates scanRefs of other clients which selfie faces were matched with this one's verification. If list is empty, a value is null.

Constraints:
duplicateDocFaces| Type: List
Explanation:

Indicates scanRefs of other clients which document faces were matched with this one's verification. If list is empty, a value is null.

Constraints:
scanRef| Type: String
Explanation:

Unique identifier of the client's verification.

Constraints:
  • Max length 40
clientId| Type: String
Explanation:

Client's unique identifier.

Constraints:
  • Max length 100
additionalData| Type: JSON object
Explanation:

Additional data that was provided alongside any additionalSteps, for example - Social Security Number in UTILITY_BILL. Must be used with additionalSteps

Constraints:

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 files​

file retrieval

Authorization: API key pair
Method: POST
Endpoint: 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.