GBG IDscan

IEOS Web API

 GBG IDscan Title

Index
1. Summary
2. Actions
• Authentication
- Signature
- JSON Example
• Upload
- Signature
- Example JSON
• Retrieval
- Signature:
- Example URL
3. Annex 1: List of document types supported in IDES
• List of supported ID document types
• List of supporting supported non-ID document types
4 Annex 2: List of Possible Extracted Fields from IDES
• Possible extracted fields from ID documents
• Possible extracted fields from utility bills, bank statements and other non-ID documents

The copyright in all material provided in this document is held by IDscan Biometrics Limited registered in the UK.
None of the material may be copied, reproduced, distributed, republished, displayed, posted or transmitted in any
form or by any means, including, but not limited to, electronic, mechanical, photocopying, recording, or otherwise,
without the prior written permission of IDscan Biometrics. Any unauthorized use of any material contained in this
document may violate copyright laws, trademark laws, the laws of privacy and publicity, and communications
regulations and statutes.

USING IDENTITY INTELLIGENTLY

 GBG IDscan IEOS Web API

GBG IDscan IEOS Web API

1. Summary
This document explains how development teams will integrate their new or existing systems with IDscan Onboard-
ing Suite API, it contains a list of the actions that can be used within the system along with examples and sample
JSON requests and responses for each action.

2. Actions
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. The key and value should be lower case
sensitive string.
Password Mandatory, The user password. The key should be lower case string; value
is case sensitive.
area Mandatory, Application area (used to check if the The key and value should be lower case
user is authorised to access the required resource), sensitive string, see Areas Table.
possible values (investigation, scanning).
grant_type Mandatory, The grant_type parameter must be set The key and value should be lower case
to “password”. sensitive string,

Result:

Key Name Description Format

Username User login name String
FullName User full name String
Role User role String
Token Authentication token String, Key is lower case

USING IDENTITY INTELLIGENTLY

 GBG IDscan IEOS Web API

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: token= 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": "rIkb07aTQ3BJIpn3tFHWU8PjZLLgHgbPZ..",
"token_type": "bearer",
"expires_in": 35999,
"https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name": "Admin",
"FullName": "",
"https://schemas.microsoft.com/ws/2008/06/identity/claims/role": "SuperAdministrator,ReportUser",
".issued": "Thu, 28 Jun 2017 09:38:36 GMT",
".expires": "Thu, 28 Jun 2017 19:38:36 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

USING IDENTITY INTELLIGENTLY

 GBG IDscan IEOS Web API

Body Parameters:
Parameter Name Description Format
AdditionalData Optional, a dictionary of string values to be associated with Name and Value Dictionary
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.
ExcludeOutputImages Optional, use “true” to exclude the output images from the Boolean as string “true” or
FromResponse response to reduce its size, defaults to “false” means output “false”
images will be included in the response payload
IdentitiyMeansId Optional, use when its intended to add more pages to a GUID
previously added documents.
InputImages Mandatory, a list of images to process, see “Input  Image  Object
Object”, This list should at least contain an element named
“WhiteImage” which is the visible image of the document.
IsDocumentExtracted Mandatory, use “true” if the document was taken via scanner Boolean
or IDScan Mobile SDK otherwise if using web camera then
use “false”
PersonEntryId Optional, use when its intended to resume an entry by GUID
adding more documents.
Source Mandatory, Indicates the device source of the image. Integer
Possible values are:
1: Passport Scanner
2: Camera
3: A4 scanner

Input Image Object

Key Description Format
Name Possible values: “WhiteImage” “NearInfraredImage” String
“SelfiePhoto” “UltravioletImage”
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 Boolean as string “true”
processing, in case of receiving three consequence errors, or “false”
IDscan support team contact is advised
IsFinished A flag to determine whether entry processing has been Boolean as string “true”
completed and there are no required actions from the user. or “false”
PersonEntryId Entry unique GUID id of the entry. GUID
RequiredAction Text string code to inform calling application with the required String
action to continue entry processing if needed, possible values
differ based on entry workflow customisations.
ResultDetails List of check result strings based on system configuration. List of string items
HighLevelResult The processing result String

