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

ParameterDescriptionRequired
metaDataSee table belowYes

MetaData Parameters

ParameterDescriptionRequired
CompanyNameCorporate/Organization name, DBA name, Legal Entity Name 
CompanyIdTypeType of company ID.
 Example – TaxIdNumber, ValueAddedTaxNumber, IbanNumber, SwiftNumber, CreditCardNumber, BusinessLicenseNumber, LegalEntityIdentifier, DunsNumber, ChamberOfCommerceNumber 
 
CompanyIdCompany/Business ID number (ex. U.S. – EIN, Italy – codice di fiscale, Brazil – CNPJ, VAT Number) 
FoundingDateCompany founding date (YYYY-MM-DD or YYYYMMDD) 
phoneCompany phone number 
emailCompany email address 
websiteCompany website URL 
CityCompany city 
CountryCodeTwo letter ISO country code 
IndividualData of the individual related to the company (Owners, Directors and Officers) 
firstNameFirst name 
lastNameLast name 
providerParametersProvider parameters. (Used to pass request parameters to the upstream data provider) 
RelayStateThis 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

idSession id
stateCreated, 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]
companyFieldMatchesDescribes request field match in supported data sources
IndividualMatchesIndividual related matches
relaystateThis 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. Examplerelaystate=zignsec_eid_1234
errorsList of errors
providersDataData returned from provider