Overview
While GDC's Worldview API is extremely powerful and flexible, this can sometimes introduce confusion regarding the myriad of input fields that are available, and the complexity of the response returned. This guide will outline some best practices for utilizing various input fields, and provide guidance on the most important elements of the response.
Most of these suggestions are relevant to both electronic Identity Verification (eIDV)/ Know Your Customer (KYC) and Business Verification (BV) use cases. Items that are specific to a single use case will be identified as such.
Request Structure: Overlapping Input Fields
There are a few different input fields that may overlap in terms of the data that would normally be provided. These will be separated into Name fields and Address fields, to align with the request structure of the Worldview API.
Name Fields (eIDV/KYC only)
Separate First and Last Names
There are two primary name fields that are used to capture an individual's first and last name, respectively. In most cases, these names will be captured/stored in your systems as separate fields, and therefore can easily be mapped to the following input fields in Worldview:
- givenfullname: the individual's first or given name. Multiple first or given names can be provided in this field, separated by a space
- surname_first: the individual's last name or surname. In most cases, multiple last names or surnames can be provided in this field, separated by a space
Multiple First or Last Names
In some cases, match rates may be improved if all names are combined together and provided in a single field (in addition to being sent separately in the givenfullname and surname_first fields above). For this purpose, the completename field can be used:
- completename: all first and last names for the individual combined into a single string (separated by spaces)
If first and last names are not captured/stored in your system as separate fields, then the completename field should be used. We recommend against separating or parsing a single name field into multiple names, as incorrectly parsing the names could negatively impact match rates.
Spanish Names (Spain, Central America, South America, excluding Brazil)
In Spanish speaking countries, it's typical to have two last names or surnames, where the first one is often referred to as the Paternal Surname, and the second one is often referred to as the Maternal Surname. When exactly two surnames are captured in a Spanish speaking country (and they are captured/stored in your systems as separate surnames), the following fields and methodology should be used:
- givenfullname: the individual's first or given name (including multiple first or given names, separated by a space)
- surname_prefix_first: the individual's first surname (paternal surname)
- surname_first: the individual's second surname (maternal surname).
- If only one surname is present, it should be provided in this field, and surname_prefix_first can be ignored (even if the single surname is known to be the paternal surname)
It is not necessary to provide all names combined together in the completename field for Spanish speaking countries.
Address Fields
Similar to name fields, there are a couple of address fields that can be used depending on whether the address information is captured/stored in your system in separate, parsed fields, or combined into one or two more generic address lines.
Parsed Addresses
If you capture/store addresses in your systems in multiple parsed fields, these can be sent to Worldview as separate fields, which can help to improve match rates and provided more accurate match messages and responses. For the first line or two found in a typical address, the following parsed fields can be used:
- houseNumber: the street number, building number, or house number part of the address
- thoroughfare: the street name part of the address, optionally including the street type written out or abbreviated (e.g. "Street", "St", "Road", "Rd", etc.)
- houseNumberAddition: a "sub-premise" element, typically a floor number, apartment letter/number, flat or unit letter/number, etc.
It's acceptable to combine both houseNumber and houseNumberAddition into the houseNumber field (separated by a space, dash, or slash) if this is reflective of how the data is captured/stored in your systems.
Unparsed Addresses
If address lines are captured/stored as a single field (or two) in your systems, they should be provided to Worldview in that format:
- addressLine1: typically the combination of houseNumber, thoroughfare, and houseNumberAddition as described above, as a single string
- addressLine2: an optional second line of address information. This could be the houseNumberAddition or other information
Remaining Address Fields
The rest of the address should always be provided in the following fields. It is recommended that as many fields as possible are provided in order to maximize match rates.
- locality: city or town
- province: province or state, where applicable
- county: county name, where applicable
- postalCode: postal code or zip code
- countryCode: two letter country code that identifies the country in which the sources to be used for verification reside
Other Input Fields
The following best practices should be followed for the rest of the input fields available in Worldview.
- dob: Date of Birth information should always be provided in standard US format, regardless of country of verification (MM/DD/YYYY)
- nationalid and businessid: National IDs and Business IDs often include formatting or separation characters that aren't material to the actual ID information. While Worldview can accept National/Business IDs in their standard format, we recommend removing all formatting and separation characters (e.g.: commas, colons, semicolons, dashes, slashes, spaces, periods, etc.) prior to sending these IDs to Worldview
- phone_number: trunk prefixes should be included in phone numbers sent to Worldview, if available. Country dialing codes are entirely optional (the leading plus sign ahead of the country dialing code is also optional)
Response Structure
Due to the wide range of services that GDC's Wordlview API supports (some of which are legacy products), the response returned by Worldview includes a number of elements that are not relevant to eIDV/KYC and BV use cases.
For both use cases, ALL relevant response data resides within the identity > codes object. All other high-level objects in the response (address, codes, email, and phone) can be ignored, as they do not provide information related to identity verification nor business verification results.
In the example response below, the relevant identity > codes section written in bold green (and all non-colored sections can be ignored):
{ "address": { "name": "", "organization": "", "houseNumber": "", "houseNumberAddition": "", "preIndicator": "", "postIndicator": "", "thoroughfare": "", "postBox": "", "postalCode": "5000", "postTown": "", "province": "", "county": "", "premise": "", "department": "", "building": "", "locality": "CORDOBA", "district": "", "subDistrict": "", "latitude": "", "longitude": "", "countryName": "Argentina", "formalCountryName": "Argentine Republic", "countryCode": "AR", "countryNumber": "32", "countryISO3": "ARG", "dpvCoded": "", "dpvFootnotes": "", "dpvIndicator": "", "dpvIsCMRA": "", "dpvIsPBSA": "", "dpvIsVacant": "", "dpvIsNoStat": "", "urbanization": "", "hausCode": "", "provinceCode": "", "countyCode": "", "municipalityCode": "", "urbanArea": "", "lotNumber": "", "eggCode": "", "congressionalDistrict": "", "census": "", "cebucoCode": "", "lacsIndicator": "", "timezone": "", "addressLine1": "ARRECIFES 482", "addressLine2": "", "addressLine3": "", "addressLine4": "", "addressLine5": "", "addressLine6": "", "addressLine7": "", "addressLine8": "", "addressLine9": "", "addressLine10": "", "codes": { "reliability": "30", "adaptation": "30", "detailCode": "WS-5162830.2022.1.9.16.37.12.179", "detail_list": "", "options": "identityverify;messageverbose;debug", "messages": [], "detailList": "" } }, "codes": { "reliability": "30", "adaptation": "30", "detailCode": "WS-5162830.2022.1.9.16.37.12.179", "detail_list": "", "options": "identityverify;messageverbose;debug", "messages": [], "detailList": "" }, "email": { "full_email_address": "", "domain": "", "top_level": "", "addressee": "", "display_name": "", "countryCode": "AR", "codes": { "reliability": "30", "adaptation": "30", "detailCode": "WS-5162830.2022.1.9.16.37.12.179", "detail_list": "", "options": "identityverify;messageverbose;debug", "messages": [ { "code": "WV", "value": "Email could not be verified. Original input returned." } ], "detailList": "" }, "displayName": "", "fullEmailAddress": "", "topLevel": "" }, "identity": { "completename": "", "formofaddress": "", "qualificationpreceding": "", "givenfullname": "DANIELA", "givennameinitials": "", "qualification_int_first": "", "surname_prefix_first": "", "surname_first": "BESSIA", "indicator": "", "qualification_int_second": "", "surname_prefix_second": "", "qualification_suceeding": "", "name_qualified": "", "function": "", "gender": "", "nationality": "", "nationalid": "92483956", "organization_name": "", "dob": "02/17/1977", "businessid": "", "contact_type": "", "countryCode": "AR", "passport": "", "codes": { "reliability": "10", "adaptation": "0", "detailCode": "WS-5162830.2022.1.9.16.37.12.179", "detail_list": "", "options": "identityverify;messageverbose;debug", "messages": [ { "code": "1MT-AR-CNS1-COMPLETENAME", "value": "Full match was made on Complete Name" }, { "code": "1MT-AR-CNS1-FIRSTINITIAL", "value": "Full match was made on First Initial" }, { "code": "1MT-AR-CNS1-FIRSTNAME", "value": "Full match was made on First Name/Given Name" }, { "code": "1MT-AR-CNS1-LASTNAME", "value": "Full match was made on Last Name/Surname " }, { "code": "1MT-AR-CNS1-ADDRESS", "value": "Full match was made on address elements provided in Address Lines" }, { "code": "1MT-AR-CNS1-HOUSENUMBER", "value": "Full match was made on House Number/Street Number" }, { "code": "1MT-AR-CNS1-THOROUGHFARE", "value": "Full match was made on Street/Thoroughfare" }, { "code": "1MT-AR-CNS1-LOCALITY", "value": "Full match was made on City/Locality" }, { "code": "1MT-AR-CNS1-POSTALCODE", "value": "Full match was made on Postal Code/Zip Code" }, { "code": "1MT-AR-CNS1-NATIONALID", "value": "Full match was made on National ID" }, { "code": "1MT-AR-CNS1-PHONENUMBER", "value": "Full match was made on Phone Number" }, { "code": "1MT-AR-CNS1-DATEOFBIRTH", "value": "Full match was made on Date of Birth" }, { "code": "1MT-AR-CNS1-DAYOFBIRTH", "value": "Full match was made on Day of Birth" }, { "code": "1MT-AR-CNS1-MONTHOFBIRTH", "value": "Full match was made on Month of Birth" }, { "code": "1MT-AR-CNS1-YEAROFBIRTH", "value": "Full match was made on Year of Birth" }, { "code": "4MT-AR-CNS1-SUBPREMISE", "value": "Datasource does not contain element Sub Premise Descriptors provided in Address Lines" }, { "code": "1AU-400-LASTNAME", "value": "Full match was made on Last Name/Surname" }, { "code": "1AU-350-FIRSTNAME", "value": "Full match was made on First Name/Given Name" }, { "code": "1AU-375-FIRSTINITIAL", "value": "Full match was made on First Initial" }, { "code": "1AU-425-COMPLETENAME", "value": "Full match was made on Complete Name" }, { "code": "1AU-625-YEAROFBIRTH", "value": "Full match was made on Year of Birth" }, { "code": "1AU-600-MONTHOFBIRTH", "value": "Full match was made on Month of Birth" }, { "code": "1AU-575-DAYOFBIRTH", "value": "Full match was made on Day of Birth" }, { "code": "1AU-550-DATEOFBIRTH", "value": "Full match was made on Date of Birth" }, { "code": "1AU-650-PHONENUMBER", "value": "Full match was made on Phone Number" }, { "code": "1AU-525-NATIONALID", "value": "Full match was made on National ID" }, { "code": "1AU-275-POSTALCODE", "value": "Full match was made on Postal Code/Zip Code" }, { "code": "1AU-250-LOCALITY", "value": "Full match was made on City/Locality" }, { "code": "1AU-175-THOROUGHFARE", "value": "Full match was made on Street/Thoroughfare" }, { "code": "1AU-150-HOUSENUMBER", "value": "Full match was made on House Number/Street Number" }, { "code": "1AU-200-ADDRESS", "value": "Full match was made on Address Elements provided in Address Lines" }, { "code": "1MT-AR-MATCHED-1+1", "value": "Full Match for 1+1 verification" }, { "code": "Codes", "value": "1AU-150-HOUSENUMBER;1AU-175-THOROUGHFARE;1AU-200-ADDRESS;1AU-250-LOCALITY;1AU-275-POSTALCODE;1AU-350-FIRSTNAME;1AU-375-FIRSTINITIAL;1AU-400-LASTNAME;1AU-425-COMPLETENAME;1AU-525-NATIONALID;1AU-550-DATEOFBIRTH;1AU-575-DAYOFBIRTH;1AU-600-MONTHOFBIRTH;1AU-625-YEAROFBIRTH;1AU-650-PHONENUMBER;1MT-AR-CNS1-ADDRESS;1MT-AR-CNS1-COMPLETENAME;1MT-AR-CNS1-DATEOFBIRTH;1MT-AR-CNS1-DAYOFBIRTH;1MT-AR-CNS1-FIRSTINITIAL;1MT-AR-CNS1-FIRSTNAME;1MT-AR-CNS1-HOUSENUMBER;1MT-AR-CNS1-LASTNAME;1MT-AR-CNS1-LOCALITY;1MT-AR-CNS1-MONTHOFBIRTH;1MT-AR-CNS1-NATIONALID;1MT-AR-CNS1-PHONENUMBER;1MT-AR-CNS1-POSTALCODE;1MT-AR-CNS1-THOROUGHFARE;1MT-AR-CNS1-YEAROFBIRTH;1MT-AR-MATCHED-1+1;4MT-AR-CNS1-SUBPREMISE;" } ], "detailList": "" }, "contactType": "", "nameQualified": "", "organizationName": "", "qualificationIntFirst": "", "qualificationIntSecond": "", "qualificationSuceeding": "", "surnameFirst": "BESSIA", "surnamePrefixFirst": "", "surnamePrefixSecond": "" }, "phone": { "name": "", "phone_number": "2293450213", "calling_from": "", "formatted_international": "", "line_type": "", "international_prefix": "", "calling_code": "", "trunk": "", "area_code": "", "number": "", "timezone": "", "countryCode": "AR", "codes": { "reliability": "30", "adaptation": "30", "detailCode": "WS-5162830.2022.1.9.16.37.12.179", "detail_list": "", "options": "identityverify;messageverbose;debug", "messages": [], "detailList": "" }, "areaCode": "", "callingCode": "", "callingFrom": "", "formattedInternational": "", "internationalPrefix": "", "lineType": "", "phoneNumber": "2293450213" } }