USING IDENTITY INTELLIGENTLY

 GBG IDscan IEOS Web API

Possible Processing result values for CurrentResult:

Result 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

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 String
captured, Possible values: (“ID Document”, “ID Document
Back” applicable only with ID documents) and “A4 Paper”
when scanning A4 documents
Id Unique ID of the image GUID
IdentityMeansId The unique ID of the document record generated by GUID
processing the image
Role A code name for the image. Possible values: String
“ChipPhoto”, “FacePortraitImage”, “NearInfraredImage”
“SelfiePhoto”, “UltravioletImage”, “WhiteImage”

USING IDENTITY INTELLIGENTLY

 GBG IDscan IEOS Web API

Example JSON

Request:
{
"AdditionalData":[
{"Name":"UserName","Value":"username"}, //optional
{"Name":"BranchCode","Value":"Postman"}, //optional
],
"InputImages": [{
"Name":"WhiteImage",
"ImageFormat":"jpg",
"Data":""
},],
"IsDocumentExtracted":"false",
"Source":2,
"ExcludeOutputImagesFromResponse":"true"
}

Response:
{"PersonEntryId": "618e917a-ae93-42d0-a87f-075677e64a3d",
"EntryDateTime": "2015-10-23T07:53:04.5088722Z",
"RequiredAction": "NONE",
"CurrentResult": "Passed",
EntryImages [
{
“Id”: "716d215a-ce33-4540-a776-021627e54d3d",
"Role": "WhiteImage",
"Data": “BASE64 string”,
"CreateDatetime": "2015-10-23T07:53:04.5088722Z"
}],
"IsFinished": true,
"RequestId": "9e2b1a3d-572d-43a5-a056-b17192e0924e",
"HasError": false,
"ResultDetails": [
"DOCUMENTEXPIRY:PASSED",
"DOCUMENTSUPPORT:PASSED",
"DOCUMENTVALIDATION:PASSED"],
"EntryData": {
"UserName": "username",
"BranchCode": " Web Upload ",
"DocumentType": "Capital Territory Driver Licence",
"CountryCode": "AUS",
"ExtractedFields.PortraitPhoto": null,
"ExtractedFields.DocumentNumber": "",
"ExtractedFields.FullName": "",
"ExtractedFields.FirstName": "",
"ExtractedFields.LastName": "",
"ExtractedFields.BirthDate": "1983-03-12",
"ExtractedFields.ExpiryDate": "2013-03-12",
"ExtractedFields.AddressFull": "",
"ExtractedFields.PersonalNumber": "A00101S832",
"ScanReference": "2SPZIFBHGA"
}}

End of upload response example.

USING IDENTITY INTELLIGENTLY

 GBG IDscan IEOS Web API

Retrieval
This action is used to retrieve the processing results for a processed journey. It accepts a journey ID and returns the
processing results for the journey and a list of the processed documents in addition to the extracted fields for each
processed document in the journey.

Signature: [GET] https://serviceurl/idscanenterprisesvc/journey/get

Request/Response format: JSON

Url Parameters:
Parameter Description Format
journeyID Mandatory, Reference number of the requested entry. String

