DIVE Online API - Validation Endpoints

The Validation Endpoints are the main endpoints used for verifying transaction with DIVE Online.

For users on DIVE API moving to DIVE Online, this endpoint is similar to the v3/v4 Verify endpoints but with some differences in request/response structure and available features.

For developers utilizing the IDScan.net Wrapper, this endpoint is called automatically after the submit function is triggered.

This means that the developer integrating to DIVE Online using the Wrapper does not have to manually create an API request with the Validation endpoint. The endpoint will be called upon submit and can the responses can be ingested via callback functions in the Wrapper.

For developers NOT utilizing the Wrapper, this endpoint will need to be called manually after making an Applicant.

Note

The /Validation endpoint contains various fields for device fingerprinting (e.g. battery info, geolocation, device width).

The IDScan.net Wrapper gathers these fields automatically. Customers not using the IDScan.net Wrapper would (optionally) need to get these fields externally due to the Wrapper not being used.

The api/v2/public/Validation/{applicantId} endpoint should only be used in conjunction with the UploadDocuments endpoint when documents are being uploaded separately via the UploadDocuments endpoint.

/api/v2/public/Validation/{applicantId}

[POST] api/v2/public/Validation/{applicantId}

Use Case - Used in conjunction with the UploadDocuments endpoint when documents are being uploaded separately via the UploadDocuments endpoint.

The requestID field returned from the UploadDocuments endpoint is used here to validate the uploaded document in the applicantId parameter.

Token - public API token (pk_) or secret API Token (sk)

Required Parameters

applicantId - The unique identifier of the applicant whose documents are being uploaded.

Optional Parameters None

Request Body

{
  "dvsRequestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "documentType": 1,
  "clientType": 0,
  "clientVersion": "string"
}

Request Body Fields

