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

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.

Header ParametersExpand Collapse

"x-correlator": optional string

Body ParametersJSONExpand Collapse

address: optional string

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: optional string

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

formatdate

cityOfBirth: optional string

City where the customer was born.

country: optional string

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

countryOfBirth: optional string

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

email: optional string

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

formatemail

familyName: optional string

Last name, family name, or surname of the customer.

familyNameAtBirth: optional string

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

gender: optional "MALE" or "FEMALE" or "OTHER"

Gender of the customer (Male/Female/Other).

One of the following:

"MALE"

"FEMALE"

"OTHER"

givenName: optional string

First/given name or compound first/given name of the customer.

houseNumberExtension: optional string

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

idDocument: optional string

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

idDocumentExpiryDate: optional string

Expiration date of the identity document (ISO 8601).

formatdate

idDocumentType: optional "passport" or "national_id_card" or "residence_permit" or 4 more

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: optional string

Locality of the customer’s address

middleNames: optional string

Middle name/s of the customer.

name: optional string

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: optional string

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

nameKanaZenkaku: optional string

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

nationality: optional string

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: optional string

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: optional string

Zip code or postal code

region: optional string

Region/prefecture of the customer’s address

streetName: optional string

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

streetNumber: optional string

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

ReturnsExpand Collapse

addressMatch: optional 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: optional 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: optional MatchResult

One of the following:

"true"

"false"

"not_available"

cityOfBirthMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

cityOfBirthMatchScore: optional number

minimum0

maximum99

countryMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

countryOfBirthMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

emailMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

emailMatchScore: optional number

minimum0

maximum99

familyNameAtBirthMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

familyNameAtBirthMatchScore: optional number

minimum0

maximum99

familyNameMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

familyNameMatchScore: optional number

minimum0

maximum99

genderMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

givenNameMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

givenNameMatchScore: optional number

minimum0

maximum99

houseNumberExtensionMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

idDocumentExpiryDateMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

idDocumentMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

idDocumentTypeMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

localityMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

localityMatchScore: optional number

minimum0

maximum99

middleNamesMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

middleNamesMatchScore: optional number

minimum0

maximum99

nameKanaHankakuMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

nameKanaHankakuMatchScore: optional number

minimum0

maximum99

nameKanaZenkakuMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

nameKanaZenkakuMatchScore: optional number

minimum0

maximum99

nameMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

nameMatchScore: optional number

minimum0

maximum99

nationalityMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

postalCodeMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

regionMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

regionMatchScore: optional number

minimum0

maximum99

streetNameMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

streetNameMatchScore: optional number

minimum0

maximum99

streetNumberMatch: optional MatchResult

One of the following:

"true"

"false"

"not_available"

streetNumberMatchScore: optional number

minimum0

maximum99

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

curl https://api.example.com/camara/knowyourcustomermatch/match \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CAMARA_BEARER_TOKEN" \
    -d '{
          "phoneNumber": "+34629255833"
        }'

{
  "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"
}