Web Service - Understanding Business Verification - Requests, Results and Required Inputs
The guide is intended to accompany Business Verification Quick Start Guide, which covers the basics of authentication, sending and mapping requests. Further details on the Business Verification product queries and response are covered below.
Business Verification Inputs
The Worldview platform requires a minimum number of inputs when making any Business Verification service call. Business Verification requires at a minimum a set of primary input data elements about a business/organization. Primary data elements include:
- Business Name (Corporate/Organization 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, country code etc.)
The minimum input requirements can differ slightly by each country and the sources chosen for verification. To maximize matching each of the three elements should be presented where possible. 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.
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 3 business message types returned by Worldview.
- Match Type Messages (MT Messages)
- Business Messages (BZ Messages)
- Business Data Enhancement Messages (BDE 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 Verifications, 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 Business Registry (BUS) source would be:
{
"code": "1MT-US-BUS1-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-BUS2-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.
|
MT Field Name |
1MT Message |
|
SUBPREMISE |
Full match was made on Sub Premise Descriptors provided in Address Lines |
|
BUILDING |
Full match was made on Building Descriptors provided in Address Lines |
|
ADDRESS |
Full match was made on address elements provided in Address Lines |
|
THOROUGHFARE |
Full match was made on Street/Thoroughfare |
|
DISTRICT |
Full match was made on District |
|
LOCALITY |
Full match was made on City/Locality |
|
POSTALCODE |
Full match was made on Postal Code/Zip Code |
|
PROVINCE |
Full match was made on State/Province |
|
HOUSENUMBER |
Full match was made on House Number |
|
ORGANIZATION_NAME |
Full match was made on Organization/Business Name |
|
BUSINESSID |
Full match was made on Organization/Business Registry Number |
|
COUNTY |
Full match was made on County |
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 "
}
The table below includes a list of possible data elements and their associated Messages & Codes. Please note that: CERTAIN CODES and MESSAGES ARE ONLY APPLICABLE TO CERTAIN COUNTRIES. Country specific codes and messages are noted in the table.
|
Identifying Elements |
1BZ Code |
1BZ Message |
|
FloorNumber |
1BZ-2100-SUBPREMISE |
Full match was made on Sub Premise Descriptors provided in Address Lines |
|
HouseExtension |
1BZ-2100-SUBPREMISE |
|
|
HouseNumber |
1BZ-2150-HOUSENUMBER |
Full match was made on House Number/Street Number |
|
StreetNumber |
1BZ-2150-HOUSENUMBER |
|
|
StreetName |
1BZ-2175-THOROUGHFARE |
Full match was made on Street/Thoroughfare |
|
Thoroughfare |
1BZ-2175-THOROUGHFARE |
|
|
StreetType |
N/A - INCLUDED IN LOGIC FOR STREET/THOROUGHFARE |
|
|
Home_Address |
1BZ-2200-ADDRESS |
Full match was made on address elements provided in Address Lines |
|
Address1 |
1BZ-2200-ADDRESS |
|
|
Mail_Address |
1BZ-2200-ADDRESS |
|
|
Locality |
1BZ-2250-LOCALITY |
Full match was made on City/Locality |
|
PostTown - UK |
1BZ-2250-LOCALITY |
|
|
City |
1BZ-2250-LOCALITY |
|
|
Home_City |
1BZ-2250-LOCALITY |
|
|
Mail_City |
1BZ-2250-LOCALITY |
|
|
Suburb – BZ, BR, NZ, ZA |
1BZ-2250-LOCALITY |
|
|
Municipality - CA |
1BZ-2250-LOCALITY |
|
|
PostalCode |
1BZ-2275-POSTALCODE |
Full match was made on Postal Code/Zip Code |
|
Mail_Zip |
1BZ-2275-POSTALCODE |
|
|
ZipCode |
1BZ-2275-POSTALCODE |
|
|
County – IE |
1BZ-2300-COUNTY |
Full match was made on County |
|
Province – CA, IT |
1BZ-2325-PROVINCE |
Full match was made on State/Province |
|
State |
1BZ-2325-PROVINCE |
|
|
Home_State |
1BZ-2325-PROVINCE |
|
|
Mail_State |
1BZ-2325-PROVINCE |
|
|
Prefecture – JP |
1BZ-2325-PROVINCE |
|
|
Business Name |
1BZ-2000-ORGANIZATION |
Full match was made on Organization/Business Name |
|
OrganizationName |
1BZ-2000-ORGANIZATION |
Full match was made on Organization/Business Name |
|
Organization_name |
1BZ-2000-ORGANIZATION |
Full match was made on Organization/Business Name |
|
Any country specific Business ID that is returned today (e.g. CNPJ, RFC) |
1BZ-2525-BUSINESSID |
Full match was made on Organization/Business Registry Number |
|
Business Verification match |
1BZ-2295-MATCHED_1+1 |
Full Match for business 1+1 verification |
Business Data Enrichment Messages
Business Data Enrichment (BDE) messages provide information from matched data sources to allow you to confirm, or enrich, the data you have about a business entity. This information can be used to reduce the data input requirements you have on your users, or can be used to confirm and validate information supplied by a user.
The available data differs by the product-level chosen, which is confirmed in the below table.
BDEs are formatted as:
BDE-**-****-(enrichment type), where:
The table below explains the BDEs available and additional detail. To explain the API response information (noting in the table some items in red) you may expect to see something like: where:
- BDE = business data enhancement message, as distinct from MT or BZ messages
- ** = is country code for the matched data, for example ‘NZ’ for New Zealand
- **** = is the source of matched information, for example BUS1. This is presented so you can store in records for future audit purposes where the matched data is sourced from.
- (enrichment type) the type of BDE being returned, e.g. ORGANIZATION_NAME
e.g. "BDE-NZ-BUS1-ORGANIZATION_NAME"
|
BDE Description |
API Response |
Value |
Product Availability |
|
Business ID |
BDE-**-****-BUSINESSID |
Where a match has been made on name and address values, allows business ID to be saved |
BV and BV+ |
|
Business Name |
BDE-**-****-ORGANIZATION_NAME |
Where a match has been made on business ID, or a partial business name match, allows business name to be saved |
BV and BV+ |
|
Business Address (multiple) |
BDE-**-****-ADDRESS BDE-**-****-ADDRESSLINE1 BDE-**-****-THOROUGHFARE BDE-**-****-LOCALITY BDE-**-****-COUNTRYCODE |
Where a match has been made on business ID, or a partial address match, allows business registered address details to be saved. Notes:
|
BV and BV+ |
|
Company Type |
BDE-**-****-COMPANY_TYPE |
Type of business registered. Values are not standardized - that is, we pass through the type from the business registry. An example may be 'LLC', 'Sole Trader', etc |
BV+ only |
|
Company Status |
BDE-**-****-COMPANY_STATUS |
Status of business registered. Values are not standardized - that is, we pass through the status from the business registry. An example may be 'active', 'closed', 'insolvent', etc |
BV+ only |
|
Registration Date |
BDE-**-****-REGISTRATION_DATE |
When business was first registered within business registry. Values passed back in US date format (MM/DD/YYYY) |
BV+ only |
Note that where value is null from the business record, the BDE message will not be returned. For example, if a registry holds only locality and postcode information, not street address info, only the locality and postcode address information will return.
Important - unless you specifically request for these enhancements in your API request, the detail will not be provided. To enable it, pass the value 'businessenrich' in your options parameters.
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 five 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 |
|
BUS |
Business Registry |
|
CRT |
Court Records |
|
TAX |
Tax Registry |
|
REG |
Regulatory Body |
|
CDY |
Commercial Directory |
Address Match Case Scenarios:
For cases where address elements are matched, we provide an MT message reflecting the match.
"code": "1MT-GB-BUS2-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. |
|
BusinessEnrich |
Required to enable the return of BDE messages. |
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.
Business Verification Input Fields
To maximize matching, a business name, address and business ID should be passed by default. Below is a table confirming available business ID types for matching and special format requirements.
|
Country Name |
Country Code |
Government BV Source |
Business Registration Description |
Abbreviation or best local language description |
ID Format Notes |
|
Australia |
AU |
Australian Securities and Investments Commission (ASIC) |
Australian Business Number |
ABN |
11 digits |
|
Austria |
AT |
Austrian Commercial Register (FIrmenbuch) |
Commercial Register Number (Firmenbuchnummer) |
FN |
6 digits and followed by a letter |
|
Belgium |
BE |
Crossroads Bank for Enterprises |
Company Number |
Numéro |
Ten digits in format XXXX.XXX.XXX (dots/periods must be passed in inputs) |
|
Canada |
CA |
Corporations Canada |
Corporations Number or Business Number |
Corporations Number or Business Number |
Corporations Number - 7 digits Business Number - 9 digits |
|
China |
CN |
State Administration of Market Regulation (SAMR) |
Unified Social Credit Identifier (USCN) |
USCN |
18-digit alphanumeric code |
|
Germany |
DE |
German Trade Register, or Handelsregister (Gemeinsames Registerportal der Länder) |
Handelsregisternummer or simply Registernummer |
Registernummer |
Prefix or HRA or HRB, followed by 5 digits (e.g. HRB 12345) |
|
Denmark |
DK |
Central Business Register Denmark (VIRK) |
Central Business Register Number - Det Centrale Virksomhedsregister Number |
CVR Number |
8 digits |
|
Spain |
ES |
Business Registry (Registros Mercantiles) |
Número de Identificación Fiscal - Tax Identification Number (formerly known |
TIN (formerly known as a CIF) |
A letter followed by 8 digits (example: B12345678). |
|
Finland |
FI |
Business Information System (YTJ) (maintained by Finnish Patent and Registration Office, PRH) |
Business ID |
Y-tunnus |
7 digits, hyphen, 1 digit |
|
France |
FR |
Infogreffe (les greffes des tribunaux de commerce) |
SIREN number |
SIREN |
9 digits |
|
United Kingdom |
GB |
Companies House United Kingdom |
Company Registration Number or just Company Number |
Company Number |
• England and Wales - 8 digits • Scotland and Northern Ireland - 2 letters and 6 digits |
|
Hong Kong |
HK |
Hong Kong Companies Registry |
Company Registration Number |
CRN |
7 digits |
|
Ireland |
IE |
Companies Registration Office (CRO) |
Company Number |
Company Number |
6 digits |
|
India |
IN |
Ministry of Corporate Affairs – Registrar of Companies (ROC) |
1. Corporate Identity Number (CIN) 2. Limited Liability Partnership Identification Number (LLPIN) |
1. CIN 2. LLPIN |
1. 21 alphanumeric 2. LLPIN - 7 numeric character |
|
Italy |
IT |
Business Register of the Italian Chambers of Commerce (InfoCamere) |
Codice fiscale |
CF |
11 digits |
|
Japan |
JP |
Ministry of Economy, Trade and Industry of Japan |
Japan Corporate Number |
JCN |
13 digits |
|
Malaysia |
MY |
Suruhanjaya Syarikat Malaysia (Companies Commission of Malaysia) |
Company Registration Number or Business Registration Number |
CRN, BRN |
12 digits (pre 2019 6 digits followed by 1 letter) |
|
Mexico |
MX |
Federal Taxpayers Registry |
Registro Federal de Contribuyentes |
RFC |
12 characters |
|
Netherlands |
NL |
Handelsregister (Trade Register), managed by Netherlands Chamber of Commerce, or Kamer van Koophandel (KVK) |
KVK-nummer |
KVK-nummer |
8 digits |
|
Norway |
NO |
Register Centre (Brønnøysund) |
Organisation Number |
Organisasjonsnummer |
9 digits |
|
New Zealand |
NZ |
Companies Office New Zealand (Companies Register) |
New Zealand Business Number |
NZBN |
13 digits |
|
Poland |
PL |
National Court Register (Krajowy Rejestr Sądowy, KRS) |
Registration number |
Numer KRS |
10 digits |
|
Sweden |
SE |
Swedish Companies Registration Office (‘Bolagsverket’) |
Business Registration Number |
Organisationsnummer |
10 digits (do not pass any hyphens) |
|
Singapore |
SG |
Accounting and Corporate Regulatory Authority (ACRA) |
Unique Entity Number |
UEN |
9 or 10 digits |
|
United States |
US |
1. Various State-based Registries, usually through Secretary of State departments 2. Internal Revenue Service (IRS) |
Tax Identification Number (or Employer Identification Number) |
TIN / EIN |
9 digits |
|
Taiwan |
TW |
Ministry of Economy of the Republic of China |
Unified Business Number |
UBN |
8 digits |
Business Verification Default Match Rules
|
Reliability |
Business Name Match |
Business Address Match |
Business ID Match |
|
10 |
Match |
Match |
Any Value (Match / No Match) |
|
Match |
Any Value (Match / No Match) |
Match |
|
|
Any Value (Match / No Match) |
Any Value (Match / No Match) |
Match |
|
|
20 |
Match |
Partial Match |
Any Value (Match / No Match) |
|
30 |
All other combinations |
||
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.