API Manual

In this documentation, we describe in detail all the endpoints available via the DIVE API.

Base URL

https://dvs2.idware.net/

Request Authentication

The DIVE API uses bearer tokens to authenticate every request. Public keys have the prefix pk_ and secret keys have the prefix sk_.

Public keys are no longer needed in V4 of the DIVE API but in previous versions they were used only for creating a request for document verification.

Secret keys have full access to DIVE API and will allow the user to make any request to the DIVE API.

Warning

Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authenticating requests to the DIVE API is done using the public key/secret key as a Bearer token in the Authorization Header like in the example below

Authorization: Bearer sk_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

verify Request

[POST] /api/v4/verify

Note

Uses the secret key

Upload documents to the DIVE server for verification

Parameters

returnRequest (boolean) If returnRequest=true then requestData is returned to the Response body.
returnContent (boolean) If returnContent=true then Base64 image of the document is returned to the Response body.

Request data:

{
  "documentType": 1,
  "frontImageBase64": "string",
  "backOrSecondImageBase64": "string",
  "faceImageBase64": "string",
  "trackString": {
    "data": "string",
    "barcodeParams": "string"
  },
  "ssn": "string",
  "overriddenSettings": {
    "isOCREnabled": true,
    "isBackOrSecondImageProcessingEnabled": true,
    "isFaceMatchEnabled": true,
    "isFaceMatchOptional": true,
    "isGenderCheckEnabled": true,
    "isAgeCheckEnabled": true,
    "isExternalAddressVerificationEnabled": true,
    "isExternalShuftiEnabled": true,
    "isExternalOFACWatchlistEnabled": true,
    "isCrossMatchRequired": true,
    "isDocTypeChangeEnabled": true,
    "bothSidedScreeningStrategy": 0,
    "oneSidedScreeningStrategy": 1,
    "ageYearsDifference": 0
  },
  "metadata": {
    "captureMethod": "string",
    "userAgent": "string",
    "frontEndMetadata": "string",
    "otherMetadata": "string"
  }
}

documentType (string or int) Type of document.
- ID – 1
- Passport - 2
- PassportCard – 3
- Common Access Card – 4
- Uniformed Services ID – 5
- GreenCard – 6
- InternationalId – 7
frontImageBase64 (string) Front of the document which contains the data for OCR and a photo.
backOrSecondImageBase64 (string) Image of the reverse side or back of the document which contains a barcode (PDF417) or MRZ
faceImageBase64 (string) Image of the face of the document owner if it is necessary to compare it with the photo of the face on the document.
trackString.data (string)(optional) PDF417 barcode data (or MRZ data) encoded as a base64 string
trackString.barcodeParams (string)(optional)
ssn (string)(optional) this is an optional field that must conform to the following format XXXX or XXX-XX-XXXX for a Social Security Number
overriddenSettings.isExternalAddressVerificationEnabled (boolean)(optional) enables the verification of the address found on the submitted document by using a third party address verification web service
overriddenSettings.isExternalShuftiEnabled (boolean)(optional) enables processing international IDs using our partner's web service
overriddenSettings.isExternalOFACWatchlistEnabled (boolean)(optional) enables an OFAC watchlist check to be performed on the document's data
overriddenSettings.isOCREnabled (boolean)(optional) enables processing the front image of a document using OCR technology
overriddenSettings.isBackOrSecondImageProcessingEnabled (boolean)(optional) enables processing the back image of a document
overriddenSettings.isFaceMatchEnabled (boolean)(optional) enables performing a face match between a submitted selfie and a cropped image of the document owner's face from the front image of the document
overriddenSettings.isFaceMatchOptional (boolean)(optional) this setting will make it optional to perform a face match if for some reason a cropped image of the document owner's face from the front image of the document cannot be obtained
overriddenSettings.isCrossMatchRequired (boolean)(optional) this setting makes it a requirement that both the front and the back of the document are able to be read successfully, if this is disabled a submission will be considered successful if either the front or the back of the document can be read
overriddenSettings.isGenderCheckEnabled (boolean)(optional) enables a verification check to be run that makes sure the gender of the person on the front of the document matches the gender of the person submitting the selfie
overriddenSettings.isAgeCheckEnabled (boolean)(optional) enables a verification check to be run that makes sure the age of the person on the front of the document matches the age (within a 10 year window) of the person submitting the selfie
overriddenSettings.isDocTypeChangeEnabled (boolean)(optional) enables the option to change the type of the document in cases when the document is sent with the wrong document type. For example, if International ID (document type - 7) is recognized as Passport (document type - 2) then the document type is changed to Passport (document type -2)
overriddenSettings.bothSidedScreeningStrategy (int)(optional) this is the setting used to configure which third party checks will be run when both sides of a document can be processed successfully
- No Third Party Checks should be run – 0
- DMV Only - 1
- Identifraud Only – 2
- DMV will be run where possible, if it is not possible then Identifraud will be run - 3
- DMV and Identifraud will be run – 4
overriddenSettings.oneSidedScreeningStrategy (int)(optional) this is the setting used to configure which third party checks will be run when overriddenSettings.isCrossMatchRequired is set to false and only one side of a document can be processed successfully
- DMV Only - 1
- Identifraud Only – 2
- DMV will be run where possible, if it is not possible then Identifraud will be run - 3
- DMV and Identifraud will be run – 4
overriddenSettings.ageYearsDifference (int)(optional)
metadata.captureMethod (string)(optional) this string captures how the images were captured
- File Upload – 0
- Auto Capture - 1
metadata.userAgent (string)(optional) this can be populated with the navigator.userAgent value to help track which devices your users are using
metadata.frontEndMetadata (string)(optional) provides data obtained from the web lib (we may learn the version of the app and the fronts are debugged using this information)
metadata.otherMetadata (string)(optional) random data that a customer needs to save/ provide apart from the original data

