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/v2/private/Applicants

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/v2/public/Applicants/{applicantId}/Completed

Checks if an applicant has completed.

The HTTP response code will be a 200 value indicating the request has been passed the threshold scoring set by the DIVE Online account.

Transactions that do not meet the threshold scoring/pass verification will not return a 200 response code. A 200 code will only return for the first attempt that passes verification.

Required Parameters

  • applicantId A unique ID generated on each request creation. A single applicant ID can have multiple response IDs (attempts) per instance.
[POST] api/v2/public/Applicants/{applicantId}/Complete

Force completion of an applicant.

Any applicant IDs that are currently in progress of receiving a passing verification can automatically be closed through this API call.

This includes any applicant IDs that are currently pending or have only failed attempts.

Required Parameters

  • applicantId A unique ID generated on each request creation. A single applicant ID can have multiple response IDs (attempts) per instance.
[GET] api/v2/private/Applicants

List all applicants in a paginated list.

Required Parameters

  • Page specifies the page number to return. The value must be between 1 and 2147483647.

  • PageSize specifies the number of items to return per page. The value must be between 1 and 400.

Optional Parameters

  • CreatedFrom specifies the start date of the range to filter applicants by creation date. This value is in YYYY-MM-DD format.

  • CreatedTo specifies the end date of the range to filter applicants by creation date. This value is in YYYY-MM-DD format.

  • SortField specifies the field to sort the results by. The value must be one of the following: Id, FirstName, LastName, Phone, Email, ReferenceId, OpenedLinkTimes, AttemptsUsed, Created, AccountId, Completed, Status, ResponsesCount, CallbackUrl, VerificationMethod, LastPriorityMessageStatus, LastPriorityEmailStatus, NotificationType

  • Order can be either asc or desc to specify the order of the results.

  • TextFilter Filters the results by a text value.

[GET] api/v2/private/Applicants/{applicantId}

Retrieves an applicants by their unique ID.

Required Parameters

  • applicantId A unique ID generated on each request creation. A single applicant ID can have multiple response IDs (attempts) per instance.

  • includeSuccessResponse A boolean value that indicates whether to include the successful response in the result. If set to true, the successful response will be included in the result. If set to false, only the failed responses will be included in the result.

[DELETE] api/v2/public/Applicants/{applicantId}

Deletes an applicant by their unique ID.

Required Parameters

  • applicantId A unique ID generated on each request creation. A single applicant ID can have multiple response IDs (attempts) per instance.
[GET] api/v2/private/Applicants/{applicantId}/Attempts/{attemptId}

Retrieves an applicant's attempt by their unique ID.

Required Parameters

  • applicantId A unique ID generated on each request creation. A single applicant ID can have multiple response IDs (attempts) per instance.

  • attemptId A unique ID generated for each attempt made by the applicant. This ID is used to retrieve the specific attempt data. This value is also called a response ID.

[GET] api/v2/private/Applicants/{applicantId}/Attempts

Retrieves all of an applicant's attempt by their unique ID.

Required Parameters

  • applicantId A unique ID generated on each request creation. A single applicant ID can have multiple response IDs (attempts) per instance.
[POST] api/v2/private/Applicants/{applicantId}/ReNotify

This request will trigger re-sending the initial SMS/Email message with a link to the validation web page to an end user.

Required Parameters

  • applicantId A unique ID generated on each request creation. A single applicant ID can have multiple response IDs (attempts) per instance.
[GET] api/v2/private/Applicants/{applicantId}/Attempts/{attemptId}/Images

Retrieves all of an applicant's images by their unique ID.

Required Parameters

  • applicantId A unique ID generated on each request creation. A single applicant ID can have multiple response IDs (attempts) per instance.

  • attemptId A unique ID generated for each attempt made by the applicant. This ID is used to retrieve the specific attempt data. This value is also called a response ID.