Verfiy Identity

This service verifies a person’s address or identity information such as name and address via background data source lookups in a multitude of registers. The list of supported countries is large and is expanded through quick configuration.

Step 1 : Start Identity Verification Session

POST to

Test enviornment : https://test-gateway.zignsec.com/core/api/sessions/identity_check/gdc

Production enviornment :  https://gateway.zignsec.com/core/api/sessions/identity_check/gdc

ValidationMethod and the Pricing Level

To know more about the price level, please contact sales.

ValidationMethods:

  1. id1x1: Queries until found in one data source allows:
    1. validate identity fields see more details in Match Guide_Default_1x1
    2. Validate Name, National ID and Date of birth NID matchguide
    3. Validate Name_Address_ID NAI_Match Guide
    4. Validate Name_Address_ID v2 NAI_v2_Match Guide
    5. Validate Name_Address
  2. id2x2: Queries until found in two data sources. Suitable for UK.
    1. MatchGuide for Validate_Identity_Default_2x2

Note that the different tenants described above are available in different countries. You can check the coverage with sales or support service.

You can select a specialized query configuration with the ValidationMethod parameter. Contact ZignSec for the correct set up.

1.1 Request example

POST https://test-gateway.zignsec.com/core/api/sessions/identity_check/gdc
Content-Type :  application/json
Authorization : 12345678-YOUR-ACCESS-TOKEN-5352305c9fb0
Content-Length :725

{
  "metadata": {
    "address": {
      "address_line1": "DAVTASHEN 4TAX 4-22",
      "city": "YEREVAN",
      "country_code": "AM",
      "house_number": "4-22",
      "postal_code": "10"

    },
    "birth_date": "1974-02-17",
    "first_name": "MESROP",
    "last_name": "MASHTOTS",
    "national_id": "AH0278181",
    "options": [
      "IdentityVerify"
    ]
  },
  "relay_state": "string",
  "webhook": "string"
}

1.2 Description of request model

ParameterDescriptionRequired
metadataContain parameters like : address_line1, city , country_code etcYes
addressaddressLine1 , addressLine2 , addressLine3 
cityCity 
country_codeTwo letter ISO country code 
house_numberHouse number 
provinceRegion dependent. (For example can be used to specify USA state) 
birth_dateDate of birth (YYYY-MM-DD or YYYYMMDD) 
emailEmail 
first_nameFirst name 
last_nameLast name 
national_idNational ID (ex. Social Security Number – SSN) 
options

IdentityVerify – For those countries that support this feature the service will attempt to verify the identity 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 identity results.
IdentityEnrich – For those countries that support this feature the service will attempt to verify the identity with the best match using all provided input data and enrich with any data elements that may be returned or appended.

NativeOutputScript – Address option. Return the validated or verified result in the native alphabet. For example Greek for Greece, Cyrillic for Russia, and Arabic for the UAE.
UpperCase – Address option. Return all data in upper case where possible.

LowerCase – Address option. Return all data in lower case where possible.

GeoCoding – Address option. Attempt to geocode the address results AFTER verification and append a latitude and longitude to the return.,
Parse – Parses input from addressline fields into proper individual address elements prior to performing the verification.,
PreserveDiacritics – This option maintains the integrity of diacritics during processing.,
PreserveScript – This option maintains non-latin characters before processing. The default is to remove the non-latin characters before processing.]

 
provider_parameters

Provider parameters. (Used to pass request parameters to the upstream data provider)

 
tenantTenant. Optional parameter to overwrite default tenant 
relay_stateOptional Custom Parameter to be included in webhook calls 
webhookWebhook URL where your backend will receive session events. 

Note:

* The system requires a minimum of Complete Name, Zip Code and Country code to make a minimal Identity Verification check. Generally speaking, the more information that is provided with the request, the better the confidence in the match.

Additionally, it is best practice to provide additional inputs when making an Identity call such as DOB. Certain countries and data sources have mandatory, required fields that are necessary to successfully obtain a result from the service.  The required input fields vary by country. In Argentina, China, Brazil and Mexico is best practice to provide a National Identifier. In the United States, it is best practice to provide State (Administrative Area).

