v3 – API flow

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

locale

Preferred Language to use, we support multiple languages like : en , se ,de , fr, gr, it ,ru ,es , cz,tr.

We can add more languages as per your business requirements

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
flowUsed to customize your flowselfie_heading: string

steps:

  • type: string, enum [SelectDocTypePage, UploadPage]
  • heading: string
  • ref: string
locale: string
default_country_code: string
docignore_errors_in_fieldsstring,
exple:
[“Surname”,”Surname_And_Given_Names”,”Given_Names”,”Surname_And_Given_Names_local”,”Surname_local”,”Date_of_Birth”]
verification_types
(getting all per default)		string, Enum [ Mrz, Visual, Barcode, MrzVisual, MrzBarcode, VisualBarcode ]]

Create scanning session – response

See Session

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
  • document: jpg/jpeg
  • fraud: This feature have been deprecated

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 Note: Only an uppload option no OCR or analisis is done on document. 

About multipart/formdata

Add documents – response

See Session

{
    "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"]
}

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
selfieAutomatically finds analyses and evaluates the bio-metric resemblance of faces represented in uploaded images
expert/ FraudNot available, have been deprecated

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_resultnot available
fraud_analysis_risk_scorenot available
expert_analysis_resultnot available
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_detailsnot available
expert_analysis_detailsnot available
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": "NotRequested",
    "fraud_analysis_result": "NotRequested",
    "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": "NotRequested",
        "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": ["selfie", "document"]
}

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)

See Analysis Status

 

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)

See Analysis Summary 

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_summarynot available
expert_analysis_summarynot available
{
  "result": "DECLINED",
  "result_title": "Declined",
  "result_reason": "Id document was DECLINED. Selfie 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": "NotRequested",
    "error": null,
    "all_errors": [],
    "risk_score": "Undefined",
    "result_reason": null,
    "result_title": "Not Requested"
  },
  "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]",
        "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": "NotRequested",
        "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",
        "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": "NotRequested",
            "error": null,
           "all_errors": [],
            "risk_score": "Undefined",
            "result_reason": null,
            "result_title": "NotRequested"
        },
        "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": "NotRequested",
            "fraud_analysis_result": null,
            "fraud_analysis_risk_score": "Undefined",
            "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": "NotRequested",
                "analysed_images": [],
                 
                "risk_score": "Undefined"
            },
            "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 (Deprecated)

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 and Expert are not available, have been deprecated)

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
gender‘M‘ 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
Not available
fraud_analysis_result
Not available
fraud_analysis_risk_score
Not available
expert_analysis_state
Not available
expert_analysis_result
Not available
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
Not available
expert_analysis_details
Not available
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

CreatedSession is created
AnalysingSession analysis is in progress.
Not startedSession analysis not started.
AcceptedSession is successful..
DeclinedDocument is declined . when data is incorrect or bad document image quality.
FailedSession is failed . Document Image  not found becuase of bad image quality or network issues .
Not RequestedAnalysis not requested . Ex: Selfie not requested 
CancelledSession cancelled by user

Risk score enum (Deprecated)

Represents risk score in fraud analysis

Undefinedrisk is not calculated
Copyright © 2024 Zignsec AB. All right reserved