API Manual
Base URL
https://dvs.checkpointid.com/
Authentication
The DVS API uses API keys to authenticate 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 validation. They can be integrated into the client app.
Secret keys have full access to API and allow to make any requests to the server. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Authentication via the API is executed through HTTP Header Authorization using the Bearer.
(e.g.:Authorization: Bearer sk_a47764c0-e3da-4300-ba2d-fdf148c011ea)
API-requests without authentication also will not be executed.
Only for Cloud:
All API-requests must be made through HTTPS. Requests which will be made through usual HTTP will incur an error.
Add header in request
Authorization: bearer sk_00000000-0000-0000-0000-000000000000"
Example Authenticated Request
curl -X GET https://dvs.checkpointid.com/api/Request/42523452453/content -H "Content-Type: application/json" -H "Authorization: Bearer {token}"
Note
For verify request use Secret key
- sk_..
For creation request use Public key
- pk_..
Requirements for images
- no more than 1500px on the larger side
- resolution no less than 96dpi (150 dpi recommended)
- JPEG compression is no more than 15%
Verification POST /api/Verify
Verify document images on DVS using your secret key.
POST https://dvs.checkpointid.com/api/Verify
Request data:
{
"documentType": 1,
"verifyFace": true,
"frontImageBase64": "string",
"backOrSecondImageBase64": "string",
"faceImageBase64": "string",
"trackString": "string"
}
Note
For verify request use Secret key
- 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.)
Response:
{
"requestId": "string",
"documentType": 1,
"document": {...},
"visual": {...},
"machineReadable": {...},
"facePhotoFromDocument": "string",
"facePhoto": "string",
"signature": "string",
"documentVerificationResult": {...},
"faceVerificationResult": {...},
"request": {...}
}
Verification Response Details..
Creation Request of Verification POST /api/Request
Upload the document images onto the server using your public key by making a request to check the document.
POST https://dvs.checkpointid.com/api/Request
Request data:
{
"documentType": 1,
"verifyFace": true,
"frontImageBase64": "string",
"backOrSecondImageBase64": "string",
"faceImageBase64": "string",
"trackString": "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.)
The server will return the identificator of the created request and a status.
{
"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.
Verification POST /api/Verify/{requestId}
POST https://dvs.checkpointid.com/api/Verify/{requestId}
After making a request it is possible to check the document. For this purpose it is necessary to send requestId in the method POST /Verify/{requestId}.
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:
{
"requestId": "string",
"documentType": 1,
"document": {...},
"visual": {...},
"machineReadable": {...},
"facePhotoFromDocument": "string",
"facePhoto": "string",
"signature": "string",
"documentVerificationResult": {...},
"faceVerificationResult": {...},
"request": {...}
}
Verification Response Details..
Verification request PHP Sample
Also you can send requestId in the method POST /Verify/{requestId} from PHP.
<?php
$host = "<dvs_api_url>";
$sk = "<secret_key>";
$post = file_get_contents('php://input');
$data = json_decode($post, true);
$requestId = $data["requestId"];
$curl = curl_init();
$header = array();
$header[] = 'Content-type: text/plain';
$header[] = 'Authorization: Bearer '.$sk;
curl_setopt($curl, CURLOPT_HTTPHEADER, $header);
curl_setopt($curl, CURLOPT_URL, $host.'/Verify/'.$requestId.'?returnContent=false');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode(array('requestId' => $requestId)));
$result = curl_exec($curl);
echo json_encode($result);
curl_close($curl);
?>
Get request content GET /api/Request/{id}/content
Retrieves the request content with the given request ID.
GET https://dvs.checkpointid.com/api/Request/{id}/content
Response:
{
"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.)
Retrieve an request GET /api/Request/{id}
Retrieves the request with the given ID.
GET https://dvs.checkpointid.com/api/Request/{id}
Response:
{
"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 request result GET /api/Request/{id}/result
Retrieves the request processed result with the given request ID.
GET https://dvs.checkpointid.com/api/Request/{id}/result
Response:
{
"requestId": "string($uuid)",
"verificationResult": object,
"succeeded": boolean,
"failureMessage": "string"
}
Verification Response
The response of the server will be the recognized document and the result of checking the document and the face.
{
"requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"documentType": 1,
"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"
},
"visual": {
"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"
},
"confidence": {
"idType": 0,
"country": 0,
"abbrCountry": 0,
"abbr3Country": 0,
"id": 0,
"dob": 0,
"issued": 0,
"expires": 0,
"fullName": 0,
"privateName": 0,
"familyName": 0,
"city": 0,
"state": 0,
"zip": 0,
"address": 0,
"class": 0,
"gender": 0,
"height": 0,
"eyes": 0,
"hair": 0,
"weight": 0,
"template": 0,
"firstName": 0,
"middleName": 0
}
},
"machineReadable": {
"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"
},
"confidence": {
"idType": 0,
"country": 0,
"abbrCountry": 0,
"abbr3Country": 0,
"id": 0,
"dob": 0,
"issued": 0,
"expires": 0,
"fullName": 0,
"privateName": 0,
"familyName": 0,
"city": 0,
"state": 0,
"zip": 0,
"address": 0,
"class": 0,
"gender": 0,
"height": 0,
"eyes": 0,
"hair": 0,
"weight": 0,
"template": 0,
"firstName": 0,
"middleName": 0
}
},
"facePhotoFromDocument": "string",
"facePhoto": "string",
"signature": "string",
"documentVerificationResult": {
"status": 0,
"verificationConfidence": {
"idType": 0,
"country": 0,
"abbrCountry": 0,
"abbr3Country": 0,
"id": 0,
"dob": 0,
"issued": 0,
"expires": 0,
"fullName": 0,
"privateName": 0,
"familyName": 0,
"city": 0,
"state": 0,
"zip": 0,
"address": 0,
"class": 0,
"gender": 0,
"height": 0,
"eyes": 0,
"hair": 0,
"weight": 0,
"template": 0,
"firstName": 0,
"middleName": 0
},
"totalConfidence": 0
},
"faceVerificationResult": {
"confidence": 0,
"antiSpoofing": 0
},
"request": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"documentType": 1,
"content": {
"frontImageBase64": "string",
"backOrSecondImageBase64": "string",
"faceImageBase64": "string",
"trackString": "string"
},
"status": 0,
"created": "2020-04-13T07:01:51.486Z",
"ocrVisual": true
}
}
Response Attributes:
- 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
- document (object) Contains all the fields of the document which have been imported from the Barcode (PDF417) or MRZ, and also additional fields which have been recognized from the front of the document and which are present only there.
- visual (object) This object contains the result of OCR of the document front.
- document (object) Contains the values of document fields.
- confidence (object) Contains the level of trust to the values of document fields. The less the value is, the higher the possibility of an error in the value is. The quality is influenced by the quality of a shot and the cleanliness of the document. Possible values (0, 100).
- machineReadable (object) This object contains the result of recognizing the machine-readable area of the document Barcode (PDF417) or MRZ.
- document (object) Contains the values of document fields.
- confidence (object) Contains the level of trust to the values of document fields.
- For
PDF417
the check of the fidelity of an identificator and other markers of the information fidelity in PDF417, which cannot be referred to other fields of the document, is performed. Possible values (-1, 0, 100), where -1 is not checked, 0 is not valid. - For
MRZ
, the combination of the level of trust and values of OCR and validity of fields, according to which it is possible to calculate the hash total, is made. - Possible values (-1, 0 - 100), where
-1
is not checked, 0 is not valid, > 0 % of trust.
- For
- facePhotoFromDocument (base64) – Face of the person found on the document.
- facePhoto (base64) – Face of the person found on faceImage which has been uploaded in the request for verification.
- signature (base64) – Signature of the document owner which has been found on the document.
- documentVerificationResult (object) – Result of the document check.
- status (enum) – Total result of the check. It can have the following values:
- 0 – OK the document has passed the check
- 1 – ItsFake the document has the evidence of forgery. The decision is taken on the basis of values in confidence of the object machineReadable
- 2 – Expired the document is expired. The decision is taken on the basis of values in the field expires f the object document
- 3 – LowConfidence the level of total trust to the document is less than 80.
- verificationConfidence(object) For those types of documents which support OCR of the front, contains the percent of similarity of valuable document fields from the object visual and machineReadable. For other document types it contains the level of trust to the values of document fields.
- totalConfidence Total trust to the document calculated as an average value from verificationConfidence
- status (enum) – Total result of the check. It can have the following values:
- faceVerificationResult (object) Result of comparing the faces from the document and the uploaded photo. The value of the face similarity is contained in the field confidence , possible values are from 0 to 100.
- confidence The value of similarity between face from document and selfie, possible values are from 0 to 100. As far as it is not the probability of the similarity of faces but it is a vector distance, which is defined from 0 to 100, then the value of more than 50 means that we deal with alike people or the photos have been taken after a period of time of some years, more than 70 – absolutely the same person or a twin.
- antiSpoofing The value reflecting the detection of a real selfie photo, possible values from 0 to 100. The higher the value, the lower the likelihood of fake.
- request (object) Initial request for verification.
Errors
DVS uses conventional HTTP response codes to indicate the success or failure of an API request. In general:
Codes in the 2xx range indicate success.
Codes in the 4xx range indicate an error based on provided information (e.g., a required parameter was omitted, a document's verification failed, etc.). 4xx errors that could be handled programmatically include an error code that briefly explains the error reported.
Codes in the 5xx range indicate an error with DVS's server (these are rare). Everything 5xx errors include an error code " ApiError" and message that briefly explains the error reported. If run server in development mode then error message will include field DeveloperMessage with details error's description.
Response:
{
"traceId": "string",
"code": "string",
"message": "string",
"propertyErrors": {},
"multipleErrors": [
null
]
}
Error Object Attributes:
- traceId (string) Error ID, required to contact technical support.
- code (string) The type of error returned. One of Error Codes.
- message (string) A human-readable message about the error.
- propertyErrors (object) Dictionary, which contains the fields from the model where the errors have been found. Key: field name from the model, meaning: error message. The error code will appear as 'ValidationError'.
- multipleErrors (Error's array) a set of errors of the same structure as a describable object. The error code will appear as 'MultipleErrors'.
Error Codes Summary for 400 HTTP Status Code:
- ValidationError Request fields validation is failed.
- MultipleErrors Multiple errors.
- OCRError Unable to capture data from the front of the document.
- MRZOCRError Unable to capture MRZ from the image of the document.
- MrzIsNotPresentError Image with MRZ is not present.
NEW
- FrontImageRequiredError Front image is required.
- BackImageOrTrackStringNotPresentError Back image or TrackString is not present.
- PDF417Error Unable to capture data from the back of the document.
- FaceDocNotDetectError The face has not been found on the document.
- FacePhotoNotDetectError The face has not been found on the photo.
- DocumentVerifyError Unable to Verify the Document(s).
- TrackStringParserError Failed to parse the TrackString.
- CompareFacesError Error to compare faces.
- CaptureFacesError Error to capture faces.
NEW
- RequestAlreadyProcessed This request has already been processed.
- RequestExpired This request has expire.
- AntiSpoofing Anti spoofing analyzing failed.
NEW
Error Codes Summary for 404 HTTP Status Code:
- NotFound The requested resource doesn't exist.
Read next: API on Swagger / API Reference