Insert excerpt

	Version 2 greenID API
	Version 2 greenID API
nopanel	true

In the Web Method Details section, there is a complete discussion of the parameters that are passed to, and returned from, the Web Service methods in the API. This This section provides additional conversation about the most important elements, what those elements mean, and their relevance to the verification process.

Table of Contents

Interpreting the sourceList

A call to any method in the greenID API will return, as part of the CurrentStatus object, a sourceList element. The sourceList contains the currentStatusV2 object, a sourceList element. The sourceList contains a list of data sources that can contribute to the person's verification attempt. This This list of sources is not fixed, it is computed based on the current state of the person's verification attempt, so it can be useful because it can indicate which data sources are not worth attempting, and also which data sources, if passed, will result in the person being verified immediately (we refer to this as "one source left").

Consider the snippet of XML below:

Code Block

language	xml

<sourceList>
     <sources>
         <available>true</available>
         <name>nswregodvs</name>
         <notRequired>false</notRequired>
         <oneSourceLeft>false</oneSourceLeft>
         <order>1</order>
         <passed>false</passed>
         <state>EMPTY</state>
         <version>1</version>
     </sources>
     ...
 <sourceList>

This output shows a single source in a sourceList. One One of the most important elements here is the name element, which contains the name of the data source, which is "nswregodvs" in this case. This This name is used to refer to this data source when calling setFieldscalling setFields. The The other important elements are described below:

available available - if the data source is able to be used, then this element will contain "true", otherwise it will contain "false". If If a data source is not available (usually because greenID cannot currently access the data source), then setFields should then setFields should not be called for that data source, since the call will fail.
passed passed - if the data source has been previously attempted, and passed, then this element will contain "true", otherwise it will contain "false". If If the data source is passed, then calling setFields for calling setFields for that data source will fail, and have no effect.
oneSourceLeft oneSourceLeft - this element indicates if this data source is sufficient to get the person completely verified. If If this element contains "true", then callingsetFields for calling setFields for this data source, and having a successful outcome, will be enough to get the person completely verified. The The value is computed based on the current state of the person's verification attempt, so it can change after calls to setFieldsto setFields.
state state - while the passed element provides a simple yes/no indication of whether the person has successfully completed this data source, the state element provides a more detailed indication. Please Please refer to the detailed description of the CheckResult type the CheckResult type below for the list of values that may appear in this field.
notRequired notRequired - this element indicates whether this data source can contribute to the person's verification attempt. If If this field contains "true", then there is no value in attempting this data source, since it cannot make any difference the person's verification attempt. A A call to setFields for to setFields for this data source would be wasted.

Interpreting the sourceFields

A call to getFields for to getFields for a given data source (using the name provided in the sourceList, detailed above), will return a list of data fields required for that data source. If If the fields are filled, by collecting data from the person being verified, and passed to setFieldsto setFields, then the data source will be checked. HoweverHowever, there is a lot of detail in the return object from getFieldsfrom getFields, and it is important to know what to do with the information.

The main aim of the getFields method the getFields method is to provide the customer with enough detail to render HTML input fields to collect input from the person being verified. GreenID GreenID also generates an HTML fragment that can be used directly, if desired. This This is discussed in more detail later.

The getFields method returns a CurrentStatus objectThe getFields method returns a currentStatusV2 object, like all the other methods, but with the sourceFields member the sourceFields member populated. Below Below is a snippet of XML from a SOAP envelope:

Code Block

language	xml

