Location Check
Mitigate fraud by cross-checking customer location and roaming information provided by Orange.

The Location Check France API gives you information for Orange customers authenticating on your service through the Orange Authentication API. It can typically be used to retrieve information about user's mobile handset location (e.g. isRoaming, roaming country). You will need the end-user's consent in order to access his information. A dedicated UI is provided with the Orange Authentication API.

Before starting

Our Location Check France API uses a specific methodology, the SMS OTP Authentication and Consent, which will allow you to authenticate the user and collect his consent over a single transaction. In order to use this authentication mean, your application will be specifically configured by an Orange administrator.

When building your request to Location Check France API, you will have to provide the user’s mobile number onto which the authentication will be performed. Our specific documentation will help you through all the required steps.

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

Retrieve Orange customer's information

You need a valid access token to invoke the Location Check France API. This access token must be provided in the HTTP Authorization header:

curl -X GET \
    -H "Authorization: {authorization_header}" \
    https://api.orange.com/locationcheck/fr/v1/premiuminfo

As an example:

curl -X GET -H "Authorization: Bearer OFR-948ef...d5de1f4" 
"https://api.orange.com/locationcheck/fr/v1/premiuminfo"
a/ If the transaction succeed

In the context of the Location Check France API, the location_check scope gives permissions to the following claims only:

ClaimTypeDescription
substringSubject - 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.
is_roamingbooleanIndicates if the device associated with the Mobile Connect user id is roaming (false/true).
roaming_countrystringCountry code for the country where the device is roaming (ISO 3166 format).
location_countrystringCountry code for the country of the Orange customer's MNO (ISO 3166 format).

On success, the PremiumInfo request returns a 200 OK HTTP status code with JSON data containing requested claims about the end-user.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 168
Cache-Control: no-store
Pragma: no-cache

{
  "sub": "PBYJJF-200-DwltrLnXq+7jwTQEkO...asUgUgEs=",
  "updated_at": 1433551702,
  "is_roaming": false,
  "roaming_country": "FR",
  "location_country": "FR"
}
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 OFR-948ef...d5de1f4 not found"
}

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