kyc_match
kyc_match checks the identity data you hold for a customer
against the subscriber records of the customer's mobile operator. The
operator's own data is never returned. For each element you send, you get
a score that says how closely it matches.
Request
Put kyc_match in commands and add a
kyc_challenges object with the data to check.
kyc_challenges is required whenever kyc_match
is requested, and it must contain an address: either the structured
address or the free-text inline_address.
{
"number": "+393273339145",
"commands": ["kyc_match"],
"kyc_challenges": {
"name": { "first_name": "Luigi", "last_name": "Armani" },
"dob": { "day": 28, "month": 2, "year": 1999 },
"address": {
"street": "Via Corsini",
"street_no": "21",
"city": "Fanano",
"province": "MO",
"postcode": "41021",
"country": "IT"
}
}
}| Field | Content and rules |
|---|---|
name |
Optional. first_name, last_name,
middle_name, family_name_at_birth,
and, for operators that use them, name_kana_hankaku
and name_kana_zenkaku. |
address |
A structured address: street,
street_no, house_number_extension,
city, province, postcode,
country (ISO code) and national_id.
Send every part you have: an element you leave out cannot be
checked. |
inline_address |
The alternative to address: the whole address as
one string, in address. If you send both forms, the
structured address is used and
inline_address is ignored. |
dob |
Date of birth. Send day, month and
year together, as a real calendar date, or leave the
whole object out. An empty dob counts as left
out. |
email |
Optional. The customer's email address. |
gender |
Optional, for operators that support it: MALE,
FEMALE or OTHER. |
These requests are rejected with HTTP 400 before any
operator is contacted, and they are not charged:
kyc_matchrequested withoutkyc_challenges;kyc_challengeswith no address in either form;- a
dobwith only some of its parts, or a date that does not exist (for example 31 February).
If you send kyc_challenges without requesting
kyc_match, it is ignored.
Plumma® Connect does not require a minimum set of elements, but an operator may: some refuse a check that does not include, for example, a first name. Operators also differ in which elements they can check. An element the operator cannot check gets no score.
Response
When an operator answers, the response contains a
kyc_results block with one score for each element it
checked:
{
"status": 0,
"status_message": "Response from one supplier",
"kyc_results": {
"first_name_score": 100,
"last_name_score": 100,
"dob_score": 0,
"street_score": 87,
"street_no_score": 100,
"city_score": 100,
"postcode_score": 100
},
"version": "..."
}| Score fields (integer) |
|---|
first_name_score, last_name_score,
middle_name_score, name_score,
dob_score, email_score,
address_score, street_score,
street_no_score, city_score,
province_score, postcode_score,
country_score, national_id_score
|
Reading a score
| Value | Meaning |
|---|---|
100 | Exact match. |
1 to 99 | Partial match, for example a spelling difference. How the operator grades it is its own. |
0 | The operator holds this element, and it does not match. |
-1 | The operator holds no data for this element, so it can neither confirm nor deny it. |
| Field absent | The element was not sent, or the operator could not check it. |
Some operators grade on the whole 0 to 100 range. Others answer only
match or no match, which comes back as 100 or
0. Your logic should treat every value in between as
possible.
Treat an absent score and -1 the same way: as "not
verified", never as a failed match. Only 0 means the data
is there and differs.
When there is no kyc_results block
If the operator returned no result, for example because the number is
not one of its subscribers or because the check is not enabled for that
operator, the response has no kyc_results block. The
status is 4, and the
status_message names kyc_match and, where the
operator gave one, the reason:
{
"status": 4,
"status_message": "Response from one supplier - Commands [kyc_match] were routed but returned no data (kyc_match: ...)",
...
}
A kyc_match with no kyc_results block is not
charged. If the number's country is not covered for
kyc_match, you get status 2 when
it was the only command, or 4 together with the other
commands, and it is not charged either.