Matching a customer identity by checking a set of attributes related against the account data bound to their phone number.

client.knowyourcustomermatch.match(, ?): KnowyourcustomermatchMatchResponse { addressMatch, addressMatchScore, birthdateMatch, 35 more }

POST/knowyourcustomermatch/match

Verify matching of a number of attributes related to a customer identity against the verified data bound to their phone number in the Operator systems. Regardless of whether the phoneNumber is explicitly stated in the request body, at least one of the other fields must be provided, otherwise a HTTP 400 - KNOW_YOUR_CUSTOMER.INVALID_PARAM_COMBINATION error will be returned.

The API will return the result of the matching process for each requested attribute. This means that the response will only contain the attributes for which validation has been requested. Possible values are:

true: the attribute provided matches with the one in the Operator systems, which is equal to a match_score of 100.
false: the attribute provided does not match with the one in the Operator systems.
not_available: the attribute is not available to validate.

ParametersExpand Collapse

params: KnowyourcustomermatchMatchParams { address, birthdate, cityOfBirth, 23 more }

address?: string

Body param: Complete address of the customer. For some countries, it is built following the usual concatenation of parameters in a country, but for other countries, this is not the case. For some countries, it can use streetName, streetNumber and/or houseNumberExtension. For example, in ESP, streetName+streetNumber; in NLD, it can be streetName+streetNumber or streetName+streetNumber+houseNumberExtension.

birthdate?: string

Body param: The birthdate of the customer, in RFC 3339 / ISO 8601 calendar date format (YYYY-MM-DD).

formatdate

cityOfBirth?: string

Body param: City where the customer was born.

country?: string

Body param: Country of the customer’s address. Format ISO 3166-1 alpha-2

countryOfBirth?: string

Body param: Country where the customer was born. Format ISO 3166-1 alpha-2.

email?: string

Body param: Email address of the customer in the RFC specified format (local-part@domain).

formatemail

familyName?: string

Body param: Last name, family name, or surname of the customer.

familyNameAtBirth?: string

Body param: Last/family/sur- name at birth of the customer.

gender?: "MALE" | "FEMALE" | "OTHER"

Body param: Gender of the customer (Male/Female/Other).

One of the following:

"MALE"

"FEMALE"

"OTHER"

givenName?: string

Body param: First/given name or compound first/given name of the customer.

houseNumberExtension?: string

Body param: Specific identifier of the house needed depending on the property type. For example, number of apartment in an apartment building.

idDocument?: string

Body param: Id number associated to the official identity document in the country. It may contain alphanumeric characters.

idDocumentExpiryDate?: string

Body param: Expiration date of the identity document (ISO 8601).

formatdate

idDocumentType?: "passport" | "national_id_card" | "residence_permit" | 4 more

Body param: Type of the official identity document provided.

One of the following:

"passport"

"national_id_card"

"residence_permit"

"diplomatic_id"

"driver_licence"

"social_security_id"

"other"

locality?: string

Body param: Locality of the customer’s address

middleNames?: string

Body param: Middle name/s of the customer.

name?: string

Body param: Complete name of the customer, usually composed of first/given name and last/family/sur- name in a country. Depending on the country, the order of first/give name and last/family/sur- name varies, and middle name could be included. It can use givenName, middleNames, familyName and/or familyNameAtBirth. For example, in ESP, name+familyName; in NLD, it can be name+middleNames+familyName or name+middleNames+familyNameAtBirth, etc.

nameKanaHankaku?: string

Body param: Complete name of the customer in Hankaku-Kana format (reading of name) for Japan.

nameKanaZenkaku?: string

Body param: Complete name of the customer in Zenkaku-Kana format (reading of name) for Japan.

nationality?: string

Body param: ISO 3166-1 alpha-2 code of the customer’s nationality. In the case a customer has more than one nationality, it is supposed to be the nationality related to the ID document provided in the match request.

phoneNumber?: string

Body param: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with ’+’.

postalCode?: string

Body param: Zip code or postal code

region?: string

Body param: Region/prefecture of the customer’s address

streetName?: string

