Id Match Spain
Id Match Spain, allow Orange 3rd Parties to check in a smooth way if the data provide by a customer in a Web form is valid.

The ID Match Spain API gives you ability to verify if claims provided to you by one of your customer are equivalent to the ones from Orange Information System. This mechanism is available for Orange customers authenticating on your service through Mobile Connect Authentication. It can typically be used to protect your business, reassuring on the user identity and reducing fraud risk. You will need the end-user's consent in order to access these informations. A dedicated UI is provided with the Orange Authentication API. As there is no data exchange, this API is less intrusive from customer perspective.

Before starting

Our ID Match Spain API requires a 3-legged authentication with our OpenID Connect platform. Please follow the method described here, with id_match scope, in order to get an access token that will be granted to retrieve end-user's claims.

Verify Orange customer's information

You need a valid access token to invoke the ID Match Spain API. This access token must be provided in the HTTP Authorization header:

curl -X POST \
    -H "Authorization: {access_token}" \
    --header "Content-Type: application/json" 
    --header "Accept: application/json" 
    \-d "{
    \"sub\": \"PBYJJF-200-DwltrLnXq+7jwTQEkOx9Z9jelg0t0NQrxWFasUgUgEs=\",
    \"updated_at\": 1433551702,
    \"name\": \"Jane Doe\",
    \"address\": {
        \"postal_code\": \"28070\",
        \"country\": \"Spain\",
    \},
    \"subscriber_msisdn\": \"+34712345678\"
    }" https://api.orange.com/idmatch/es/v1/premiuminfo

The ID Match Spain API gives you the capability to verify any of the following claims:

ClaimTypeDescription
substring(optional) Subject - Issuer identifier for the end-user.
updated_atnumberTime the end-user's information was last updated. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
namestringEnd-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences.
given_namestringGiven name(s) or first name(s) of the end-user. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.
family_namestringSurname(s) or last name(s) of the end-user. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.
addressJSON object(optional) End-user's preferred postal address. See Address structure below.
emailstring(optional) End-user's preferred e-mail address. Its value MUST conform to the RFC 5322 addr-spec syntax.
email_verifiedboolean(optional) True if the end-user's e-mail address has been verified; otherwise false.
subscriber_msisdnstring(optional) User's mobile number linked to his Orange subscription [E.164].
phone_numberstring(optional) End-user's preferred telephone number (E.164).
phone_number_verifiedboolean(optional) True if the end-user's phone number has been verified; otherwise false.

The Address JSON object represents a physical mailing address. It is bound of the following attributes:

AttributeTypeDescription
formattedstring(optional) Full mailing address, formatted for display. MAY contain multiple lines, separated by newline characters (\n or \r\n).
street_addressstring(optional) May contain house number, street name, PO Box number. If using multiple lines, the lines are separated by newline characters.
localitystring(optional) City or Town.
regionstring(optional) State, Province or County.
postal_codestring(optional) Post Code or ZIP code.
countrystring(optional) Country name.

NOTE: on server side, the criteria being implemented to check the match are the following:

  • all spaces are removed,
  • the value is converted to lower case,
  • the special characters included in the mapping are removed ('\n', ',', 'º', '(', ')'),
  • the country prefix in the MSISDN value are removed ('+34'),
  • accented vowels are changed by vowels without accent.
a/ If the transaction succeed

In the context of the ID Match Spain API, the id_match scope gives permissions to the following claims only.

