This service verifies a company’s information such as name and address via background data source lookup in a multitude of registers. The list of supported countries is large and is expanded through quick configuration.
1. APIs
POST to
Test Env : https://test-gateway.zignsec.com/api/v4/kyb/companies/validation
Prod Env: https://gateway.zignsec.com/api/v4/kyb/companies/validation
Swagger: test-link
Swagger: prod-link
MatchLevel
The main response is a MatchLevel set to HIGH, MEDIUM or LOW indicating the similarity between the in-data and the the best found match in the specified country.
- HIGH – very good match
- MEDIUM – moderate match
- LOW – poor match
To learn more about match configuration, see KYB_BV_Match_Configuration for Business Verify and KYB_Default_BV+ODO for BV_ODO configuration.
Test Data and Tuning
In our test environment we query against a cache of test persons listed here
1.1 Request Body example
POST to https://test-gateway.zignsec.com/api/v4/kyb/companies/validation
Content-Type: application/json; charset=UTF-8
Authorization: YOUR ACCESS TOKEN
Host: https://test-gateway.zignsec.com/
{
"companyIdType": "TaxIdNumber",
"companyId": "47-423432",
"companyName": "Random Inc.",
"houseNumber": "47-9",
"street": "Glove Park Lane",
"city": "Ashville",
"postalCode": "66327",
"countryCode": "US",
"province": "NC",
"addressLine1": "",
"addressLine2": "",
"addressLine3": "",
"foundingDate": "1997-12-14",
"phone": "",
"email": "",
"website": "random.com",
"individual": {
"firstName": "Marcus",
"lastName": "Stark",
"nationalid": "",
"birthDate": "1990-01-03",
"addressLine1": "",
"postalCode": ""
},
"providerParameters": {
"dataProviderCode": "DP03",
"parameters": {
"options": "debug;MessageVerbose;ODOVerify",
"credentials": {
"tenant": "",
"username": "",
"password": ""
},
"address": {},
"identity": {
"organization_name": "",
"codes": {
"messages": []
}
}
}
},
"relayState": "123456"
}
1.2 Request Body Parameters
| Parameter | Description | Required |
| metaData | See table below | Yes |
MetaData Parameters
| Parameter | Description | Required |
CompanyName | Corporate/Organization name, DBA name, Legal Entity Name | |
CompanyIdType | Type of company ID. Example – TaxIdNumber, ValueAddedTaxNumber, IbanNumber, SwiftNumber, CreditCardNumber, BusinessLicenseNumber, LegalEntityIdentifier, DunsNumber, ChamberOfCommerceNumber | |
CompanyId | Company/Business ID number (ex. U.S. – EIN, Italy – codice di fiscale, Brazil – CNPJ, VAT Number) | |
FoundingDate | Company founding date (YYYY-MM-DD or YYYYMMDD) | |
phone | Company phone number | |
email | Company email address | |
website | Company website URL | |
City | Company city | |
CountryCode | Two letter ISO country code | |
Individual | Data of the individual related to the company (Owners, Directors and Officers) | |
firstName | First name | |
lastName | Last name | |
providerParameters | Provider parameters. (Used to pass request parameters to the upstream data provider) | |
RelayState | This semi-optional parameter will be returned to you at the redirect back to your server. Use it to link an unique ID of your choice that you can parse. |
1.3 Response Example
{
"id": "984c45c7-fb26-4d4f-9052-815ed48a0dc7",
"state": "Finished",
"matchLevel": "High",
"companyFieldMatches": [
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "TelephoneCompany",
"dataSourceNumber": 1,
"fieldName": "AFILLIATED",
"description": "Full match was made on Affiliated status"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "TelephoneCompany",
"dataSourceNumber": 1,
"fieldName": "BENEFICIAL",
"description": "A full match was made on Beneficial Status"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "TelephoneCompany",
"dataSourceNumber": 1,
"fieldName": "BIRTH_DATE",
"description": "Full match was made on DOB"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "TelephoneCompany",
"dataSourceNumber": 1,
"fieldName": "CITY",
"description": "Full match was made on Organization/Business City/Locality"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "GovernmentRegistry",
"dataSourceNumber": 1,
"fieldName": "CITY",
"description": "Full match was made on Organization/Business City/Locality"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "DigitalAndCommerce",
"dataSourceNumber": 1,
"fieldName": "CITY",
"description": "Full match was made on Organization/Business City/Locality"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "GovernmentRegistry",
"dataSourceNumber": 1,
"fieldName": "COMPANY_ID",
"description": "Full match was made on Organization/Business Registry Number"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "TelephoneCompany",
"dataSourceNumber": 1,
"fieldName": "COMPANY_ID",
"description": "Full match was made on Organization/Business Registry Number"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "DigitalAndCommerce",
"dataSourceNumber": 1,
"fieldName": "COMPANY_ID",
"description": "Full match was made on Organization/Business Registry Number"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "GovernmentRegistry",
"dataSourceNumber": 1,
"fieldName": "COMPANY_NAME",
"description": "Full match was made on Organization/Business name"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "DigitalAndCommerce",
"dataSourceNumber": 1,
"fieldName": "COMPANY_NAME",
"description": "Full match was made on Organization/Business name"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "TelephoneCompany",
"dataSourceNumber": 1,
"fieldName": "COMPANY_NAME",
"description": "Full match was made on Organization/Business name"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "TelephoneCompany",
"dataSourceNumber": 1,
"fieldName": "COMPLETENAME",
"description": "Full match was made on Complete Name"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "TelephoneCompany",
"dataSourceNumber": 1,
"fieldName": "EMPLOYEE",
"description": "Full match was made on Employee status"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "TelephoneCompany",
"dataSourceNumber": 1,
"fieldName": "FIRSTINITIAL",
"description": "Full match was made on First Initial"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "TelephoneCompany",
"dataSourceNumber": 1,
"fieldName": "FIRSTNAME",
"description": "Full match was made on First Name/Given Name"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "DigitalAndCommerce",
"dataSourceNumber": 1,
"fieldName": "FOUNDINGDATE",
"description": "Full match was made on Founding Date"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "GovernmentRegistry",
"dataSourceNumber": 1,
"fieldName": "FOUNDINGDATE",
"description": "Full match was made on Founding Date"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "TelephoneCompany",
"dataSourceNumber": 1,
"fieldName": "FOUNDINGDATE",
"description": "Full match was made on Founding Date"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "TelephoneCompany",
"dataSourceNumber": 1,
"fieldName": "LASTNAME",
"description": "Full match was made on Last Name/Surname"
},
{
"matchType": "FullMatch",
"countryCode": "US",
"dataSource": "TelephoneCompany",
"dataSourceNumber": 1,
"fieldName": "OWNER",
"description": "A full match was made on Owner status"
}
],
"individualMatches": [
{
"matchType": "FullMatch",
"code": "BENEFICIAL_OWNER",
"description": "Confirmed Beneficial Ownership between the Entity and the Organization"
}
],
"relayState": "123456",
"errors": [],
"providerData": {
"identity": {
"indicator": "",
"codes": {
"reliability": "10",
"adaptation": "0",
"detailCode": "WS-6939537.2021.3.12.11.20.22.210",
"detail_list": "",
"options": "debug;MessageVerbose;ODOVerify",
"detailList": "",
"messages": [
{
"code": "FOUNDING_DATE",
"value": "12/14/1997"
},
{
"code": "1MT-US-TEL1-ORGANIZATION",
"value": "Full match was made on Organization/Business name"
},
{
"code": "1MT-US-TEL1-LOCALITY",
"value": "Full match was made on Organization/Business City/Locality"
},
{
"code": "1MT-US-TEL1-BUSINESSID",
"value": "Full match was made on Organization/Business Registry Number"
},
{
"code": "1MT-US-TEL1-FOUNDINGDATE",
"value": "Full match was made on Founding Date"
},
{
"code": "1MT-US-DIG1-ORGANIZATION",
"value": "Full match was made on Organization/Business name"
},
{
"code": "1MT-US-DIG1-LOCALITY",
"value": "Full match was made on Organization/Business City/Locality"
},
{
"code": "1MT-US-DIG1-BUSINESSID",
"value": "Full match was made on Organization/Business Registry Number"
},
{
"code": "1MT-US-DIG1-FOUNDINGDATE",
"value": "Full match was made on Founding Date"
},
{
"code": "1MT-US-GVT1-ORGANIZATION",
"value": "Full match was made on Organization/Business name"
},
{
"code": "1MT-US-GVT1-LOCALITY",
"value": "Full match was made on Organization/Business City/Locality"
},
{
"code": "1MT-US-GVT1-BUSINESSID",
"value": "Full match was made on Organization/Business Registry Number"
},
{
"code": "1MT-US-GVT1-FOUNDINGDATE",
"value": "Full match was made on Founding Date"
},
{
"code": "1MT-US-TEL1-COMPLETENAME",
"value": "Full match was made on Complete Name"
},
{
"code": "1MT-US-TEL1-FIRSTINITIAL",
"value": "Full match was made on First Initial"
},
{
"code": "1MT-US-TEL1-FIRSTNAME",
"value": "Full match was made on First Name/Given Name"
},
{
"code": "1MT-US-TEL1-LASTNAME",
"value": "Full match was made on Last Name/Surname"
},
{
"code": "1MT-US-TEL1-DOB",
"value": "Full match was made on DOB"
},
{
"code": "1MT-US-TEL1-AFILLIATED",
"value": "Full match was made on Affiliated status"
},
{
"code": "1MT-US-TEL1-EMPLOYEE",
"value": "Full match was made on Employee status"
},
{
"code": "1MT-US-TEL1-OWNER",
"value": "A full match was made on Owner status"
},
{
"code": "1MT-US-TEL1-BENEFICIAL",
"value": "A full match was made on Beneficial Status"
},
{
"code": "1BZ-2000-ORGANIZATION",
"value": "Full match was made on Organization/Business Name"
},
{
"code": "1BZ-2250-LOCALITY",
"value": "Full match was made on Organization/Business City/Locality"
},
{
"code": "1BZ-2525-BUSINESSID",
"value": "Full match was made on Organization/Business Registry Number"
},
{
"code": "1BZ-2850-FOUNDINGDATE",
"value": "Full match was made on Organization/Business Founding Date"
},
{
"code": "1BZ-2725-DOMAIN",
"value": "Full match was made on Domain Name"
},
{
"code": "1BZ-2500-COMPANY_STATUS",
"value": "ACTIVE"
},
{
"code": "1BZ-2550-COMPANY_TYPE",
"value": "Corporation"
},
{
"code": "1ODO-3800-BENEFICIAL_OWNER",
"value": "Confirmed Beneficial Ownership between the Entity and the Organization"
},
{
"code": "Codes",
"value": "1BZ-2000-ORGANIZATION;1BZ-2250-LOCALITY;1BZ-2500-COMPANY_STATUS;1BZ-2525-BUSINESSID;1BZ-2550-COMPANY_TYPE;1BZ-2725-DOMAIN;1BZ-2850-FOUNDINGDATE;1MT-US-DIG1-BUSINESSID;1MT-US-DIG1-FOUNDINGDATE;1MT-US-DIG1-LOCALITY;1MT-US-DIG1-ORGANIZATION;1MT-US-GVT1-BUSINESSID;1MT-US-GVT1-FOUNDINGDATE;1MT-US-GVT1-LOCALITY;1MT-US-GVT1-ORGANIZATION;1MT-US-TEL1-AFILLIATED;1MT-US-TEL1-BENEFICIAL;1MT-US-TEL1-BUSINESSID;1MT-US-TEL1-COMPLETENAME;1MT-US-TEL1-DOB;1MT-US-TEL1-EMPLOYEE;1MT-US-TEL1-FIRSTINITIAL;1MT-US-TEL1-FIRSTNAME;1MT-US-TEL1-FOUNDINGDATE;1MT-US-TEL1-LASTNAME;1MT-US-TEL1-LOCALITY;1MT-US-TEL1-ORGANIZATION;1MT-US-TEL1-OWNER;1ODO-3800-BENEFICIAL_OWNER;FOUNDING_DATE;"
},
{
"code": "BusinessMatchCodes",
"value": "TEL1-BNFDZ:DIG1-BFZ:GVT1-BFZ"
},
{
"code": "IdentityMatchCodes",
"value": ""
}
]
},
"completename": "",
"formofaddress": "",
"qualificationpreceding": "",
"givenfullname": "Marcus",
"givennameinitials": "",
"qualification_int_first": "",
"surname_prefix_first": "",
"surname_first": "Stark",
"qualification_int_second": "",
"surname_prefix_second": "",
"qualification_suceeding": "",
"name_qualified": "",
"function": "",
"gender": "",
"nationality": "",
"nationalid": "1234567890",
"organization_name": "Random Inc.",
"dob": "01/03/1990",
"businessid": "47-423432",
"contact_type": "Affiliated;Employee;Director;Beneficial;Owner",
"countryCode": "US",
"passport": "",
"contactType": "Affiliated;Employee;Director;Beneficial;Owner",
"nameQualified": "",
"organizationName": "Random Inc.",
"qualificationIntFirst": "",
"qualificationIntSecond": "",
"qualificationSuceeding": "",
"surnameFirst": "Stark",
"surnamePrefixFirst": "",
"surnamePrefixSecond": ""
},
"address": {
"addressLine1": "",
"addressLine2": "",
"addressLine3": "",
"houseNumber": "47-9",
"houseNumberAddition": "",
"thoroughfare": "Glove Park Lane",
"locality": "Ashville",
"postalCode": "66327",
"province": "NC",
"countryCode": "US",
"name": "",
"organization": "",
"preIndicator": "",
"postIndicator": "",
"postBox": "",
"postTown": "",
"county": "",
"premise": "",
"department": "",
"building": "",
"district": "",
"subDistrict": "",
"latitude": "",
"longitude": "",
"countryName": "United States",
"formalCountryName": "United States of America",
"countryNumber": "840",
"countryISO3": "USA",
"dpvCoded": "",
"dpvFootnotes": "",
"dpvIndicator": "",
"dpvIsCMRA": "",
"dpvIsPBSA": "",
"dpvIsVacant": "",
"dpvIsNoStat": "",
"urbanization": "",
"hausCode": "",
"provinceCode": "",
"countyCode": "",
"municipalityCode": "",
"urbanArea": "",
"lotNumber": "",
"eggCode": "",
"congressionalDistrict": "",
"census": "",
"cebucoCode": "",
"lacsIndicator": "",
"timezone": "",
"addressLine4": "",
"addressLine5": "",
"addressLine6": "",
"addressLine7": "",
"addressLine8": "",
"addressLine9": "",
"addressLine10": "",
"codes": {
"reliability": "30",
"adaptation": "30",
"detailCode": "WS-6939537.2021.3.12.11.20.22.210",
"detail_list": "",
"options": "debug;MessageVerbose;ODOVerify",
"messages": [
{
"code": "WV",
"value": "Address could not be verified. Original input returned."
}
],
"detailList": ""
}
},
"phone": {
"name": "",
"phone_number": "",
"calling_from": "",
"formatted_international": "",
"line_type": "",
"international_prefix": "",
"calling_code": "",
"trunk": "",
"area_code": "",
"number": "",
"timezone": "",
"countryCode": "US",
"areaCode": "",
"callingCode": "",
"callingFrom": "",
"formattedInternational": "",
"internationalPrefix": "",
"lineType": "",
"codes": {
"reliability": "30",
"adaptation": "30",
"detailCode": "WS-6939537.2021.3.12.11.20.22.210",
"detail_list": "",
"options": "debug;MessageVerbose;ODOVerify",
"messages": [
{
"code": "WV",
"value": "Phone could not be verified. Original input returned."
}
],
"detailList": ""
},
"phoneNumber": ""
},
"email": {
"full_email_address": "",
"domain": "random.com",
"top_level": "",
"addressee": "",
"display_name": "",
"countryCode": "US",
"displayName": "",
"fullEmailAddress": "",
"topLevel": "",
"codes": {
"reliability": "30",
"adaptation": "30",
"detailCode": "WS-6939537.2021.3.12.11.20.22.210",
"detail_list": "",
"options": "debug;MessageVerbose;ODOVerify",
"messages": [
{
"code": "WV",
"value": "Email could not be verified. Original input returned."
}
],
"detailList": ""
}
},
"codes": {
"reliability": "30",
"adaptation": "30",
"detailCode": "WS-6939537.2021.3.12.11.20.22.210",
"detail_list": "",
"options": "debug;MessageVerbose;ODOVerify",
"messages": [],
"detailList": ""
}
}
}
1.4 Response Parameters
id | Session id |
state | Created, Pending, Finished, Failed, Timeout [Created – Session is created, Pending – Session is in progress, Finished – Session is finished, Failed – Session is failed, Timeout – Session is timed out] |
MatchLevel | High, Medium, Low . [Indicates the similarity between the in-data and the the best found match [High – A very good match, Medium – Could be accepted but need a manual inspection, Low – A poor match] |
companyFieldMatches | Describes request field match in supported data sources |
IndividualMatches | Individual related matches |
relaystate | This optional parameter will be returned to you at the redirect back to your server. Use it to link an unique ID of your choice that you can parse. Example: relaystate=zignsec_eid_1234 |
errors | List of errors |
providersData | Data returned from provider |
