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. Regular polling is not supported and may result in restricted 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 Vocabulary. |
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. See Vocabulary → Fraud tags. |
mismatchTags | Array of data mismatches between token data and document data. See Vocabulary → Mismatch tags. |
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.