Body param: Name of the street of the customer’s address. It should not include the type of the street.

streetNumber?: string

Body param: The street number of the customer’s address. Number identifying a specific property on the ‘streetName’.

xCorrelator?: string

Header param: Correlation id for the different services

ReturnsExpand Collapse

KnowyourcustomermatchMatchResponse { addressMatch, addressMatchScore, birthdateMatch, 35 more }

addressMatch?: MatchResult

true - the attribute provided matches with the one in the Operator systems, which is equal to a match_score of 100. false - the attribute provided does not match with the one in the Operator systems. not_available - the attribute is not available to validate.

One of the following:

"true"

"false"

"not_available"

addressMatchScore?: number

Indicates the similarity score assigned to the input value when it does not exactly match the value stored in the operator’s system. This property shall only be returned when the value of the corresponding match field is false. A perfect match with a score of 100 is indicated by match being ‘true’ and no matchScore is returned in this case.

minimum0

maximum99

birthdateMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

cityOfBirthMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

cityOfBirthMatchScore?: number

minimum0

maximum99

countryMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

countryOfBirthMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

emailMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

emailMatchScore?: number

minimum0

maximum99

familyNameAtBirthMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

familyNameAtBirthMatchScore?: number

minimum0

maximum99

familyNameMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

familyNameMatchScore?: number

minimum0

maximum99

genderMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

givenNameMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

givenNameMatchScore?: number

minimum0

maximum99

houseNumberExtensionMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

idDocumentExpiryDateMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

idDocumentMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

idDocumentTypeMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

localityMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

localityMatchScore?: number

minimum0

maximum99

middleNamesMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

middleNamesMatchScore?: number

minimum0

maximum99

nameKanaHankakuMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

nameKanaHankakuMatchScore?: number

minimum0

maximum99

nameKanaZenkakuMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

nameKanaZenkakuMatchScore?: number

minimum0

maximum99

nameMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

nameMatchScore?: number

minimum0

maximum99

nationalityMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

postalCodeMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

regionMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

regionMatchScore?: number

minimum0

maximum99

streetNameMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

streetNameMatchScore?: number

minimum0

maximum99

streetNumberMatch?: MatchResult

One of the following:

"true"

"false"

"not_available"

streetNumberMatchScore?: number

minimum0

maximum99

Matching a customer identity by checking a set of attributes related against the account data bound to their phone number.

import Camara from 'camara-sdk';

const client = new Camara({
  bearerToken: process.env['CAMARA_BEARER_TOKEN'], // This is the default and can be omitted
});

const response = await client.knowyourcustomermatch.match({
  address: 'Tokyo-to Chiyoda-ku Iidabashi 3-10-10',
  birthdate: '1978-08-22',
  cityOfBirth: 'Madrid',
  country: 'JP',
  countryOfBirth: 'ES',
  email: 'abc@example.com',
  familyName: 'Sanchez Arjona',
  familyNameAtBirth: 'YYYY',
  gender: 'OTHER',
  givenName: 'Federica',
  houseNumberExtension: 'VVVV',
  idDocument: '66666666q',
  idDocumentExpiryDate: '2027-07-12',
  idDocumentType: 'passport',
  locality: 'ZZZZ',
  middleNames: 'Sanchez',
  name: 'Federica Sanchez Arjona',
  nameKanaHankaku: 'federica',
  nameKanaZenkaku: 'Ｆｅｄｅｒｉｃａ',
  nationality: 'ES',
  phoneNumber: '+34629255833',
  postalCode: '1028460',
  region: 'Tokyo',
  streetName: 'Nicolas Salmeron',
  streetNumber: '4',
});

console.log(response.idDocumentExpiryDateMatch);

