Match1.1.1

You must use a discovery service to determine which Mobile Network Operator's (MNO's) API you should use for each individual mobile number (MSISDN). This ensures API requests are efficiently directed to the correct MNO. This service is not provided by Vodafone.

You need an access token in order to use this API.

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, you cannot use it to query a German mobile number.

For more information on using Authorization Basic, see RFC 6749.

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.

The attributes must be sent in a hashed format

The attributes sent to the the premiuminfo endpoint must be sent in hashed format: SHA-256 hash in hexadecimal format, and in lowercase.

See Preparing hashes below.

Note: Vodafone's Match API implements the GSMA's Mobile Connect Know Your Customer Match specification. Vodafone has implemented the hashed version of the specification, which gives you extra security measures.

Supported attributes by country

The information that can be provided by Vodafone varies in each country.

The table below describes the attributes you can request, by country:

Key

"Requested and Available" means:

• The attribute has been requested in the authorize request
• The attribute is available from Vodafone

"Requested, Available and Matched" means:

• The attribute has been requested in the authorize request
• The attribute is available from Vodafone
• At least one of the attributes has been positively matched

Using keys within the mc_claims object

Below is a table of keys which must/may be provided within the mc_claims object:

Request to the endpoint example

curl --location -g --request
    POST https://eu2.api.vodafone.com/mobileconnect/premiuminfo/v1 
    Content-Type: application/json
    Authorization: Bearer LTRjZDMtNDUyYi1iNjk 
    vf-trace-transaction-id: aaaef4cf-1212-4009-8e25-4bcad9a9b206 
    User-ID-Type: MSISDN
    User-ID: 447767787990
    {
       "mc_claims":{
          "given_name_hash":{
             "value":"30cdaab49c530cbfa7d04c02ab6b11f1f4ad8736051e5bc36bee14f82335d245"
          },
          "given_name_match":{
             "essential":true,
             "values":[
                "Y",
                "N-AV",
                "N-AD",
                "N- NA"
             ]
          },
          "family_name_hash":{
             "value":"30cdaab49c530cbfa7d04c02ab6b11f1f4ad8736051e5bc36bee14f82335d245"
          },
          "family_name_match":{
             "essential":true,
             "values":[
                "Y",
                "N-AV",
                "N-AD",
                "N-NA"
             ]
          },
          "postal_code_hash":{
             "value":"30cdaab49c530cbfa7d04c02ab6b11f1f4ad8736051e5bc36bee14f82335d245"
          },
          "postal_code_match":{
             "essential":true,
             "values":[
                "Y",
                "N-AV",
                "N-AD",
                "N- NA"
             ]
          },
          "houseno_or_housename_hash":{
             "value":"30cdaab49c530cbfa7d04c02ab6b11f1f4ad8736051e5bc36bee14f82335d245"
          },
          "houseno_or_housename_match":{
             "essential":true,
             "values":[
                "Y",
                "N-AV",
                "N-AD",
                "N-NA"
             ]
          },
          "town_hash":{
             "value":"30cdaab49c530cbfa7d04c02ab6b11f1f4ad8736051e5bc36bee14f82335d245"
          },
          "town_match":{
             "essential":true,
             "values":[
                "Y",
                "N-AV",
                "N-AD",
                "N-NA"
             ]
          },
          "country_hash":{
             "value":"30cdaab49c530cbfa7d04c02ab6b11f1f4ad8736051e5bc36bee14f82335d245"
          },
          "country_match":{
             "essential":true,
             "values":[
                "Y",
                "N-AV",
                "N-AD",
                "N-NA"
             ]
          },
          "birthdate_hash":{
             "value":"30cdaab49c530cbfa7d04c02ab6b11f1f4ad8736051e5bc36bee14f82335d245"
          },
          "birthdate_match":{
             "essential":true,
             "values":[
                "Y",
                "N-AV",
                "N-AD",
                "N- NA"
             ]
          },
          "national_id_hash":{
             "value":"30cdaab49c530cbfa7d04c02ab6b11f1f4ad8736051e5bc36bee14f82335d245"
          },
          "national_id_match":{
             "essential":true,
             "values":[
                "Y",
                "N-AV",
                "N-AD",
                "N- NA"
             ]
          },
          "is_lost_stolen":{
             "values":[
                true,
                false
             ]
          },
          "billing_segment":{
             "values":[
                "PAYG",
                "PAYM",
                "Business"
             ]
          },
          "account_state":{
             "values":[
                "active",
                "inactive"
             ]
          }
       }
    }
    

Response example

HTTP/1.1 200 OK.
    Date: Tue, 03 Oct 2017 09:37:43 GMT.
    Server: XXXXXXX
    Expires: Thu, 19 Nov 1981 08:52:00 GMT.
    Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0. 
    Pragma: no-cache.
    vf-trace-transaction-id: aaaef4cf-1212-4009-8e25-4bcad9a9b206
    Content-Length: xx.
    Content-Type: application/json
    {
       "given_name_hash":"2fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
       "given_name_match":"Y",
       "family_name_hash":"3fd4e1c67a2d28fced849ee1bb76e7391b93eb13",
       "family_name_match":"Y",
       "postal_code_hash":"de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3",
       "postal_code match":"Y",
       "houseno_or_housename_hash":"de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3",
       "houseno_or_housename_match":"Y",
       "birthdate_hash":"feff2c7fd25e1b3afad3e85a0bd17d9b100db4b1",
       "birthdate_match":"Y",
       "national_id_match":"Y",
       "national_id_hash":"31cdaab49c530cbfa7d04c02ab6b11f1f4ad8736051e5bc36bee14f82335d455",
       "is_lost_stolen":false,
       "billing_segment":"PAYM",
       "account_state":"active"
    }
    

Key to responses

To successfully match the data, The Service Provider's customer data must be prepared and hashed following the same process that Vodafone uses.

For the UK (GB)

Examples:

For Germany (DE)

For Spain (ES)

Note: The middle name is not a separate attribute within the ES service. However, many middle names in the ES market are combined in the given_name response from the market, as it is combined in the database.
If an Service Provider wishes to improve their match rate where a middle name is present as a separate attribute in their service, it must be combined in the given_name submission as per the hash process below.
We assume that if a middle name has been combined in the database, and presented in the response and a middle name is not submitted as a combination in the given_name_hash, a match of "N-AV" will be returned.

For The Netherlands (NL)

MSISDNs for the Sandbox environment

447772000001

447772000002

447772000004

447772000006