Business Verification Integration Guide

Web Service - Understanding Business Verification - Requests, Results and Required Inputs

The guide is intended to accompany other product guides such as the Worldview Web Services BV Quick Start Guide. Business Verification via the Worldview Web Services API is designed to answer the question “Is this a real business?”.

 

Business Verification Inputs

The Worldview platform requires a minimum number of inputs when making any Business Verification service call. The Business Verification check requires at a minimum a set of primary input data elements about a business/organization. Primary data elements include:

• Business Name (Corporate/Organization name, DBA name, Legal Entity Names)
• Business ID Number (e.g. U.S.: EIN, Italy: codice fiscale, Brazil: CNPJ, VAT Number)
• Address (Address Line 1, locality, postal code etc.) 

In some countries/markets, there is not an established Business ID Number, in which case that input element is considered optional. These primary input values are included in the Identity & Address section of the input payload for a Worldview API request.

Business Data Elements

"identity": {
   "organization_name": "",
   "businessid": ""
   }

Address Elements

  "address": {
   "addressLine1": "",
   "addressLine2": "",
   "addressLine3": "",
   "houseNumber": "",
   "houseNumberAddition":"",
   "thoroughfare": "",
   "locality": "",
   "postalCode": "",
   "province": "",
   "countryCode": ""
   }

 

Reliability Scores

There are 3 types of reliability in the Worldview Service. Reliability Scores represent a scoring system designed to be easy to understand and implement/decision. The scores work similar to a stoplight with 3 primary classifications:

  "reliability": "10"
  "reliability": "20"
  "reliability": "30"

10	(Good/Correct/Pass)	Messages and match types indicate that this is a passing match combination based on the defined rule set.
20	(Probable/Partial)	Messages and match types are sufficient to consider this as a possible match/pass.
30	(Did not Pass/Doubtful)	There may or may not have been matched elements, but it is doubtful this is sufficient information.

 

The variable in how Reliability is interpreted is not in the definition (Good/Partial/Bad) but in the rules defined for each use case.

 

Business Verification Reliability Codes

An overall reliability score is returned for a business result. The score is based on the complete, partial or non-match of business data elements passed as input. The status messages returned identify the specific matches returned from the input provided. See the section on Codes & Messages for more information.

The Worldview Platform is designed to make Business Verification simple by providing Messages and Scores within the API response for ease of decisioning. To provide this validated scoring, the system requires a minimum of Business Name, Business ID, and Country Code to perform a Business Verify check. The more information that is provided in the request the higher confidence in the match. It is best practice to provide additional inputs when making Business Verification calls. In most markets Business ID is specifically a government issued number which can be used to identify and unlock other match criteria.  

The required input fields vary by country. You may contact your sales/account executive to learn more about the best practices for the countries which you wish to activate.

 

Understanding Business Messages

The Worldview Service performs Business Verification based on input data elements provided and, along with returning the input fields, provides a series of response Message Codes & Values based on the Match (1)/ Partial Match (3)/ No Data Available (4) verification of the submitted inputs.

There are 2 business message types returned by Worldview.

- Business Messages (BZ Messages)
- Match Type Messages (MT Messages)

These messages are returned from Worldview in a Code/Message Value construct and detail how input elements match against data sources.  Messages are at the core of how Worldview defines and delivers reliability scores and other match scoring metrics. BZ messages are specific to Business Verify checks, while MT messages span and underpin all aspects of matching business and identity data in the Worldview Service.

 

Match Type Codes & Messages

Worldview generates messages at a per data source level called Match Type (or “MT”) codes and messages. MT codes and messages are meant to provide the most granular level of detail for matching an individual input element to a specific match field in an underlying data source.

Match Type (MT) messages take the following format:

[1|3|4] MT-[Country Code]-[Data source Abbreviation]-[Field Name]

For example, a House Number element match in United States of America (US) that matched using the in-country Postal (PST) source would be:

  {
   "code": "1MT-US-PST1-HOUSENUMBER",
   "value": "Full match was made on House Number/Street Number"
   }

Often, multiples of the same type of data source are available in a specific country, therefore a number is appended to the Data Source Type (DST) abbreviation. [Example: 1MT-CH-TEL2-POSTALCODE]

Match Type Categories

1MT	Element fully matched with the data source.
3MT	Element partially matched with the data source.
4MT	Element is not contained in the data source.

MT messages are only surfaced when the option MessageVerbose is passed.

 

Business Codes and Messages

BZ (Business) messages provide an overall match rating on the input element provided, spanning data providers and sources leveraged for scoring. The BZ message is designed to be a roll-up across data sources based on the input elements. BZ messages are surfaced based on the interconnection or “crosswalk” between the input elements and how they matched across the available sources. These messages provide detail on the overall match level of the input elements and are meant to be a higher-level compliment to the Match Type (MT) messages

Business (BZ) messages take the following format:

[1/2/3]BZ-[Unique Numeric Code]-[Field Name]

Types of BZ messages

The table below defines the different BZ codes which can be returned by the service.

1BZ	Indicates a complete match was made across one or more data sources on the input element.
2BZ	Indicates a match could not be made in any data source on input element.
3BZ	Indicates a partial match was made across all data sources on input element.

 

A match made on organization name would take the form of:

  {
   "code": " 1BZ-2000-ORGANIZATION",
   "value": "Full match was made on Organization/Business Name"
  }