ClaimTypeDescription
substringSubject - Issuer identifier for the end-user.
sub_matchbooleanxx
updated_atnumberTime the end-user's information was last updated. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
updated_at_matchbooleanxx
namestringEnd-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences.
name_matchbooleanxx
given_namestringGiven name(s) or first name(s) of the end-user. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.
given_name_matchbooleanxx
family_namestringSurname(s) or last name(s) of the end-user. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.
family_name_matchbooleanxx
addressJSON objectEnd-user's preferred postal address. See Address structure below.
emailstringEnd-user's preferred e-mail address. Its value MUST conform to the RFC 5322 addr-spec syntax.
email_matchbooleanTrue is the user's email stored into Orange Spain Information System is matching with the value provided by the SP ; otherwise false.
email_verifiedbooleanTrue if the end-user's e-mail address has been verified; otherwise false.
email_verified_matchbooleanTrue is the value stored into Orange Spain Information System is matching with the value provided by the SP ; otherwise false.
subscriber_msisdnstringUser's mobile number linked to his Orange subscription [E.164].
subscriber_msisdn_matchbooleanTrue is the user’s mobile number (E164) stored into Orange Spain Information System is matching with the value provided by the SP ; otherwise false.
phone_numberstringEnd-user's preferred telephone number (E.164).
phone_number_matchbooleanTrue is the user’s preferred telephone number (E.164) stored into Orange Spain Information System is matching with the value provided by the SP ; otherwise false.
phone_number_verifiedbooleanTrue if the end-user's phone number has been verified; otherwise false.
phone_number_verified_matchbooleanTrue is the value stored into Orange Spain Information System is matching with the value provided by the SP ; otherwise false.

The Address JSON object represents a physical mailing address. It is bound of the following attributes:

AttributeTypeDescription
formattedstringFull mailing address, formatted for display. MAY contain multiple lines, separated by newline characters (\n or \r\n).
formatted_matchbooleanTrue is the value stored into Orange Spain Information System is matching with the value provided by the SP ; otherwise false.
street_addressstringMAY contain house number, street name, PO Box number. If using multiple lines, the lines are separated by newline characters.
street_address_matchbooleanTrue is the value stored into Orange Spain Information System is matching with the value provided by the SP ; otherwise false.
localitystringCity, Town.
locality_matchbooleanTrue is the value stored into Orange Spain Information System is matching with the value provided by the SP ; otherwise false.
regionstringState, Province, County.
region_matchbooleanTrue is the value stored into Orange Spain Information System is matching with the value provided by the SP ; otherwise false.
postal_codestringPost Code, ZIP code.
postal_code_matchbooleanTrue is the value stored into Orange Spain Information System is matching with the value provided by the SP ; otherwise false.
countrystringCountry name.
country_matchbooleanTrue is the value stored into Orange Spain Information System is matching with the value provided by the SP ; otherwise false.

If the value of a user's claim provided in the body part of the request is equivalent to the value stored into Orange Information System, the claim is sent back in the response with the corresponding '*_match' claim set to true.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 71

{
  "phone_number": "+34712345678",
  "phone_number_match": true
}

Otherwise, if not equivalent, the corresponding '*_match' claim is returned only with the false value. For instance:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 71

{
  "phone_number_match": false
}

As an example with several user's claims provided by your application using the POST /premiuminfo operation (see above).

On success, the PremiumInfo request returns a 200 OK HTTP status code with JSON data containing details about the matching.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 354

{
  "sub": "PBYJJF-200-DwltrLnXq+7jwTQEkOx9Z9jelg0t0NQrxWFasUgUgEs=",
  "sub_match": true,
  "updated_at_match": false,
  "name": "Jane Doe",
  "name_match": true,
  "address": {
    "postal_code_match": false,
    "country": "Spain",
    "country_match": true    
  },
  "subscriber_msisdn": "+34712345678",
  "subscriber_msisdn_match": true
}
b/ If the transaction failed

In case of error, the PremiumInfo endpoint returns an error response (JSON format) with the following information:

  • code (required): single ASCII error code
  • message (required): short localized string that describes the error.
  • description (optional): human-readable ASCII text providing additional information, used to assist the developer in understanding the error that occurred.

If the access_token is missing, a 401 Unauthorized HTTP status code is returned.

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

{
   "code": 40,
   "message": "Missing or invalid credentials",
   "description": "The requested service needs credentials, but the ones provided were invalid or missing."
}

If the access_token is expired, revoked or invalid, a 401 Unauthorized HTTP status code is returned. In that case, you'll have to renew the access token.

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

{
    "code": 41, 
    "message": "Invalid credentials", 
    "description": "access token resource OES-948ef...d5de1f4 not found"
}

If an invalid JSON body part is sent, a 400 Bad Request HTTP status code is returned.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
   "code": 22,
   "message": "Invalid body",
   "description": "The posted body is not well-formed and thus can not be parsed."
}

See API Reference section for the exhaustive list of error codes.