Additional Information | Vodafone Developer Marketplace

Select The Correct MNO For The Mobile Number

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.

Getting An Access Token

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.

Using Attributes

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.

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:

Attribute	UK	DE	ES	NL
name_match	Not supported	Not supported	Not supported	Not supported
given_name_match	Always	Always	Always	Always
family_name_match	Always	Always	Always	Always
address_match	Not supported	Not supported	Not supported	Not supported
houseno_or_housename_match	Always	Always	Always	Always
postal_code_match	Always	Always	Always	Always
town_match	Not supported	Not supported	Not supported	Not supported
country_match	Not supported	Not supported	Not supported	Not supported
birthdate_match	Requested and Available	Requested and Available	Requested and Available	Requested and Available
is_lost_stolen	Requested, Available and Matched	Not Supported	Not Supported	Not Supported
billing_segment	Requested, Available and Matched	Requested, Available and Matched	Requested, Available and Matched	Requested, Available and Matched
account_state	Requested, Available and Matched	Requested, Available and Matched	Requested, Available and Matched	Requested, Available and Matched

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:

Key	Requirement	Data Type	Description
given_name_hash	Mandatory	Object	This object contains a “value” object. The value is the subscriber’s given name. This is presented as a SHA-256 hash in hexadecimal format, lowercase. Example: `"given_name_hash": {"value":"2fd4e1c67a2d28fced849ee1 bb76e7391b93eb12"}`
family_name_hash	Mandatory	Object	This object itself contains a “value” object. The value is the subscriber’s family name. This is presented as a SHA-256 hash in hexadecimal format, lowercase.
family_name_match	Mandatory	Object	This contains a JSON object specifying that this claim is essential in the response. The possible values are: `{"essential":true, "values": ["Y","N-AV", "N-AD", "N-NA"]}`
houseno_or_housename_hash	Mandatory	Object	This object itself contains a “value” object. The value is the subscriber’s house number or house name. This is presented as a SHA-256 hash in hexadecimal format, lowercase.
houseno_or_housename_match	Mandatory	Object	This contains a JSON object specifying that this claim is essential in the response. The possible values are: `{"essential":true, "values": ["Y","N-AV", "N-AD", "N-NA"]}`
postal_code_hash	Mandatory	Object	This object itself contains a “value” object. The value is the subscriber’s postal code. This presented as a SHA-256 hash in hexadecimal format, lowercase.
postal_code_match	Mandatory	Object	This contains a JSON object specifying that this claim is essential in the response. The possible values are: `{"essential":true, "values": ["Y","N-AV", "N-AD", "N-NA"]}`
birthdate_hash	Optional	Object	This object itself contains a “value” object. The value is the subscriber’s birth date. This is presented as a SHA-256 hash in hexadecimal format, lowercase.
birthdate_match	Optional	Object	This contains a JSON object specifying the possible values in the response: `{"values": ["Y","N-AV", "N-AD", "N-NA"]}`
national_id_hash	Optional	Object	This object itself contains a “value” object. The value is the subscriber’s national id. This is presented as a SHA-256 hash in hexadecimal format, lowercase.
national_id_match	Optional	Object	Contains a JSON object specifying the possible values in the response: `{"values": ["Y","N-AV", "N-AD", "N-NA"]}`
is_lost_stolen	Optional	Object	This object contains an object of values: “is_lost_stolen”: {“values”: [true, false]} The values in the “values” array have no impact in the response value. (The existence of the “is_lost_stolen” key determines if a response is to be attempted).
billing_segment	Optional	Object	This object contains an object of values: “billing_segment”: {“values”: [“PAYG”, “PAYM”, “Business”]} The values in the “values” array have no impact in the response value. (The existence of the “billing_segment” key determines if a response is to be attempted).
account_state	Optional	Object	This object contains an object of values: “account_state”: {“values”: [“active”, “inactive”]} The values in the “values” array have no impact in the response value. (The existence of the “account_state” key determines if a response is to be attempted).

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

If	Response
No data is available for the particular attribute	N-NA
The data that the customer submits does not match with the data that Vodafone holds	N-AV
The data that the customer submits does match with the data that Vodafone holds	Y
One of the mandatory attributes (Name or Last Name or House No/Name or Postcode) match	Vodafone also returns the optional attributes in the response: Lost/Stolen, Account State: Active/Inactive, Billing Segment (PAYG, PAYM, Business)

Preparing Hashes

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)