In the test environment the ValidateAddress and ValidateIdentity calls query against a table of pre-defined set of test persons per country. See it in Test_cache

1.3 Example of Response Body

{
  "data": {
    "errors": [],
    "id": "cdb06f85-1327-4e72-a1ed-ea08db5be46e",
    "result": {
      "fieldMatches": [
        {
          "countryCode": "AM",
          "dataSource": "Commercial",
          "dataSourceNumber": 9,
          "description": "Full match was made on Complete Name",
          "fieldName": "COMPLETENAME",
          "matchType": "FullMatch"
        },
        {
          "countryCode": "AM",
          "dataSource": "Commercial",
          "dataSourceNumber": 9,
          "description": "Full match was made on First Initial",
          "fieldName": "FIRSTINITIAL",
          "matchType": "FullMatch"
        },
        {
          "countryCode": "AM",
          "dataSource": "Commercial",
          "dataSourceNumber": 9,
          "description": "Full match was made on First Name/Given Name",
          "fieldName": "FIRSTNAME",
          "matchType": "FullMatch"
        },
        {
          "countryCode": "AM",
          "dataSource": "Commercial",
          "dataSourceNumber": 9,
          "description": "Full match was made on Last Name/Surname ",
          "fieldName": "LASTNAME",
          "matchType": "FullMatch"
        },
        {
          "countryCode": "AM",
          "dataSource": "Commercial",
          "dataSourceNumber": 9,
          "description": "Full match was made on Postal Code/Zip Code",
          "fieldName": "POSTALCODE",
          "matchType": "FullMatch"
        },
        {
          "countryCode": "AM",
          "dataSource": "Commercial",
          "dataSourceNumber": 9,
          "description": "Full match was made on National ID",
          "fieldName": "NATIONALID",
          "matchType": "FullMatch"
        },
        {
          "countryCode": "AM",
          "dataSource": "Commercial",
          "dataSourceNumber": 9,
          "description": "Full match was made on Date of Birth",
          "fieldName": "DATEOFBIRTH",
          "matchType": "FullMatch"
        },
        {
          "countryCode": "AM",
          "dataSource": "Commercial",
          "dataSourceNumber": 9,
          "description": "Full match was made on Day of Birth",
          "fieldName": "DAYOFBIRTH",
          "matchType": "FullMatch"
        },
        {
          "countryCode": "AM",
          "dataSource": "Commercial",
          "dataSourceNumber": 9,
          "description": "Full match was made on Month of Birth",
          "fieldName": "MONTHOFBIRTH",
          "matchType": "FullMatch"
        },
        {
          "countryCode": "AM",
          "dataSource": "Commercial",
          "dataSourceNumber": 9,
          "description": "Full match was made on Year of Birth",
          "fieldName": "YEAROFBIRTH",
          "matchType": "FullMatch"
        },
        {
          "countryCode": "AM",
          "dataSource": "Commercial",
          "dataSourceNumber": 9,
          "description": "Partial match made on element Address Lines",
          "fieldName": "ADDRESS",
          "matchType": "PartialMatch"
        }
      ],
      "matchLevel": "Medium",
      "providerData": {
        "address": {
          "timezone": "",
          "countryISO3": "ARM",
          "countryName": "Armenia",
          "addressLine10": "",
          "countryCode": "AM",
          "lotNumber": "",
          "formalCountryName": "Republic of Armenia",
          "dpvFootnotes": "",
          "houseNumberAddition": "",
          "premise": "",
          "dpvIsVacant": "",
          "addressLine2": "YEREVAN",
          "postIndicator": "",
          "addressLine5": "",
          "dpvIsPBSA": "",
          "latitude": "",
          "dpvIsCMRA": "",
          "dpvCoded": "",
          "countyCode": "",
          "addressLine4": "",
          "eggCode": "",
          "municipalityCode": "",
          "lacsIndicator": "",
          "locality": "",
          "hausCode": "",
          "census": "",
          "department": "",
          "addressLine7": "",
          "dpvIsNoStat": "",
          "county": "",
          "postBox": "",
          "addressLine8": "",
          "postTown": "",
          "longitude": "",
          "congressionalDistrict": "",
          "addressLine6": "",
          "urbanization": "",
          "cebucoCode": "",
          "province": "string",
          "codes": {
            "adaptation": "30",
            "detailCode": "WS-851504.2022.3.28.8.44.22.393",
            "detailList": "",
            "detail_list": "",
            "messages": [],
            "options": "Debug;IdentityVerify;MessageVerbose",
            "reliability": "30"
          },
          "addressLine1": "DAVTASHEN 4TAX 4-22",
          "postalCode": "10",
          "houseNumber": "4-22",
          "countryNumber": "51",
          "urbanArea": "",
          "building": "",
          "subDistrict": "",
          "addressLine9": "",
          "dpvIndicator": "",
          "district": "",
          "name": "",
          "thoroughfare": "string",
          "preIndicator": "",
          "addressLine3": "",
          "provinceCode": "",
          "organization": ""
        },
        "codes": {
          "adaptation": "30",
          "detailCode": "WS-851504.2022.3.28.8.44.22.393",
          "detailList": "",
          "detail_list": "",
          "messages": [],
          "options": "Debug;IdentityVerify;MessageVerbose",
          "reliability": "30"
        },
        "email": {
          "addressee": "",
          "codes": {
            "adaptation": "30",
            "detailCode": "WS-851504.2022.3.28.8.44.22.393",
            "detailList": "",
            "detail_list": "",
            "messages": [
              {
                "code": "WV",
                "value": "Email could not be verified.  Original input returned."
              }
            ],
            "options": "Debug;IdentityVerify;MessageVerbose",
            "reliability": "30"
          },
          "countryCode": "AM",
          "displayName": "",
          "display_name": "",
          "domain": "",
          "fullEmailAddress": "",
          "full_email_address": "",
          "topLevel": "",
          "top_level": ""
        },
        "identity": {
          "indicator": "",
          "gender": "",
          "nationalid": "AH0278181",
          "qualification_int_second": "",
          "surname_prefix_first": "",
          "organization_name": "",
          "surname_prefix_second": "",
          "countryCode": "AM",
          "businessid": "",
          "qualificationIntFirst": "",
          "passport": "",
          "organizationName": "",
          "formofaddress": "",
          "qualification_int_first": "",
          "givennameinitials": "",
          "surnamePrefixFirst": "",
          "qualificationIntSecond": "",
          "contact_type": "",
          "givenfullname": "MESROP",
          "qualification_suceeding": "",
          "completename": "",
          "surname_first": "MASHTOTS",
          "surnamePrefixSecond": "",
          "qualificationpreceding": "",
          "name_qualified": "",
          "contactType": "",
          "codes": {
            "adaptation": "0",
            "detailCode": "WS-851504.2022.3.28.8.44.22.393",
            "detailList": "",
            "detail_list": "",
            "messages": [
              {
                "code": "1MT-AM-CMM9-COMPLETENAME",
                "value": "Full match was made on Complete Name"
              },
              {
                "code": "1MT-AM-CMM9-FIRSTINITIAL",
                "value": "Full match was made on First Initial"
              },
              {
                "code": "1MT-AM-CMM9-FIRSTNAME",
                "value": "Full match was made on First Name/Given Name"
              },
              {
                "code": "1MT-AM-CMM9-LASTNAME",
                "value": "Full match was made on Last Name/Surname "
              },
              {
                "code": "1MT-AM-CMM9-POSTALCODE",
                "value": "Full match was made on Postal Code/Zip Code"
              },
              {
                "code": "1MT-AM-CMM9-NATIONALID",
                "value": "Full match was made on National ID"
              },
              {
                "code": "1MT-AM-CMM9-DATEOFBIRTH",
                "value": "Full match was made on Date of Birth"
              },
              {
                "code": "1MT-AM-CMM9-DAYOFBIRTH",
                "value": "Full match was made on Day of Birth"
              },
              {
                "code": "1MT-AM-CMM9-MONTHOFBIRTH",
                "value": "Full match was made on Month of Birth"
              },
              {
                "code": "1MT-AM-CMM9-YEAROFBIRTH",
                "value": "Full match was made on Year of Birth"
              },
              {
                "code": "3MT-AM-CMM9-ADDRESS",
                "value": "Partial match made on element Address Lines"
              },
              {
                "code": "1AU-425-COMPLETENAME",
                "value": "Full match was made on Complete Name"
              },
              {
                "code": "1AU-375-FIRSTINITIAL",
                "value": "Full match was made on First Initial"
              },
              {
                "code": "1AU-350-FIRSTNAME",
                "value": "Full match was made on First Name/Given Name"
              },
              {
                "code": "1AU-400-LASTNAME",
                "value": "Full match was made on Last Name/Surname "
              },
              {
                "code": "1AU-275-POSTALCODE",
                "value": "Full match was made on Postal Code/Zip Code"
              },
              {
                "code": "1AU-525-NATIONALID",
                "value": "Full match was made on National ID"
              },
              {
                "code": "1AU-550-DATEOFBIRTH",
                "value": "Full match was made on Date of Birth"
              },
              {
                "code": "1AU-575-DAYOFBIRTH",
                "value": "Full match was made on Day of Birth"
              },
              {
                "code": "1AU-600-MONTHOFBIRTH",
                "value": "Full match was made on Month of Birth"
              },
              {
                "code": "1AU-625-YEAROFBIRTH",
                "value": "Full match was made on Year of Birth"
              },
              {
                "code": "3AU-200-ADDRESS",
                "value": "Partial match made on element Address Lines"
              },
              {
                "code": "Codes",
                "value": "1AU-275-POSTALCODE;1AU-350-FIRSTNAME;1AU-375-FIRSTINITIAL;1AU-400-LASTNAME;1AU-425-COMPLETENAME;1AU-525-NATIONALID;1AU-550-DATEOFBIRTH;1AU-575-DAYOFBIRTH;1AU-600-MONTHOFBIRTH;1AU-625-YEAROFBIRTH;1MT-AM-CMM9-COMPLETENAME;1MT-AM-CMM9-DATEOFBIRTH;1MT-AM-CMM9-DAYOFBIRTH;1MT-AM-CMM9-FIRSTINITIAL;1MT-AM-CMM9-FIRSTNAME;1MT-AM-CMM9-LASTNAME;1MT-AM-CMM9-MONTHOFBIRTH;1MT-AM-CMM9-NATIONALID;1MT-AM-CMM9-POSTALCODE;1MT-AM-CMM9-YEAROFBIRTH;3AU-200-ADDRESS;3MT-AM-CMM9-ADDRESS;"
              }
            ],
            "options": "Debug;IdentityVerify;MessageVerbose",
            "reliability": "20"
          },
          "surnameFirst": "MASHTOTS",
          "function": "",
          "nationality": "",
          "nameQualified": "",
          "dob": "02/17/1974",
          "qualificationSuceeding": ""
        },
        "phone": {
          "areaCode": "",
          "area_code": "",
          "callingCode": "",
          "callingFrom": "",
          "calling_code": "",
          "calling_from": "",
          "codes": {
            "adaptation": "30",
            "detailCode": "WS-851504.2022.3.28.8.44.22.393",
            "detailList": "",
            "detail_list": "",
            "messages": [
              {
                "code": "WV",
                "value": "Phone could not be verified.  Original input returned."
              }
            ],
            "options": "Debug;IdentityVerify;MessageVerbose",
            "reliability": "30"
          },
          "countryCode": "AM",
          "formattedInternational": "",
          "formatted_international": "",
          "internationalPrefix": "",
          "international_prefix": "",
          "lineType": "",
          "line_type": "",
          "name": "",
          "number": "",
          "phoneNumber": "",
          "phone_number": "",
          "timezone": "",
          "trunk": ""
        }
      }
    },
    "status": "Finished"
  }
}