<sourceFields>
   <fieldList>
      <sourceField>
         <attribute>
            <name>id</name>
            <value>greenid_nswregodvs_number</value>
         </attribute>
         <attribute>
            <name>class</name>
            <value>form-control required</value>
         </attribute>
         <attribute>
            <name>aria-required</name>
            <value>true</value>
         </attribute>
         <label>Licence number</label>
         <name>greenid_nswregodvs_number</name>
         <type>text</type>
         <value/>
      </sourceField>
      <sourceField>
         <attribute>
            <name>id</name>
            <value>greenid_nswregodvs_givenname</value>
         </attribute>
         <attribute>
            <name>class</name>
            <value>form-control namevalidation required</value>
         </attribute>
         <attribute>
            <name>aria-required</name>
            <value>true</value>
         </attribute>
         <label>First name</label>
         <name>greenid_nswregodvs_givenname</name>
         <type>text</type>
         <value>Test</value>
      </sourceField>
      <sourceField>
         <attribute>
            <name>id</name>
            <value>greenid_nswregodvs_middlename</value>
         </attribute>
         <attribute>
            <name>class</name>
            <value>form-control</value>
         </attribute>
         <attribute>
            <name>aria-required</name>
            <value>false</value>
         </attribute>
         <label>Middle name(s)</label>
         <name>greenid_nswregodvs_middlename</name>
         <type>text</type>
         <value>Q</value>
      </sourceField>
      <sourceField>
         <attribute>
            <name>id</name>
            <value>greenid_nswregodvs_surname</value>
         </attribute>
         <attribute>
            <name>class</name>
            <value>form-control namevalidation required</value>
         </attribute>
         <attribute>
            <name>aria-required</name>
            <value>true</value>
         </attribute>
         <label>Surname</label>
         <name>greenid_nswregodvs_surname</name>
         <type>text</type>
         <value>Citizen</value>
      </sourceField>
      <sourceField>
         <attribute>
            <name>id</name>
            <value>greenid_nswregodvs_dob</value>
         </attribute>
         <attribute>
            <name>class</name>
            <value>form-control dobvalidation required</value>
         </attribute>
         <attribute>
            <name>aria-required</name>
            <value>true</value>
         </attribute>
         <label>Date of birth (dd/mm/yyyy)</label>
         <name>greenid_nswregodvs_dob</name>
         <type>text</type>
         <value>01/01/1980</value>
      </sourceField>
      <sourceField>
         <attribute>
            <name>id</name>
            <value>greenid_nswregodvs_tandc</value>
         </attribute>
         <attribute>
            <name>class</name>
            <value>required</value>
         </attribute>
         <attribute>
            <name>aria-required</name>
            <value>true</value>
         </attribute>
         <label>I consent to the information above being checked with the Issuer or Official Record Holder</label>
         <name>greenid_nswregodvs_tandc</name>
         <type>checkbox</type>
      </sourceField>
      ...
   </fieldList>
   ...
</sourceFields>

Each sourceField element Each sourceField element represents a single data field that is required for the data source. The fieldList element The fieldList element contains a list of sourceField elementsof sourceField elements, which, in totality, represent all the fields required for the data source.

Important elements of the sourceField element the sourceField element are:

name name - contains the name of the field. This This name is used when the data fields are passed to setFields. Because Because of this, the names can be a little long. The The id is also the suggested id for the field if it is rendered in HTML The . The names are also prefixed with "greenid_" in order to avoid name clashes with anything else that might be on the customer's page.
label label - please see the section about Labels.
type type - indicates the type of the field, and this corresponds to an HTML input field type. Most Most fields are "text" fields. In In the example above, thegreenidthe greenid_nswregodvs_tandc field tandc field is a checkbox, which should be rendered using an HTML checkbox input field.
value value - contains any pre-existing value. For For example, from the snippet above, the greenidthe greenid_nswregodvs_givenname field givenname field has a pre-existing value of "Test". Customers Customers should include this value when rendering HTML input fields.

Each sourceField element Each sourceField element also contains a list of attribute elements. These These attributes are intended to be applied to HTML input fields that are rendered to gather input from the person being verified. The name element The name element is the intended name of the attribute, and the value element is the intended value of the attribute. For For example, from the snippet above, the greenidthe greenid_nswregodvs_number input number input field is intended to have the HTML attributes "id='greenid_nswregodvs_number' class='required'" applied applied when rendered in HTML.

