API Manual

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

Base URL

https://dvs2.idware.net/

Authentication

The DVS Web API uses API keys to authenticate all requests. Public keys have the prefix pk_ and secret keys have the prefix sk_.

Public keys are used only for creating a request for document verification and they are intended to be used in the client application.

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

Warning

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

Authenticating requests with the DVS Web API is done using the public key/secret key as a Bearer token in the Authorization Header.

Authorization: Bearer sk_a47764c0-e3da-4300-ba2d-fdf148c011ea

Rest API Endpoints

[POST] /api/v3/Verify
Note

Uses the secret key

Upload documents to the DVS server for verification

Request data:

{
  "documentType": 1,
  "verifyFace": true,
  "captureMethod": "string",
  "userAgent": "string",
  "frontImageBase64": "string",
  "backOrSecondImageBase64": "string",
  "faceImageBase64": "string",
  "trackString": "string",
  "ssn": "string"
}
  • documentType (string or int) Type of document.
    • ID – 1
    • Passport - 2
    • PassportCard – 3
    • GreenCard – 6
    • InternationalId – 7
  • frontImageBase64 (string) Front of the document which contains the data for OCR and a photo.
  • backOrSecondImageBase64 Image of the reverse side or back of the document which contains the Barcode (PDF417) or MRZ (this is not necessary if trackString is filled in.)
  • faceImageBase64 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(optional) PDF417 in base64 decoded from Barcode. (it is not necessary if backOrSecondImageBase64 is filled in.)
  • verifyFace (bool)(optional) is it necessary to check the face (default true)
  • captureMethod (string)(optional) this string captures how the images were submitted
    • File Upload – 0
    • Auto Capture - 1
    • Manual Capture – 2
  • userAgent (string)(optional) this can be populated with the navigator.userAgent value to help track which devices your users are using
  • 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

Response:

API Reference Errors Description 
{
  "requestId": "string",
  "documentType": 1,
  "document": {...},
  "visual": {...},
  "machineReadable": {...},    
  "facePhotoFromDocument": "string",
  "facePhoto": "string",
  "signature": "string",
  "documentVerificationResult": {...},
  "faceVerificationResult": {...},
  "request": {...} 
}

[POST] /api/v3/Request
Note

Uses the public key

Create a new verification request on the DVS server

Request data:

{
  "documentType": 1,
  "verifyFace": true,
  "captureMethod": "string",
  "userAgent": "string",
  "frontImageBase64": "string",
  "backOrSecondImageBase64": "string",
  "faceImageBase64": "string",
  "trackString": "string",
  "ssn": "string"
}
  • documentType (string or int) Type of document.
    • ID – 1
    • Passport - 2
    • PassportCard – 3
    • GreenCard – 6
    • InternationalId – 7
  • frontImageBase64 (string) Front of the document which contains the data for OCR and a photo.
  • backOrSecondImageBase64 Image of the reverse side or back of the document which contains the Barcode (PDF417) or MRZ (this is not necessary if trackString is filled in.)
  • faceImageBase64 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 PDF417 in base64 decoded from Barcode. (it is not necessary if backOrSecondImageBase64 is filled in.)
  • verifyFace (bool)(optional) is it necessary to check the face (default true)
  • captureMethod (string)(optional) this string captures how the images were submitted
    • File Upload – 0
    • Auto Capture - 1
    • Manual Capture – 2
  • userAgent (string)(optional) this can be populated with the navigator.userAgent value to help track which devices your users are using
  • 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

The server will return the Id of the created request and its status.

API Reference Errors Description 
{
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": 0,
  "documentType": 1
}

Response Attributes:

  • requestId (uuid) Unique identifier for the object.
  • status (int) The status of verification's request
  • documentType (int) The type of document. One of Supported type of documents
    • ID – 1
    • Passport - 2
    • PassportCard – 3
    • GreenCard – 6
    • InternationalId – 7

Statuses Request of Verification Summary (int 0-3):

  • Pending (0) The request has been created but the document check has not been made yet.
  • Success (1) The document has been successfully checked. (The status of success does not mean the validity of a document)
  • Failed (2) The document check has failed.
  • Expired (3) Time for checking the document has expired before it has been checked. Images of the document have been deleted.
> POST /api/v3/Verify/{requestId}
Note

Uses the secret key

After making a request it is possible to retrieve the document's submitted with that request within 30 minutes of making it

Request:

curl -X POST "<dvs_api_url>/Verify/00000000-0000-0000-0000-000000000000" 
-H "accept: application/json" 
-H "Authorization: Bearer sk_00000000-0000-0000-0000-000000000000"

Response:

API Reference Errors Description 
{
  "requestId": "string",
  "documentType": 1,
  "document": {...},
  "visual": {...},
  "machineReadable": {...},    
  "facePhotoFromDocument": "string",
  "facePhoto": "string",
  "signature": "string",
  "documentVerificationResult": {...},
  "faceVerificationResult": {...},
  "request": {...} 
}

Verification Response Details..

[GET] /api/v3/Request/{id}/content
Note

Uses the secret key

Retrieves the request content with the given request ID.

Response:

API Reference Errors Description 
{
  "frontImageBase64": "string",
  "backOrSecondImageBase64": "string",
  "faceImageBase64": "string",
  "trackString": "string"
}
  • frontImageBase64 (string) Front of the document which contains the data for OCR and a photo.
  • backOrSecondImageBase64 Image of the reverse side or back of the document which contains the Barcode (PDF417) or MRZ (this is not necessary if trackString is filled in.)
  • faceImageBase64 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 PDF417 in base64 decoded from Barcode. (it is not necessary if backOrSecondImageBase64 is filled in.)
[GET] /api/v3/Request/{id}
Note

Uses the public key

Retrieves the request with the given ID.

Response:

API Reference Errors Description 
{
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": 0,
  "documentType": 1
}
  • requestId (uuid) Request identifier.
  • documentType (int) The type of document. One of Supported type of documents
    • ID – 1
    • Passport - 2
    • PassportCard – 3
    • GreenCard – 6
    • InternationalId – 7
  • Status (int) The status of request processing
    • Pending - 0
    • Success - 1
    • Failed - 2
    • Canceled - 3

​

[GET] /api/v3/Request/{id}/result
Note

Uses the secret key

Retrieves the request processed result with the given request ID.

Response:

API Reference Errors Description 
{
    "requestId":	"string($uuid)",
    "verificationResult": object,
    "succeeded":	boolean,
    "failureMessage":	"string"    
}