DIVE Online API - Authentication

The authentication endpoints are designed to be used with a hardware scanner that is capable of taking UV/IR images of documents.

These endpoints allow not only white light verification, but also additional layers with these new set of images.

Note

Developers without hardware scanner solutions are not advised to use these endpoints.

Both endpoints will acheive the same result. The difference is submitting the payload as base64 strings(/api/v2/public/Authentication) or multipart/form-data (/api/v2/public/Authentication/from-form).

/api/v2/public/Authentication

[POST] /api/v2/public/Authentication

Use Case - 6 image (as base 64 strings) authentication including UV/IR/RGB images. Additionaly, a face match image can be attached to the request for face matching.

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

Required Parameters

None

Optional Parameters

None

Request Body

{
  "applicantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "embeddedAppConnectionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": {
    "frontImageBase64": "string",
    "backOrSecondImageBase64": "string",
    "frontImageBase64Uv": "string",
    "backOrSecondImageBase64Uv": "string",
    "frontImageBase64Ir": "string",
    "backOrSecondImageBase64Ir": "string",
    "faceImageBase64": "string",
    "trackString": {
      "data": "string",
      "barcodeParams": "string"
    },
    "ssn": "string"
  },
  "model": {
    "documentType": 1,
    "captureMethod": "string",
    "userAgent": "string",
    "frontEndMetadata": "string",
    "overriddenSettings": {
      "isFaceMatchEnabled": true,
      "isFaceMatchOptional": true
    }
  }
}

applicantId (string) - The unique identifier for the applicant.
embeddedAppConnectionId (string) - The unique identifier for the embedded application connection.

content — An array of payload images/ssn/trackstrings.

content.frontImageBase64 (string) - Base64 encoded string of the front image of the document.
content.backOrSecondImageBase64 (string) - Base64 encoded string of the back or second image of the document.
content.frontImageBase64Uv (string) - Base64 encoded string of the front UV image of the document.
content.backOrSecondImageBase64Uv (string) - Base64 encoded string of the back or second UV image of the document.
content.frontImageBase64Ir (string) - Base64 encoded string of the front IR image of the document.
content.backOrSecondImageBase64Ir (string) - Base64 encoded string of the back or second IR image of the document.
content.faceImageBase64 (string) - Base64 encoded string of the face image for face matching.
content.trackString (object) - Object containing track string data and barcode parameters.
- content.trackString.data (string) - The track string data.
- content.trackString.barcodeParams (string) - The barcode parameters.
content.ssn (string) - The social security number associated with the applicant.

model — An array of fields for metadata and request body settings.

model.documentType (int) - The type of document being authenticated.
- 1 - ID
- 2 - Passport
- 3 - PassportCard
- 4 - Common Access Card
- 5 - Uniformed Services ID
- 6 - GreenCard
- 7 - InternationalId
model.captureMethod (string) - The method used to capture the document images.
- 0 - File Upload
- 1 - Auto Capture
model.userAgent (string) - The user agent string of the device making the request.
model.frontEndMetadata (string) - Additional metadata from the front end.
model.overriddenSettings (object) - Object containing overridden settings for the authentication request.
- model.overriddenSettings.isFaceMatchEnabled (bool) - Indicates if face matching is enabled.
- model.overriddenSettings.isFaceMatchOptional (bool) - Indicates if face matching is optional.

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,
  "isCompleted": true,
  "applicantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "attemptId": 0,
  "authenticationResults": [
    {
      "name": "string",
      "description": "string",
      "response": "string",
      "score": 0
    }
  ]
}

Response Fields

document — The document object provided in the successful attempt.

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 (int) - The number of authentication attempts made.
attemptsLeft (int) - The number of authentication attempts remaining.
status (int) - The status of the authentication attempt.

validationStatus — An array of validation status results.

validationStatus.expired (bool) - Indicates whether the document is expired.
validationStatus.documentIsValid (bool) - Indicates whether the document is valid.
validationStatus.faceIsValid (bool) - Indicates whether the face match is valid.
validationStatus.antiSpoofingIsValid (bool) - Indicates whether the anti-spoofing check is valid.

invalidDataErrors — An array of invalid data errors encountered during authentication.

invalidDataErrors.code (string) - The error code for the invalid data.
invalidDataErrors.message (string) - The error message for the invalid data.

faceSuccess (bool) - Indicates whether the face match was successful.
documentSuccess (bool) - Indicates whether the document authentication was successful.
documentHasNotExpired (bool) - Indicates whether the document has not expired.
hasRiskEvents (bool) - Indicates whether there are any risk events associated with the authentication attempt.

documentValidationTests — An array of document validation tests performed during authentication.

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

callBackUrl (string) - The callback URL for the authentication attempt.
notificationType (int) - The type of notification for the authentication attempt.
- 0 - None
- 1 - SMS
- 2 - Email
- 3 - EmailAndSMS
isCompleted (bool) - Indicates whether the authentication attempt is completed.
applicantId (string) - The unique identifier for the applicant.
attemptId (int) - The unique identifier for the authentication attempt.
authenticationResults (array) - An array of authentication results from various checks performed during the authentication attempt.
- authenticationResults.name (string) - The name of the authentication test.
- authenticationResults.description (string) - The description of the authentication test.
- authenticationResults.response (string) - The response for the authentication result. This will appear when a test has not completed.
- authenticationResults.score (int) - The score for the authentication test.