Result:
Key Description Format
InitiatedDateTime DateTime
Date and time of entry in local format of the server PC
JourneyId A unique formatted id of the entry GUID
HighLevelResultDetails Values will vary depending
The details of the high level result decision. This will
on the configured business
include the reasons that caused the journey to refer
rules to refer a journey
HighLevelResult The processing result, see Table for possible values String
ProcessedDocuments Collection of processed documents (see Processed  Object
Document 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:
1. System needs more documents or needs to scan the backside of the document as
defined in business rules configurations.
2. System needs to scan the document again due to bad image quality.

USING IDENTITY INTELLIGENTLY

 GBG IDscan IEOS Web API

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: List of Object
"Role": "WhiteImage",
"Url": “Http URL to download the image in jpg format”
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, String
Resident Permit etc. (see Annex1 for possible values)
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 String
possible values. String “true”, “false”
IsValidated Determines whether the doc was validated by the system or not or “undetermined”
ScanDateTime Date and time of scanning the document image. DateTime

Extracted Field Object

Key Description Format
Name Name of the extracted field String
Value The extracted value from the document String

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

USING IDENTITY INTELLIGENTLY

 GBG IDscan IEOS Web API

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": "f060f4d3-7286-4839-9f4c-220092a6420f",
"HighLevelResult": "Passed",
"HighLevelResultDetails": [
"DOCUMENTEXPIRY:SKIPPED",
"DOCUMENTSUPPORT:PASSED",
"DOCUMENTEXPIRY:SKIPPED",
"DOCUMENTSUPPORT:FAILED",
"DOCUMENTPROOFPOLICY:SKIPPED",
"DOCUMENTVALIDATION:FAILED",
"DOCUMENTACCEPTANCEPOLICY:PASSED"
],
"InitiatedDateTime": "2017-08-03T08:29:06.0768247",
"ProcessedDocuments": [
{
"IssuingCountryCode": " ZAF ",
"IssuingCountryName": " South Africa ",
"DocumentCategory": " Passport ",
"DocumentType": "Passport ",
"DocumentName": " South Africa - Passport ",
"DocumentSide": "Front",
"IsValidated": "true",
"ScanDateTime": "2017-08-03T08:29:06.0768247",
"HighLevelResult": " Passed ",
"DocumentImages": [
{
"Role": "WhiteImage",
"Url":
"https://{serviceURL}/IDScanEnterpriseSVC/Search/GetImage?id=2eb84f2a-b590-
42de-9f2d-45d9e2b28123&role=OutputWhiteImage"
},
{
"Role": "NearInfraredImage",
"Url":
"https://{serviceURL}/IDScanEnterpriseSVC/Search/GetImage?id=2eb84f2a-b590-
42de-9f2d-45d9e2b28123&role=OutputNearInfraredImage"
},
{
"Role": "UltravioletImage",
"Url": "https://{serviceURL}/IDScanEnterpriseSVC/Search/GetImage?id=2eb84f2a-b590-
42de-9f2d-45d9e2b28123&role=OutputUltravioletImage"
},

USING IDENTITY INTELLIGENTLY

 GBG IDscan IEOS Web API

{
"Role": "FacePortraitImage",
"Url": "https://{serviceURL}/IDScanEnterpriseSVC/Search/GetImage?id=2eb84f2a-b590-
42de-9f2d-45d9e2b28123&role=FacePortraitImage"
}
],
"ExtractedFields": [
{
"Name": "BirthDate",
"Value": "1980-01-01",
}, {
"Name": "BirthPlace",
"Value": "Cape Town",
}, {
"Name": "DocumentNumber",
"Value": "A123456789",
},
{
"Name": "ExpiryDate",
"Value": "2020-01-01",
},
{
"Name": "FirstName",
"Value": "JOHN",
},
{
"Name": "FullName",
"Value": "JOHN SMITH",
},
{
"Name": "LastName",
"Value": "SMITH",
},
{
"Name": "Sex",
"Value": "Male",
}]}],
"AuthenticationToleranceLevel" : "strict",
"AdditionalData": [
{
"Name": "UserName",
"Value": "SYSTEM"
},
{
"Name": "ScannerIp",
"Value": "192.168.1.23"
}
]
}

End of retrieval response example.

USING IDENTITY INTELLIGENTLY

 GBG IDscan IEOS Web API

3. Annex 1
List of document types supported in IDscan Document Expert System:

Agents License
Driving License Electoral Card
Foreigner Identification Card Health Card
Job License Membership Identification Card
Military Identification Card National Identification Card
Passport Proof of Age Card
Travel Permit Visa
Weapons Licence

List of supporting supported non-ID document types:

