API Manual

In this documentation, we describe in detail all the endpoints available via the DIVE Online Web API as well as how to authenticate your requests.

Base URL

https://api-dvsonline.idscan.net/

Authentication

Every endpoint in the DIVE Online Web API requires authentication. You will need to include a bearer token with each request to authenticate. The bearer token will be included in the Authorization header of each request made.

Important

When making requests using the DIVE Online Web API we call the bearer token an API token, this differs from the public key and secret key we use when making requests to the DIVE API. They all serve the same purpose (i.e. serving as the bearer token to authenticate a request) but they have different names to denote their different uses.

You can generate a token for authentication in the DIVE Online Web Portal here.

REST API Endpoints

[POST] /api/ValidationRequests

When making a new request, if you chose not to send an SMS message containing a link to a web page where documents can be uploaded by your users, you will need to determine a different method of delivering that link. When sending an SMS message, you have the option to configure a callback URL for the system to redirect your user to after submitting documents to DIVE.

For security reasons, when redirecting a user, the supplied callback URL in the body of the POST will be validated against the list of callback URLs in the DIVE Online Web Portal. If the list of callback URLs is empty or the URL can not be found, the user will be redirected to the page of the closed request.

Field metadata is useful for storing additional, structured information on an object. As an example, you could store your user's full name and corresponding unique identifier from your system. The metadata fields are not used by the DIVE API.

Request Body:

{
  "firstName": "string",
  "lastName": "string",
  "phone": "string",
  "email": "string",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "callbackUrl": "string",
  "sendSms": true
}

[GET] /api/ValidationRequests

This request will return a paginated list of all previously created requests.

[GET] /api/ValidationRequests/{requestId}

This request will obtain a request's data by it's unique ID.

[GET] /api/ValidationRequests/Images/{responseId}

This request made with a response ID will return the images that were submitted.

Response:

{
  "frontImageBase64": "string",
  "backOrSecondImageBase64": "string",
  "faceImageBase64": "string"
}
  • frontImageBase64 Front of the document which contains the data for OCR and a photo.
  • backOrSecondImageBase6 Image of the reverse side or back of the document which contains the Barcode (PDF417) or MRZ
  • faceImageBase64 Image of the face of the document owner
[POST] /api/ValidationRequests/ReNotify/{requestId}

This request will trigger sending another SMS message with a link to the validation web page to an end user.

[GET] /api/ValidationRequests/Response/{requestId}/{responseId}

This request will return a specific response for a specified request ID. Every response contains the following data model which includes the type of the document, date of the response's creation, identified fields of the document, validation status of the document and data errors if there are any.

Response:

{
  "validationRequestId": "00000000-0000-0000-0000-000000000000",
  "document": {
    "idType": "string",
    "country": "string",
    "abbrCountry": "string",
    "abbr3Country": "string",
    "id": "string",
    "dob": "string",
    "issued": "string",
    "expires": "string",
    "fullName": "string",
    "privateName": "string",
    "familyName": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "address": "string",
    "class": "string",
    "gender": "string",
    "height": "string",
    "eyes": "string",
    "hair": "string",
    "weight": "string",
    "template": "string",
    "firstName": "string",
    "middleName": "string"
  },
  "documentFailStatusReasons": [
    "string"
  ],
  "faceFailStatusReasons": [
    "string"
  ],
  "invalidDataErrors": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "validationResponseId": 0,
  "created": "0000-00-00T00:00:00.000Z",
  "documentType": "string",
  "documentTypeInt": 0,
  "status": 0,
  "validationStatus": {
    "expired": true,
    "documentIsValid": true,
    "faceIsValid": true
  }
}

Listed below are the possible values and descriptions:

  • - status - possible values: 0, 1, 2, 3

    0 - document is valid

    1 - document is fake

    2 - data error. If a document is of poor quality and we are not able to identify it, this status will be shown. Also in the field "InvalidDataErrors" there will be a list of problems related to the code and to the message.

    3 - server error during the document identification

  • - validationStatus - list of meanings for validation steps.

expired - whether the license is valid at the moment of validation or not

documentIsValid - whether a document is valid or not

faceIsValid - whether the face in the document coincides with the face of the user.

Note

expired - does not influence the final decision with respect to the validity of the document and only serves as a guideline.