So the goal is that customers can read the fieldList elementthe fieldList element, and get enough information to render HTML dynamically. Of Of course, given that the fields and their names are not subject to frequent change, their values can be assumed.

The sourceFields element The sourceFields element also contains an element called rawData that called rawData that contains a pre-rendered HTML fragment that can be used directly by the customer, if desired. From From the example above, the rawData element the rawData element contains:

Code Block

language	xml

<rawData><![CDATA[<?xml version="1.0"?>
	<sourcefields>
		<div class="row">
			<div class="form-group col-sm-3">
				<label for="greenid_nswregodvs_number" class="control-label">{{{nswregodvs_number_label}}}
			                <span class="greenid-helpicon" title="{{{nswregodvs_number_tooltip}}}">
			                      <span class="greenid-sr-only">{{{nswregodvs_number_tooltip}}}</span>
			                </span>
			        </label>
				<input type="text" name="greenid_nswregodvs_number" id="greenid_nswregodvs_number" class="required" value=""/>
			</div>
		</div>
		<div class="row">
			<div class="form-group col-sm-4">
				<label for="greenid_nswregodvs_givenname">{{{nswregodvs_givenname_label}}}</label>
				<input type="text" name="greenid_nswregodvs_givenname" id="greenid_nswregodvs_givenname" class="form-control namevalidation required" value="Test"/>
			</div>
			<div class="form-group col-sm-4">
				<label for="greenid_nswregodvs_surname">{{{nswregodvs_surname_label}}}</label>
				<input type="text" name="greenid_nswregodvs_surname" id="greenid_nswregodvs_surname" class="form-control namevalidation required" value="McTestie"/>
			</div>
		</div>
		<div class="row">
			<div class="form-group col-sm-3">
				<label for="greenid_nswregodvs_dob">{{{nswregodvs_dob_label}}}</label>
				<input type="text" name="greenid_nswregodvs_dob" id="greenid_nswregodvs_dob" class="form-control dobvalidation required" value="01/02/1980"/>
			</div>
		</div>
		<div class="checkbox">
			<label for="greenid_nswregodvs_tandc">
			<input type="checkbox" name="greenid_nswregodvs_tandc" id="greenid_nswregodvs_tandc" class="required"/> {{{nswregodvs_tandc_label}}}</label>
		</div>
	</sourcefields>]]>
</rawData>

The HTML fragment is the result of the most basic strategy for taking the input fields, as listed in the fieldList elementthe fieldList element, and transforming them into HTML. The customer is free to use this HTML fragment, or ignore it.

Tooltips returned in rawData and accessibility

Note: this section only relates to versions of the rawData HTML prior to April 2016 and remains here to help customers using these versions.

Some field labels returned in the rawData HTML include tooltips to provide additional explanatory information to the user about the field requirements. The tooltip wording is included in two ways in the returned HTML (see nswregodvs_number_tooltip in the sample above). It is included in the title attribute of the .greenid-helpicon tooltip element because this is the way that many popular tooltip javascript libraries work (e.g. Bootstrap, jQuery UI, Tooltipster). However, the titleattribute is usually not accessible to screen reader users (e.g. those with visual disabilities), so the tooltip content is included a second time for the benefit of screen readers in the .greenid-sr-only element.

If you use the rawData HTML provided, you will need to add the following to your CSS file to ensure that this screenreader-only content is hidden from the screen but available to screen readers:

Code Block

language	css

.greenid-sr-only { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip: rect(0,0,0,0); border: 0; }

Versions Compared

Old Version 1

New Version Current

Key

Interpreting the sourceList

Interpreting the sourceFields

Tooltips returned in rawData and accessibility

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

Interpreting the sourceList

Interpreting the sourceFields

Tooltips returned in rawData and accessibility