Account Statement
Agreement (Tenancy) Bank Document
Bank Letter Bank Statement
Benefit Letter Certificate (Birth, Marriage, Civil partnership)
Council Document Council Letter
Council Tax Driving Licence
DWP Document HMRC Document
Information Sheet Insurance Document
Insurance Letter Invoice
NIC Letter NINO Letter
Official Document Official Letter
Repayment Letter (related to Tax or Social support)
Tax Letter
Tax Statement Tel Bill
Tel Letter Telecommunication Document
TV Licence University Letter
Utility Bill Utility Document
Utility Letter Water Bill
Water Document

USING IDENTITY INTELLIGENTLY

 GBG IDscan IEOS Web API

4. Annex 2
List of Possible Extracted Fields from IDscan Document Expert System:
Field Name Description
AddressBuildingName The building name of the address
AddressBuildingNumber The building number of the address
AddressCity The city of the address
AddressCountry The country of the address
AddressDeliveryPointIdentifier The delivery point identifier (DPID) of the address
AddressDistrict The district of the address
AddressFull The full address (all lines)
AddressLine1 The first line of the address
AddressLine2 The second line of the address
AddressLine3 The third line of the address
AddressLine4 The fourth line of the address
AddressLine5 The fifth line of the address
AddressPostCode The post code of the address
AddressPostCodeType The postcode type of the address
AddressState The state of the address
AddressStateCode The state code of the address
AddressStreet The street of the address
AddressStreetSuffix The street suffix of the address
AddressStreetType The street type of the address
AddressStreetTypeAbbreviation The street abbreviation of the address
AddressSubBuildingName The sub-building name of the address
AddressSubBuildingNumber The sub-building number of the address
AddressUnitNumber The unit number of the address
AddressUnitType The unit type of the address
AgeCategory The category into which the document holder's age falls
AlienNumber The alien number extracted from the document
ArbitraryDigit The arbitrary digit of the document number field
BankCardSecurityCode The security code on the bank card
BankCardType The type of bank card
BarcodeItems Collection of generic barcode items
BirthDate The birth date of person in the document in ISO 8601 format
BirthPlace The document holder's place of birth extracted from the document
BirthPlaceCity The city in which the document holder was born in, extracted from the document
BirthPlaceCountry The Country in which the document holder was born in, extracted from the doc.
BirthPlaceState The State in which the documentholder was born in, extracted from the doc.
BOSNumber The BOS number of the document
CardNumber The card number of the document
ChildrenCount The total number of children the document holder has
Conditions The conditions which are mentioned in the document
Constraints Any constraint that is mentioned in the document
CreditCardNumber The number on the credit card
CustomerNumber The customer number of the document
DistinguishingMarks The distinguishing marks of the document holder
DocumentNumber The identifying number of the doc. such as doc no., driver no., passport no.
DocumentNumberCheckDigit The check digit character of the document number field
DocumentTypeCode The code type of the document.
Donor Determine if the document holder is an organ donor, this is used when somebody
is killed by accident and their organ can be transferred to another person.
Employer The name of the employer extracted from the document.
Endorsements Any endorsement that is mentioned in the document.

USING IDENTITY INTELLIGENTLY

 GBG IDscan IEOS Web API

