Match (CAMARA)0.2.1

Match (CAMARA) uses a three-legged OAuth flow. A three-legged OAuth process involves three parties: the end-user (or resource owner), the client (the third-party application), and the server (or authorization server):

1. Get an authorization code
2. Exchange the authorization code for an access token
3. Match the mobile number

For more information on OAuth, see OAuth 2.0 RFC 6749, section 4.1 (external website).

1. Make a request to Vodafone’s “/bc-authorize” endpoint.
2. Vodafone's API validates the client_id provided.
3. Vodafone provides an auth_req_id  in the response that can be used for token call.

Authorization request example

curl -X 'POST' \
          'https://217d24e9-160c-434a-8e95-4f04d40cceac.mock.pstmn.io/openIDConnectCIBA/v1/bc-authorize' \
          -H 'Authorization: Basic d3lCOHF1R0RPWTdXTnUyVUV2eGF5Sk9aNVpTSU1KM1Y6V2ZHQUJqSUJpRDIySg==' \
          -H 'X-Correlator: 42da5b19-457a-4d30-a5c4-038c62dccbb0' \
          -H 'Content-Type: application/x-www-form-urlencoded' \
          -d 'login_hint=tel%3A%2B447123456789&scope=kyc-match%3Amatch'
                

Authorization response example

HTTP/1.1 200 OK
        {
          "auth_req_id": "39da5b19-457a-4d30-a5c4-047c62dcca3b",
          "expires_in": 300,
          "interval": 0
        }
                

In order to use this API, you must exchange the auth_req_id for an access token.

The token is valid for 59 minutes and 59 seconds. It can be used for multiple requests.

The bearer tokens can only be used for a specific country. For example: If you generate a token for a UK mobile number (MSISDN), you cannot use it to query a German number.

If the request is valid, the API returns an access_token, along with expiry and scope information.
This access token can then be used in one or more requests, for as long as the token remains valid.

If the request is not valid, the APIs returns an error message.

To exchange the auth_req_id for an access token:

1. Make a “/token” request.

Token request example

curl -X 'POST' \
          'https://217d24e9-160c-434a-8e95-4f04d40cceac.mock.pstmn.io/openIDConnectCIBA/v1/token' \
          -H 'accept: application/json' \
          -H 'X-Correlator: 42da5b19-457a-4d30-a5c4-038c62dccbb0' \
          -H 'Content-Type: application/x-www-form-urlencoded' \
          -d 'auth_req_id=39da5b19-457a-4d30-a5c4-047c62dcca3b&grant_type=urn%3Aopenid%3Aparams%3Amc%3Agrant-type%3Aciba'

Token response example

HTTP/1.1 200 OK
                {
          "access_token": "dUk4Bs0qgKQKujbGxQDvIdXkI6Bz",
          "token_type": "Always \"Bearer\"",
          "expires_in": 3599,
          "id_token": "eyJraWQiOiJ0ZXN0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYeyJpc3MiOiJodHRwczovL2FwaXN0YWdpbmdyZWYuZGV2ZWxvcGVyLnZvZGFmb25lLmNvbSIsInN1YiI6ImRhNTNhOWRlLTljMmQtNGZkYy1hODY1LWE4OWZiZThmZGE2MyIsImF1ZCI6ImJSdlJKZVBHaGlMQndmelJSdEx3Z3REVFZ4UFdSQU1BIiwiZXhwIjoxNjA2OTE2Mzc2LCJpYXQiOjE2MDY5MTI3NzYsImF1dGhfdGltZSI6MTYwNjkxMjc1Niwibm9uY2UiOiI0NTI1OTUtOWRhMS00NDZiLWE0MmEtMWJkZmJmMTRhOGJjIiwiYXRfaGFzaCI6Ik9FRkZRVFpCTURCQ09FTkJRVVZFT0RnMU1qRTRSalJCUXpaQ1FUVXdRa1E0TWtRM1JFSTVSamsyT1RVMVJEbERPRE5GUkVFM05qa3hOVFl4UWpjM09BPT0iLCJhY3IiOiIwIiwiYW1yIjpbIk5PX0FVVEhOIl0sImF6cCI6IjU0NjEyNTk1LTlkYTAtNDQ2Yi1hNDJhLTFiZGZiZjE0YThhZiIsImhhc2hlZF9sb2dpbl9oaW50IjoiQUVBNkEwMEI4Q0FBRUQ4ODUyMThGNEFDNkJBNTBCRDgyRDdEQjlGOTY5NTVEOUM4M0VEQTc2OTE1NjFCNzc4In0.8Y4SArYeLdwyVUF7zjW9hyWTULiANn_MbvfXkxk62mKdPEeTI0HNOAG9tsItR1KVhHQdotAZOcoTNLRn66w4TMphQ1K2wfRcWTWKrTXtUA3Xuyx_bhZTkm7Zkz8k944JgpxejWgCjVUejlOiaQJZhu23UWufpd1An4x8UY7JU1LsKJj_OFMleESuM4xoJru0fPUkMMcNKB9D76sfBeSaZeMdqUARBhoWLyO_cb79sFfpu1Uf9V8SFB3NLRuktu0KANwqipwc_5c4LtxzP_rw3A_hWcaGpT67Qk1-tisW6ITCvrFKzZ5aqn8qWPEcte-XGoCXwd7pp0HKzgd1G8xw"
        }

