Skip to main content

Business Verification Quick Start Guide

  • Updated

Welcome to the Global Data Consortium’s (GDC) Worldview Platform Quick Start Guide for Business Verification. This guide is intended to help GDC clients quickly test and validate Worldview platform integration. The guide is intended to accompany the Integration Guide for Business Verification.

 

Connecting to Worldview 

  1. Download the Postman collection and use a preferred API testing client (Postman is shown below).

Worldview supports REST format for API requests. The Quick Start Guide is focused on how to integrate and validate using REST. The Postman collection is available for download here (click to download). To import this collection, click on the “import” button on the top left corner of the postman window.

Screen_Shot_2020-05-28_at_4.16.05_PM.png

Then click on “Import File” and select the JSON file from the postman collection.

Screen_Shot_2020-05-28_at_4.16.16_PM.png

Once it is connected successfully, there will be a sample request in Postman which is available for testing.

TLS v1.2: The API requires that calling applications be TLS v1.2 compliant. Contact support if you have any questions – help@globaldataconsortium.com

  1. Properly Format the Request.

Enter the Credentials provided to you by the GDC Sales team.

  • Tenant Name
  • Username
  • Password
{
"options": "businessverify;messageverbose",
"credentials": {
     "tenant": "",
     "username": "",
     "password": ""
},
"address": {
     "addressLine1": "",
     "thoroughfare": "Macon Avenue",
     "houseNumber": "290",
     "locality": "ASHEVILLE",
     "postalCode": "28804",
     "province": "NC",
     "countryCode": "US"
},
"identity": {
     "organization_name": "Random Inc.",
     "businessid": "47-423432"
}
}

  1. Make a Request and Validate Result

Using the Postman client with the populated sample request, you should be able to make a request to our service. After submitting the request, you should see the response returned, without any errors.