An example subset response message could include:

  {
   "code": " 1BZ-2000-ORGANIZATION ",
   "value": " Full match was made on Organization/Business Name"
   },
  {
   "code": "1BZ-2275-POSTALCODE",
   "value": "Full match was made on Organization/Business Postal Code "
   }

 

BZ Message Generation

By default, Business Name + an additional Business input element must match across multiple data sources to “Crosswalk” the sources and generate BZ messages. However, these rules can be customized to fit specific customer use cases. Common options for customization include requiring an element of locality or Business ID along with Business Name to match cross sources. Some of these rules are illustrated in the following examples:

Example 1

Message Output: 1BZ for Business Name and Address

Example 2

Message Output: 1BZ for Business Name and Address

Example 3

Message Output: 1BZ for Business Name and Address

 

Business Name and Address Matching

The Worldview platform provides classifications of “FULL” (1MT) or “PARTIAL” (3MT) matches with the current release of the API. It also provides “Not Contained in Source” (4MT) elements. The configuration for each of these is tuned per country and data source. You may contact your sales/account executive to know more about the best practices for the countries which you wish to activate.

 

Data Source Codes Classification

There are 8 currently supported Business Data Source codes listed below. These codes give details related to what sources were matched against in MT messages and allow verification rule sets to be applied to calculate Reliability.

Data Source Abbreviation	Data Source Type
CRD	Credit
GVT	Government
BUS	Business Registry
COC	Local Reg / Chamber
DIG	Digital & Commerce
UTL	Utility
TEL	Telco
PST	Postal

 

Address Match Case Scenarios: 

For cases where address elements are matched, we provide an MT message reflecting the match.

   "code": "1MT-GB-TEL2-ADDRESS",
   "value": "Full match was made on address elements provided in Address Lines"
  },

For business verifications, an address is said to be a match when any one of the following conditions is met:

Match on House Number + City

Match on Street + City

Match on Building + City

Match on District + City

Match on House Number + Postal Code

Match on Street + Postal Code

Match on Building + Postal Code

Match on District + Postal Code

 

As you might notice, the message for an address match states that the address elements have matched but it shows that the minimum requirements have been met for an address match.

 

Utilizing Business Options

The WV Platform allows per record directives or options which explicitly dictate a feature or service to be applied to the results of the initial validation/verification. For the current release, below is a list of parameters which can be applied as option(s). These parameters are passed as a semicolon delimited string of values – example “MessageVerbose;BusinessVerify.” Please note that though the options are listed here in explicit case the options values are not actually case sensitive.

This guide includes options that are included in most initial Worldview configurations. While these options can be changed within a transaction, you may wish to switch 'ON' some of these options for your tenants by default. To activate that or to discuss any additional business use cases which might be deployed through an option please reach out to your sales/account executive or reach out to us at help@globaldataconsortium.com. 

Business Options
Option Parameter	Definition
BusinessVerify	For those countries that support this feature the service will attempt to verify the business data element inputs with the best match using all provided input data. Note that when running this option, the input data may be corrected in the data quality step and this may affect results.
MessageVerbose	Using this option in combination with the Business or Identity verification options will provide all MT messages returned with a processed result rather than what is configured as the default, or filter messages based on the input.
debug	The debug option is critical to understand and leverage as you are verifying the Worldview integration. Debug instructs the service to persist and log the resulting transaction detail for 7 days. The detail is indexed by the transaction id, or detailcode returned with the request. As you are tuning and improving your integration you may activate debug and provide GDC support with the detailcode of a transaction in order to better troubleshoot and answer questions.

 

Understanding the Detail Code (WSID)

"detailCode": "WS-9664570.2021.5.19.0.30.7.287"

Every inquiry on the Worldview service returns a unique detail code. The detail code is the unique transaction identifier for the request and response to and from the Worldview service. This detail code is critical to be logged by customers and partners as it allows for troubleshooting and an audit trail with the WV support team.

NOTE: GDC does not store the original request information nor PII, so this transaction ID / detailCode is the first and best way to troubleshoot integration and verification result questions with the GDC team. The detail code is important for customers to utilize if there are questions about a specific record or the need to audit records. The customer should provide the detailCode (or WSID) to the support team along with the original input, whenever possible.

 

Programming Languages

Please refer to the Quick Start Guide for examples and information which you might find helpful. In case, you still need information on any issue or programming examples, please contact us at help@globaldataconsortium.com.

 

Coming Soon

Indicator Types for Business ID

The Worldview Service supports multiple types of Business ID numbers in the different countries and markets covered. The default value or assumption related to the indicator type for the businessid is the local market Tax ID number. However, in the request, the specific type can be defined and thus allows for verification of different types of Business ID numbers in countries where this is supported. The following snippet shows how indicator would be set if the VAT number was provided in the "businessid" field:

  "identity": {
   "indicator": "1",
   "businessid": "20439193000199",

The table below lists the indicator types for Business ID that may be supported by Business Verification in the future:

Indicator Type	Indicator Number	Description
TAX	0	Government or Tax ID number for the business in the country. This is the default
VAT	1	VAT Number for the business in the country
IBAN	2	IBAN number
SWT	3	SWIFT Banking Number
CRD	4	Credit card number or last 4 of CC
BLN	5	Business License Number in local market
LEI	6	Legal Entity Identifier
LOC	8	Local Registry or Chamber of Commerce Number