The DocumentImageService web service is used to access image and OCR information from greenID mobile, including but not limited to; raw OCR information, confirmed user information and document images. This web service provides this information for each combination source attempt for a given verificationId. Version 3 is the most recent version, changes between the versions are to do with how the document type is returned and the addition of document type detection capability. Customers are not required to upgrade to version 3 at this time but may optionally use the new version (version 3) if they require document detection functionality. 

Document Image Service V3 (New)

For information on version 3 of the Document Image Service please refer to the Document Image Service V3 Page.

Document Image Service V2 (Existing)

Setup

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

This webservice can be accessed on our test servers using: 

And in Australian production using: https://au.vixverify.com/Registrations-Registrations/DocumentImageServiceV2?wsdl

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@vixverify.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

<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>
               <region>NZ</region>
               <subregion>unknown</subregion>
               <type>PASSPORT</type>
            </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.
  • 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

Last Updated: 02 Dec 2016 

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

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.

Common Problems and Solutions