{
"address": {
"name": "",
"organization": "",
"houseNumber": "290",
"houseNumberAddition": "",
"preIndicator": "",
"postIndicator": "",
"thoroughfare": "Macon Avenue",
"postBox": "",
"postalCode": "28804",
"postTown": "",
"province": "NC",
"county": "",
"premise": "",
"department": "",
"building": "",
"locality": "ASHEVILLE",
"district": "",
"subDistrict": "",
"latitude": "",
"longitude": "",
"countryName": "United States",
"formalCountryName": "United States of America",
"countryCode": "US",
"countryNumber": "840",
"countryISO3": "USA",
"dpvCoded": "",
"dpvFootnotes": "",
"dpvIndicator": "",
"dpvIsCMRA": "",
"dpvIsPBSA": "",
"dpvIsVacant": "",
"dpvIsNoStat": "",
"urbanization": "",
"hausCode": "",
"provinceCode": "",
"countyCode": "",
"municipalityCode": "",
"urbanArea": "",
"lotNumber": "",
"eggCode": "",
"congressionalDistrict": "",
"census": "",
"cebucoCode": "",
"lacsIndicator": "",
"timezone": "",
"addressLine1": "",
"addressLine2": "",
"addressLine3": "",
"addressLine4": "",
"addressLine5": "",
"addressLine6": "",
"addressLine7": "",
"addressLine8": "",
"addressLine9": "",
"addressLine10": "",
"codes": {
"reliability": "30",
"adaptation": "30",
"detailCode": "WS-2460732.2021.3.13.12.55.57.881",
"detail_list": "",
"options": "businessverify;messageverbose",
"messages": [
{
"code": "WV",
"value": "Address could not be verified. Original input returned."
}
],
"detailList": ""
}
},
"codes": {
"reliability": "30",
"adaptation": "30",
"detailCode": "WS-2460732.2021.3.13.12.55.57.881",
"detail_list": "",
"options": "businessverify;messageverbose",
"messages": [],
"detailList": ""
},
"email": {
"full_email_address": "",
"domain": "random.com",
"top_level": "",
"addressee": "",
"display_name": "",
"countryCode": "US",
"codes": {
"reliability": "30",
"adaptation": "30",
"detailCode": "WS-2460732.2021.3.13.12.55.57.881",
"detail_list": "",
"options": "businessverify;messageverbose",
"messages": [
{
"code": "WV",
"value": "Email could not be verified. Original input returned."
}
],
"detailList": ""
},
"displayName": "",
"fullEmailAddress": "",
"topLevel": ""
},
"identity": {
"completename": "",
"formofaddress": "",
"qualificationpreceding": "",
"givenfullname": "",
"givennameinitials": "",
"qualification_int_first": "",
"surname_prefix_first": "",
"surname_first": "",
"indicator": "",
"qualification_int_second": "",
"surname_prefix_second": "",
"qualification_suceeding": "",
"name_qualified": "",
"function": "",
"gender": "",
"nationality": "",
"nationalid": "",
"organization_name": "Random Inc.",
"dob": "",
"businessid": "47-423432",
"contact_type": "",
"countryCode": "US",
"passport": "",
"codes": {
"reliability": "10",
"adaptation": "0",
"detailCode": "WS-2460732.2021.3.13.12.55.57.881",
"detail_list": "",
"options": "businessverify;messageverbose",
"messages": [
{
"code": "1MT-US-TEL1-ORGANIZATION",
"value": "Full match was made on Organization/Business name"
},
{
"code": "1MT-US-TEL1-ADDRESS",
"value": "Full match was made on Organization/Business address elements provided in Address Lines"
},
{
"code": "1MT-US-TEL1-HOUSENUMBER",
"value": "Full match was made on Organization/Business Street Number"
},
{
"code": "1MT-US-TEL1-THOROUGHFARE",
"value": "Full match was made on Organization/Business Street/Thoroughfare"
},
{
"code": "1MT-US-TEL1-LOCALITY",
"value": "Full match was made on Organization/Business City/Locality"
},
{
"code": "1MT-US-TEL1-POSTALCODE",
"value": "Full match was made on Organization/Business Postal Code"
},
{
"code": "1MT-US-TEL1-BUSINESSID",
"value": "Full match was made on Organization/Business Registry Number"
},
{
"code": "1MT-US-DIG1-ORGANIZATION",
"value": "Full match was made on Organization/Business name"
},
{
"code": "1MT-US-DIG1-ADDRESS",
"value": "Full match was made on Organization/Business address elements provided in Address Lines"
},
{
"code": "1MT-US-DIG1-HOUSENUMBER",
"value": "Full match was made on Organization/Business Street Number"
},
{
"code": "1MT-US-DIG1-THOROUGHFARE",
"value": "Full match was made on Organization/Business Street/Thoroughfare"
},
{
"code": "1MT-US-DIG1-LOCALITY",
"value": "Full match was made on Organization/Business City/Locality"
},
{
"code": "1MT-US-DIG1-POSTALCODE",
"value": "Full match was made on Organization/Business Postal Code"
},
{
"code": "1MT-US-DIG1-BUSINESSID",
"value": "Full match was made on Organization/Business Registry Number"
},
{
"code": "1MT-US-GVT1-ORGANIZATION",
"value": "Full match was made on Organization/Business name"
},
{
"code": "1MT-US-GVT1-ADDRESS",
"value": "Full match was made on Organization/Business address elements provided in Address Lines"
},
{
"code": "1MT-US-GVT1-HOUSENUMBER",
"value": "Full match was made on Organization/Business Street Number"
},
{
"code": "1MT-US-GVT1-THOROUGHFARE",
"value": "Full match was made on Organization/Business Street/Thoroughfare"
},
{
"code": "1MT-US-GVT1-LOCALITY",
"value": "Full match was made on Organization/Business City/Locality"
},
{
"code": "1MT-US-GVT1-POSTALCODE",
"value": "Full match was made on Organization/Business Postal Code"
},
{
"code": "1MT-US-GVT1-BUSINESSID",
"value": "Full match was made on Organization/Business Registry Number"
},
{
"code": "1BZ-2000-ORGANIZATION",
"value": "Full match was made on Organization/Business Name"
},
{
"code": "1BZ-2200-ADDRESS",
"value": "Full match was made on Organization/Business address elements provided in Address Lines"
},
{
"code": "1BZ-2150-HOUSENUMBER",
"value": "Full match was made on Organization/Business Street Number"
},
{
"code": "1BZ-2175-THOROUGHFARE",
"value": "Full match was made on Organization/Business Street/Thoroughfare"
},
{
"code": "1BZ-2250-LOCALITY",
"value": "Full match was made on Organization/Business City/Locality"
},
{
"code": "1BZ-2275-POSTALCODE",
"value": "Full match was made on Organization/Business Postal Code"
},
{
"code": "1BZ-2525-BUSINESSID",
"value": "Full match was made on Organization/Business Registry Number"
},
{
"code": "Codes",
"value": "1BZ-2000-ORGANIZATION;1BZ-2150-HOUSENUMBER;1BZ-2175-THOROUGHFARE;1BZ-2200-ADDRESS;1BZ-2250-LOCALITY;1BZ-2275-POSTALCODE;1BZ-2525-BUSINESSID;1MT-US-DIG1-ADDRESS;1MT-US-DIG1-BUSINESSID;1MT-US-DIG1-HOUSENUMBER;1MT-US-DIG1-LOCALITY;1MT-US-DIG1-ORGANIZATION;1MT-US-DIG1-POSTALCODE;1MT-US-DIG1-THOROUGHFARE;1MT-US-GVT1-ADDRESS;1MT-US-GVT1-BUSINESSID;1MT-US-GVT1-HOUSENUMBER;1MT-US-GVT1-LOCALITY;1MT-US-GVT1-ORGANIZATION;1MT-US-GVT1-POSTALCODE;1MT-US-GVT1-THOROUGHFARE;1MT-US-TEL1-ADDRESS;1MT-US-TEL1-BUSINESSID;1MT-US-TEL1-HOUSENUMBER;1MT-US-TEL1-LOCALITY;1MT-US-TEL1-ORGANIZATION;1MT-US-TEL1-POSTALCODE;1MT-US-TEL1-THOROUGHFARE;founding_date;"
},
{
"code": "BusinessMatchCodes",
"value": "TEL1-BAZ:DIG1-BAZ:GVT1-BAZ"
}
],
"detailList": ""
},
"contactType": "",
"nameQualified": "",
"organizationName": "Random Inc.",
"qualificationIntFirst": "",
"qualificationIntSecond": "",
"qualificationSuceeding": "",
"surnameFirst": "",
"surnamePrefixFirst": "",
"surnamePrefixSecond": ""
},
"phone": {
"name": "",
"phone_number": "",
"calling_from": "",
"formatted_international": "",
"line_type": "",
"international_prefix": "",
"calling_code": "",
"trunk": "",
"area_code": "",
"number": "",
"timezone": "",
"countryCode": "US",
"codes": {
"reliability": "30",
"adaptation": "30",
"detailCode": "WS-2460732.2021.3.13.12.55.57.881",
"detail_list": "",
"options": "businessverify;messageverbose",
"messages": [
{
"code": "WV",
"value": "Phone could not be verified. Original input returned."
}
],
"detailList": ""
},
"areaCode": "",
"callingCode": "",
"callingFrom": "",
"formattedInternational": "",
"internationalPrefix": "",
"lineType": "",
"phoneNumber": ""
}
}

