Actions | GBG IDscan Documentation

The API service exposes the following actions in JSON format:

Authentication

This action is used for user authentication. It accepts the login credentials and returns the user full name, his role and an authentication token.

For demonstration purposes, the system will be supported with service accounts to be used with authentication calls, no password policies are applied on these accounts, and these accounts are:

Username	Password	Format
scanuser	scanpassword	Case Sensitive
invuser	invpassword	Case Sensitive

Signature

[POST] https://{serviceURL}/idscanenterprisesvc/token Request/Response
format: application/x-www-form-urlencoded

Parameters:

Name	Description	Format
UserName	Mandatory, the user login name	String
Password	Mandatory, the user password	String
area	Mandatory, application area (used to check if the user is authorised to access the required resource), possible values (investigation, scanning)	String
grant_type	Mandatory, the grant_type parameter must be set to “password”	String, the key is in lower case

Result:

Key Name	Description	Format
Username	User login name	String
FullName	User full name	String
Role	User role	String
Token	Authentication token	String, the key is in lower case

Important Notes: Notice that the content-type and payload type is “x-www-form-urlencoded” so the payload body will be on form (grant_type=password&username=”yourusername”&password=”yourpassword”). If all is correct, you’ll notice that you’ve received signed token on the response.

The Authentication Token should be sent along with every forthcoming request in the http headers. The authentication token can be set in the HTTP request one of the following ways:

By using Cookie:
- Cookie: token= DE14ydbxNEiUuIaV2tHN2A
By using Authorization Http header:
- Authorization: DE14ydbxNEiUuIaV2tHN2A

Authentication action must be called before attempting Upload or Retrieval, each action has its designated value of the “area” parameter in the authentication request.

Calls must have an authentication token that was acquired with the appropriate “area” in order to do successful calls, the area names required for calls are as of the following:

Action Name	Area	Format
Retrieval	Investigation	Lower case string
Upload	Scanning	Lower case string

Response:

{
"access_token": "OpZPv7wD2pS1PVCqXQEvcA7UCdmeMk…", "token_type": "bearer",
"expires_in": 35999, "BranchCode": "",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name": "Superadministrator", "FullName": "",
"AbbeyServiceCentre": "", "JourneyId": "",
"http://schemas.microsoft.com/ws/2008/06/identity/claims/role": "SuperAdministrator", ".issued": "Mon, 07 Jan 2019 07:00:18 GMT",
".expires": "Mon, 07 Jan 2019 17:00:18 GMT"
}

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.

Signature

[POST] https://{serviceURL}/idscanenterprisesvc/journey/upload
Request/Response format: JSON

Body Parameters:

Parameter	Description	Format
journeyID	Mandatory, Reference number of the requested entry	String

Result:

Key	Description	Format
InitiatedDateTime	Date and time of entry in local format of the server PC	DateTime
JourneyId	A unique formatted id of the entry	GUID
HighLevelResultDetails	The details of the high level result decision. This will include the reasons that caused the journey to refer	Values will vary depending on the configured business rules to refer a journey
HighLevelResult	The processing result, see Table for possible values	String
ProcessedDocuments	Collection of processed documents (see Processed Document object)	Object
ReferenceNumber	Unique entry reference number	String
AuthenticationToleranceLevel	Applied Authentication Tolerance Level in journey	String
AdditionalData	Set of Additional Data that linked to the journey	Object

Possible Processing result for HighLevelResult:

Result	Description
Expired	One or more of the documents in the case was expired
NotAccepted	One or more of the documents in the case was not accepted by business rules
Notsupported	One or more of the documents in the case was not recognized by IDES
Passed	All documents in the case(entry) has passed the business rules and authentication checks
Refer	One or more of the documents in the case did not pass authentication checks
Undefined	The system does not have enough information to provide a decision on the case, possible reasons: – System needs more documents or needs to scan the backside of the document as defined in business rules configurations. – System needs to scan the document again due to bad image quality.

Processed Document Object:

