This action is used for uploading a document image to the 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.
Note: The authentication must be done using (area=”scanning”) 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 backside (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. JourneyDefinitionId: Optional, use when multiple journey definitions have been created to call a specific one. ManualFirstName: Optional, use when “ManualCrossCheckEnabled” configuration is true. ManualLastName: Optional, use when “ManualCrossCheckEnabled” configuration is true. ManualBirthDate: Optional, use when “ManualCrossCheckEnabled” configuration is true. | 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 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” “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"},
{"Name":"ManualFirstName","Value":"firstnamevalue"},
{"Name":"ManualLastName","Value":"lastnamevalue"},
{"Name":"ManualBirthDate","Value":"dateofbirthvalue"}, //this should be sent as yyyy-MM-dd(1990-10-15) for example
],
"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.