/api/v2/public/Authentication/from-form

[POST] /api/v2/public/Authentication/from-form

Use Case - 6 image (as multipart/form-data) authentication including UV/IR/RGB images. Additionaly, a face match image can be attached to the request for face matching.

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

Required Parameters

None

Optional Parameters

None

Request Body

{
  "applicantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "embeddedAppConnectionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": {
    "frontImageBase64": "string",
    "backOrSecondImageBase64": "string",
    "frontImageBase64Uv": "string",
    "backOrSecondImageBase64Uv": "string",
    "frontImageBase64Ir": "string",
    "backOrSecondImageBase64Ir": "string",
    "faceImageBase64": "string",
    "trackString": {
      "data": "string",
      "barcodeParams": "string"
    },
    "ssn": "string"
  },
  "model": {
    "documentType": 1,
    "captureMethod": "string",
    "userAgent": "string",
    "frontEndMetadata": "string",
    "overriddenSettings": {
      "isFaceMatchEnabled": true,
      "isFaceMatchOptional": true
    }
  }
}

applicantId (string) - The unique identifier for the applicant.
embeddedAppConnectionId (string) - The unique identifier for the embedded application connection.

content — An array of payload images/ssn/trackstrings.

content.frontImageBase64 (string) - Base64 encoded string of the front image of the document.
content.backOrSecondImageBase64 (string) - Base64 encoded string of the back or second image of the document.
content.frontImageBase64Uv (string) - Base64 encoded string of the front UV image of the document.
content.backOrSecondImageBase64Uv (string) - Base64 encoded string of the back or second UV image of the document.
content.frontImageBase64Ir (string) - Base64 encoded string of the front IR image of the document.
content.backOrSecondImageBase64Ir (string) - Base64 encoded string of the back or second IR image of the document.
content.faceImageBase64 (string) - Base64 encoded string of the face image for face matching.
content.trackString (object) - Object containing track string data and barcode parameters.
- content.trackString.data (string) - The track string data.
- content.trackString.barcodeParams (string) - The barcode parameters.
content.ssn (string) - The social security number associated with the applicant.

model — An array of fields for metadata and request body settings.

model.documentType (int) - The type of document being authenticated.
- 1 - ID
- 2 - Passport
- 3 - PassportCard
- 4 - Common Access Card
- 5 - Uniformed Services ID
- 6 - GreenCard
- 7 - InternationalId
model.captureMethod (string) - The method used to capture the document images.
- 0 - File Upload
- 1 - Auto Capture
model.userAgent (string) - The user agent string of the device making the request.
model.frontEndMetadata (string) - Additional metadata from the front end.
model.overriddenSettings (object) - Object containing overridden settings for the authentication request.
- model.overriddenSettings.isFaceMatchEnabled (bool) - Indicates if face matching is enabled.
- model.overriddenSettings.isFaceMatchOptional (bool) - Indicates if face matching is optional.

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",
   "isCompleted": true,
  "applicantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "attemptId": 0,
  "authenticationResults": [
    {
      "name": "string",
      "description": "string",
      "response": "string",
      "score": 0
    }
  ]
}

Response Fields

document — The document object provided in the successful attempt.

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 (int) - The number of authentication attempts made.
attemptsLeft (int) - The number of authentication attempts remaining.
status (int) - The status of the authentication attempt.

validationStatus — An array of validation status results.

validationStatus.expired (bool) - Indicates whether the document is expired.
validationStatus.documentIsValid (bool) - Indicates whether the document is valid.
validationStatus.faceIsValid (bool) - Indicates whether the face match is valid.
validationStatus.antiSpoofingIsValid (bool) - Indicates whether the anti-spoofing check is valid.

invalidDataErrors — An array of invalid data errors encountered during authentication.

invalidDataErrors.code (string) - The error code for the invalid data.
invalidDataErrors.message (string) - The error message for the invalid data.

faceSuccess (bool) - Indicates whether the face match was successful.
documentSuccess (bool) - Indicates whether the document authentication was successful.
documentHasNotExpired (bool) - Indicates whether the document has not expired.
hasRiskEvents (bool) - Indicates whether there are any risk events associated with the authentication attempt.

documentValidationTests — An array of document validation tests performed during authentication.

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

callBackUrl (string) - The callback URL for the authentication attempt.
notificationType (int) - The type of notification for the authentication attempt.
- 0 - None
- 1 - SMS
- 2 - Email
- 3 - EmailAndSMS
isCompleted (bool) - Indicates whether the authentication attempt is completed.
applicantId (string) - The unique identifier for the applicant.
attemptId (int) - The unique identifier for the authentication attempt.
authenticationResults (array) - An array of authentication results from various checks performed during the authentication attempt.
- authenticationResults.name (string) - The name of the authentication test.
- authenticationResults.description (string) - The description of the authentication test.
- authenticationResults.response (string) - The response for the authentication result. This will appear when a test has not completed.
- authenticationResults.score (int) - The score for the authentication test.