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
1. Create session
We need to create a new session to start using scanning
POST https://`env`.zignsec.com/v3/eid/scanningsessions
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
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/
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
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](https://docs.zignsec.com/id-scan/v3-api-flow/#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
| Parameter | Description | |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --- |
| `locale` | Preferred Language to use, we support multiple languages like : en , se ,de , fr, gr, it ,ru ,es , cz,tr.<br><br>We can add more languages as per your business requirements | |
| `relay_state` | This 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_types` | array of analysis to perform. See Analysis types | |
| `target` | f this parameter is supplied the browser session will finally be redirected to this URL-value | |
| `target_error` | targetError works as `target` except it is navigated on user cancel or error situations | |
| `webhook` | A URL where success/error results will automatically be POST:ed | |
| Parameter | Description | |
| --------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `flow` | Used to customize your flow | `selfie_heading`: string |
| | | `steps:`<br><br>- type: string, enum [SelectDocTypePage, UploadPage]<br>- heading: string<br>- ref: string |
| | | `locale`: string |
| | | `default_country_code`: string |
| `doc` | `ignore_errors_in_fields` | string, <br>exple: <br>[“Surname”,”Surname_And_Given_Names”,”Given_Names”,”Surname_And_Given_Names_local”,”Surname_local”,”Date_of_Birth”] |
| | `verification_types` <br>(getting all per default) | string, Enum [ Mrz, Visual, Barcode, MrzVisual, MrzBarcode, VisualBarcode ]] |
### Create scanning session – response
#### Session Model
Session is a logical container for a single person authentication process
| | |
| -------------------- | ---------------------------------------- |
| `session_id` | scanning session id |
| `provider_folder_id` | an id used on the scanning provider side |
| `documents` | session documents. |
```json
{
"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
| | |
|---|---|
|`scanningSessionId`|Session id|
|`documentType`|The type of the document to upload – see below [Document Type](https://docs.zignsec.com/id-scan/v3-api-flow/#document-type)|
|`reference`|The document reference|
#### Document Type
The type of the document to upload. Only image/jpeg supported so far
| | |
|---|---|
|`Passport`|Passport – the page with face photo required|
|`IdentityCard`|ID card – 2 sides required|
|`DriversLicense`|Driver license – the side with photo required|
|`Selfie`|Selfie (a biometric image)|
|`OtherDocument`|Other document – the page without photo required Note: Only an uppload option no OCR or analisis is done on document.|
#### About multipart/formdata
- - [General description (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST)
- Usage
- [Using FormData objects (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/FormData/Using_FormData_Objects)
- [FormData (javascript.info)](https://javascript.info/formdata)
- [Upload files (.NET Core)](https://docs.microsoft.com/en-us/aspnet/core/mvc/models/file-uploads?view=aspnetcore-3.1#upload-small-files-with-buffered-model-binding-to-physical-storage)
- [RFC 7578](https://tools.ietf.org/html/rfc7578)
#### Add documents – response
```json
{
"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
| | |
|---|---|
|`scanningSessionId`|Session id|
|`timeZoneOffset`|Client time zone offset in minutes|
#### Request Model
| | |
|---|---|
|`analysis_types`|array of analysis to perform. See [Analysis types](https://docs.zignsec.com/id-scan/v3-api-flow/#analysis-types)|
#### Analysis types
| | |
|---|---|
|`document`|Analyses and verifies the content of the uploaded image of the id-card, passport or driver’s license|
|`selfie`|Automatically finds analyses and evaluates the bio-metric resemblance of faces represented in uploaded images|
|`expert/ Fraud`|Not available, have been deprecated|
#### Start analysis – response
#### Analysis Result Model
Represents a single analysis result
| | |
|---|---|
|`analysis_id`|an analisys identifier|
|`started_at`|analysis start time|
|`finished_at`|analysis finish time|
|`total_process_state`|session state (see [State](https://docs.zignsec.com/id-scan/v3-api-flow/#state-enum))|
|`document_analysis_result`|document analysis result|
|`document_analysis_failed_fields`|failed fields from the document analysis if any|
|`fraud_analysis_result`|not available|
|`fraud_analysis_risk_score`|not available|
|`expert_analysis_result`|not available|
|`identity`|Identity filled from the given document , contains local values (see [Identity](https://docs.zignsec.com/id-scan/v3-api-flow/#identity-model))|
|`identity_english`|English version of the identity (see [Identity](https://docs.zignsec.com/id-scan/v3-api-flow/#identity-model))|
|`document_analysis_details`|document analysis details|
|`fraud_analysis_details`|not available|
|`expert_analysis_details`|not available|
|`selfie_analysis_results`|selfie analysis results|
|`analysed_documents`|analysed documents (see [Document](https://docs.zignsec.com/id-scan/v3-api-flow/#document-model))|
```json
{
"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
```json
{
"id": "231a7aa4-f6d3-468b-9aab-7ec4c6ee3a8c",
"errors": [],
"redirect_url": "https://test.zignsec.com/v3/eid/scanningsessions/scan/231a7aa4-f6d3-468b-9aab-7ec4c6ee3a8c"
}
```
| | |
|---|---|
|`id`|The session identifier, a GUID (globally unique identifier) unique for the started workflow, used both in the `redirect_url` and the [get analysis results](https://docs.zignsec.com/id-scan/v3-api-flow/#step5).|
|`errors`|A 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_url`|The 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_id`|a session identifier|
|`total_process_state`|a state of the current operation. See [State](https://docs.zignsec.com/id-scan/v3-api-flow/#state-enum)|
|`session_parameters`|session parameters. See [Session Parameters](https://docs.zignsec.com/id-scan/v3-api-flow/#session-parameters-model)|
```json
{
"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_id` | a session identifier |
| `total_process_state` | a state of the current operation. See [State](https://docs.zignsec.com/id-scan/v3-api-flow/#state-enum) |
| `session_parameters` | session parameters. See [Session Parameters](https://docs.zignsec.com/id-scan/v3-api-flow/#session-parameters-model) |
| `result` | an overall analysis result. See [Result](https://docs.zignsec.com/id-scan/v3-api-flow/#result-enum) |
| `result_title` | result string representation |
| `result_reason` | result reason string |
| `analysis_duration_sec` | analysis duration in seconds |
| `id_document_summary` | See [Id Document Summary](https://docs.zignsec.com/id-scan/v3-api-flow/#id-document-summary-model) |
| `selfie_summary` | See [Selfie Summary](https://docs.zignsec.com/id-scan/v3-api-flow/#selfie-summary-model) |
| `fraud_analysis_summary` | not available |
| `expert_analysis_summary` | not available |
```json
{
"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
#### Scanning Session with Analysis Results Model
Represents a scanning session with analysis results
| | |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `total_result` | an overall analysis result. See [Result](https://docs.zignsec.com/id-scan/v3-api-flow/#result-enum) |
| `session_id` | a session identifier |
| `start_date` | session start date |
| `finish_date` | session finish date |
| `provider_folder_id` | an id used on the scanning provider side |
| `request_parameters` | session parameters. See [Session Parameters](https://docs.zignsec.com/id-scan/v3-api-flow/#session-parameters-model) |
| `synopsis_human_readable` | a human readable synopsis |
| `identity` | identity (local values) |
| `identity_english` | identity (English values) |
| `analysis_summary` | see [Analysis Summary](https://docs.zignsec.com/id-scan/v3-api-flow/#analysis-summary-model) |
| `analysis_details` | see [Analysis Details](https://docs.zignsec.com/id-scan/v3-api-flow/#analysis-details-model) |
| `documents` | analyzed documents |
| `error` | error string |
```json
{
"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)
| | |
|---|---|
|`id`|document id|
|`file_name`|document file name|
|`image_url`|document url|
#### Id Document Summary Model
Represents an id document analysis summary
| | |
|---|---|
|`result`|an overall analysis result. See [Result](https://docs.zignsec.com/id-scan/v3-api-flow/#result-enum)|
|`result_title`|result string representation|
|`result_reason`|reason behind the result (usually – for DECLINED sessions)|
|`error`|all errors as a text|
|`document_type_name`|a document type name of the first found document|
|`first_name`|first name (local value)|
|`last_name`|last name (local value)|
|`full_name`|full name (local value)|
|`first_name_english`|first name (English)|
|`last_name_english`|last name (English)|
|`full_name_english`|full name (English)|
|`age`|age|
|`expiration_date`|document expiration date|
|`issuer_state`|document issuer state|
|`fields`|found fields formatted as a JSON object|
#### Selfie Summary Model
Represents a selfie analysis summary
| | |
|---|---|
|`result`|an overall analysis result. See [Result](https://docs.zignsec.com/id-scan/v3-api-flow/#result-enum)|
|`result_title`|result string representation|
|`result_reason`|reason behind the result (usually – for DECLINED sessions)|
|`error`|all errors as a text|
|`min_confidence`|min confidence in the selfie match|
|`max_confidence`|max confidence in the selfie match|
#### Fraud Summary Model (Deprecated)
Represents a fraud analysis summary
| | |
|---|---|
|`result`|an overall analysis result. See [Result](https://docs.zignsec.com/id-scan/v3-api-flow/#result-enum)|
|`result_title`|result string representation|
|`result_reason`|reason behind the result (usually – for DECLINED sessions)|
|`error`|the first error reported from images fraud analysis|
|`all_errors`|all errors from fraud analysis (see details to get errors for each particular image)|
|`risk_score`|fraud risk score. See [Risk](https://docs.zignsec.com/id-scan/v3-api-flow/#risk-enum)|
#### Session Parameters Model
Represents a session parameters
| | |
|---|---|
|`relay_state`|state sent from the client persisted in session. Is sent back to redirect urls and webhooks as is|
|`session_type`|session type `Api` \| `BrowserFlow` \| `WebSdk`|
|`webhook`|webhook url|
|`target`|to be used by the Browser Flow to redirect user when analysis is finished|
|`target_error`|to be used by Browser Flow to redirect user when analysis is `FAILED`|
|`analysis_types`|an 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_code`|country code|
|`first_name`|first name|
|`last_name`|last name|
|`full_name`|full name|
|`personal_number`|personal number|
|`date_of_birth`|date of birth|
|`age`|age|
|`expiration`|document expiration date if any|
|`expired`|**true** 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_state`|the name of the state that issued a document|
|`gender`|‘**M**‘ for male, ‘**F**‘ – female, **null** – not recognized|
|`id_provider_name`|id provider name (‘**Scanning**‘)|
|`identification_date`|identification date (UTC)|
|`id_provider_request_id`|internal id for the scanning provider|
### Analysis results details
|Field|Description|
|---|---|
|`total_process_state`|The 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](https://docs.zignsec.com/id-scan/v3-api-flow/#document-model)|
### Enums
#### State enum
Represents a state of the current analysis in-progress
| | |
|---|---|
|`NotRequested`|analysis not requested|
|`Processing`|analysis is in progress|
|`Finished`|analysis finished, check result|
|`Failed`|an internal error occured during analysis|
#### Result enum
Represents a single analysis result
| | |
|---|---|
|Created|Session is created|
|Analysing|Session analysis is in progress.|
|Not started|Session analysis not started.|
|Accepted|Session is successful..|
|Declined|Document is declined . when data is incorrect or bad document image quality.|
|Failed|Session is failed . Document Image not found becuase of bad image quality or network issues .|
|Not Requested|Analysis not requested . Ex: Selfie not requested|
|Cancelled|Session cancelled by user|
#### Risk score enum (Deprecated)
Represents risk score in fraud analysis
| | |
|---|---|
|`Undefined`|risk is not calculated|