1. Use the access token to make a request to the Vodafone KYC Match (Camara) API. 

Match API request:

This example is of KYC Match API:

curl -X 'POST' \
          'https://217d24e9-160c-434a-8e95-4f04d40cceac.mock.pstmn.io/match' \
          -H 'Authorization: Bearer LTRjZDMtNDUyYi1iNjk' \
          -H 'X-Correlator: "TEST_CORRELATION_ID"' \
          -H 'Content-Type: application/json' \
          -d '{
          "phoneNumber": "+34629255833",
          "idDocument": "66666666q",
          "name": "Federica Sanchez Arjona",
          "givenName": "Federica",
          "familyName": "Sanchez Arjona",
          "nameKanaHankaku": "federica",
          "nameKanaZenkaku": "Ｆｅｄｅｒｉｃａ",
          "middleNames": "Sanchez",
          "familyNameAtBirth": "YYYY",
          "address": "Tokyo-to Chiyoda-ku Iidabashi 3-10-10",
          "streetName": "Nicolas Salmeron",
          "streetNumber": 4,
          "postalCode": 1028460,
          "region": "Tokyo",
          "locality": "ZZZZ",
          "country": "JP",
          "houseNumberExtension": "VVVV",
          "birthdate": "1978-08-22",
          "email": "abc@example.com",
          "gender": "MALE"
        }'
                

Match API Response:

Below is an example response for KYC Match API. In this situation, the attribute provided is partial matched, the match score would be returned.

1. If the attribute is 100% matched, 'true' is returned.
2. If the attribute is partial match, 'false' is returned.
3. If the attribute is partial match, matchScore is returned.
4. If the attribute is not available, 'not _available' is returned.

HTTP/1.1 200 OK.
        {
          "idDocumentMatch": "not_available",
          "nameMatch": "true",
          "givenNameMatch": "true",
          "familyNameMatch": "true",
          "nameKanaHankakuMatch": "not_available",
          "nameKanaZenkakuMatch": "not_available",
          "middleNamesMatch": "true",
          "familyNameAtBirthMatch": "not_available",
          "addressMatch": "true",
          "streetNameMatch": "true",
          "streetNumberMatch": "true",
          "postalCodeMatch": "true",
          "regionMatch": "true",
          "localityMatch": "true",
          "countryMatch": "not_available",
          "houseNumberExtensionMatch": "not_available",
          "birthdateMatch": "false",
          "birthdateMatchScore": "87",
          "emailMatch": "not_available",
          "genderMatch": "not_available"
        }
                

Examples of mapping an address to the camara fields:-

• Building Numbers take precedence over flat numbers: Vodafone will use the 'streetNumber' value provided to match first with 'buildingNumber'; if 'buildingNumber' is blank in our system we will then use the 'flatNumber'.
• There is no matching on House name at this time

KYC Match (Camara) API uses Yaro-Winkler fuzzy logic. Along with binary true/false result, the API now returns a match score from 0 to 100. This allows for a nuanced view of matching results, giving you more control over what you consider a successful match.

1. 100%: Full Match (True)
2. 85%-100%: Strong Match (False)
3. 80%-84%: Good Match (False)
4. 75%-79%: Likely Match (False)
5. 1%-74%: Low Match (False)
6. 0%: No Match (False)

Supported Attributes per country:

Supported attributes for ES, DE and NL may change before the actual go live of the service in the specific country.