This action is used for uploading a document image to IDscan backend to be processed along with an optional face match input data to match two faces, the high level result of processing is included in the response of this action call.
Important note: Authentication must be done before calling this action, for more information please refer to Authentication section.
Important note: In order to upload the backside of the document after receiving the required action as back side (RequiredAction:BACKSIDE) PersonEntryId parameter can be sent as the journeyId which is returned back from the response of upload action of the front side.
Important note: The file size could be maximum 10mb, if it is over 10mb then error413 will be returned in the response.
Signature
[POST] https://serviceURL/idscanenterprisesvc/journey/upload Request/Response format: JSON
Body Parameters:
| Parameter Name | Description | Format |
| AdditionalData | Optional, a dictionary of string values to be associated with the case, all of the items included here will be returned in the response payload. Examples: Username: Optional, User name conducting the upload, optional, used as metadata to identify the user sending the request. BranchCode: Optional, used to identify the branch the request is coming from. | Name and Value Dictionary |
| ExcludeOutputImages FromResponse | Optional, use “true” to exclude the output images from the response to reduce its size, defaults to “false” means output images will be included in the response payload | Boolean as string “true” or “false” |
| IdentitiyMeansId | Optional, use when it’s intended to add more pages to a previously added documents. | GUID |
| InputImages | Mandatory, a list of images to process, see “Input Image Object”, This list should at least contain an element named “WhiteImage” which is the visible image of the document. | Object |
| IsDocumentExtracted | Mandatory, use “true” if the document was taken via scanner or IDScan Mobile SDK otherwise if using web camera then use “false” | Boolean |
| PersonEntryId | Optional, use when it’s intended to resume an entry by adding more documents. | GUID |
| Source | Mandatory, Indicates the device source of the image. Possible values are: 1: Passport Scanner 2: Camera 3: A4 scanner | Integer |
Input Image Object:
| Key | Description | Format |
| Name | Possible values: “WhiteImage” “NearInfraredImage” “SelfiePhoto” “UltravioletImage” | String |
| ImageFormat | The format of the image, possible values: “jpg” and “bmp”. | String |
| Data | Image binary data. | Base64 String encoded |
Result:
| Key name | Description | Format |
| CurrentResult | The processing result. See Table for possible values. | String |
| Doument source | See “Doument source” in Processed Document Object. | String |
| EntryData | Extracted information from processed input. | Name and Value Dictionary |
| EntryDateTime | Date and time of entry. | DateTime |
| EntryImages | A list of the images to process, see “Entry Image Object”. | List of Objects |
| HasError | Indicates whether an error has happened during entry processing, in case of receiving three consequence errors, IDscan support team contact is advised. | Boolean as string “true” or “false” |
| IsFinished | A flag to determine whether entry processing has been completed and there are no required actions from the user. | Boolean as string “true” or “false” |
| PersonEntryId | Entry unique GUID id of the entry. | GUID |
| RequiredAction | Text string code to inform calling application with the required action to continue entry processing if needed, possible values differ based on entry workflow customisations. | String |
| ResultDetails | List of check result strings based on system configuration. | List of string items |
| HighLevelResult | The processing result. | String |
Possible Processing result values for CurrentResult:
| Results | Description |
| CaseUpdateFailed | Might appear when using IDscan Case Management Module. |
| ErrorSavingData | IDscan Backend Services has encountered an error while saving the scan data to database, further information can be obtained from IDscan log files. |
| Failed | The scanned document image has failed due to one of the following: 1. A document in the entry was not recognized by IDES 2. A document in the entry did not pass validation checks 3. A document in the entry was expired 4. A document in the entry was rejected by document proof policy 5. A document in the entry was rejected by a business rule |
| Pass | The entry has passed business rules & authentication checks and was saved successfully. |
| ProcessingError | IDscan Backend Services has encountered an error while communicating with IDES, further information can be obtained from IDscan log files. |
| SpecifiedEntryNotFound | Returned as an error when specifying a value in the upload request parameter PersonEntryId that does not exist in the system. |
Possible Processing result values for HighLevelResult:
| Results | Description |
| DateOfBirthCrossCheck | A check whether the extracted date of birth from the front side and the backside of provided ID document are equal or not. |
| DocumentNumberCrosscheck | A check whether the document number of front side and backside ID document are equal or not. |
| DocumentTypeCrosscheck | A Check whether the both sides (the front and the back) have the same document type. |
| ExpiryDateCrosscheck | A check whether the both sides have the same expiry date or not. |
| FirstNameCrosscheck | A check whether the extracted first name on both sides (the front and the back) are equal or not. |
| LastNameCrosscheck | A check whether the extracted last name on both sides (the front and the back) are equal or not. |
| PaperDocumentCrosscheck | A check whether the Identity document and the POA/A4 document belong to the same person or not. |
| FaceMatchValidation | The outcome of the Face match validation between the provided selfie image and the extracted portrait image. |
| ChipPhotoValidation | The outcome of the Face match validation between the extracted chip photo (If exists) and the extracted portrait image. |
Entry Image Object:
| Key | Description | Format |
| CreateDatetime | Date and time of image processing. | DateTime |
| Data | Image binary data. | Base64 String encoded |
| Document role | Determines for which side of the document image was captured, Possible values: (“ID Document”, “ID Document Back” applicable only with ID documents) and “A4 Paper” when scanning A4 documents. | String |
| Id | Unique ID of the image | GUID |
| IdentityMeansId | The unique ID of the document record generated by processing the image. | GUID |
| Role | A code name for the image. Possible values: “ChipPhoto”, “FacePortraitImage”, “NearInfraredImage” “SelfiePhoto”, “UltravioletImage”, “WhiteImage” | String |
Example JSON
Request:
{
"AdditionalData":[
{"Name":"UserName","Value":"username"},
{"Name":"BranchCode","Value":"1234"},
{"Name":"CustomerNumber","Value":"c1234"},
{"Name":"Channel","Value":"Postman"},
],
"InputImages": [{
"Name":"WhiteImage",
"ImageFormat":"jpg",
"Data":"BASE64_IMAGE"
},],
"IsDocumentExtracted":"false",
"Source":2,
"ExcludeOutputImagesFromResponse":"true"
}
Response:
{
"PersonEntryId": "461c9e05-3a0d-422b-8902-b3ce748b485a",
"EntryDateTime": "2019-11-21T13:49:15.9717097Z",
"RequiredAction": "NONE",
"CurrentResult": "Pass",
"HighLevelResult": "Passed",
"EntryImages": [],
"IsFinished": true,
"RequestId": "00000000-0000-0000-0000-000000000000",
"HasError": false,
"ResultDetails": [
"UNDERAGERULE:PASSED",
"DOCUMENTBACKSIDECHECK:NOTNEEDED",
"DOCUMENTBLOCKINGPOLICY:PASSED",
"DOCUMENTEXPIRY:PASSED",
"DOCUMENTSUPPORT:PASSED",
"DOCUMENTPROOFPOLICY:SKIPPED",
"DOCUMENTVALIDATION:PASSED"
],
"EntryData": {
"BranchCode": "1234",
"CustomerNumber": "c1234",
"Channel": "Postman",
"UserName": "psc",
"RequiredJourneySteps": "BACKSIDE,FRONTSIDE",
"UnderAgeRuleResult": "PASSED",
"DocumentType": "Driving License",
"CountryCode": "GBR",
"ExtractedFields.AddressFull": "12 TORWOOD CRESCENT EDINBURGH EH12 9GJ",
"ExtractedFields.AddressCity": "EDINBURGH",
"ExtractedFields.AddressPostCode": "EH12 9GJ",
"ExtractedFields.LastNameFirstPart": "MORGA",
"ExtractedFields.Sex": "FEMALE",
"ExtractedFields.BirthPlace": "1 LA",
"ExtractedFields.IssueNumber": "35",
"ExtractedFields.DocumentNumberCheckDigit": "IJ",
"ExtractedFields.BirthDate": "1976-03-11",
"ExtractedFields.DocumentNumber": "MORGA753116SM9IJ 35",
"ExtractedFields.FirstName": "SARAH",
"ExtractedFields.ArbitraryDigit": "9",
"ExtractedFields.FirstNameInitial": "SM",
"ExtractedFields.ExpiryDate": "2023-01-18",
"ExtractedFields.IssueDate": "2013-01-19",
"ExtractedFields.LastName": "MORGAN",
"ExtractedFields.LicenseCategory": "AM/A/B1/B/F/K/I/N/P/Q",
"ExtractedFields.DocumentCategory": "Driving License",
"ExtractedFields.DocumentType": "Driving License",
"QualityChecks.BlurCheck": "Good",
"QualityChecks.GlareCheck": "Good",
"QualityChecks.LowResolutionCheck": "Good",
"ScanReason": "",
"AuthenticationLevel": "medium",
"ScanReference": "1000010181"
}
}
End of upload response example.