Claim	Hashing Process
given_name_hash and family_name_hash	1. Truncate the given/family name to 20 characters 2. Convert to lowercase 3. “Downgrade” all non-standard characters base characters, i.e.: "àèìòùÀÈÌÒÙ äëïöüÄËÏÖÜ âêîôûÂÊÎÔÛ áéíóúÁÉÍÓÚðÐýÝ ãñõÃÑÕšŠžŽçÇåÅøØß“ becomes "aeiouAEIOU aeiouAEIOU aeiouAEIOU aeiouAEIOUdDyY anoANOsSzZcCaAoOss" 4. Downgrade any "ß" as "ss" 5. Remove any non-alphanumeric characters (including spaces) 6. Hash the resulting string (SHA-256, hexadecimal format, lowercase)
houseno_or_housename_hash	1. If: - The house number exists, truncate it to 20 characters (and go to step 2) - The house number does not exist, use the flat number, truncate to 20 characters - The house number or flat number does not exist, use the house name, truncate it to 80 characters 2. Convert to lowercase 3. "Downgrade” non-standard characters 4. Remove non-alphanumeric characters and spaces 5. Hash the resulting string (SHA-256, hexadecimal format, lowercase)
postal_code_hash	1. Truncate the result to 10 characters 2. Convert to lowercase 3. "Downgrade” umlauted characters 4. Remove non-alphanumeric characters and spaces 5. Hash the resulting string (SHA-256, hexadecimal format, lowercase)
birthdate_hash	1. Convert the DoB to the format yyyy-MM-dd 2. Hash the resulting string (SHA-256, hexadecimal format, lowercase)

Examples:

Claim	Source Value	Hashed Value
Family Name	LONG FAMILY NAME IN UPPER CASE	80573753c0fd91f4fbc17c9f9edd5f0b8a0e880c3e0f0e41edeceffe917bbacc
House Number	HouseNumber1234567890AB	bc8cf7e0f0accd2c9cc33b9ac11ead71df826108613c90c07126f314b7858183
House Name	This HOUSE NAME is greater than eighty characters in length and contains some upper case and umlaut characters	d5e023ef91359b81736e972ce94b7a2aa7c9e8d5a3b1dd5e7597571ce42565c3
Postal Code	àèìòùÀÈÌÒÙ äëïöüÄËÏÖÜ	5b6ccbb9fe9d67e2279ce9b213f76749bb2fc5db35e31a9a53ca24522944c36e
Birthdate	1978-12-25	752ab87516a9624851708550ff52a735b986d8d0bfe1840ebc4f40ce219902ff

For Germany (DE)

Claim	Hashing Process
given_name_hash and family_name_hash	1. Convert to lowercase 2. Turn German umlaut into plain/standard latin using the following rule: ö -> oe, ä -> ae, ü -> ue 3. Downgrade all other non-standard characters to base characters using the following conversion rule: "àèìòùÀÈÌÒÙ äëïöüÄËÏÖÜ âêîôûÂÊÎÔÛ áéíóúÁÉÍÓÚðÐýÝ ãñõÃÑÕšŠžŽçÇåÅøØ" becomes "aeiouAEIOU aeiouAEIOU aeiouAEIOU aeiouAEIOUdDyY anoANOsSzZcCaAoO" 4. Downgrade any "ß" as "ss" 5. Replace any non-alphanumeric characters with spaces 6. Replace any prepositions from the set with a space (making sure to have spaces around the preposition if you use a String.replace) { a, aan, ab, abu, af, ait, al, an, ap, at, ath, auf, aus, austre, av, bar, bat, ben, bet, bij, bin, bint, binte, binti, boven, d, da, das, de, degli, deh, del, dele, della, dem, den, der, di, dos, du, e, e v, el, en, erch, ev, fetch, gil, het, i, ibn, in, kil, la, le, les, lille, lu, m, mac, mc, mck, mellom, mhic, mic, myljom, na, ned, nedre, nic, nin, nordre, norr, ny, ní, o, ofver, onder, op, opp, ostre, over, ovre, ovste, oz, pour, putera, puteri, putra, putri, s, setia, setya, sonder, sondre, sor, sore, stor, syd, syndre, t, te, ten, ter, tot, tre, ua, ui, uiji, uijt, uit, upp, v, van, vast, vaster, vd, ver, vesle, vest, vetch, vetle, vom, von, voor, vor, war, zu, zum, zur } 7. Keep only the first word and remove the rest (trimming the remaining spaces) 8. Truncate the result to 20 characters 9. Hash the resulting string (SHA-256, hexadecimal format, lowercase)
houseno_or_housename_hash	1. Apply given_name_hash normalization rules 1-4. 2. Remove any non-alphanumeric characters (including spaces) 3. Replace all “strasse” occurrences to “str” 4. Replace all “sankt”, “sanct” or "saint” occurrences to “st” 5. Truncate the result to 80 characters 6. Hash the resulting string (SHA-256, hexadecimal format, lowercase)
postal_code_hash	1. Apply given_name_hash normalization rules 1-4. 2. Remove any non-alphanumeric characters (including spaces) 3. Truncate the result to 10 characters 4. Hash the resulting string (SHA-256, hexadecimal format, lowercase)
birthdate_hash	1. Convert the DoB to the format yyyy-MM-dd 2. Hash the resulting string (SHA-256, hexadecimal format, lowercase)

For Spain (ES)