Response:

Successful Response

{
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "document": {
    "abbr3Country": "string",
    "abbrCountry": "string",
    "address": "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",
    "maidenName": "string",
    "middleName": "string",
    "placeOfBirth": "string",
    "postalBox": "string",
    "state": "string",
    "issuedBy": "string",
    "weight": "string",
    "zip": "string",
    "cardRevisionDate": "string",
    "hazmatExpirationDate": "string",
    "race": "string",
    "ssn": "string",
    "suffix": "string"
  },
  "documentVerificationResult": {
    "isDocumentExpired": true,
    "isOcrSuccess": true,
    "isPdf417Success": true,
    "isMrzSuccess": true,
    "isShuftiSuccess": true,
    "isDriversLicenseRealID": true,
    "isDriveOnly": true,
    "isVeteran": true,
    "isDonor": true,
    "isLimitedDurationDocument": true,
    "isInvalidated": true,
    "documentConfidence": 0
  },
  "faceMatchVerificationResult": {
    "falseAcceptanceRate": 0,
    "faceMatchConfidence": 0,
    "isAgeCheckSuccess": true,
    "isGenderCheckSuccess": true,
    "assessedAgeFromSelfie": 0,
    "assessedAgeFromDocument": 0,
    "isSuspiciousPhoto": true
  },
  "antiSpoofingVerificationResult": {
    "antiSpoofingFaceImageConfidence": 0,
    "isDataFieldsTampered": true,
    "isPhotoFromDocumentTampered": true
  },
  "externalVerificationResults": [
    {
      "name": "string",
      "displayName": "string",
      "reason": "string",
      "effect": 0,
      "values": [
        {
          "score": 0,
          "effect": 0,
          "fieldName": "string",
          "priority": 0
        }
      ],
      "status": 0
    }
  ],
  "authenticationResults": [
    {
      "name": "string",
      "description": "string",
      "response": "string",
      "score": 0
    }
  ],
  "requestData": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "documentType": 1,
    "requestIpAddress": "string",
    "geolocation": {
      "continentCode": "string",
      "continent": "string",
      "countryCode": "string",
      "country": "string",
      "stateCode": "string",
      "state": "string",
      "city": "string",
      "postCode": "string",
      "accuracyRadius": 0,
      "latitude": 0,
      "longitude": 0,
      "timeZone": "string",
      "network": "string"
    },
    "trackString": {
      "data": "string",
      "barcodeParams": "string"
    },
    "metadata": {
      "captureMethod": "string",
      "userAgent": "string",
      "frontEndMetadata": "string",
      "otherMetadata": "string"
    },
    "settings": {
      "isOCREnabled": true,
      "isCrossMatchRequired": true,
      "isGenderCheckEnabled": true,
      "isAgeCheckEnabled": true,
      "isDocTypeChangeEnabled": true,
      "isExternalOFACWatchlistEnabled": true,
      "ageYearsDifference": 0,
      "submissionDaysCount": 0,
      "bothSidedScreeningStrategy": 0,
      "oneSidedScreeningStrategy": 0,
      "isExternalAddressVerificationEnabled": true,
      "isExternalShuftiEnabled": true,
      "isFaceMatchOptional": true,
      "isBackOrSecondImageProcessingEnabled": true,
      "isFaceMatchEnabled": true
    }
  },
  "images": {
    "frontImage": "string",
    "backOrSecondImage": "string",
    "frontImageUv": "string",
    "backOrSecondImageUv": "string",
    "frontImageIr": "string",
    "backOrSecondImageIr": "string",
    "faceImage": "string",
    "croppedFaceImage": "string",
    "croppedFaceImageFromDocument": "string",
    "signatureImage": "string"
  },
  "transactionData": {
    "updateDate": "2024-10-16T17:16:50.257Z",
    "remainingAmount": 0
  },
  "reference": "string"
}

