We are in the process of updating this product. This will result in a new version of the API which is not backwards-compatible with the current version.
ID document checking and general document scanning are historically the most common means of identifying new customers and is still considered an option to national electronic identification methods. We offer automatic detection and analysis of most European identity cards, passports and driving licenses.
API Calls
Set up: POST to https://env.zignsec.com/v2/eid/scanning Result: GET from https://env.zignsec.com/v2/eid/id where env is api or test. and id is a session identifier retrieved from the setup call.
Call Order
- Step 1. Set up: Call our API entry point to set up a login workflow. The returned
redirect_urlis used for starting the browser workflow, identified byId. - Step 2. Start the login workflow in a web browser. Simply navigate to the
redirect_urlin a web browser. The workflow’s user interactions can be quite different and include external devices like the Swedish mobile BankID app. - Step 3. Get status/results: Call our API to retrieve status/error or collected user identity data for the logged in person, using the unique workflow
Idcode. Make this call during or after the workflow is completed. The workflow can signal “completed/error” via a browser redirect to thetargeturl and/or via a configured web hook.
Note: The above call order is the same for all our browser-based authentications.
Main Use Cases
- IDScan: The Scanning product’s main feature is the fully automatic detection of type of document (ie passport, driver license or id card) and from the document: nationality, holder name, identity number, authenticity level for document etc. The user workflow is capture, upload and validation of established identity documents in a large number of countries.
- General document scanning: The product can also be used to capture the looser “Proof-of-identity” documents that are often requested, for example the utility bills in the UK. In this scenario we recommend you activate the OCR parameter in the call which makes it possible to automatically detect name and address in the scanned document. Use for example our FuzzyMatch API for the comparison.
Send SMS-Link Feature
We say it is better to capture images on a mobile. And therefore recommends the option to switch over from a desktop to a mobile device via the send-SMS link feature. However, the user may stay on the desktop computer to upload stored images from the desktop computer.
Parameters
| Parameter | Description | Required |
|---|---|---|
TypeOfScan | Optional use case selector, can be set to either
| No |
VerifyIDWithSelfie | In the case of IDScan this parameter can be set to either Disabled (default), Optional or Required to automatically compare the face image on the identity card to a selfie image. The face resemblance is scored and shown in the result. | No |
IncludeOCR | Boolean value of true or false(default). If this parameter is set to true then all text on scanned document is read and included in the response. | No |
Phone | A phone number in international format including a + sign and countrycode. Setting this parameter prefills the Sms-link number. | No |
CountryCode | A country code for the issuer of the Id document, according to this ISO 3166 standard. Note that the country is automatically determined in the analysis process, this parameter is intended for determining in advance if a single-sided or double-sided scan is recommended in the respective country and type of identity document. | No |
Request example 1: Fully Automatic ID Scan
POST https://test.zignsec.com/v2/eid/scanning HTTP/1.1
Content-Length: 27
Content-Type: application/json; charset=UTF-8
Authorization: YOUR-KEY....
{
"TypeOfScan":"IDScan"
}The response – automatically identified a UK Identity card
{
"Identity": {
"CountryCode": "UK",
"FirstName": "JOHN",
"LastName": "PUBLIC",
"FullName": "JOHN PUBLIC",
"PersonalNumber": "1356130845",
"DateOfBirth": "1981-04-12",
"Age": 37,
"IdProviderName": "IDScan",
"IdentificationDate": "2018-08-08T10:24:04.6000972+02:00",
"IdProviderRequestId": "",
"IdProviderPersonId": "",
"CustomerPersonId": "",
"IdProviderAuthenticityScore": "HIGH",
"ResultReportPdf": "https://api.zignsec.com/v2//AnalysisResults/2018/8/011b18f1cea944758535519783ad7b2e.pdf"
},
"IDScan": {
"DocumentDataResult": {
"DocumentInformationResult": [
{
"Type": "Normal",
"Code": "TYPE",
"Value": "IDENTITY",
"Description": "TYPE"
},
{
"Type": "Normal",
"Code": "SIDE",
"Value": "2",
"Description": "SIDE"
},
{
"Type": "Normal",
"Code": "EXPEDITOR",
"Value": "MEX",
"Description": "EXPEDITOR"
},
{
"Type": "Normal",
"Code": "NATIONALITY",
"Value": "UK",
"Description": "NATIONALITY"
},
{
"Type": "Normal",
"Code": "NAME",
"Value": "JOHN",
"Description": "NAME"
},
{
"Type": "Normal",
"Code": "SURNAME",
"Value": "PUBLIC",
"Description": "SURNAME"
},
{
"Type": "Normal",
"Code": "ID_NUMBER",
"Value": "1356130845",
"Description": "ID_NUMBER"
},
{
"Type": "Normal",
"Code": "DOC_NUMBER",
"Value": "123456",
"Description": "DOC_NUMBER"
},
{
"Type": "Normal",
"Code": "BIRTHDATE",
"Value": "1981-04-12",
"Description": "BIRTHDATE"
},
{
"Type": "Normal",
"Code": "EXPIRY",
"Value": "2020-06-15",
"Description": "EXPIRY"
},
{
"Type": "Normal",
"Code": "SEX",
"Value": "M",
"Description": "SEX"
},
{
"Type": "Normal",
"Code": "NATIONALITY_MRZ",
"Value": "UK",
"Description": "NATIONALITY_MRZ"
},
{
"Type": "Normal",
"Code": "NAME_MRZ",
"Value": "JOHN",
"Description": "NAME_MRZ"
},
{
"Type": "Normal",
"Code": "SURNAME_MRZ",
"Value": "PUBLIC",
"Description": "SURNAME_MRZ"
},
{
"Type": "Normal",
"Code": "ID_NUMBER_MRZ",
"Value": "1356130845",
"Description": "ID_NUMBER_MRZ"
},
{
"Type": "Normal",
"Code": "DOC_NUMBER_MRZ",
"Value": "595818",
"Description": "DOC_NUMBER_MRZ"
},
{
"Type": "Normal",
"Code": "BIRTHDATE_MRZ",
"Value": "1981-04-12",
"Description": "BIRTHDATE_MRZ"
},
{
"Type": "Normal",
"Code": "EXPIRY_MRZ",
"Value": "2020-06-15",
"Description": "EXPIRY_MRZ"
},
{
"Type": "Normal",
"Code": "SEX_MRZ",
"Value": "M",
"Description": "SEX_MRZ"
},
{
"Type": "Normal",
"Code": "EXPEDITOR_VIZ",
"Value": "MEX",
"Description": "EXPEDITOR_VIZ"
},
{
"Type": "Validation",
"Code": "TEST_EXPIRY_DATE",
"Value": "OK",
"Description": "TEST_EXPIRY_DATE"
},
{
"Type": "Validation",
"Code": "TEST_COLOR_IMAGE",
"Value": "OK",
"Description": "TEST_COLOR_IMAGE"
},
{
"Type": "Normal",
"Code": "TEST_GLOBAL_AUTHENTICITY_RATIO",
"Value": "0.990000",
"Description": "TEST_GLOBAL_AUTHENTICITY_RATIO"
},
{
"Type": "Normal",
"Code": "TEST_GLOBAL_AUTHENTICITY_VALUE",
"Value": "OK",
"Description": "TEST_GLOBAL_AUTHENTICITY_VALUE"
},
{
"Type": "Normal",
"Code": "MODEL_ID",
"Value": "IDMEXA2",
"Description": "MODEL_ID"
},
{
"Type": "Normal",
"Code": "SIDES_NUMBER",
"Value": "2",
"Description": "SIDES_NUMBER"
},
{
"Type": "Normal",
"Code": "RESULT_DOCUMENT_ID",
"Value": "IDMEXA2",
"Description": "RESULT_DOCUMENT_ID"
}
],
"DocumentImageResult": {
"Image1cut": "https://api.zignsec.com/v2//AnalysisResults/2018/8/e1141d4dfac14d921aa6b7bdef6f51db.png",
"Image2cut": null,
"ImagePhoto": null,
"ImageFingerPrint": "https://api.zignsec.com/v2//AnalysisResults/2018/8/7c8555e90da84025f9f27b286df2d096.png",
"ImageSignature": "https://api.zignsec.com/v2//AnalysisResults/2018/8/467ea29c364c459684daf48dcc7dd8c4.png"
},
"DocumentImageUploaded": {
"Uploadedfile1": "https://api.zignsec.com/v2//Upload/Document/2018/8/f5772c9be83d74ed9cd31225a2195182.png",
"Uploadedfile2": "",
"Uploadedfile3": ""
}
},
"ResultValue": "Ok",
"Result": "Ok",
"WarningMessage": "",
"Messages": ""
},
"id": "35dc4012-100f-46b1-a388-16c579443212"
}; Response IDScan Details Section
Here you find a table explaining the response detail section that is unique to ID-Scanning:
| Field | Description |
|---|---|
Identity -> ResultReportPdf | This url is a result report in PDF format suitable for archiving. See this example https://api.zignsec.com/v2//AnalysisResults/2018/8/011b18f1ce………..ad7b2e.pdf. |
TYPE | Document type. Example: IDENTITY = Identity card. PASSPORT = Passport. DRIVER_LICENSE = Driver license. NONREAD_MRZ_DOCUMENT = MRZ document not properly recognized. |
SIDE | Document side. Example: 1 = front side. 2 = back side 0 = unknown. |
EXPEDITOR | A 3-letter country code according to this ISO 3166 standard. Aka as a ICAO code which refers to the document expediter country. |
NAME | Document bearer first name. |
SURNAME | Document bearer surname. If the bearer has more than one surname and they are separately written, some SURNAME fields, containing each one of the surnames, will be returned in order. If the surnames are not separately written, only one SURNAME field will be returned.. |
ID_NUMBER | Personal identification number. This number optionally appears in official documents. |
DOC_NUMBER | Document number. Only document number in the expeditor country. This number appears in all officials documents. |
BIRTHDATE | Document bearer birthday. |
EXPEDITION_DATE | Document expedition date. |
EXPIRY | Document expiration date.Date or PERMANENT. Instead of date a permanent string can be found. Then it is returned PERMANENT. |
TEST_EXPIRY_DATE | Expiry date check. Compares the system date with the expiry date of the document. Example: OK = The document is valid.. FAIL = The document has expired. UNVALIDATED = Value was read but could not be validated. |
TEST_COLOR_IMAGE | Checks if the image is a color image or not. Example: OK = Color image DOUBTFUL = No confirmation. FAIL = Not a color image. |
TEST_GLOBAL_AUTHENTICITY_RATIO | Numeric value result of the document`s global validation based on the results of tests done on the document. Example: -1 = The global test was not performed (i.e. UNVALIDATED) may be because there are no tests in the document to be done or a test could not be performed. 0-1= Percentage value of the global test performed. |
MODEL_ID | Model identifier of the identified document. |
SIDES_NUMBER | Number of sides of the document identified. |
DocumentImageResult | Links allowing you to download documents as images. Example: Image1cut = Front side of document Image2cut = back side of document ImagePhoto = cropped image only of the facial phone ImageSignature = cropped image only of the signature |
ID Authenticity
The field IdProviderAuthenticityis returning different values based on the calculated authenticity of the document. The value is calculated based on a combination of several checks carried out including checking Expiry date, Colors and fonts, MRZ Integrity if present and selfie comparison. Each company has to fine-tune their own acceptance to the level of authenticity. Our general recommendation is to approve document with IdProviderAuthenticity set to HIGH in isolation and MEDIUM and HIGH if backed with additional validation.
| IdProviderAuthenticity | Description |
HIGH | Valid document. By default, equivalent to higher values than 0.90 in the TEST_GLOBAL_ AUTHENTICITY_RATIO field. |
MEDIUM | Unable to totally ensure it is a valid document. By default, equivalent to values between 0.75 and 0. 90 in the TEST_GLOBAL_ AUTHENTICITY_RATIO field. |
LOW | Most likely invalid document. By default, equivalent to lower values than 0.75 in the TEST_GLOBAL_ AUTHENTICITY_RATIO field. |
NOT SET | Unable to perform the global test. By default, equivalent to -1 in the TEST_GLOBAL_ AUTHENTICITY_RATIO field. |
Accepted image formats (when typfeofscan=IDScan)
- Windows bitmaps – *.bmp, *.dib
- JPEG files – *.jpeg, *.jpg, *.jpe
- JPEG 2000 files – *.jp2
- Portable Network Graphics – *.png
- Portable image format – *.pbm, *.pgm, *.ppm
- Sun rasters – *.sr, *.ras
- TIFF files – *.tiff, *.tif (without compression)
- PDF files – *.pdf (one page)
Image quality recommendations (when typfeofscan=IDScan)
- The images must not be severely geometrically distorted due to the camera lens (without barrel or pincushion effects).
- The document images must be well focused. The possible causes of a lack of definition may be:
- -the camera cannot focus at short distances (it has no macro lens).
- -the movement of the object to be photographed is larger than what the exposure time allows (with poor light, a blurred image is more likely to be obtained).
- The document must not have reflections or shine, above all in the areas used for identification or OCR data reading areas. The blinding effect makes information disappear in this area, and it is therefore illegible.
- The surface of the paper must be lit uniformly. The presence of considerable shadows can alter the reading capacity by bringing structures into the image which are not part of the document to be read.
- The best results are obtained if the document is acquired in such a way that that it can be seen in its entirety but taking up a significant part of the image, and especially when the document has good contrast against the background. If the device 30 is used, sufficient background image must appear around the document.
- The minimum size of an image is 2 megapixels (at least equivalent to 200 dpi of a scanner). Bear mind that a much larger image increases the number of mobile data sent to the server and penalises the processing time.
- They must not be highly compressed. For example, in jpg images the factor must be over 90%.
They must not be photocopies of documents
Request Example 2 – OCR Document Scan
POST https://test.zignsec.com/v2/eid/scanning HTTP/1.1
Content-Length: 27
Content-Type: application/json; charset=UTF-8
Authorization: YOUR-KEY....
{typeofscan:"document", includeocr:true}In the upload workflow, for example give the below picture to scan (Response below).
The Response
{
"OcrTextPage1": "klD säkerhets /EOL/ Hämta BanklD /EOL/
Välj ditt lösenord /EOL/ Välj ett svårgissat lösenord med minst
6 tecken. /EOL/ Lösenord; /EOL/ Bekräfta Idsenord: /EOL/
Fortsatt /EOL/ ",
"OcrTextPage2": null,
"Document": {
"DocumentDataResult": {
"DocumentInformationResult": null,
"DocumentImageResult": {
"Image1cut": null,
"Image2cut": null,
"ImagePhoto": null,
"ImageFingerPrint": null,
"ImageSignature": null
},
"DocumentImageUploaded": {
"Uploadedfile1": "https://test.zignsec.com/v2//Upload/Document/2018/10/b063c4f7a6f84fe2a03ce655ce77fc0c.png",
"Uploadedfile2": "",
"Uploadedfile3": ""
}
},
"ResultValue": null,
"Result": null,
"WarningMessage": null,
"Messages": null
},
"id": "7ddc2de3-2f66-4547-9b28-623466027c0c"
}