This method explains what fields your account has configured for the selected country.
The GlobalGateway Get Fields call returns exactly this information. For example, the response to a GetFields call in China might look like this:
{
"title": "DataFields",
"type": "object",
"properties": {
"PersonInfo": {
"title": "PersonInfo",
"type": "object",
"properties": {
"FirstGivenName": {
"type": "string",
"description": "First name of the individual to be verified",
"label": "First Name (名)"
},
"MiddleName": {
"type": "string",
"description": "Second given name of the individual to be verified",
"label": "Middle Name"
},
"FirstSurName": {
"type": "string",
"description": "Last name of the individual to be verified",
"label": "Last Name (姓)"
},
"ISOLatin1Name": {
"type": "string",
"description": "ISO Latin 1 Full name as it appears on passport",
"label": "Passport Full Name"
},
"DayOfBirth": {
"type": "int",
"description": "Day of birth date (ie 23 for a date of birth of 23/11/1975)",
"label": "Day Of Birth (日)"
},
"MonthOfBirth": {
"type": "int",
"description": "Month of birth date (ie 11 for a date of birth of 23/11/1975)",
"label": "Month Of Birth (月)"
},
"YearOfBirth": {
"type": "int",
"description": "Year of birth date (ie 1975 for a date of birth of 23/11/1975)",
"label": "Year Of Birth (年)"
},
"Gender": {
"type": "string",
"description": "Gender, may be 'M' for male or 'F' for female",
"label": "Gender"
},
"AdditionalFields": {
"type": "object",
"description": "Family name and given names, together as found on identification documents",
"label": "Full Name (姓名)",
"properties": {
"title": "AdditionalFields",
"type": "object",
"properties": {
"FullName": {
"type": "string",
"description": "Family name and given names, together as found on identification documents",
"label": "Full Name (姓名)"
}
},
"required": [
"FullName"
]
}
}
},
"required": [
"FirstGivenName",
"FirstGivenName",
"FirstSurName",
"FirstSurName",
"AdditionalFields",
"ISOLatin1Name"
]
},
"Location": {
"title": "Location",
"type": "object",
"properties": {
"BuildingNumber": {
"type": "string",
"description": "Building number of home address",
"label": "Building Number (楼房号码)"
},
"BuildingName": {
"type": "string",
"description": "Building name of home address",
"label": "Building Name (楼房名称)"
},
"UnitNumber": {
"type": "string",
"description": "Flat/Unit/Apartment number of primary residence",
"label": "Unit Number"
},
"StreetName": {
"type": "string",
"description": "Street name of primary residence",
"label": "Street Name (街道名称)"
},
"StreetType": {
"type": "string",
"description": "Street type of primary residence (Typically St, Rd etc)",
"label": "Street Type (街道种类)"
},
"City": {
"type": "string",
"description": "City of home address",
"label": "City (城市)"
},
"Suburb": {
"type": "string",
"description": "City or Suburb of primary residence",
"label": "Suburb"
},
"County": {
"type": "string",
"description": "County of home address",
"label": "County (县)"
},
"StateProvinceCode": {
"type": "string",
"description": "State or Province",
"label": "State Province"
},
"PostalCode": {
"type": "string",
"description": "ZIP Code or Postal Code of primary residence",
"label": "Postal Code"
},
"POBox": {
"type": "string",
"description": "Post Office Box",
"label": "PO Box"
},
"AdditionalFields": {
"type": "object",
"description": "Street address of primary residence",
"label": "Address 1",
"properties": {
"title": "AdditionalFields",
"type": "object",
"properties": {
"Address1": {
"type": "string",
"description": "Street address of primary residence",
"label": "Address 1"
}
},
"required": []
}
}
},
"required": []
},
"Communication": {
"title": "Communication",
"type": "object",
"properties": {
"Telephone": {
"type": "string",
"description": "Telephone number of the individual to be verified",
"label": "Telephone (固定电话号码)"
},
"EmailAddress": {
"type": "string",
"description": "Email Address",
"label": "Email Address"
}
},
"required": [
"EmailAddress"
]
},
"NationalIds": {
"title": "NationalIds",
"type": "object",
"properties": {
"Number": {
"type": "string",
"description": "(National ID Number)"
},
"Type": {
"type": "string",
"value": "nationalid"
},
"DistrictOfIssue": {
"type": "string",
"description": "District where document was issued",
"label": "District Of Issue (发证区)"
},
"CityOfIssue": {
"type": "string",
"description": "City where document was issued",
"label": "City Of Issue (发证城市)"
},
"ProvinceOfIssue": {
"type": "string",
"description": "Province where document was issued",
"label": "Province Of Issue (发证省)"
},
"CountyOfIssue": {
"type": "string",
"description": "County where document was issued",
"label": "County Of Issue (发证县)"
}
},
"required": [
"ProvinceOfIssue",
"nationalid"
]
},
"CountrySpecific": {
"title": "CountrySpecific",
"type": "object",
"properties": {
"CN": {
"title": "CN",
"type": "object",
"properties": {
"PassportMRZLine1": {
"type": "string",
"description": "First line of the Machine Readable Zone (MRZ) of passport, 44 letters and digits, i.e. 'P<CZESPECIMEN<<VZOR<<<<<<<<<<<<<<<<<<<<<<<<<'",
"label": "Passport MRZ Line 1 (护照第一行MRZ)"
},
"PassportMRZLine2": {
"type": "string",
"description": "Second line of the Machine Readable Zone (MRZ) of passport, 44 letters and digits, i.e. '99003853<1CZE1101018M1207046110101111<<<<<94'",
"label": "Passport MRZ Line 2 (护照第二行MRZ)"
},
"PassportDayOfExpiry": {
"type": "string",
"description": "Day of month of expiration of passport, 2 digits, i.e. '14'",
"label": "Passport Day Of Expiry"
},
"PassportMonthOfExpiry": {
"type": "string",
"description": "Month of year of expiration of passport, 2 digits, i.e. '08'",
"label": "Passport Month Of Expiry"
},
"PassportNumber": {
"type": "string",
"description": "Passport number of the individual to be verified",
"label": "Passport Number (护照号)"
},
"PassportYearOfExpiry": {
"type": "string",
"description": "Year of expiration of passport, 4 digits, i.e. '1980'",
"label": "Passport Year Of Expiry"
}
},
"required": [
"PassportMRZLine1",
"PassportMRZLine2"
]
}
}
}
}
}
There is a lot of information in the response shown above, so we will break it down. The simplest way to think about it, is as a list of objects.
The List
The first list of keys is our top level. These are the GlobalGateway DataObjects, so in the example above, if you were to iterate over each of these you will have the list of object keys: ["PersonInfo", "Location", "Communication", "NationalIds", "CountrySpecific"]. You can loop over these keys with a simple iterator, for example in JavaScript:
for (var key in properties) {
console.log(key + " -> " + properties[key]);
}
The Data Fields
Inside each DataObject is a list of all the fields available for verification. For PersonInfo in the example above, the list is ["FirstGivenName", "MiddleName", "FirstSurName", "ISOLatin1Name", "DayOfBirth", "MonthOfBirth", "YearOfBirth", "Gender", "AdditionalFields"]
for (var key in properties) {
for (var fields in key) {
console.log(fields + " -> " + key[fields]);
}
}
In case of a web form, these are the fields that have to be translated into user input. If you are integrating into an existing code flow, make sure you have gathered at least the required fields by the time you make your Verify request.
You can see below, that each field includes the type of field and the label that can be used for display, making it quick and easy to create the form dynamically:
var form = document.createElement("form");
for (var key in properties) {
for (var fields in key) {
var input = document.createElement("input"); //input element, text
input.setAttribute('type',fields.type);
input.setAttribute('name',fields.label);
form.appendChild(input);
}
}
var submit = document.createElement("input"); //input element, Submit button
submit.setAttribute('type',"submit");
submit.setAttribute('value',"Submit");
form.appendChild(submit);
Required
Each top-level DataObject contains a list of required fields underneath the "required" node. This is the collection of required fields across all datasources in the requested country. For "PersonInfo" in the example above, this array is: ["FirstGivenName", "FirstGivenName", "FirstSurName", "FirstSurName", "AdditionalFields", "ISOLatin1Name"]. You will notice that these values are a subset of the fields listed in the previous section. When building your form you can reference this list to set particular elements as mandatory for your users to provide.
Country Specific
You may have also noticed the top level object CountrySpecific. For the most part, while the exact list of available and required fields may vary from country to country, each field has the same name in each country where it is available. As an example, although the national ID numbers of the U.S. and India has different names (SSN and Aadhar), both can be sent to GlobalGateway simply as NationalIDNumber. This simplifies the integration process if you have multiple countries configured for your account, since you don't need to keep track of what each field is named in each country.
However, some countries have fields that do not fit into this normalized model. These fields are returned underneath the CountrySpecific node, and have to be handled specially for that country. For example, for a GetFields call in Australia you might see:
"CountrySpecific": {
"title": "CountrySpecific",
"type": "object",
"properties": {
"AU": {
"title": "AU",
"type": "object",
"properties": {
"AuImmiCardNumber": {
"type": "string"
}
}
}
}
}
In the above response, you can see that for Australia there is a very specific field called AuImmiCardNumber. This is returned in CountrySpecific because it is an input specifically for Australia and no other country.
JSON Schema
The GetFields response follows the JSON schema format. This gives you the option of using a library to automatically generate UI elements from the GetFields call. A list of possible libraries is given here.