Scanning of identity documents, like passports and driving licenses, is the most globally available alternative to national electronic identification methods.

The below API integration is suitable for integration into customized scenarios like mobile apps.

API Calls

Step1. Create session
We need to create a new session to start using scanning

POST https://env.zignsec.com/v3/eid/scanningsessions

Step 2. Add documents
Now we’re ready to add documents

POST https://env.zignsec.com/v3/eid/scanningsessions/scanningSessionId/documents?documentType={documentType}&reference={reference}

Now we have everything to start analysis

Step 3. Start analysis 

The regular flow without UI to be started as

POST https://env.zignsec.com/v3/eid/scanningsessions/scanningSessionId/analyses/

And the one with UI:

POST https://env.zignsec.com/v3/eid/scanningsessions/scanningSessionId/ui/analyses/

Step 4. Get analysis status
Now use webhook to subscribe to analysis status changes or poll status using

GET https://env.zignsec.com/v3/eid/scanningsessions/scanningSessionId/analysisStatus

Step 5. Get analysis results
And when analysis is finished we can finally get results

GET https://env.zignsec.com/v3/eid/scanningsessions/scanningSessionId/analyses/ – get all analyses results

GET https://env.zignsec.com/v3/eid/scanningsessions/scanningSessionId/analyses/analysisId
get analysis result by id

      • env is API or test.
      • scanningSessionId is the analysis session identifier retrieved from the setup call.
      • analysisId identifies a specific analysis.
      • documentType is the type of the document to upload – see below Document Type.
      • reference is the document reference.

A scanning session is the overarching unit of work. It contains a collection of documents to be analysed. A scanning session can contain several analyses. An analysis is started by supplying the scanning session with an analysis configuration object.

After starting analysis check analysis status or use webhook to get a notification when analysis is finished. When it’s done results are available 

Step 1. Create scanning session

Create Scanning Session – request

POST https://test.zignsec.com/v3/eid/scanningsessions HTTP/1.1
Content-Type: application/json
Authorization: YOUR-KEY....
or
POST https://test.zignsec.com/v3/eid/scanningsessions HTTP/1.1
Content-Type: application/json
Authorization: YOUR-KEY....
{
    "webhook": "https://webhook.site/c12432bf-1765-4abd-acf3-c85ed7c94633"
}

Request Model

relay_stateThis semi-optional parameter will be returned to you at the redirect back to your server. Use it to link an unique ID of your choice that you can parse. If not relaystate is specified, ZignSec will automatically set the ZignSec’s unique session identifier, the RequestID token here.
analysis_typesarray of analysis to perform. See Analysis types
targetf this parameter is supplied the browser session will finally be redirected to this URL-value
target_errortargetError works as target except it is navigated on user cancel or error situations
webhookA URL where success/error results will automatically be POST:ed

Create scanning session – response

Session Model

Session is a logical container for a single person authentication process

session_idscanning session id
provider_folder_idan id used on the scanning provider side
documentssession documents. See Document
{
    "session_id": "e2fa3adb-67e2-4ecc-9ac2-5de874509e4c",
    "provider_folder_id": "ad8d1ee6-814c-4b78-9ec6-89f10fafd12f",
    "documents": []
}

Step 2. Add documents

Add documents – request

POST https://test.zignsec.com/v3/eid/scanningsessions/{scanningSessionId}/documents?documentType={documentType}&reference={reference} HTTP/1.1
Authorization: YOUR-KEY....
Content-Type: multipart/form-data; boundary=12345

--12345
Content-Type: image/jpeg
Content-Disposition: form-data; name="document" filename="id_document.jpg"

...(binary bytes of the image)...
--12345--

Supported image formats

The supported binary image formats per the different Analysis types are:

selfie: jpg/jpeg, png
fraud: jpeg/jpg, pdf
document: jpg/jpeg

Note about the fraud detection: 98% of digital cameras natively take photos in JPG format – by analyzing those natively we can get information about photo’s authenticity by analyzing traces about compression and noise characteristics of the camera. PDF will only be fraud-analyzed if the source for the PDF was a JPG image. 

Parameters in the URL

scanningSessionIdSession id
documentTypeThe type of the document to upload – see below Document Type
referenceThe document reference

Document Type

The type of the document to upload. Only image/jpeg supported so far

PassportPassport – the page with face photo required
IdentityCardID card – 2 sides required
DriversLicenseDriver license – the side with photo required
SelfieSelfie (a biometric image)
OtherDocumentOther document – the page without photo required

Add documents – response

{
    "session_id": "e2fa3adb-67e2-4ecc-9ac2-5de874509e4c",
    "provider_folder_id": "ad8d1ee6-814c-4b78-9ec6-89f10fafd12f",
    "documents": [        {
            "id": 16266,
            "file_name": "Ukrainian_passport_for_travel_abroad.jpg",
            "image_url": "https://zignsecfilestorage.blob.core.windows.net/images-test/e2293adb-67e2-4ecc-9ac2-5de87de09e4c/Ukrainian_passport_for_travel_abroad.jpg?sv=2019-02-02&sr=b&sig=sBH71gEMEOidqZr2G6mVB7I8lrZv3we2ypEZJB23xvQ%3D&st=2020-02-11T12%3A43%3A19Z&se=2020-04-11T12%3A43%3A19Z&sp=r"
        }]
}