1.4 Description of Response Body

idUnique session identifier, used for GET Request .
country_codeCountry code
data_source[Credit – Data sources containing Credit Bureau, Credit Registry, Credit Monitoring Services and/or other credit related data sources which can be used in a country to identify an individual. Examples of credit could be Credit Header Records from Bureau data, Credit Monitoring databases, debt management, and potentially bankruptcy or financial statements., Government – A government, public, or public/private partnership providing data sources covering individuals or citizens in a country or countries. Examples of government could be electoral rolls, census data, citizenship databases, and real estate or tax data sets., Commercial – Commercial data is sourced from commerce-based transaction data, registers of professionals, consumer and marketing data sources. Examples of commercial include professional membership directory data, publishing and media (including television) subscriber data, direct mail, e-commerce consumer and loyalty card program databases., Consumer – Consumer data is a sub-set of Commercial data that comes from marketing sources with opt-in/consent. Examples of consumer could be digital consumer data sources, direct mail, e-commerce, and loyalty card programs, and lead generation., Utility – Data sourced from utility billing, customer profile, provisioning and management records for electric, gas, water, sewer, internet, cable, and public/private utility companies in a country or region. Examples of utility could be electric bill statements data, customer records on delivery of electrical or gas services, and utility databases used for customer communication., Proprietary – Data sources which are typically either unique to a region or country, private in the nature of the data acquisition, and cannot be classified into any other specific data source type., TelephoneCompany – Data sources from telephone/telco companies and their affiliates which include mobile, landline and telephone registry data. Examples of telco could be whitepages telco registries, HLR/VLR databases, telco customer databases and customer billing and invoicing records., Postal – Data sources from government and quasi-governmental postal authorities. These data sets may also include delivery data from private couriers, package delivery, and geospatial providers. Examples of postal could range from Change of Address (COA) databases, receipt and delivery verification databases, and postal address registries., OtherDataSource – Other data source]
data_source_numberData source number. Often multiples of the same type of data source are available in a specific country this number helps to distinguish between them
field_nameName of the field that was matched
match_type

