Data Retrieval

Retrieve identity verification status, extracted document data, and uploaded files via the iDenfy API as a fallback to webhook delivery.

Webhooks are the recommended method for receiving verification results. They deliver data efficiently as events happen.

Use these endpoints only as a fallback:

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

Do not poll /api/v2/status as part of your main integration flow. iDenfy does not support regular polling and may restrict your access.

Some data fields may be null if the information was not present on the document or unreadable due to image quality.

---

Verification Status

POST https://ivs.idenfy.com/api/v2/status
Authorization: Basic {API_KEY}:{API_SECRET}
Content-Type: application/json

Request

{
  "scanRef": "328c6766-934e-11ed-bb9b-025ad99a18e7"
}

Response

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

Response Fields

Field	Description
status	Overall verification status: APPROVED, DENIED, SUSPECTED, REVIEWING, ACTIVE, EXPIRED. See Status Handling for what to do with each.
autoDocument	Automated document check result (e.g., DOC_VALIDATED, DOC_NOT_FOUND).
autoFace	Automated face check result (e.g., FACE_MATCH, FACE_MISMATCH).
manualDocument	Manual review document result. Empty if not reviewed yet.
manualFace	Manual review face result. Empty if not reviewed yet.
fraudTags	Array of fraud indicators that can produce a SUSPECTED status. See Suspected Status for examples.
mismatchTags	Array of data mismatches between token data and document data. See Suspected Status for examples.
scanRef	Unique verification identifier.
clientId	Your client identifier.

---

Verification Data

POST https://ivs.idenfy.com/api/v2/data
Authorization: Basic {API_KEY}:{API_SECRET}
Content-Type: application/json

Request

{
  "scanRef": "328c6766-934e-11ed-bb9b-025ad99a18e7"
}

Response

{
  "docFirstName": "JOHN",
  "docLastName": "SAMPLE BUTCH",
  "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 BUTCH",
  "orgFirstName": "JOHN",
  "orgLastName": "SAMPLE BUTCH",
  "orgNationality": "NEDERLANDSE",
  "orgBirthPlace": "LONDON",
  "orgAuthority": "BURG",
  "orgAddress": null,
  "selectedCountry": "NL",
  "ageEstimate": null,
  "clientIpProxyRiskLevel": null,
  "duplicateFaces": null,
  "duplicateDocFaces": null,
  "addressVerification": null,
  "additionalData": {},
  "scanRef": "328c6766-934e-11ed-bb9b-025ad99a18e7",
  "clientId": "W2GL2K333Y"
}

Key Data Fields

Field	Description
docFirstName / docLastName	Parsed name from document (standardized).
orgFirstName / orgLastName	Original name as it appears on the document (may include native characters).
docNumber	Document number.
docPersonalCode	Personal/national code from document.
docExpiry / docDob / docDateOfIssue	Document dates (format: YYYY-MM-DD).
docType	Document type (PASSPORT, ID_CARD, DRIVER_LICENSE, etc.).
docSex	Gender from document (MALE, FEMALE).
docNationality / docIssuingCountry	ISO country codes.
selectedCountry	Country the user selected during verification.
manuallyDataChanged	true if a human reviewer corrected any OCR data.
fullName	Combined full name.
ageEstimate	Estimated age (if available).
clientIpProxyRiskLevel	Proxy risk level (if proxy check enabled).
duplicateFaces / duplicateDocFaces	Duplicate detection results (if enabled).
addressVerification	Address verification result (if enabled).
additionalData	Data from additional steps.

Any field can be null. Some fields in the original language may contain UTF-16 encoded characters.

---

Verification Files

POST https://ivs.idenfy.com/api/v2/files
Authorization: Basic {API_KEY}:{API_SECRET}
Content-Type: application/json

Request

{
  "scanRef": "328c6766-934e-11ed-bb9b-025ad99a18e7"
}

Response

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

Always use URLs from fileUrls and videoUrls. Top-level file URLs outside these objects may be removed in the future.