Step 3. Start analysis

Start analysis – request

POST https://test.zignsec.com/v3/eid/scanningsessions/{scanningSessionId}/analyses?timeZoneOffset={timeZoneOffset} HTTP/1.1
Authorization: YOUR-KEY....

{
  "analysis_types": ["document", "fraud"]
}

Parameters in the URL

scanningSessionIdSession id
timeZoneOffsetClient time zone offset in minutes

Request Model

analysis_typesarray of analysis to perform. See Analysis types

Analysis types

documentAnalyses and verifies the content of the uploaded image of the id-card, passport or driver’s license
fraudAnalyses the uploaded document/image to check if it has been manipulated with image processing software
selfieAutomatically finds analyses and evaluates the bio-metric resemblance of faces represented in uploaded images
expertThis analysis type should be considered additional and it is recommended as an separate request to be run by a compliance officer to get more information about the uploaded document/image.

Start analysis – response

See Analysis Result

Analysis Result Model

Represents a single analysis result

analysis_idan analisys identifier
started_atanalysis start time
finished_atanalysis finish time
total_process_statesession state (see State)
document_analysis_resultdocument analysis result
document_analysis_failed_fieldsfailed fields from the document analysis if any
fraud_analysis_resultfraud analysis result (see Result)
fraud_analysis_risk_scorefraud analysis risk score (see Risk Score)
expert_analysis_result 
identityIdentity filled from the given document , contains local values (see Identity)
identity_englishEnglish version of the identity (see Identity)
document_analysis_detailsdocument analysis details
fraud_analysis_detailsfraud analysis details
expert_analysis_detailsexpert analysis details
selfie_analysis_resultsselfie analysis results
analysed_documentsanalysed documents (see Document)
 
{
    "analysis_id": 12345,
    "started_at": "2020-02-11T16:17:01.9589222Z",
    "finished_at": null,
    "total_process_state": "Processing",
    "document_analysis_state": "Processing",
    "document_analysis_result": "ANALYSING",
    "document_analysis_failed_fields": "",
    "fraud_analysis_state": "Processing",
    "fraud_analysis_result": "ANALYSING",
    "fraud_analysis_risk_score": "Undefined",
    "selfie_min_confidence": null,
    "selfie_max_confidence": null,
    "expert_analysis_state": "NotRequested",
    "expert_analysis_result": "NOT_REQUESTED",
    "selfie_analysis_process_state": "Processing",
    "selfie_analysis_result": "ANALYSING",
    "document_analysis_details": {
        "process_status": "Processing",
        "document_type": null,
        "found_document_types": [],
        "found_text_fields": [],
        "found_image_parts": null
    },
    "fraud_analysis_details": {
        "process_status": "Processing",
        "analysed_images": [],
        "risk_score": "Undefined"
    },
    "expert_analysis_details": {
        "process_state": "NotRequested",
        "filter_results": []
    },
    "selfie_analysis_details": {
        "process_state": "Processing",
        "resolution_status": null,
        "resolution": "NONE",
        "min_confidence": null,
        "max_confidence": null,
        "resolution_message": "",
        "found_images": []
    },
    "analysed_documents": [
        {
            "id": 16266,
            "file_name": "Ukrainian_passport_for_travel_abroad.jpg",
            "image_url": "https://zignsecfilestorage.blob.core.windows.net/images-test/e2293adb-67e2-4ecc-9ac2-5de87de09e4c/Ukrainian_passport_for_travel_abroad.jpg?sv=2019-02-02&sr=b&sig=sBH71gEMEOidqZr2G6mVB7I8lrZv3we2ypEZJB23xvQ%3D&st=2020-02-11T12%3A43%3A19Z&se=2020-04-11T12%3A43%3A19Z&sp=r"
        },
        {
            "id": 16269,
            "file_name": "photo_2019-12-19_14-21-28.jpg",
            "image_url": "https://zignsecfilestorage.blob.core.windows.net/images-test/e2293adb-67e2-4e8c-9ac2-5de8ed509e4c/photo_2019-12-19_14-21-28.jpg?sv=2019-02-02&sr=b&sig=L6ao390C6g7C2fEJbwDDLxO8IgrKdCvdg0CTWwxmP5Y%3D&st=2020-02-11T12%3A43%3A19Z&se=2020-04-11T12%3A43%3A19Z&sp=r"
        }
    ]
}

Start analysis with ui – request

POST https://test.zignsec.com/v3/eid/scanningsessions/{scanningSessionId}/ui/analyses?timeZoneOffset={timeZoneOffset} HTTP/1.1
Authorization: YOUR-KEY....

{
  "analysis_types": ["liveness", "document", "fraud"]
}

Start analysis with ui – response

{
    "id": "231a7aa4-f6d3-468b-9aab-7ec4c6ee3a8c",
    "errors": [],
    "redirect_url": "https://test.zignsec.com/v3/eid/scanningsessions/scan/231a7aa4-f6d3-468b-9aab-7ec4c6ee3a8c"
}
idThe session identifier, a GUID (globally unique identifier) unique for the started workflow, used both in the redirect_url and the get analysis results.
errorsA JSON object that contains information on error conditions that might have resulted from the request, in an array of property-value pairs. If multiple errors occur, a pair of parameters is returned for each error. code Code for the error. List of codes is in table below. description A string that describes the type of error that occurred. If no errors occur, then this object is empty. errors : []
redirect_urlThe URL that the user need to be redirected to complete the data via the web interface