[ NoMatch, PartialMatch, FullMatch, Missing ]

NoMatch – Element did not match with the data source, PartialMatch – Element partially matched with the data source, FullMatch – Element fully matched with the data source, Missing – Element is not contained in the data source

match_level

[ High, Medium, Low ]

High – A very good match, Medium – Could be accepted but need a manual inspection, Low – A poor match

provider_data

Data returned from provider

status[ Created, Finished, Failed, Timeout ]

Step 2 : Get Session Result

GET to https://test-gateway.zignsec.com/core/api/sessions/{sessionId}

Swagger Links

Test enviornment : https://test-gateway.zignsec.com/#/Session%20Data/getSessionById

Production enviornment : https://gateway.zignsec.com/#/Session%20Data/getSessionById

Gets GDC identity verification session by ID

Data Source List

NameDefinition
Credit

– Data sources containing Credit Bureau, Credit Registry, Credit Monitoring Services and/or other credit related data sources which can be used in a country to identify an individual.

Examples of credit could be Credit Header Records from Bureau data, Credit Monitoring databases, debt management, and potentially bankruptcy or financial statements.

Government

– A government, public, or public/private partnership providing data sources covering individuals or citizens in a country or countries.

Examples of government could be electoral rolls, census data, citizenship databases, and real estate or tax data sets.

