Upload

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.