Your transaction response should also include a detailCode, called the WSID. This is unique to the specific transaction you made at a point in time. Please store this code and provide it for support and audit inquiries. Example:

<detailCode>WS-5039873.2020.8.30.8.13.53.798</detailCode>

 

Worldview Integration and Mappings

Mapped input values for integration testing using cache data

 

Credentials 

{username}

username

{password}

password

{tenant}

tenant name

 

Business Elements

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

 

Address Elements

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

The addresses can either be sent parsed or unparsed. To optimize match rates it is recommended addresses are sent parsed out in house number and street fields. We also have parsing engines if you send it unparsed in addressLine1.

 

Options

businessverify;messageverbose;businessenrich;debug = these are the options/parameters which instruct the Worldview platform as to what process should occur on this request. 

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.

For a complete list of options and messages available please refer to the Integration Guide.

 

Map Request

  {
   "options": "businessverify;messageverbose",
   "credentials": {
   "tenant": "{tenant}",
   "username": "{username}",
   "password": "{password}"
   },
   "address": {
   "addressLine1": "{addressLine1}",
   "addressLine2": "",
   "houseNumber": "{houseNumber}",
   "houseNumberAddition":"",
   "thoroughfare": "{thoroughfare}",
   "locality": "{locality}",
   "postalCode": "{postalCode}",
   "province": "{province}",
   "countryCode": "{countryCode}"
   },
   "identity": {
   "organization_name": "{organizationname}",
   "businessid": "{businessid}"
   }
  }

 

Map Response

You are now ready to map the responses that are returned by Worldview into your Third-Party application. You can map the responses either based on reliability codes, BZ messages or MT messages. Please refer to the Integration Guide for details on the response.

 

Confirming Worldview Integration Using the Test Cache

The Worldview test cache is a great tool during all integration and testing phases. The test cache is an engineered set of test records designed to be used by developers to validate integration and validate results processing without the need for live data and “real businesses.” For the final steps of the quick start guide, we recommend using these records for validation of the integration.

 

1) Endpoints and Credentials

Use the following Worldview endpoint:

JSON/REST Endpoint https://api.globaldataconsortium.com/rest/validate

Use the test cache credentials to access the test cache records. 

The demo postman collection contains a couple sample requests using test cache data. When you enter your test cache tenant credentials into the appropriate fields you'll see the relevant responses.

Important – Test cache input records do not work in production.

 

2) Sample Request & Response

The onboarding package which is included with the Quick Start Guide contains 3 files which will be useful in testing the integration with the sample data.

  1. Excel spreadsheet named - xlsx contains the list of test input which will function with the cache for integration testing and sign-off.
  2. json contains the request in JSON format for a single request in the cache.
  3. json contains the response in JSON format for a single request in the cache.

Switching Worldview Integration to Production

After you have successfully validated the integration using the test cache, you can switch to production or live access with the following step:

 

Change to production credentials

Request production credentials from our sales/account rep and/or support (help@globaldataconsortium.com).

Credentials consist of:

username: username provided for authentication
password: strong password for the user within the tenant
tenant: this is the company rule set that has been configured. A tenant represents a company’s configuration and it is shared between users.

Related articles

Powered by Zendesk