The middle name is not a separate attribute within the ES service. However, many middle names in the ES market are combined in thegiven_nameresponse 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 thegiven_namesubmission 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 thegiven_name_hash, a match of "N-AV" will be returned.

Claim	Hashing Process
given_name_hash and family_name_hash	1. Convert to lowercase 2. "Downgrade” umlauted characters base characters, i.e.: "àèìòùÀÈÌÒÙ äëïöüÄËÏÖÜ âêîôûÂÊÎÔÛ áéíóúÁÉÍÓÚðÐýÝ ãñõÃÑÕšŠžŽçÇåÅøØ“ becomes "aeiouAEIOU aeiouAEIOU aeiouAEIOU aeiouAEIOUdDyY anoANOsSzZ cCaAoO" 3. Downgrade any "ß" to "ss" 4. Remove any non-alphanumeric characters (including spaces) 5. Truncate the result to 20 characters 6. Hash the resulting string (SHA-256, hexadecimal format, lowercase) Note: Middle names If you wish to match the middle name, this also needs to be concatenated. Include this in the “given_name_hash” submission i.e. a. First Name = Luis b. Middle Name = Contaurez c. The submission to be hashed would be luiscontaurez
houseno_or_housename_hash	1. Take all to the left of the comma of the street field 2. Apply the given_name/family_name normalization rules (including the lowercasing of words) 3. Remove any non-alphabetical chars (including numbers but excluding spaces) 4. Use only the last (rightmost) word of the remaining street name. For example: CL. MUELA DE SAN JUAN, 9 1º D" --> juan RU. RITA RIVERA CHAO, 2 ESC. 3 1º B" --> chao 5. Truncate the result to 80 characters 6. Hash the resultant string (SHA-256, hexadecimal format, lowercase)
postal_code_hash	1. Apply given_name/family_name normalization steps (steps 2-5 above) 2. Remove any letters 3. Truncate the result to 20 characters 5. Hash the resulting string (SHA-256, hexadecimal format, lowercase)
birthdate_hash	1. Convert the DoB to the format yyyy-MM-dd 2. Hash the resulting string (SHA-256, hexadecimal format, lowercase)
national_id_hash	1. Convert to lowercase 2. Hash the resulting string (SHA-256, hexadecimal format, lowercase)

For The Netherlands (NL)

Claim	Hashing Process
family_name_hash	1. Convert to lowercase 2. Downgrade all other non-standard characters to base characters using the following conversion rule: àèìòùäëïöüâêîôûáéíóúðýãñõšžçåø to aeiouaeiouaeiouaeioudyanoszcao 3. Downgrade any "ß" to "ss" 4. Replace any non-alphanumeric characters with spaces 5. Replace any prepositions from the set with a space (making sure to have spaces around the preposition if you use a String.replace) { a, aan, ab, abu, af,ait, al, an, ap, at, ath, auf, aus, austre, av, bar, bat, ben, bet, bij, bin, bint, binte, binti, boven, d, da, das, de, degli, deh, del, dele, della, dem, den, der, di, dos, du, e, e v, el, en, erch, ev, fetch, gil, het, i, ibn, in, kil, la, le, les, lille, lu, m, mac, mc, mck, mellom, mhic, mic, myljom, na, ned, nedre, nic, nin, nordre, norr, ny, ní, o, ofver, onder, op, opp, ostre, over, ovre, ovste, oz, pour, putera, puteri, putra, putri, s, setia, setya, sonder, sondre, sor, sore, stor, syd, syndre, t, te, ten, ter, tot, tre, ua, ui, uiji, uijt, uit, upp, v, van, vast, vaster, vd, ver, vesle, vest, vetch, vetle, vom, von, voor, vor, war, zu, zum, zur } 6. Remove any spaces 7. Truncate the result to 20 characters 8. Hash the resulting string (SHA-256, hexadecimal format, lowercase)"
given_name_hash	1. Convert to lowercase 2. Downgrade all other non-standard characters to base characters using the following conversion rule: àèìòùäëïöüâêîôûáéíóúðýãñõšžçåø to aeiouaeiouaeiouaeioudyanoszcao 3. Downgrade any "ß" to "ss" 4. Remove any non-alphanumeric characters with spaces 5. Use initials only 6. Remove any non-alphanumeric characters (including spaces) 7. Truncate the result to 20 characters 8. Hash the resulting string (SHA-256, hexadecimal format, lowercase)
houseno_or_housename_hash	1. Remove all non-numerical characters 2. Truncate the result to 80 characters 3. Hash the resulting string (SHA-256, hexadecimal format, lowercase)
postal_code_hash	1. Convert to lowercase 2. Remove any non-alphanumeric characters including spaces 3. Truncate the result to 20 characters 4. Hash the resulting string (SHA-256, hexadecimal format, lowercase)
birthdate_hash	1. Convert the DoB to the format yyyy-MM-dd 2. Hash the resulting string (SHA-256, hexadecimal format, lowercase)

MSISDNs For The Sandbox Environment

447772000001

447772000002

447772000004

447772000006

Match