{
  "idDocumentMatch": "true",
  "idDocumentTypeMatch": "true",
  "idDocumentExpiryDateMatch": "true",
  "nameMatch": "true",
  "givenNameMatch": "not_available",
  "familyNameMatch": "not_available",
  "nameKanaHankakuMatch": "true",
  "nameKanaZenkakuMatch": "false",
  "middleNamesMatch": "true",
  "familyNameAtBirthMatch": "false",
  "familyNameAtBirthMatchScore": 90,
  "addressMatch": "true",
  "streetNameMatch": "true",
  "streetNumberMatch": "true",
  "postalCodeMatch": "true",
  "regionMatch": "true",
  "localityMatch": "not_available",
  "countryMatch": "true",
  "houseNumberExtensionMatch": "not_available",
  "birthdateMatch": "false",
  "emailMatch": "false",
  "emailMatchScore": 87,
  "genderMatch": "false",
  "cityOfBirthMatch": "false",
  "cityOfBirthMatchScore": 86,
  "countryOfBirthMatch": "true",
  "nationalityMatch": "true"
}

{
  "status": 400,
  "code": "INVALID_ARGUMENT",
  "message": "Client specified an invalid argument, request body or query param."
}

{
  "status": 400,
  "code": "KNOW_YOUR_CUSTOMER.INVALID_PARAM_COMBINATION",
  "message": "Indicated parameter combination is invalid"
}

{
  "status": 401,
  "code": "UNAUTHENTICATED",
  "message": "Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required."
}

{
  "status": 403,
  "code": "PERMISSION_DENIED",
  "message": "Client does not have sufficient permissions to perform this action."
}

{
  "status": 403,
  "code": "INVALID_TOKEN_CONTEXT",
  "message": "phoneNumber is not consistent with access token."
}

{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "The specified resource is not found."
}

{
  "status": 404,
  "code": "IDENTIFIER_NOT_FOUND",
  "message": "The phone number provided is not associated with a customer account"
}

{
  "status": 422,
  "code": "SERVICE_NOT_APPLICABLE",
  "message": "The service is not applicable for the provided phone number"
}

{
  "status": 422,
  "code": "MISSING_IDENTIFIER",
  "message": "No phone number has been provided"
}

Returns Examples

{
  "idDocumentMatch": "true",
  "idDocumentTypeMatch": "true",
  "idDocumentExpiryDateMatch": "true",
  "nameMatch": "true",
  "givenNameMatch": "not_available",
  "familyNameMatch": "not_available",
  "nameKanaHankakuMatch": "true",
  "nameKanaZenkakuMatch": "false",
  "middleNamesMatch": "true",
  "familyNameAtBirthMatch": "false",
  "familyNameAtBirthMatchScore": 90,
  "addressMatch": "true",
  "streetNameMatch": "true",
  "streetNumberMatch": "true",
  "postalCodeMatch": "true",
  "regionMatch": "true",
  "localityMatch": "not_available",
  "countryMatch": "true",
  "houseNumberExtensionMatch": "not_available",
  "birthdateMatch": "false",
  "emailMatch": "false",
  "emailMatchScore": 87,
  "genderMatch": "false",
  "cityOfBirthMatch": "false",
  "cityOfBirthMatchScore": 86,
  "countryOfBirthMatch": "true",
  "nationalityMatch": "true"
}

{
  "status": 400,
  "code": "INVALID_ARGUMENT",
  "message": "Client specified an invalid argument, request body or query param."
}

{
  "status": 400,
  "code": "KNOW_YOUR_CUSTOMER.INVALID_PARAM_COMBINATION",
  "message": "Indicated parameter combination is invalid"
}

{
  "status": 401,
  "code": "UNAUTHENTICATED",
  "message": "Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required."
}

{
  "status": 403,
  "code": "PERMISSION_DENIED",
  "message": "Client does not have sufficient permissions to perform this action."
}

{
  "status": 403,
  "code": "INVALID_TOKEN_CONTEXT",
  "message": "phoneNumber is not consistent with access token."
}

{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "The specified resource is not found."
}

{
  "status": 404,
  "code": "IDENTIFIER_NOT_FOUND",
  "message": "The phone number provided is not associated with a customer account"
}

{
  "status": 422,
  "code": "SERVICE_NOT_APPLICABLE",
  "message": "The service is not applicable for the provided phone number"
}

{
  "status": 422,
  "code": "MISSING_IDENTIFIER",
  "message": "No phone number has been provided"
}