Key	Description	Format
IssuingCountryCode	The issuing country code	String, 3 digits ISO 3166-1 standard
IssuingCountryName	The issuing country name	String
DocumentCategory	High level grouping of doc types as of Document Expert knowledge	String
DocumentImages	A list of output image objects in the following format: “Role”: “WhiteImage”, “Url”: “Http URL to download the image in jpg format”	List of Object
DocumentName	Friendly name of the document including the issuing country name	String
DocumentSide	Deprecated, the captured side of the document.	String. Possible Values: “Front”, “Back”
DocumentType	Determines the document type, e.g. Passport, Driving License, Resident Permit etc. (see Annex1 for possible values)	String
ExtractedFields	List of the extracted fields from doc, see “Extracted Field Object”	List of Object
HighLevelResult	The processing result for a particular document image, see Table for possible values	String
IsValidated	Determines whether the doc was validated by the system or not	String “true”, “false” or “undetermined”
ScanDateTime	Date and time of scanning the document image	DateTime
DigitalTamperingValidator	Determines the document is tampered or not	String “Passed” or “Failed

Extracted Field Object

Key	Description	Format
Name	Name of the extracted field	String
Value	The extracted value from the document	String
OCRValue	The original OCR value	String
LocalValue	The local value from the document	String
OCRLocalValue	The original OCR local value	String

Important Note: The authentication must be done before calling this action, for more information please refer to Authentication section.

Example URL

Request:

[GET] https://serviceurl/idscanenterprisesvc/journey/get?journeyId=13ccc9de-0e6c-4e18-8518-f7a7586cc316

Response:

Note: The structure of the response will be the same regardless of the document type but the extracted field list in this example is for demonstration purposes only; possible list of extracted fields depends on the document type being processed, list of possible extracted fields can be found under Annex2.