dvsRequestId - The unique identifier for the document verification session. This ID is generated by the DIVE Online Web Library or SDK during the document capture process.
documentType - The type of document being uploaded. (e.g., passport, driver's license, ID card).
- ID = 1
- Passport = 2
- PassportCard = 3
- Common Access Card = 4
- Uniformed Services ID = 5
- GreenCard = 6
- InternationalId = 7
clientType - Type of client application.
clientVersion - Version of the IDScan.net UI.

Response Body

{
  "documentType": 0,
  "document": {
    "abbr3Country": "string",
    "abbrCountry": "string",
    "address": "string",
    "auditInformation": "string",
    "city": "string",
    "class": "string",
    "country": "string",
    "dob": "string",
    "expires": "string",
    "eyes": "string",
    "familyName": "string",
    "firstName": "string",
    "fullName": "string",
    "gender": "string",
    "hair": "string",
    "height": "string",
    "id": "string",
    "idType": "string",
    "issued": "string",
    "issuedBy": "string",
    "maidenName": "string",
    "middleName": "string",
    "placeOfBirth": "string",
    "postalBox": "string",
    "state": "string",
    "weight": "string",
    "zip": "string",
    "template": "string",
    "privateName": "string"
  },
  "attemptsCount": 0,
  "attemptsLeft": 0,
  "status": 0,
  "validationStatus": {
    "expired": true,
    "documentIsValid": true,
    "faceIsValid": true,
    "antiSpoofingIsValid": true
  },
  "invalidDataErrors": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "faceSuccess": true,
  "documentSuccess": true,
  "documentHasNotExpired": true,
  "hasRiskEvents": true,
  "documentValidationTests": [
    {
      "displayName": "string",
      "name": "string",
      "status": 0,
      "statusString": "string",
      "reason": "string"
    }
  ],
  "callBackUrl": "string",
  "notificationType": 0,
  "applicantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "attemptId": 0
}

Response Fields

documentType - The type of document that was validated.
- 1 - ID
- 2 - Passport
- 3 - PassportCard
- 4 - Common Access Card
- 5 - Uniformed Services ID
- 6 - GreenCard
- 7 - InternationalId

document — The document object which contains data fields.

document.abbr3Country - The three-letter country abbreviation of the document.
document.abbrCountry - The two-letter country abbreviation of the document.
document.address - The address on the document.
document.city - The city on the document.
document.class - The class on the document.
document.country - The country on the document.
document.dob - The date of birth on the document.
document.expires - The expiration date on the document.
document.eyes - The eye color on the document.
document.familyName - The family name on the document.
document.firstName - The first name on the document.
document.fullName - The full name on the document.
document.gender - The gender on the document.
document.hair - The hair color on the document.
document.height - The height on the document.
document.id - The ID number on the document.
document.idType - The type of ID on the document.
document.issued - The issue date on the document.
document.issuedBy - The issuing authority on the document.
document.maidenName - The maiden name on the document.
document.middleName - The middle name on the document.
document.placeOfBirth - The place of birth on the document.
document.postalBox - The postal box on the document.
document.state - The state on the document.
document.weight - The weight on the document.
document.zip - The zip code on the document.
document.template - The template data on the document.
document.privateName - The private name on the document.

attemptsCount - The number of validation attempts made.
attemptsLeft - The number of validation attempts remaining.
status - The overall status of the validation.
- 0 - Pending
- 1 - Success
- 2 - Failed
- 3 - Canceled
- 4 - Expired
- 5 - FailedAttempt

validationStatus — The validation status object which contains validation results.

validationStatus.expired - Indicates if the document is expired.
validationStatus.documentIsValid - Indicates if the document is valid.
validationStatus.faceIsValid - Indicates if the face on the document is valid.
validationStatus.antiSpoofingIsValid - Indicates if the anti-spoofing check passed.

invalidDataErrors — An array of invalid data error objects.

invalidDataErrors.code - The error code.
invalidDataErrors.message - The error message.

faceSuccess - Indicates if the face validation was successful.
documentSuccess - Indicates if the document validation was successful.
documentHasNotExpired - Indicates if the document has not expired.
hasRiskEvents - Indicates if there are any risk events associated with the document.

documentValidationTests — An array of document validation test objects.

documentValidationTests.displayName - The display name of the validation test.
documentValidationTests.name - The name of the validation test.
documentValidationTests.status - The status of the validation test.
documentValidationTests.statusString - The status string of the validation test.
documentValidationTests.reason - The reason for the validation test result.

callBackUrl - The callback URL for notifications.
notificationType - The type of notification.
- Possible values:
  - 0 - None
  - 1 - SMS
  - 2 - Email
  - 3 - Both SMS and Email
applicantId - The unique identifier of the applicant.
attemptId - The unique identifier of the validation attempt.

/api/v2/public/Validation/

[POST] api/v2/public/Validation/

Use Case - Main Endpoint used for validting identities.

Token - public API token (pk_) or secret API Token (sk)

Required Parameters

None

Optional Parameters

None

Request Body

{
  "model": {
    "documentType": 1,
    "captureMethod": "string",
    "userAgent": "string",
    "frontEndMetadata": "string",
    "clientType": 0,
    "clientVersion": "string",
    "geolocation": {
      "latitude": 0,
      "longitude": 0,
      "accuracy": 0
    },
    "stepsTiming": {
      "face": 0,
      "front": 0,
      "back": 0,
      "mrz": 0,
      "pdf417": 0
    },
    "browserMetadata": {
      "navigatorInfo": {
        "userAgent": "string",
        "cookieEnabled": true,
        "platform": "string",
        "hardwareConcurrency": 0,
        "languages": [
          "string"
        ]
      },
      "screenInfo": {
        "width": 0,
        "height": 0,
        "availWidth": 0,
        "availHeight": 0,
        "colorDepth": 0,
        "pixelDepth": 0,
        "orientationAngle": 0,
        "orientationType": "string",
        "innerWidth": 0,
        "innerHeight": 0,
        "outerWidth": 0,
        "outerHeight": 0
      },
      "batteryInfo": {
        "charging": true,
        "chargingTime": 0,
        "dischargingTime": 0,
        "level": 0
      },
      "connectionInfo": {
        "effectiveType": "string",
        "downlink": 0,
        "rtt": 0,
        "saveData": true,
        "type": "string",
        "downlinkMax": 0
      },
      "browserInfo": "string",
      "canvasInfo": "string",
      "fontsInfo": "string",
      "html5Info": "string",
      "webGlInfo": "string"
    },
    "deviceMetadata": {
      "ip": "string",
      "vpnUsage": true,
      "timeZone": "string",
      "root": true,
      "jailBreak": true,
      "virtualCamera": true,
      "systemLanguage": "string",
      "userLanguage": "string"
    },
    "fullName": "string",
    "verifyFace": true,
    "isOcrEnabled": true,
    "isBackOrSecondImageProcessingEnabled": true,
    "frontImageBase64": "string",
    "backOrSecondImageBase64": "string",
    "faceImageBase64": "string",
    "ssn": "string",
    "trackString": "string"
  },
  "applicantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "embeddedAppConnectionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Request Body Fields

model — The model object which contains validation parameters.

model.documentType - The type of document being uploaded. (e.g., passport, driver's license, ID card).
- 1 - ID
- 2 - Passport
- 3 - PassportCard
- 4 - Common Access Card
- 5 - Uniformed Services ID
- 6 - GreenCard
- 7 - InternationalId
model.captureMethod - The method used to capture the document.
model.userAgent - The user agent string of the browser or application used to capture the document.
model.frontEndMetadata - Additional metadata from the front-end application.
model.clientType - The type of client application.
model.clientVersion - Version of the IDScan.net UI.

model.geolocation — The geolocation object which contains location data.

geolocation.latitude - The latitude of the location where the document was captured.
geolocation.longitude - The longitude of the location where the document was captured.
geolocation.accuracy - The accuracy of the geolocation data.

model.stepsTiming — The steps timing object which contains timing data for each step of the capture process.

stepsTiming.face - The time taken for the face capture step.
stepsTiming.front - The time taken for the front document capture step.
stepsTiming.back - The time taken for the back document capture step.
stepsTiming.mrz - The time taken for the MRZ capture step.
stepsTiming.pdf417 - The time taken for the PDF417 capture step.

model.browserMetadata — The browser metadata object which contains metadata about the browser used for capture.

model.browserMetadata.navigatorInfo — The navigator info object which contains information about the browser navigator.

navigatorInfo.userAgent - The user agent string of the browser.
navigatorInfo.cookieEnabled - Indicates if cookies are enabled in the browser.
navigatorInfo.platform - The platform of the browser.
navigatorInfo.hardwareConcurrency - The number of logical processors available.
navigatorInfo.languages - An array of languages supported by the browser.

model.browserMetadata.screenInfo — The screen info object which contains information about the screen.

screenInfo.width - The width of the screen.
screenInfo.height - The height of the screen.
screenInfo.availWidth - The available width of the screen.
screenInfo.availHeight - The available height of the screen.
screenInfo.colorDepth - The color depth of the screen.
screenInfo.pixelDepth - The pixel depth of the screen.
screenInfo.orientationAngle - The orientation angle of the screen.
screenInfo.orientationType - The orientation type of the screen.
screenInfo.innerWidth - The inner width of the screen.
screenInfo.innerHeight - The inner height of the screen.
screenInfo.outerWidth - The outer width of the screen.
screenInfo.outerHeight - The outer height of the screen.

model.browserMetadata.batteryInfo — The battery info object which contains information about the device battery.

batteryInfo.charging - Indicates if the device is currently charging.
batteryInfo.chargingTime - The time remaining until the battery is fully charged.
batteryInfo.dischargingTime - The time remaining until the battery is fully discharged.
batteryInfo.level - The current battery level as a percentage.

model.browserMetadata.connectionInfo — The connection info object which contains information about the network connection.

connectionInfo.effectiveType - The effective type of the network connection.
connectionInfo.downlink - The downlink speed of the network connection.
connectionInfo.rtt - The round-trip time of the network connection.
connectionInfo.saveData - Indicates if the user has enabled data saving mode.
connectionInfo.type - The type of network connection.
connectionInfo.downlinkMax - The maximum downlink speed of the network connection.

model.browserMetadata.browserInfo - Additional browser information.
model.browserMetadata.canvasInfo - Canvas fingerprinting information.
model.browserMetadata.fontsInfo - Information about the fonts installed.
model.browserMetadata.html5Info - HTML5 feature support information.
model.browserMetadata.webGlInfo - WebGL fingerprinting information.

model.deviceMetadata — The device metadata object which contains metadata about the device used for capture.

deviceMetadata.ip - The IP address of the device.
deviceMetadata.vpnUsage - Indicates if a VPN was used on the device.
deviceMetadata.timeZone - The time zone of the device.
deviceMetadata.root - Indicates if the device is rooted.
deviceMetadata.jailBreak - Indicates if the device is jailbroken.
deviceMetadata.virtualCamera - Indicates if a virtual camera is being used.
deviceMetadata.systemLanguage - The system language of the device.
deviceMetadata.userLanguage - The user language of the device.

model.fullName - The full name of the applicant.
model.verifyFace - Indicates if face verification is required.
model.isOcrEnabled - Indicates if OCR is enabled for document processing.
model.isBackOrSecondImageProcessingEnabled - Indicates if back or second image processing is enabled.
model.frontImageBase64 - The base64-encoded string of the front image.
model.backOrSecondImageBase64 - The base64-encoded string of the back image.
model.faceImageBase64 - The base64-encoded string of the face image.
model.ssn - The social security number of the applicant.
model.trackString - The track string from the document.

applicantId - The unique identifier of the applicant whose documents are being validated.
embeddedAppConnectionId - The unique identifier of the embedded app connection.