Overview

Version 3 of the document image service includes capability to return the document type and region of the document the user initially selected (or was asked to take a photo of, depending on the configuration of your account) and what document type and region the greenID system detected they actually took a photo of. This is returned in the getInfoForAllDocuments method.

This new information is also returned by getVerificationResult if your configuration supports it so it's possible to retrieve the values from either call if required. Information on how the information is returned for getVerificationResult can be found in the Mobile Specific greenID API Results page.

Please note that not all document types can be detected by our system at this time, for a list of all documents which can be detected please take a look at our /wiki/spaces/GREEN/pages/220954974 page. 

Version 3 also contains the new method getDocUploadImages. This method returns the additional document upload (if present on the transaction) as either a url that is live for 30 minutes (the image can be downloaded from this url) or the base64 encoded image.

Initial Setup

This is a WSDL based web service and as such is consumed in the normal WSDL way using the below URLs. 

Request Parameters

Required Parameters

accountId - The account code provided to you as a customer for use with greenID

password - The webservice password provided to you as a customer for use with greenID

verificationId - The verificationId of the verification you wish to get the information for.

Optional Parameters

getConfirmedOcrData - Set to true to get the confirmed OCR data for all combination source attempts.

getRawOcrData - Set to true to get the raw OCR data for all combination source attempts.

getImageData - Set to true to return document image and selfie information for all combination source attempts. Please note that this function is disabled by default, please contact us at support@edentiti.com to have this enabled for your account.

Optional parameters are passed into the webservice using the a param tag which needs the parameter name and value to be set. All of the parameters can be set to either true or false and will include or exclude their corresponding elements based on the setting, true will return the corresponding data, false will exclude it. If a parameter is not provided it will default to false.

The operation which returns the image data is more intensive for us then the other two so we ask that you keep your calls to get the image data to a minimum.

Example Payloads

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dyn="http://dynamicform.services.registrations.edentiti.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <dyn:getInfoForAllDocuments>
         <accountId>account_id</accountId>
         <password>web-service-password</password>
         <verificationId>A1a1aAAA</verificationId>
         <param>
            <name>getConfirmedOcrData</name>
            <value>true</value>
         </param>
         <param>
            <name>getRawOcrData</name>
            <value>true</value>
         </param>
         <param>
            <name>getImageData</name>
            <value>true</value>
         </param>
      </dyn:getInfoForAllDocuments>
   </soapenv:Body>
</soapenv:Envelope>

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Header/>
   <env:Body>
      <ns2:getInfoForAllDocumentsResponse xmlns:ns2="http://dynamicform.services.registrations.edentiti.com/">
         <return>
            <document>
               <confirmed>
                  <confirmedItem>
                     <name>surname</name>
                     <value>SMITH</value>
                  </confirmedItem>
                  <confirmedItem>
                     <name>documentNumber</name>
                     <value>A1111111</value>
                  </confirmedItem>
               </confirmed>
               <images>
                  <imageItem>
                     <index>FRONT</index>
                     <url>https://s3-ap-southeast-2.amazonaws.com/public.folder.test/images/123.jpg</url>
                  </imageItem>
                  <imageItem>
                     <index>FACE</index>
                     <url>https://s3-ap-southeast-2.amazonaws.com/public.folder.test/images/1234.jpg</url>
                  </imageItem>
                  <imageItem>
                     <index>SELFIE</index>
                     <url>https://s3-ap-southeast-2.amazonaws.com/public.folder.test/images/12345.jpg</url>
                  </imageItem>
               </images>
               <raw>
                  <rawItem>
                     <name>surname</name>
                     <value>SMITH</value>
                  </rawItem>
                  <rawItem>
                     <name>documentNumber</name>
                     <value>A2222222</value>
                  </rawItem>
               </raw>
               <detectedDocumentType>
               	  <documentRegion>XU</documentRegion>
                  <documentSubregion/>
                  <documentType>UNKNOWN</documentType>
               </detectedDocumentType>
			   <selectedDocumentType>
                  <documentRegion>AU</documentRegion>
                  <documentType>PASSPORT</documentType>
               </selectedDocumentType>
            </document>
         </return>
      </ns2:getInfoForAllDocumentsResponse>
   </env:Body>
</env:Envelope>

Return Data

It is important to note that though this example only contains one document object real results may contain none or several as a single verification can have multiple combination source attempts. The same is true for confirmedItems and rawItems, real results are likely to contain many more results, but will provide these additional fields in the same format.

• document - This is a single document container, it represents a single combination source attempt and contains all other return data.
  • selectedDocumentType - The document type selected by the user when the registration was created, you can think of it as what the document is supposed to be.
    • region - The region of the document used for the combination source attempt.
    • subregion - The subregion of the document used for the combination source attempt, will default to "unknown" if no subregion is used on the document.
    • type - The document type of the combination source.
  • detectedDocumentType  - The document type we detected the document to actually be, this may be different then the selectedDocumentType or the same depending on what the user submitted and how well our system was able to catogorise it. In some cases the document type may be returned as unknown if the document sumitted is not supported or the images were not of good enough quality to support recognition.
    • region - The region of the document used for the combination source attempt.
    • subregion - The subregion of the document used for the combination source attempt, will default to "unknown" if no subregion is used on the document.
    • type - The document type of the combination source.
  • confirmed - An object which contains the list of confirmedItems.
    • confirmedItem - A single confirmed data item such as a name or document number. 
      
      • name - The name of the field, could also be considered to be key.
      • value - The value of the field.
  • images - an object which contains the list of images for the combination source
    • imageItem - A single imageItem object containing information about a single image.
      • index - the index contains the type of image, possibilities include: FRONT, BACK, FACE and SELFIE. Please note that not all documents will have any or all of these indexes attached since they are not always captured depending on the account settings and the how the capture process went for the user.
      • url - The url of the image file.
  • raw - an object which contains the list of rawItems, can be empty if no fields were successfully OCRed off the document.
    • rawItem - A single raw data item such as a name or DoB, etc. Please note that these field can contain all sorts of weird and wonderful characters since it is the raw output from the OCR process. In addition only the fields which were successfully OCRed will be returned, the fields returned can and will fluctuate depending on the OCR result.
      • name - The name of the field,could also be considered to be key.
      • value - The value of the field.