Step 4. Get analysis status

Get analysis status – request

 
GET https://test.zignsec.com/v3/eid/scanningsessions/{scanningSessionId}/analysisStatus HTTP/1.1
Authorization: YOUR-KEY....

Get analysis status – response (analysis is in progress)

Analysis Status Model

Represents the status of the current analysis in-progress

session_ida session identifier
total_process_statea state of the current operation. See State
session_parameterssession parameters. See Session Parameters
{
  "session_id": "e2fa3adb-67e2-4ecc-9ac2-5de874509e4c",
  "total_process_state": "Processing",
  "session_parameters": {
    "relay_state": null,
    "session_type": 0,
    "webhook": null
  }
}

Get analysis status – response (analysis is completed)

Analysis Summary Model

Represents a finished analysis summary
session_ida session identifier
total_process_statea state of the current operation. See State
session_parameterssession parameters. See Session Parameters
resultan overall analysis result. See Result
result_titleresult string representation
result_reasonresult reason string
analysis_duration_secanalysis duration in seconds
id_document_summarySee Id Document Summary
selfie_summarySee Selfie Summary
fraud_analysis_summarySee Fraud Summary
expert_analysis_summarySee Expert Summary
{
  "result": "DECLINED",
  "result_title": "Declined",
  "result_reason": "Id document was DECLINED. Selfie was DECLINED. Fraud was DECLINED",
  "analysis_duration_sec": 71.7,
  "id_document_summary": {
    "result": "DECLINED",
    "error": null,
    "document_type_name": "Ukraine - Passport (2007)",
    "first_name": "ІВАН",
    "last_name": "ГРИЦЕНКО",
    "full_name": "ІВАН ГРИЦЕНКО",
    "first_name_english": null,
    "last_name_english": null,
    "full_name_english": null,
    "age": 36,
    "expiration_date": "2019-08-03T00:00:00",
    "issuer_state": "Ukraine",
    "result_title": "Declined",
    "result_reason": "FinalCheckDigit,Document_Number_CheckDigit,Date_of_Expiry,RemainderTerm,Document_Number",
    "fields": {
      
    }
  },
  "selfie_summary": {
    "result": "DECLINED",
    "error": null,
    "min_confidence": 0.0000,
    "max_confidence": 0.0000,
    "result_reason": "Percent of similarity 0.00%",
    "result_title": "Declined"
  },
  "fraud_summary": {
    "result": "DECLINED",
    "error": "The image is probably not original.The image was probably compressed.Information about image height and width differs from information in metadata: 569x407, 592x433.Some important metadata values are corrupted or not exist.Probably the image was resaved with one of such editors: adobe photoshop elements 8.0 macintosh.The image was edited with one of Adobe applications (Photoshop, Lightroom, etc...).Information about image editors was found in metadata: photoshop, adobe, elements, macintosh, microsoft, picasa, shop, win, windows,  windows.Fields which couldn't be found in metadata: Brand, Model.This editor was found in metadata: adobe photoshop elements 8.0 macintosh.",
    "risk_score": "HighRisk",
    "result_reason": "High Risk",
    "result_title": "Declined"
  },
  "session_id": "e2fa3adb-67e2-4ecc-9ac2-5de874509e4c",
  "total_process_state": "Finished",
  "session_parameters": {
    "relay_state": null,
    "session_type": 0,
    "webhook": null
  }
}

Step 5. Get analysis results

Get all analysis results – request

GET https://test.zignsec.com/v3/eid/scanningsessions/{scanningSessionId}/analyses HTTP/1.1
Authorization: YOUR-KEY....

Get analysis result by id – request

 
GET https://test.zignsec.com/v3/eid/scanningsessions/{scanningSessionId}/analyses/{analysisId} HTTP/1.1
Authorization: YOUR-KEY....

Get analysis results – response

See Scanning Session Analysis

Scanning Session with Analysis Results Model

Represents a scanning session with analysis results