Failure Response

{
  "code": "string",
  "message": "string",
  "additionalData": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "multipleErrors": [
    null
  ],
  "traceId": "string"
}

authentication Request

[POST] /api/v4/authentication

Note

Uses the secret key

Upload documents to the DIVE server for authentication

Parameters

returnRequest (boolean) If returnRequest=true then requestData is returned to the Response body.
returnContent (boolean) If returnContent=true then Base64 image of the document is returned to the Response body.

{
  "documentType": 1,
  "frontImageBase64": "string",
  "backOrSecondImageBase64": "string",
  "frontImageBase64Uv": "string",
  "backOrSecondImageBase64Uv": "string",
  "frontImageBase64Ir": "string",
  "backOrSecondImageBase64Ir": "string",
  "faceImageBase64": "string",
  "trackString": {
    "data": "string",
    "barcodeParams": "string"
  },
  "ssn": "string",
  "overriddenSettings": {
    "isExternalAddressVerificationEnabled": true,
    "isExternalShuftiEnabled": true,
    "isOCREnabled": true,
    "isBackOrSecondImageProcessingEnabled": true,
    "isFaceMatchEnabled": true,
    "isFaceMatchOptional": true,
    "isCrossMatchRequired": true,
    "isGenderCheckEnabled": true,
    "isAgeCheckEnabled": true,
    "isDocTypeChangeEnabled": true,
    "bothSidedScreeningStrategy": 0,
    "oneSidedScreeningStrategy": 0,
    "isGpuEnabled": true
  },
    "metadata": {
    "captureMethod": "string",
    "userAgent": "string",
    "frontEndMetadata": "string",
    "otherMetadata": "string"
  }
}

documentType (string or int) Type of document.
- ID – 1
- Passport - 2
- PassportCard – 3
- Common Access Card – 4
- Uniformed Services ID – 5
- GreenCard – 6
- InternationalId – 7
frontImageBase64 (string) Front of the document which contains the data for OCR and a photo.
backOrSecondImageBase64 (string) Image of the reverse side or back of the document which contains the Barcode (PDF417) or MRZ.
frontImageBase64Uv (string) Ultraviolet image of the front of the document.
backOrSecondImageBase64Uv (string) Ultraviolet image of the image of the reverse side or back of the document.
frontImageBase64Ir (string) Infrared image of the front of the document.
backOrSecondImageBase64Ir (string) Infrared image of the image of the reverse side or back of the document.
faceImageBase64 (string) Image of the face of the document owner if it is necessary to compare it with the photo of the face on the document.
trackString.data (string)(optional) PDF417 barcode data (or MRZ data) encoded as a base64 string
trackString.barcodeParams (string)(optional)
ssn (string)(optional) this is an optional field that must conform to the following format XXXX or XXX-XX-XXXX for a Social Security Number
overriddenSettings.isExternalAddressVerificationEnabled (boolean)(optional) enables the verification of the address found on the submitted document by using a third party address verification web service
overriddenSettings.isExternalShuftiEnabled (boolean)(optional) enables processing international IDs using our partner's web service
overriddenSettings.isOCREnabled (boolean)(optional) enables processing the front image of a document using OCR technology
overriddenSettings.isBackOrSecondImageProcessingEnabled (boolean)(optional) enables processing the back image of a document
overriddenSettings.isFaceMatchEnabled (boolean)(optional) enables performing a face match between a submitted selfie and a cropped image of the document owner's face from the front image of the document
overriddenSettings.isFaceMatchOptional (boolean)(optional) this setting will make it optional to perform a face match if for some reason a cropped image of the document owner's face from the front image of the document cannot be obtained
overriddenSettings.isCrossMatchRequired (boolean)(optional) this setting makes it a requirement that both the front and the back of the document are able to be read successfully, if this is disabled a submission will be considered successful if either the front or the back of the document can be read
overriddenSettings.isGenderCheckEnabled (boolean)(optional) enables a verification check to be run that makes sure the gender of the person on the front of the document matches the gender of the person submitting the selfie
overriddenSettings.isAgeCheckEnabled (boolean)(optional) enables a verification check to be run that makes sure the age of the person on the front of the document matches the age (within a 10 year window) of the person submitting the selfie
overriddenSettings.isDocTypeChangeEnabled (boolean)(optional) enables the option to change the type of the document in cases when the document is sent with the wrong document type. For example, if International ID (document type - 7) is recognized as Passport (document type - 2) then the document type is changed to Passport (document type -2)
overriddenSettings.bothSidedScreeningStrategy (int)(optional) this is the setting used to configure which third party checks will be run when both sides of a document can be processed successfully
- No Third Party Checks should be run – 0
- DMV Only - 1
- Identifraud Only – 2
- DMV will be run where possible, if it is not possible then Identifraud will be run - 3
- DMV and Identifraud will be run – 4
overriddenSettings.oneSidedScreeningStrategy (int)(optional) this is the setting used to configure which third party checks will be run when overriddenSettings.isCrossMatchRequired is set to false and only one side of a document can be processed successfully
- DMV Only - 1
- Identifraud Only – 2
- DMV will be run where possible, if it is not possible then Identifraud will be run - 3
- DMV and Identifraud will be run – 4
overriddenSettings.isGpuEnabled (boolean)(optional) enabled the use of GPUs when processing the submission
metadata.captureMethod (string)(optional) this string captures how the images were captured
- File Upload – 0
- Auto Capture - 1
metadata.userAgent (string)(optional) this can be populated with the navigator.userAgent value to help track which devices your users are using
metadata.frontEndMetadata (string)(optional)provides data obtained from the web lib (we may learn the version of the app and the fronts are debugged using this information)
metadata.otherMetadata (string)(optional) random data that a customer needs to save/ provide apart from the original data