EntryMode The mode of allowed entries for the document holder. Values such as Multi or
Single could be used.
ExpiryDate The expiration date of the document in ISO 8601 format
ExpiryDate2 The second expiry date of the document in ISO 8601 format
ExpiryDate3 The third expiry date of the document in ISO 8601 format
ExpiryDate4 The fourth expiry date of the document in ISO 8601 format
EyeColor The eye colour of the document holder
FatherName The father name extracted from the document
Fingerprint The finger print extracted from the document
FirstIssuanceDate The first issue date of this document in ISO 8601 format
FirstName The first name extracted from the document
FirstNameInitial The first character of the first name extracted from the document
FullName The full name extracted from document
HairColor The hair colour of the document holder
HealthNumber The health number extracted from the document
Height The height of the document holder
Hologram The hologram extracted from the document
IssueDate The issue date of the document in ISO 8601 format
IssueDate2 The second issue date of the document in ISO 8601 format
IssueDate3 The third issue date of the document in ISO 8601 format
IssueDate4 The fourth issue date of the document in ISO 8601 format
IssueNumber The issue number extracted from the document
IssuingAuthority The authority issuing the document
IssuingAuthorityType The type of the authority issuing the document
IssuingLocation The location where the document was issued
LastName The last name extracted from the document
LastNameFirstPart The first few characters of the last name extracted from the document
LensData The lens data of the document holder
LicenseCategory The license category of the document
LicenseCategory2 The second license category of the document
LicenseCategory3 The third license category of the document
LicenseCategory4 The fourth license category of the document
LicenseNumber The license number of the document
LicenseType The type of the license specified in the document.
LicenseType2 The second type of the license specified in the document.
LicenseType3 The third type of the license specified in the document.
LicenseType4 The fourth type of the license specified in the document.
MaritalStatus The marital status of the document holder (single or married).
MembershipNumber The membership number extracted from the document
MiddleName The middle name extracted from the document
MiddleNameInitial The first character of the middle name
MotherName The mother name extracted from the document
MRZBirthDateCheckDigit The check digit of the date of birth contained in the MRZ
MRZCode1 The first letter of the MRZ which specifies the first part of the MRZ code. This can
specify the type of the doc. such as P for passports, I for identity cards and so on
MRZCode2 The second letter of the MRZ which specifies the second part of the MRZ code.
This can specify the subtype of the document and is country-specific
MRZCompositeCheckDigit The composite check digit of the MRZ
MRZDocumentNumberCheckDigit The check digit of the document number contained in the MRZ
MRZExpiryDateCheckDigit The check digit of the expiry date contained in the MRZ
MRZFull The full MRZ (all lines)
MRZLine1 The first line of the MRZ
MRZLine2 The second line of the MRZ
MRZLine3 The third line of the MRZ
MRZPersonalNumberCheckDigit The check digit of the personal number contained in the MRZ
MRZStandardType The standard type of the ICAO document

USING IDENTITY INTELLIGENTLY

 GBG IDscan IEOS Web API

NationalInsuranceNumber The National Insurance number extracted from the document

NationalityCode The nationality ISO code of the document holder
NationalityName The nationality of the document holder
ObservationPage The observation page number of the document
Occupation The occupation of the document holder
Parents The names of the document holder's parents
PeriodOfStay The allowed period for stay extracted from the document
PermitNumber The permit number of the document
PersonalNumber The personal number extracted from the document
PortraitPhoto The document holder's photo extracted from the document
Race The race of the document holder
ReferenceNumber The reference number of the document
Remarks Any remark mentioned in the document
RFIDG1 The raw data from RFID (Data Group 1)
RFIDG15 The raw data from RFID (Data Group 15)
RFIDG2 The raw data from RFID (Data Group 2)
RFIDG3 The raw data from RFID (Data Group 3)
RFIDPortraitPhoto The document holder's photo stored in the biometric chip (after decoding)
RFIDSOD The raw data from RFID
SecondaryPortraitPhoto The second portrait photo extracted from the document if exists
SecondLastName The second last name extracted from the document. This is special case in some
documents where the two last names exist
Sex The gender of the document holder
Signature The signature of the document holder (Image)
SocialSecurityNumber The social security number extracted from the document
StudentID The student identification number extracted from the document
TaxNumber The tax number extracted from the document
Title The title of the document holder such as Mr, Ms and so on
VAFNumber The visa application form number extracted from the document
VersionNumber The version number of the document
Weight The weight of the document holder

Possible extracted fields from utility bills, bank statements and other non-ID documents:
Field Description
DocumentCategory High level category of the document type.
DocumentType Type of the document as recognised by IDscan Document Expert System.
IssueDate Issuing date of the document.
Issuer Issuer of the document. For example the bank name in case of bank statements.
Logo Logo of the issuer of the document if present on the document.
RecipientAddress Full address of the recipient, the entity addressed in the document.
RecipientName Name of the entity(s) addressed in this document. Could be one person or more or a company.

USING IDENTITY INTELLIGENTLY