{
"JourneyId": "f1d6ea32-cec2-46ad-a041-4bd53e17d450",
"HighLevelResult": "Passed",
"HighLevelResultDetails": [
"UNDERAGERULE:SKIPPED",
"DOCUMENTBACKSIDECHECK:SKIPPED",
"DOCUMENTBLOCKINGPOLICY:PASSED",
"DOCUMENTEXPIRY:SKIPPED",
"DOCUMENTSUPPORT:PASSED",
"DOCUMENTPROOFPOLICY:SKIPPED",
"DOCUMENTVALIDATION:PASSED",
"DOCUMENTACCEPTANCEPOLICY:PASSED"
],
"InitiatedDateTime": "2019-01-07T09:59:58.782926",
"ProcessedDocuments": [
{
"IssuingCountryCode": "DEU",
"IssuingCountryName": "Germany",
"DocumentCategory": "National Identification Card",
"DocumentType": "National Identification Card",
"DocumentName": "Germany-National Identification Card",
"DocumentSide": "Front",
"IsValidated": "true",
"ScanDateTime": "2019-01-07T09:59:58.782926",
"HighLevelResult": "Passed",
"ExtractedFields": [
{
"Name": "DocumentNumber",
"Value": "{{Extracted Document Number}}"
"OCRValue": "{{Extracted Document Number OCR Value}}"
"LocalValue": "{{Extracted Document Number Local Value}}"
"OCRLocalValue": "{{Extracted Document Number OCR Local Value}}"
},
{
"Name": "FirstName",
"Value": "{{Extracted First Name}}"
"OCRValue": "{{Extracted Document Number OCR Value}}"
"LocalValue": "{{Extracted Document Number Local Value}}"
"OCRLocalValue": "{{Extracted Document Number OCR Local Value}}"
},
{
"Name": "BirthDate",
"Value": "{{Extracted Birth Date}}"
"OCRValue": "{{Extracted Document Number OCR Value}}"
"LocalValue": "{{Extracted Document Number Local Value}}"
"OCRLocalValue": "{{Extracted Document Number OCR Local Value}}"
},
{
"Name": "BirthPlace",
"Value": "{{Extracted Birth Place}}"
"OCRValue": "{{Extracted Document Number OCR Value}}"
"LocalValue": "{{Extracted Document Number Local Value}}"
"OCRLocalValue": "{{Extracted Document Number OCR Local Value}}"
},
{
"Name": "LastName",
"Value": "{{Extracted Last Name}}"
"OCRValue": "{{Extracted Document Number OCR Value}}"
"LocalValue": "{{Extracted Document Number Local Value}}"
"OCRLocalValue": "{{Extracted Document Number OCR Local Value}}"
},
{
"Name": "SecondLastName",
"Value": "{{Extracted Second Last Name}}"
"OCRValue": "{{Extracted Document Number OCR Value}}"
"LocalValue": "{{Extracted Document Number Local Value}}"
"OCRLocalValue": "{{Extracted Document Number OCR Local Value}}"
},
{
"Name": "NationalityCode",
"Value": "DEU"
"OCRValue": "{{Extracted Document Number OCR Value}}"
"LocalValue": "{{Extracted Document Number Local Value}}"
"OCRLocalValue": "{{Extracted Document Number OCR Local Value}}"
},
{
"Name": "NationalityName",
"Value": "German"
"OCRValue": "{{Extracted Document Number OCR Value}}"
"LocalValue": "{{Extracted Document Number Local Value}}"
"OCRLocalValue": "{{Extracted Document Number OCR Local Value}}"
},
{
"Name": "FullName",
"Value": "{{Full Name}}"
"OCRValue": "{{Extracted Document Number OCR Value}}"
"LocalValue": "{{Extracted Document Number Local Value}}"
"OCRLocalValue": "{{Extracted Document Number OCR Local Value}}"
}
],
"DocumentImages": [
{
"Role": "WhiteImage",
"Url":
"http://{{serviceUrl}}/idscanenterprisesvc/Search/GetImage?id=cd89dc83-0527-4827-ac28-9eeb8b340fea&role
=OutputWhiteImage"
},
{
"Role": "DigitalTamperingHeatmapImage",
"Url": "http://
{{serviceUrl}}/idscanenterprisesvc/Search/GetImage?id=cd89dc83-0527-4827-ac28-9eeb8b340fea&role=Digital
TamperingHeatmapImage"
},
{
"Role": "FacePortraitImage",
"Url": "http://
{{serviceUrl}}/idscanenterprisesvc/Search/GetImage?id=cd89dc83-0527-4827-ac28-9eeb8b340fea&role=FacePo
rtraitImage"
}
],
"DigitalTamperingValidator": "Passed"
}
],
"ReferenceNumber": "1000020072",
"AuthenticationToleranceLevel": "Default",
"AdditionalData": [
{
"Name": "UserName",
"Value": "username"
},
{
"Name": "BranchCode",
"Value": "Web Upload"
},
{
"Name": "RequiredJourneySteps",
"Value": "FRONTSIDE"
}
]
}

End of retrieval response example.

Notification Web Hooks

On-boarding Suite also provides a set of web hooks that can be used to get notifications when certain events of interest happen. The consumer will need to implement the contract of the web hook operation in an http web service and configure the URL to this web service

The steps to make use of the notification web hook feature are as follows:

– Create an Http Web service that implements the service operations associated with the notifications you are interested in. For example if you are interested in getting notifications when a journey is finished, you need to implement the NotifyJourneyFinished operation in the web service available by calling:

POST <UrlOfNotificationWebHookServiceRoot>/OnJourneyFinished

– Publish the web service and make it accessible to On-boarding Suite backend. Configure the URL that On-boarding should locate the service in the setting item with the key “JourneyNotificationWebhookUrl” in the BackendSettings.xml file.

Supported notification web hooks are:

OnJourneyProgress notification

Invoked when an intermediate progress (events other than finishing the journey) occurs to a journey.

POST /OnJourneyProgress

Parameter	Description
JourneyId	The identifier of the journey that was affected by the error if the error was related to a journey. A code value representing the error that occurred encoded as a string value.
ErrorCode	Possible error codes are: • ProcessingError • ErrorSavingData • ServerError • JourneyViolation
ErrorDescription	A text message describing the error

OnJourneyOverridden

invoked when journey overridden

POST /OnJourneyOverridden

Parameter	Description
JourneyId	The identifier of the affected journey