Upload – GBG IDscan Documentation

Upload

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 NameDescriptionFormat
AdditionalDataOptional, 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”
IdentitiyMeansIdOptional, use when it’s intended to add more pages to a
previously added documents.
GUID
InputImagesMandatory, 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
IsDocumentExtractedMandatory, use “true” if the document was taken via scanner
or IDScan Mobile SDK otherwise if using web camera then
use “false”
Boolean
PersonEntryIdOptional, use when it’s intended to resume an entry by
adding more documents.
GUID
SourceMandatory, Indicates the device source of the image.
Possible values are:
1: Passport Scanner
2: Camera
3: A4 scanner
Integer

Input Image Object:

KeyDescriptionFormat
NamePossible values: “WhiteImage” “NearInfraredImage”
“SelfiePhoto” “UltravioletImage”
String
ImageFormatThe format of the image, possible values: “jpg” and “bmp”.String
DataImage binary data.Base64 String encoded

Result:

Key nameDescriptionFormat
CurrentResultThe processing result. See Table for possible values.String
Doument sourceSee “Doument source” in Processed Document Object.String
EntryDataExtracted information from processed input.Name and Value Dictionary
EntryDateTimeDate and time of entry.DateTime
EntryImagesA list of the images to process, see “Entry Image Object”.List of Objects
HasErrorIndicates 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”
IsFinishedA flag to determine whether entry processing has been
completed and there are no required actions from the user.
Boolean as string “true”
or “false”
PersonEntryIdEntry unique GUID id of the entry.GUID
RequiredActionText 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
ResultDetailsList of check result strings based on system configuration.List of string items
HighLevelResultThe processing result.String

Possible Processing result values for CurrentResult:

ResultsDescription
CaseUpdateFailedMight appear when using IDscan Case Management Module.
ErrorSavingDataIDscan Backend Services has encountered an error while saving the scan data to database, further information can be obtained from IDscan log files.
FailedThe 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
PassThe entry has passed business rules & authentication checks and was saved successfully.
ProcessingErrorIDscan Backend Services has encountered an error while communicating with IDES, further information can be obtained from IDscan log files.
SpecifiedEntryNotFoundReturned 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:

ResultsDescription
DateOfBirthCrossCheckA check whether the extracted date of birth from the front side and the backside of provided ID document are equal or not.
DocumentNumberCrosscheckA 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.
ExpiryDateCrosscheckA check whether the both sides have the same expiry date or not.
FirstNameCrosscheckA check whether the extracted first name on both sides (the front and the back) are equal or not.
LastNameCrosscheckA check whether the extracted last name on both sides (the front and the back) are equal or not.
PaperDocumentCrosscheckA check whether the Identity document and the POA/A4 document belong to the same person or not.
FaceMatchValidationThe outcome of the Face match validation between the provided selfie image and the extracted portrait image.
ChipPhotoValidationThe outcome of the Face match validation between the extracted chip photo (If exists) and the extracted portrait image.

Entry Image Object:

KeyDescriptionFormat
CreateDatetimeDate and time of image processing.DateTime
DataImage binary data.Base64 String encoded
Document roleDetermines 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
IdUnique ID of the imageGUID
IdentityMeansIdThe unique ID of the document record generated by processing the image.GUID
RoleA 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.

Was this page helpful?