Possible Names

Regarding the rawItem and confirmedItem names the current list of possible keys are:

General

• givenname
• middlename
• surname
• dob
• country

Document Related

• documentNumber
• secondaryDocumentNumber
• documentExpiryDate
• documentIssueDate
• documentType
• documentRegion
• documentGender

Address Related

• propertyName
• flatNumber
• streetNumber
• streetName
• streetType
• postcode
• townCity
• state

Notes on the name list

• This list is likely to expand as more document types with weird and wonderful fields continue to be added.
• The rawItem list will almost always only contain a subset of the confirmedItems since extra data (such as documentRegion and country) are added when the confirmed data is passed. 

Detecting Changes

Comparing Fields

A common scenario for using this web service is to detect changes that the person made during the confirmation step.  The simplest way to do this is to compare the values from the raw and confirmed elements in the response.

In the example given above, the surname element is the same in both the raw and confirmed elements, therefore the person did not change the surname that was extracted from the card using OCR.  However, the documentNumber field is different between the raw and confirmed elements, so the person did change the value during the confirmation step.  Specifically, the value A2222222 was extracted from the card using OCR, and the person changed it to A1111111.

Comparing Selected and Detected Document Types 

Each attempt will have one selectedDocumentType and one detectedDocumentType:

• selectedDocumentType - The document type the user selected as the type they were going to photograph at the start of the process, or the document type passed into the SDK on start if the select document screen is disabled. This is the document type they are supposed to be taking a photo of.
• detectedDocumentType -  This is the document type our system has detected the user to have actually submitted. This type can and will be different to the selected type if the user uses something other then what they said they were going to, for example using a drivers licence in stead of a national ID card. Please be aware that our system may not be able to detect what document was submitted in all cases. If it could not detect the type of the document then the document type will be returned as unknown (UNKNOWN.XU).

Result Components:

• documentType -  The type of the document, eg DRIVERS_LICENCE, NATIONAL_ID_CARD, PASSPORT, UNKNOWN, etc.
• documentRegion - The region of the docuement, eg AU (for Australian documents), SG (for Singaporen document), NZ (for New Zealander documents), XU (for Unknown) etc.

Please note that for some document the documentRegion will contain a subregion seporated by a - (dash) eg, AU-NSW (for Australia, New South Wales).

Common Problems and Solutions

Request Parameters

Required Parameters

accountId - The account code provided to you as a customer for use with greenID

password - The webservice password provided to you as a customer for use with greenID

verificationId - The verificationId of the verification you wish to get the information for.

Optional Parameters

getImageData - Set to true to get the document upload for the transaction. If this is set to false then only the name of the document upload will be returned. e.g. Telephone Bill

NOTE: The web service request cannot be used to control the format in which the image is returned. Images can be returned as a base64 encoded image or as a url that will be active for 30 minutes. This is a greenID server side setting that will be handled by the support team.

Example Payloads

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dyn="http://dynamicform.services.registrations.edentiti.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <dyn:getDocUploadImages>
         <accountId>account_id</accountId>
         <password>web-service-password</password>
         <verificationId>A1a1aAAA</verificationId>
         <param>
            <name>getImageData</name>
            <value>true</value>
         </param>
      </dyn:getDocUploadImages>
   </soapenv:Body>
</soapenv:Envelope>

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Header/>
   <env:Body>
      <ns2:getDocUploadImagesResponse xmlns:ns2="http://dynamicform.services.registrations.edentiti.com/">
         <return>
            <document>
               <dateCreated>2018-08-14T12:16:47.703+1000</dateCreated>
               <images>
                  <imageItem>
                     <index>Telephone Bill</index>
                     <url>https://s3-ap-southeast-2.amazonaws.com/public.folder.test/images/12345.jpg</url>
                  </imageItem>
               </images>
            </document>
         </return>
      </ns2:getDocUploadImagesResponse>
   </env:Body>
</env:Envelope>

Return Data

• document - This is a single document container, it represents a single combination source attempt and contains all other return data.
  • images - an object which contains the list of images for the combination source
    • imageItem - A single imageItem object containing information about a single image.
      • index - the index contains the type of image. This will be the name of the document upload the user selected e.g Telephone bill or Rates Notice. 
      • url - The url of the image file OR 
      • raw - The image in base64 encoded format

Common Problems and Solutions

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Header/>
   <env:Body>
      <ns2:getDocUploadImagesResponse xmlns:ns2="http://dynamicform.services.registrations.edentiti.com/">
         <return/>
      </ns2:getDocUploadImagesResponse>
   </env:Body>
</env:Envelope>