Successful Response

{
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "document": {
    "abbr3Country": "string",
    "abbrCountry": "string",
    "address": "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",
    "middleName": "string",
    "postalBox": "string",
    "state": "string",
    "issuedBy": "string",
    "weight": "string",
    "zip": "string",
    "ssn": "string"
  },
  "documentVerificationResult": {
    "isDocumentExpired": true,
    "isOcrSuccess": true,
    "isPdf417Success": true,
    "isMrzSuccess": true,
    "isShuftiSuccess": true,
    "isDriversLicenseRealID": true,
    "documentConfidence": 0
  },
  "faceMatchVerificationResult": {
    "falseAcceptanceRate": 0,
    "faceMatchConfidence": 0,
    "isAgeCheckSuccess": true,
    "isGenderCheckSuccess": true
  },
  "antiSpoofingVerificationResult": {
    "antiSpoofingFaceImageConfidence": 0,
    "isDataFieldsTampered": true,
    "isPhotoFromDocumentTampered": true
  },
  "externalVerificationResults": [
    {
      "name": "string",
      "displayName": "string",
      "reason": "string",
      "effect": 0,
      "values": [
        {
          "score": 0,
          "effect": 0,
          "fieldName": "string"
        }
      ],
      "status": 0
    }
  ],
  "authenticationResults": [
    {
      "name": "string",
      "description": "string",
      "response": "string",
      "score": 0
    }
  ],
  "requestData": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "documentType": 1,
    "requestIpAddress": "string",
    "geolocation": {
      "continentCode": "string",
      "continent": "string",
      "countryCode": "string",
      "country": "string",
      "stateCode": "string",
      "state": "string",
      "city": "string",
      "postCode": "string",
      "accuracyRadius": 0,
      "latitude": 0,
      "longitude": 0,
      "timeZone": "string",
      "network": "string"
    },
    "trackString": {
      "data": "string",
      "barcodeParams": "string"
    },
    "metadata": {
      "captureMethod": "string",
      "userAgent": "string",
      "frontEndMetadata": "string",
      "otherMetadata": "string"
    },
    "settings": {
      "isOCREnabled": true,
      "isCrossMatchRequired": true,
      "isGenderCheckEnabled": true,
      "isAgeCheckEnabled": true,
      "isDocTypeChangeEnabled": true,
      "bothSidedScreeningStrategy": 0,
      "oneSidedScreeningStrategy": 0,
      "isExternalAddressVerificationEnabled": true,
      "isExternalShuftiEnabled": true,
      "isFaceMatchOptional": true,
      "isBackOrSecondImageProcessingEnabled": true,
      "isFaceMatchEnabled": true
    }
  },
  "images": {
    "frontImage": "string",
    "backOrSecondImage": "string",
    "frontImageUv": "string",
    "backOrSecondImageUv": "string",
    "frontImageIr": "string",
    "backOrSecondImageIr": "string",
    "faceImage": "string",
    "croppedFaceImage": "string",
    "croppedFaceImageFromDocument": "string",
    "signatureImage": "string"
  }
}

Failure Response

{
  "code": "string",
  "message": "string",
  "additionalData": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "multipleErrors": [
    null
  ],
  "traceId": "string"
}