Carrier Lookup

Introduction

The CAMARA Carrier Lookup API provides a standardized mechanism to customer to retrieve the network id (MCC+MNC) for a given mobile phone number.

API Scope

The current API implementation is applicable to any mass-market Orange France mobile customer, including SOSH customers.

Subscribe to the API

You get the Authorization header credentials when you register your application on the Orange Developer Console.

API Authentication

HTTPS requests to the REST API are protected with CIBA 3-Legged OAuth.

In short, the API Invoker (e.g. Application Backend or Aggregator) before to request SIM swap check, needs to request a Three-Legged Access Token from Orange Authorization Server. The process follows the OpenID Connect Client-Initiated Backchannel Authentication (CIBA) flow.

Step 1: request the OAuth authorization code from the user device

The API Invoker provides in the authorization request (/bc_authorize) a login_hint with a valid User identifier together with the application credentials (client_assertion & client_assertion_type) and indicates the Purpose for processing Personal Data. The Orange implementation follows the CAMARA scope definition. The scope must be set to: opendid dpv:<dpvValue> <technicalParameter>. dpv stands for Data Privacy Vocabulary.

For current implementation only FraudPreventionAndDetection dpv value is managed, which means that:

• the scope in the bc-authorize must be set to openid dpv:FraudPreventionAndDetection network-id:resolve-network-id

Orange Authorization Server will check if the owner of the phone number did not opted-out to authorize access to this data. If this is not the case a response 200 is sent back with a authorization request identifier (auth_req_id). If the resource owner or OpenID Provider denied the request an error 403 Forbidden is sent back.

Request:

curl  -X POST \
  'https://api.orange.com/openidconnect/ciba/fr/v1/bc-authorize' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'login_hint=tel:+336666666' \
  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  --data-urlencode 'client_assertion=eyJhbGciOiJSUz...1jjGg' \
  --data-urlencode 'scope=openid dpv:FraudPreventionAndDetection network-id:resolve-network-id'

Response:

200 
Content-Type: application/json

{
  "auth_req_id": "y_azuw2HT4fWYPb0-0w2DBhaEq8",
  "expires_in": 120,
  "interval": 2
}

Step 2: Request the OAuth access token

Once the client application gets the authorization code, the API Invoker polls the token endpoint by making an "HTTP POST" request by sending the grant_type (urn:openid:params:grant-type:ciba), auth_req_id (OperatorAuthReqId) and the the application credentials (client_assertion & client_assertion_type) parameters

If the transaction succeeds, in the POST response, the acccess_token is provided.

Request:

curl  -X POST \
  'https://api.orange.com/openidconnect/ciba/fr/v1/token' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  --data-urlencode 'client_assertion=eyJhbGciOi....iuT111jjGg' \
  --data-urlencode 'auth_req_id=y_azuw2HT4fWYPb0-0w2DBhaEq8' \
  --data-urlencode 'grant_type=urn:openid:params:grant-type:ciba'

Response:

200 
Content-Type: application/json

{
  "access_token": "OFR_28Fp...Jb60y3KPvcZaOTHJ_sFnjOmyHN5PxXG...osYpKu3gA4utWicDw",
  "token_type": "Bearer",
  "refresh_token": "4bwc0ESC_IAhflf-ACC_vjD_ltc11ne-8gFPfA2Kx16",
  "expires_in": 120,
  "id_token": "OFR_28Fp...Jb60y3KPvcZaOTHJ_sFnjOmyHN5PxXG...osYpKu3gA4utWicDw"
}

Note: If Orange customer opted-out a token is not delivered and following response is provided:

Response:

400 Bad Request 
Content-Type: application/json

{
  "error": "access_denied",
  "error_description": "The end-user denied the authorization request"
}

Step 3: Access protected resources using OAuth access token

In order to call our API, the access_token is mandatory.

Specific documentation about match resource is provided below.

API Description

Summary of resources

This API has one resource resolve-network-id. This API must be used only for Fraud Prevention and Detection UC.

Summary of methods and URL

Summary of request body parameters

Summary of response parameters

Request

curl -X POST "https://api.orange.com/camara/ofr/carrier-lookup/v1/resolve-network-id"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'

Response

200 Match successful
Content-Type: application/json

{
      "networkId": "21407"
}

Fields description

Most frequent errors

If invalid input are provided in particular for the device identifier a 400 error is triggered.

HTTP/1.1 400 Invalid input
Content-Type: application/json
{
  "code": "INVALID_ARGUMENT",
  "status": 400,
  "message": "Invalid input"
}

If the network back end is not able to localize the equipment, a 404 error is sent.

HTTP/1.1 404 Not Found
Content-Type: application/json
{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "Unknown Location"
}

If the localisation service is not up and running, a 503 error is sent.

HTTP/1.1 503 Service unavailable
Content-Type: application/json
{
  "code": "UNAVAILABLE",
  "status": 503,
  "message": "Service unavailable"
}

There are some cases where your client application will no longer gain access to API resources, and get an error back.

Please check the following points:

• Here, you attempt to use an expired or revoked access_token and you get an invalid token error. You will have to request a new access_token. As an example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "code": "UNAUTHENTICATED",
  "status": 401,
  "message": "Authorization failed: ..."
}

• Here, you removed your subscription to the API so that the capability to generate an access_token is not allowed anymore. As an example:

HTTP/1.1 403 Forbidden
Content-Type: application/json
{
  "code": "PERMISSION_DENIED",
  "status": 403,
  "message": "Operation not allowed: ..."
}

Looking for support ?

Facing technical issue when using this API ? please contact us