total_resultan overall analysis result. See Result
session_ida session identifier
start_datesession start date
finish_datesession finish date
provider_folder_idan id used on the scanning provider side
request_parameterssession parameters. See Session Parameters
synopsis_human_readablea human readable synopsis
identityidentity (local values)
identity_englishidentity (English values)
analysis_summarysee Analysis Summary
analysis_detailssee Analysis Details
documentsanalyzed documents
errorerror string
{
    "total_result": "DECLINED",
    "session_id": "aa20ac2a-3706-4046-bb4b-efd1c2894b21",
    "start_date": "2020-02-07T15:27:50.5960485",
    "finish_date": "2020-02-07T15:28:32.7410571",
    "provider_folder_id": "e96e206a-1294-4f8b-af06-1f3b7fe54e1d",
    "request_parameters": {
        "relay_state": null,
        "session_type": 0,
        "webhook": null
    },
    "synopsis_human_readable": {
        "total_result": "DECLINED [Id document DECLINED] [Selfie DECLINED] [Fraud DECLINED]",
        "id_document_result": "DECLINED [ІВАН ГРИЦЕНКО (IVAN GRYTSENKO); Ukraine - Passport (2007); Age 36; INVALID FIELDS (Document_Number,RemainderTerm,Date_of_Expiry,Document_Number_CheckDigit,FinalCheckDigit)]",
        "selfie_result": "DECLINED [3.15% match]",
        "fraud_result": "DECLINED [High risk detected; The image is probably not original.The image was probably compressed.Information about image height and width differs from information in metadata: 569x407, 592x433.Some important metad...",
        "expert_result": "NOT_REQUESTED",
        "doc_issuer_state": "Ukraine",
        "doc_expiration": "2019-08-03 (EXPIRED)",
        "doc_full_name": "ІВАН ГРИЦЕНКО (IVAN GRYTSENKO)",
        "doc_date_of_birth": "1983-07-25 (Age: 36)",
        "session_started": "2020-02-07 15:27:50 (duration 42.1 s)"
    },
    "identity": {
        "country_code": "ua",
        "first_name": "ІВАН",
        "last_name": "ГРИЦЕНКО",
        "full_name": "ІВАН ГРИЦЕНКО",
        "personal_number": "3052125257",
        "date_of_birth": "1983-07-25",
        "age": 36,
        "gender": "",
        "phone": null,
        "email": null,
        "address_info_raw": null,
        "result_report_pdf": null,
        "id_provider_name": "Scanning",
        "identification_date": "2020-02-07T15:46:16.7857278Z",
        "id_provider_request_id": "27ae2df1-efbb-4da2-aa4d-24c2d6a82879",
        "id_provider_person_id": null,
        "customer_person_id": null,
        "id_provider_authenticity_score": 0
    },
    "identity_english": {
        "country_code": "ua",
        "first_name": "IVAN",
        "last_name": "GRYTSENKO",
        "full_name": "IVAN GRYTSENKO",
        "personal_number": "3052125257",
        "date_of_birth": "1983-07-25",
        "age": 36,
        "gender": "",
        "phone": null,
        "email": null,
        "address_info_raw": null,
        "result_report_pdf": null,
        "id_provider_name": "Scanning",
        "identification_date": "2020-02-07T15:46:16.7864503Z",
        "id_provider_request_id": "27ae2df1-efbb-4da2-aa4d-24c2d6a82879",
        "id_provider_person_id": null,
        "customer_person_id": null,
        "id_provider_authenticity_score": 0
    },
    "analysis_summary": {
        "result": "DECLINED",
        "result_title": "Declined",
        "result_reason": "Id document DECLINED. Selfie DECLINED. Fraud DECLINED",
        "analysis_duration_sec": 42.1,
        "id_document_summary": {
            "result": "DECLINED",
            "error": null,
            "document_type_name": "Ukraine - Passport (2007)",
            "first_name": "ІВАН",
            "last_name": "ГРИЦЕНКО",
            "full_name": "ІВАН ГРИЦЕНКО",
            "first_name_english": "IVAN",
            "last_name_english": "GRYTSENKO",
            "full_name_english": "IVAN GRYTSENKO",
            "age": 36,
            "expiration_date": "2019-08-03T00:00:00",
            "issuer_state": "Ukraine",
            "result_title": "Declined",
            "result_reason": "Document_Number,RemainderTerm,Date_of_Expiry,Document_Number_CheckDigit,FinalCheckDigit",
            "fields": {
                "Given_Names_local": "ІВАН",
                "Surname_local": "ГРИЦЕНКО",
                "Surname_And_Given_Names_local": "ГРИЦЕНКО ІВАН",
                "Given_Names": "IVAN",
                "Surname": "GRYTSENKO",
                "Surname_And_Given_Names": "GRYTSENKO IVAN",
                "Issuing_State_Name": "Ukraine",
                "Issuing_State_Code": "UKR",
                "Age": "36",
                "Document_Number": "EK000001",
                "Authority": "8090",
                "RemainderTerm": "0",
                "Date_of_Birth": "7/25/1983",
                "Date_of_Expiry": "8/3/2019",
                "Date_of_Issue": "8/3/2009",
                "Document_Class_Code": "P",
                "MRZ_Strings_MRZ": "PUKRGRYTSENKOIVA EK0000017UKR8307255M1908033305212525700",
                "MRZ_Strings_With_Correct_CheckSums_MRZ": "PUKRGRYTSENKOIVAN EK0000011UKR8307255M1908033305212525704",
                "Nationality_Code_MRZ": "UKR",
                "Nationality_MRZ": "Ukraine",
                "Optional_Data_MRZ": "3052125257",
                "Personal_Number": "3052125257",
                "Place_of_Birth": "UKR",
                "Place_of_Birth_local": "М.МИКОЛАЇВ",
                "Sex": "M",
                "Sex_local": "Ч"
            }
        },
        "selfie_summary": {
            "result": "DECLINED",
            "error": null,
            "min_confidence": 0.0315,
            "max_confidence": 0.0315,
            "result_reason": "Percent of similarity 3.15%",
            "result_title": "Declined"
        },
        "fraud_summary": {
            "result": "DECLINED",
            "error": "The image is probably not original.The image was probably compressed.Information about image height and width differs from information in metadata: 569x407, 592x433.Some important metadata values are corrupted or not exist.Probably the image was resaved with one of such editors: adobe photoshop elements 8.0 macintosh.The image was edited with one of Adobe applications (Photoshop, Lightroom, etc...).Information about image editors was found in metadata: photoshop, adobe, elements, macintosh, microsoft, picasa, shop, win, windows,  windows.Fields which couldn't be found in metadata: Brand, Model.This editor was found in metadata: adobe photoshop elements 8.0 macintosh.",
           "all_errors": [
                "The image is probably not original.The image was probably compressed.Information about image height and width differs from information in metadata: 569x407, 592x433.Some important metadata values are corrupted or not exist.Probably the image was resaved with one of such editors: adobe photoshop elements 8.0 macintosh.The image was edited with one of Adobe applications (Photoshop, Lightroom, etc...).Information about image editors was found in metadata: photoshop, adobe, elements, macintosh, microsoft, picasa, shop, win, windows,  windows.Fields which couldn't be found in metadata: Brand, Model.This editor was found in metadata: adobe photoshop elements 8.0 macintosh."
            ],
            "risk_score": "HighRisk",
            "result_reason": "High Risk",
            "result_title": "Declined"
        },
        "session_id": "aa20ac2a-3706-4046-bb4b-efd1c2894b21",
        "total_process_state": "Finished",
        "session_parameters": {
            "relay_state": null,
            "session_type": 0,
            "webhook": null
        }
    },
    "analysis_details": [
        {
            "analysis_id": 14598,
            "started_at": "2020-02-07T15:27:51.1848417",
            "finished_at": "2020-02-07T15:28:32.7396683",
            "total_process_state": "Finished",
            "document_analysis_state": "Finished",
            "document_analysis_result": "DECLINED",
            "document_analysis_failed_fields": "FinalCheckDigit, Document_Number_CheckDigit, Date_of_Expiry, RemainderTerm, Document_Number",
            "fraud_analysis_state": "Finished",
            "fraud_analysis_result": "DECLINED",
            "fraud_analysis_risk_score": "HighRisk",
            "selfie_min_confidence": 0.0315,
            "selfie_max_confidence": 0.0315,
            "expert_analysis_state": "NotRequested",
            "expert_analysis_result": "NOT_REQUESTED",
            "selfie_analysis_process_state": "Finished",
            "selfie_analysis_result": "DECLINED",
            "document_analysis_details": {
                "process_status": "Finished",
                "document_type": "Ukraine - Passport (2007)",
                "found_document_types": [
                    {
                        "file_name": "self_0IMG-9af97cd1cdd8448e45f37fd437da8650-V.jpg",
                        "document_type": "Ukraine - Passport (2007)"
                    }
                ],
                "found_text_fields": [
                    {
                        "field_name": "Given_Names_local",
                        "mrz": null,
                        "visual": "ІВАН",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 0,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Surname_local",
                        "mrz": null,
                        "visual": "ГРИЦЕНКО",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 0,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Surname_And_Given_Names_local",
                        "mrz": null,
                        "visual": "ГРИЦЕНКО ІВАН",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 0,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Given_Names",
                        "mrz": "IVAN",
                        "visual": "IVAN",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 0,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Surname",
                        "mrz": "GRYTSENKO",
                        "visual": "GRYTSENKO",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 0,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Surname_And_Given_Names",
                        "mrz": "GRYTSENKO IVAN",
                        "visual": "GRYTSENKO IVAN",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 0,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Issuing_State_Name",
                        "mrz": "Ukraine",
                        "visual": "Ukraine",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 1,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Issuing_State_Code",
                        "mrz": "UKR",
                        "visual": "UKR",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 1,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Age",
                        "mrz": "36",
                        "visual": "36",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 1,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Document_Number",
                        "mrz": "EK000001",
                        "visual": "EK000001",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 2,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Authority",
                        "mrz": null,
                        "visual": "8090",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 0,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "RemainderTerm",
                        "mrz": "0",
                        "visual": "0",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 2,
                            "Visual": 2,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Date_of_Birth",
                        "mrz": "7/25/1983",
                        "visual": "7/25/1983",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 1,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Date_of_Birth_CheckDigit",
                        "mrz": "5",
                        "visual": null,
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 1,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Date_of_Expiry",
                        "mrz": "8/3/2019",
                        "visual": "8/3/2019",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 2,
                            "Visual": 2,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Date_of_Expiry_CheckDigit",
                        "mrz": "3",
                        "visual": null,
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 1,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Date_of_Issue",
                        "mrz": null,
                        "visual": "8/3/2009",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 0,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Document_Class_Code",
                        "mrz": "P",
                        "visual": "P",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 1,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Document_Number_CheckDigit",
                        "mrz": "7",
                        "visual": null,
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 2,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "FinalCheckDigit",
                        "mrz": "0",
                        "visual": null,
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 2,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                  {
                    "field_name": "MRZ_Strings",
                    "mrz": "PUKRGRYTSENKOIVAN EK0000011UKR8307255M190803330521252570400",
                    "visual": null,
                    "barcode": null,
                    "verification_scores": {
                      "Mrz": 0,
                      "Visual": 0,
                      "Barcode": 0,
                      "MrzVisual": 0,
                      "MrzBarcode": 0,
                      "VisualBarcode": 0
                    }
                  },
                    {
                        "field_name": "MRZ_Strings_With_Correct_CheckSums",
                        "mrz": "PUKRGRYTSENKOIVAN EK0000011UKR8307255M1908033305212525704",
                        "visual": null,
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 1,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Nationality",
                        "mrz": "Ukraine",
                        "visual": null,
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 1,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Nationality_Code",
                        "mrz": "UKR",
                        "visual": null,
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 1,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Optional_Data",
                        "mrz": "3052125257",
                        "visual": null,
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 1,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Optional_Data_CheckDigit",
                        "mrz": "0",
                        "visual": null,
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 1,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Personal_Number",
                        "mrz": "3052125257",
                        "visual": "3052125257",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 0,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Place_of_Birth",
                        "mrz": null,
                        "visual": "UKR",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 0,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Place_of_Birth_local",
                        "mrz": null,
                        "visual": "М.МИКОЛАЇВ",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 0,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Sex",
                        "mrz": "M",
                        "visual": "M",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 1,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    },
                    {
                        "field_name": "Sex_local",
                        "mrz": null,
                        "visual": "Ч",
                        "barcode": null,
                        "verification_scores": {
                            "Mrz": 0,
                            "Visual": 0,
                            "Barcode": 0,
                            "MrzVisual": 0,
                            "MrzBarcode": 0,
                            "VisualBarcode": 0
                        }
                    }
                ],
                "found_image_parts": [
                    {
                        "type": 204,
                        "name": "Signature",
                        "image_url": "https://zignsecfilestorage.blob.core.windows.net/images-test/aa20ac2a-3706-4046-bb4b-efd1c2894b21/0734440d-6f7c-424f-9836-9841d29d8d16?sv=2019-02-02&sr=b&sig=rMYRcZnPV0uDy7ion4QwWJQ8l5pIj4JZ3pL5W8sZlmE%3D&st=2020-02-07T15%3A24%3A33Z&se=2020-04-07T15%3A24%3A33Z&sp=r"
                    },
                    {
                        "type": 201,
                        "name": "Portrait",
                        "image_url": "https://zignsecfilestorage.blob.core.windows.net/images-test/aa20ac2a-3706-4046-bb4b-efd1c2894b21/8891ce0f-cc0c-4d33-b27a-30afd223ac8b?sv=2019-02-02&sr=b&sig=6pxihX7F06cquxMot6d8naTlp3FMkb%2Fe41pP0Wxd%2BjM%3D&st=2020-02-07T15%3A24%3A33Z&se=2020-04-07T15%3A24%3A33Z&sp=r"
                    }
                ]
            },
            "fraud_analysis_details": {
                "process_status": "Finished",
                "analysed_images": [
                    {
                        "file_name": "self_0IMG-9af97cd1cdd8448e45f37fd437da8650-V.jpg",
                        "original_image_url": null,
                        "result_short_description": "Critical risks",
                        "result_long_description": "The image was compressed lots of times. The analyse of the image may be incorrect. The minimal threshold is 500 kb and 640x480 pixels.The image is probably not original.Information about image height and width differs from information in metadata: 270x262, 1200x1600.Probably the image was resaved with one of such editors: paint.net 4.2.5.",
                        "risk_score": "HighRisk",
                        "metadata": {
                            "maker": "",
                            "model": "",
                            "width": "270",
                            "height": "262",
                            "quality": "-2",
                            "software": "paint.net 4.2.5",
                            "width_exif": "1200",
                            "height_exif": "1600",
                            "exif_software_modified": "",
                            "datetime_create_exif_text": "",
                            "exif_gpsinfo_gpstimestamp": "",
                            "exif_image_timezoneoffset": "",
                            "exif_image_previewdatetime": "",
                            "datetime_digitize_exif_text": "",
                            "exif_image_datetimeoriginal": ""
                        }
                    },
                    {
                        "file_name": "0Ukrainian_passport_for_travel_abroad.jpg",
                        "original_image_url": null,
                        "result_short_description": "Critical risks",
                        "result_long_description": "The image is probably not original.The image was probably compressed.Information about image height and width differs from information in metadata: 569x407, 592x433.Some important metadata values are corrupted or not exist.Probably the image was resaved with one of such editors: adobe photoshop elements 8.0 macintosh.The image was edited with one of Adobe applications (Photoshop, Lightroom, etc...).Information about image editors was found in metadata: photoshop, adobe, elements, macintosh, microsoft, picasa, shop, win, windows,  windows.Fields which couldn't be found in metadata: Brand, Model.This editor was found in metadata: adobe photoshop elements 8.0 macintosh.",
                        "risk_score": "HighRisk",
                        "metadata": {
                            "maker": "",
                            "model": "",
                            "width": "569",
                            "height": "407",
                            "quality": "98",
                            "software": "adobe photoshop elements 8.0 macintosh",
                            "width_exif": "569",
                            "height_exif": "407",
                            "exif_software_modified": "",
                            "datetime_create_exif_text": "2012:03:28 03:49:12",
                            "exif_gpsinfo_gpstimestamp": "",
                            "exif_image_timezoneoffset": "",
                            "exif_image_previewdatetime": "",
                            "datetime_digitize_exif_text": "2012:03:28 03:49:12",
                            "exif_image_datetimeoriginal": ""
                        }
                    }
                ],
                "risk_score": "HighRisk"
            },
            "expert_analysis_details": {
                "process_state": "NotRequested",
                "filter_results": []
            },
            "selfie_analysis_details": {
                "process_state": "Finished",
                "resolution_status": "DECLINED",
                "resolution": "DECLINED",
                "min_confidence": 0.0315,
                "max_confidence": 0.0315,
                "resolution_message": "Percent of similarity 3.15%",
                "found_images": [
                    {
                        "source_file_name": "self_0IMG-9af97cd1cdd8448e45f37fd437da8650-V.jpg",
                        "source_image_url": "https://zignsecfilestorage.blob.core.windows.net/images-test/aa20ac2a-3706-4046-bb4b-efd1c2894b21/9e8fb983-7a3d-4964-af03-de30dbb79c31?sv=2019-02-02&sr=b&sig=S38lB9lbx7El%2FdjB%2FMjB2TEibck25WA0oFykLayfkFw%3D&st=2020-02-07T15%3A24%3A33Z&se=2020-04-07T15%3A24%3A33Z&sp=r",
                        "result_file_name": "PIL.JpegImagePlugin.JpegImageFile image mode=RGB size=112x112 at 0x7FC30558F978>",
                        "result_image_url": "https://zignsecfilestorage.blob.core.windows.net/images-test/aa20ac2a-3706-4046-bb4b-efd1c2894b21/b482e4be-170d-4c4b-a5e9-ef6df4865f15?sv=2019-02-02&sr=b&sig=pMRKwWY1d3I5w6SnhNJtIHmM5JDoTVLAKvMHteHi%2FVw%3D&st=2020-02-07T15%3A24%3A33Z&se=2020-04-07T15%3A24%3A33Z&sp=r"
                    },
                    {
                        "source_file_name": "0Ukrainian_passport_for_travel_abroad.jpg",
                        "source_image_url": "https://zignsecfilestorage.blob.core.windows.net/images-test/aa20ac2a-3706-4046-bb4b-efd1c2894b21/610098fb-39f3-4bef-b7fc-b8754d438270?sv=2019-02-02&sr=b&sig=v%2FV1draGTAxslkjqld3QaqBkzX98zocLgu3yga5GceA%3D&st=2020-02-07T15%3A24%3A33Z&se=2020-04-07T15%3A24%3A33Z&sp=r",
                        "result_file_name": "PIL.JpegImagePlugin.JpegImageFile image mode=RGB size=112x112 at 0x7FC30558F978>",
                        "result_image_url": "https://zignsecfilestorage.blob.core.windows.net/images-test/aa20ac2a-3706-4046-bb4b-efd1c2894b21/48a9676b-a054-4da4-b957-3a3fde37b60a?sv=2019-02-02&sr=b&sig=BCQ2gVphC4QkJgircjlTNH3PkCg0rdiCiQscWbfBvfU%3D&st=2020-02-07T15%3A24%3A33Z&se=2020-04-07T15%3A24%3A33Z&sp=r"
                    }
                ]
            },
            "analysed_documents": [
                {
                    "id": 16228,
                    "file_name": "0Ukrainian_passport_for_travel_abroad.jpg",
                    "image_url": "https://zignsecfilestorage.blob.core.windows.net/images-test/aa20ac2a-3706-4046-bb4b-efd1c2894b21/0Ukrainian_passport_for_travel_abroad.jpg?sv=2019-02-02&sr=b&sig=kMXqnJsROqaF55DAQffr%2BS1R88lpxUt%2FbE0zh4kAINg%3D&st=2020-02-07T15%3A24%3A33Z&se=2020-04-07T15%3A24%3A33Z&sp=r"
                },
                {
                    "id": 16229,
                    "file_name": "self_0IMG-9af97cd1cdd8448e45f37fd437da8650-V.jpg",
                    "image_url": "https://zignsecfilestorage.blob.core.windows.net/images-test/aa20ac2a-3706-4046-bb4b-efd1c2894b21/self_0IMG-9af97cd1cdd8448e45f37fd437da8650-V.jpg?sv=2019-02-02&sr=b&sig=5bL07K3n2RkNg9YLGhuAEzjK4RGEFAhqiG7JwoQznh0%3D&st=2020-02-07T15%3A24%3A33Z&se=2020-04-07T15%3A24%3A33Z&sp=r"
                }
            ]
        }
    ],
    "documents": [
        {
            "id": 16228,
            "file_name": "0Ukrainian_passport_for_travel_abroad.jpg",
            "image_url": "https://zignsecfilestorage.blob.core.windows.net/images-test/aa20ac2a-3706-4046-bb4b-efd1c2894b21/0Ukrainian_passport_for_travel_abroad.jpg?sv=2019-02-02&sr=b&sig=kMXqnJsROqaF55DAQffr%2BS1R88lpxUt%2FbE0zh4kAINg%3D&st=2020-02-07T15%3A24%3A33Z&se=2020-04-07T15%3A24%3A33Z&sp=r"
        },
        {
            "id": 16229,
            "file_name": "self_0IMG-9af97cd1cdd8448e45f37fd437da8650-V.jpg",
            "image_url": "https://zignsecfilestorage.blob.core.windows.net/images-test/aa20ac2a-3706-4046-bb4b-efd1c2894b21/self_0IMG-9af97cd1cdd8448e45f37fd437da8650-V.jpg?sv=2019-02-02&sr=b&sig=5bL07K3n2RkNg9YLGhuAEzjK4RGEFAhqiG7JwoQznh0%3D&st=2020-02-07T15%3A24%3A33Z&se=2020-04-07T15%3A24%3A33Z&sp=r"
        }
    ]}

To get all analyses for session use the followin request (a response will be similar to the previous one)

GET https://test.zignsec.com/v3/eid/scanningsessions/{scanningSessionId}/analyses HTTP/1.1
Authorization: YOUR-KEY....

API Models

Responses

 

Document Model

Represents a single document (uploaded for scanning)

iddocument id
file_namedocument file name
image_urldocument url

Id Document Summary Model

Represents an id document analysis summary

resultan overall analysis result. See Result
result_titleresult string representation
result_reasonreason behind the result (usually – for DECLINED sessions)
errorall errors as a text 
document_type_namea document type name of the first found document
first_namefirst name (local value) 
last_namelast name (local value) 
full_namefull name (local value) 
first_name_englishfirst name (English) 
last_name_englishlast name (English) 
full_name_englishfull name (English) 
ageage 
expiration_datedocument expiration date 
issuer_statedocument issuer state 
fieldsfound fields formatted as a JSON object

Selfie Summary Model

Represents a selfie analysis summary

resultan overall analysis result. See Result
result_titleresult string representation
result_reasonreason behind the result (usually – for DECLINED sessions)
errorall errors as a text
min_confidencemin confidence in the selfie match
max_confidencemax confidence in the selfie match

 

Fraud Summary Model

Represents a fraud analysis summary

resultan overall analysis result. See Result
result_titleresult string representation
result_reasonreason behind the result (usually – for DECLINED sessions)
errorthe first error reported from images fraud analysis
all_errorsall errors from fraud analysis (see details to get errors for each particular image)
risk_scorefraud risk score. See Risk

Session Parameters Model

Represents a session parameters

relay_statestate sent from the client persisted in session. Is sent back to redirect urls and webhooks as is
session_typesession type Api | BrowserFlow | WebSdk
webhookwebhook url
targetto be used by the Browser Flow to redirect user when analysis is finished
target_errorto be used by Browser Flow to redirect user when analysis is FAILED
analysis_typesan array of the Document | Selfie | Fraud | Expert 

 

Identity Model

Session is a logical container for a single person authentication process

country_codecountry code
first_namefirst name
last_namelast name
full_namefull name
personal_numberpersonal number
date_of_birthdate of birth
ageage
expirationdocument expiration date if any
expiredtrue when document expired, false if expiration date is recognized and document is not expired, null when expiration date is not recognized (or document analysis was skipped)
issuer_statethe name of the state that issued a document
genderM‘ for male, ‘F‘ – female, null – not recognized
id_provider_nameid provider name (‘Scanning‘)
identification_dateidentification date (UTC)
id_provider_request_idinternal id for the scanning provider

 

Analysis results details

FieldDescription
total_process_stateThe total process state for all analyses. Indicated whether the analyses are finished or not.
document_analysis_state
The state for the document analysis.
document_analysis_result
The result for the document analysis.
document_analysis_failed_fields
Failed fields in csv format.
fraud_analysis_state
The state for the fraud analysis.
fraud_analysis_result
The result for the fraud analysis.
fraud_analysis_risk_score
The fraud risk score. Risk score range is: no risk, low risk, medium risk, high risk
expert_analysis_state
The state for the expert analysis.
expert_analysis_result
The result for the expert analysis.
identity
If the id document analysis was performed, this is an object containing the properties pertaining to the identified person.
document_analysis_details
Contains a collection of scanned document fields. Each text field contains the field value and optional verification scores.
fraud_analysis_details
A collection of fraud analysis results. Each result object contains a risk score and additional comments.
expert_analysis_details
Contains links to images of the different expert analysis filters.
analysed_documents
The documents that were analysed in this analysis. See Document

Enums

 

State enum

Represents a state of the current analysis in-progress

NotRequestedanalysis not requested
Processinganalysis is in progress
Finishedanalysis finished, check result
Failedan internal error occured during analysis

Result enum

Represents a single analysis result

NOT_REQUESTEDanalysis not requested
ANALYSINGanalysis is in progress
FAILEDinternal error occured during analysis
ACCEPTEDanalysis finished, documents have been ACCEPTED
OPERATOR_REQUIREDanalysis finished, OPERATOR REQUIRED to make a final decision
DECLINEDanaysis finished, documents have been DECLINED
TIMEOUTtime out waiting for the response from the scanning provider. there is still a chance that session could be completed manually (from the admin UI)

Risk score enum

Represents risk score in fraud analysis
Undefinedrisk is not calculated
NoRiskno risk
LowRisklow risk
MediumRiskmedium risk
HighRiskhigh risk