Home / Docs / KYC Match

Know Your Customer Match

Know Your Customer (KYC) Match allows you to check the accuracy of customer info by cross-checking against the customer's records in their teleoperator's customer records. It allows you to verify that their phone number, ID document number, names, addresses and other similar information matches the values provided to the teleoperator. Some teleoperators can also calculate match rates for these values to give a more gradual rating for the accuracy of each field.

Performing a KYC Matchheader link

To match customer records, you must have at minimum the customer's phone number. You can then match against one or multiple of the following additional customer record types:

ID document number
Names, either in full or parts of a name
Address, full address or parts of it
Birth date
Email address
Gender

You don't have to match against all possible fields, you can only provide the fields that you are interested in and only receive matches for those.

You can then supply all the information you want into the request to have them checked. The system will then return the matches on each of the fields provided, including the optional match rate to check for a partial match.

import network_as_code as nac

# Initialize the client object with your application key
client = nac.NetworkAsCodeClient(
   token="<your-application-key-here>"
)

# Then, supply the customer identity data, which is to be used in matching
# a customer against the account data bound to their phone number.
customer_match_result = client.kyc.match_customer(
                phone_number= "+99999991000",
                id_document= "66666666q",
                name= "Federica Sanchez Arjona",
                given_name= "Federica",
                family_name= "Sanchez Arjona",
                name_kana_hankaku= "federica",
                name_kana_zenkaku= "Ｆｅｄｅｒｉｃａ",
                middle_names= "Sanchez",
                family_name_at_birth= "YYYY",
                address= "Tokyo-to Chiyoda-ku Iidabashi 3-10-10",
                street_name= "Nicolas Salmeron",
                street_number= "4",
                postal_code= "1028460",
                region= "Tokyo",
                locality= "ZZZZ",
                country= "JP",
                house_number_extension= "VVVV",
                birthdate= "1978-08-22",
                email= "[email protected]",
                gender= "OTHER")

# If successful, you can access the results like so:
print(customer_match_result)

The request may be populated with the following parameters:

Parameter	Description	Mandatory or Optional
`phone_number`	A public identifier addressing a telephone subscription, formatted in international format according to E.164 standard (prefixed with '+'). Example: "+123456789".	Mandatory
`id_document`	Id number associated to the official identity document in the country. May contain alphanumeric characters.	Optional
`name`	Complete name of the customer, usually composed of first/given name and last/family/surname in a country. Depending on the country, the order of first/given name and last/family/surname varies.	Optional
`given_name`	First/given name or compound first/given name of the customer.	Optional
`family_name`	Last name, family name, or surname of the customer.	Optional
`name_kana_hankaku`	Complete name of the customer in Hankaku-Kana format (reading of name) for Japan.	Optional
`name_kana_zenkaku`	Complete name of the customer in Zenkaku-Kana format (reading of name) for Japan.	Optional
`middle_names`	Middle names of the customer.	Optional
`family_name_at_birth`	Last/family/surname at birth of the customer.	Optional
`address`	Complete address of the customer, built following the usual concatenation of parameters in a country.	Optional
`street_name`	Name of the street of the customer's address. Should not include the type of the street.	Optional
`street_number`	The street number of the customer's address. Number identifying a specific property on the 'streetName'.	Optional
`postal_code`	Zip code or postal code.	Optional
`region`	Region/prefecture of the customer's address. Format ISO 3166-1 alpha-2.	Optional
`locality`	Locality of the customer's address.	Optional
`country`	Country of the customer's address. Format ISO 3166-1 alpha-2.	Optional
`house_number_extension`	Specific identifier of the house needed depending on the property type. For example, number of apartment in an apartment building.	Optional
`birthdate`	The birthdate of the customer, in RFC 3339 / ISO 8601 calendar date format (YYYY-MM-DD).	Optional
`email`	Email address of the customer in the RFC specified format (local-part@domain).	Optional
`gender`	Gender of the customer (Male/Female/Other).	Optional

The result will be an object with the following parameters, where the parameters reflecting the request should be set:

Property Name	Description
`id_document_match`	Indicates whether the ID number associated with the customer's document matches the one in the Operator's system.
`name_match`	Indicates whether the complete name of the customer matches the one in the Operator's system.
`name_match_score`	Optional: Numeric accuracy of the match as a percentage from 0 to 100.
`given_name_match`	Indicates whether the first name or given name of the customer matches with the one in the Operator's system.
`given_name_match_score`	Optional: Numeric accuracy of the match as a percentage from 0 to 100.
`family_name_match`	Indicates whether the last name, surname, or family name of the customer matches with the one in the Operator's system.
`family_name_match_score`	Optional: Numeric accuracy of the match as a percentage from 0 to 100.
`name_kana_hankaku_match`	Indicates whether the complete name of the customer in Hankaku-Kana format (reading of name) for Japan matches with the one in the Operator's system.
`name_kana_hankaku_match_score`	Optional: Numeric accuracy of the match as a percentage from 0 to 100.
`name_kana_zenkaku_match`	Indicates whether the complete name of the customer in Zenkaku-Kana format (reading of name) for Japan matches with the one in the Operator's system.
`name_kana_zenkaku_match_score`	OptionaL: Numeric accuracy of the match as a percentage from 0 to 100.
`middle_names_match`	Indicates whether the middle names of the customer match with the one in the Operator's system.
`middle_names_match_score`	Optional: Numeric accuracy of the match as a percentage from 0 to 100.
`family_name_at_birth_match`	Indicates whether the Family Name At Birth of the customer matches with the one in the Operator's system.
`family_name_at_birth_match_score`	Optional: Numeric accuracy of the match as a percentage from 0 to 100.
`address_match`	Indicates whether the complete address of the customer matches with the one in the Operator's system.
`address_match_score`	Optional: Numeric accuracy of the match as a percentage from 0 to 100.
`street_name_match`	Indicates whether the street name of the customer matches with the one in the Operator's system.
`street_name_match_score`	Optional: Numeric accuracy of the match as a percentage from 0 to 100.
`street_number_match`	Indicates whether the street number of the customer matches with the one in the Operator's system.
`street_number_match_score`	Optional: Numeric accuracy of the match as a percentage from 0 to 100.
`postal_code_match`	Indicates whether the postal code / zip code of the customer matches with the one in the Operator's system.
`region_match`	Indicates whether the region of the customer's address matches with the one in the Operator's system.
`region_match_score`	Optional: Numeric accuracy of the match as a percentage from 0 to 100.
`locality_match`	Indicates whether the locality of the customer's address matches with the one in the Operator's system.
`locality_match_score`	Optional: Numeric accuracy of the match as a percentage from 0 to 100.
`country_match`	Indicates whether the country of the customer's address matches with the one in the Operator's system.
`house_number_extension_match`	Indicates whether the house number extension of the customer's address matches with the one in the Operator's system.
`birthdate_match`	Indicates whether the birthdate of the customer matches with the one in the Operator's system.
`email_match`	Indicates whether the email address of the customer matches with the one in the Operator's system.
`email_match_score`	Optional: Numeric accuracy of the match as a percentage from 0 to 100.
`gender_match`	Indicates whether the gender of the customer matches with the one in the Operator's system.

The response will contain all the same keys as specified in the request and binary matches will either be specified as True/true or False/false. If the requested attribute is not availabe for validation, API will return not_available, which is converted to None/null value for Python and Typescript. Some operators also provide additional fields containing the granular matchrate may be available and will be specified as an integer from 0 to 100 representing a percentage.

NOTE: Match rates may not be available for every operator, so you shouldn't rely on that field being present at all times.

Last updated December 19, 2025