Commercial

– Commercial data is sourced from commerce-based transaction data, registers of professionals, consumer and marketing data sources.

Examples of commercial include professional membership directory data, publishing and media (including television) subscriber data, direct mail, e-commerce consumer and loyalty card program databases.

Consumer

Consumer data is a sub-set of Commercial data that comes from marketing sources with opt-in/consent.

Examples of consumer could be digital consumer data sources, direct mail, e-commerce, and loyalty card programs, and lead generation.

Utility

– Data sourced from utility billing, customer profile, provisioning and management records for electric, gas, water, sewer, internet, cable, and public/private utility companies in a country or region.

Examples of utility could be electric bill statements data, customer records on delivery of electrical or gas services, and utility databases used for customer communication.

Proprietary– Data sources which are typically either unique to a region or country, private in the nature of the data acquisition, and cannot be classified into any other specific data source type.
TelephoneCompany

– Data sources from telephone/telco companies and their affiliates which include mobile, landline and telephone registry data.

Examples of telco could be whitepages telco registries, HLR/VLR databases, telco customer databases and customer billing and invoicing records.

Postal

– Data sources from government and quasi-governmental postal authorities. These data sets may also include delivery data from private couriers, package delivery, and geospatial providers.

Examples of postal could range from Change of Address (COA) databases, receipt and delivery verification databases, and postal address registries.

OtherDataSource