Getting started

• Introduction
  • Subscribe to the API
  • API Authentication
  • API Description
    • Summary of resources
    • Summary of methods and URL
    • Summary of request body parameters
    • Request mobile sim swap check (from msisdn)
      • Request
      • Response
      • Fields description
    • Most frequent errors
  • History of document

Introduction

The CAMARA Sim Swap API performs real-time checks on the activation date of a SIM card on the Orange mobile network. It reveals if an individual mobile line has been ported to another SIM card.

API Scope

Current API implementation covers all Orange France mobile lines.

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 3-Legged OAuth. To learn more about how Orange Developer handles authentication, please refer to our documentation.

In short, this API uses Authorization by code (aka three-legged OAuth) mechanism as the final user of the service is requested to give their consent in order to authorize this client application to access their resources.

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

To authenticate the end-user and obtain her/his consent a GET request must be sent to the authorize endpoint from the user device. This request must provide required parameters as described in Orange tech guide referred above. It is mandatory to provide a scope in this request. Orange implementation follow CAMARA scope definition. the scope must be set to: dpv:<dpvValue>#<technicalParameter>. dpv stands for Data Privacy Vocabulary.

For current implementation only FraudDetectionAndPrevention dpv value is managed which mean that:

• for checking the SimSwap date the scope in the authorizemust be set to dpv:FraudPreventionAndDetection#sim-swap:check
• for getting the latest SimSwap date the scope in the authorize must be set to dpv:FraudPreventionAndDetection#sim-swap:retrieve-date
• for getting both, the scope in the authorize must be set to dpv:FraudPreventionAndDetection#sim-swap

Note: Only check resource is available in Orange current implementation

Once the end-user provided her/his consent, the Orange authorization server will send back to the client application an authorization code.

Step 2: Request the OAuth access token

Once the client application got the authorization code, it has to get the access token protecting the resoures. In order to retrieve it, the client application triggers a POST request to the token endpoint.

As for previous steps, detailed attribute prerequisites are described in the Orange tech guide.

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

Step 3: Access protected resources using OAuth access token

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

Specific documentation about number verify resources is provided below.

Go up

API Description

Summary of resources

This API has two resource check and retrieve-date

Only check resource is available in Orange current implementation

Summary of methods and URL

Go up

Summary of request body parameters

As only check resource is provided, following documentation will only cover this resource.

Go up

Request mobile sim swap check (from msisdn)

Request

curl -X POST "https://api.orange.com/camara/sim-swap/ofr/v0/check"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
"phoneNumber": "41793834315"
"maxAge": 240
}

Response

200 
Content-Type: application/json

{
  "swapped": false
}

Go up

Fields description

The response features only one attribute: swapped.

This attribute is boolean indicating if a sim swap has been done during the provided checking period.

Go up

Most frequent errors

If invalid or incomplete input are provided - in particular for the max_age (should between 1 to 2160) a 400 error is triggered.

HTTP/1.1 400 Error: bad Request
Content-Type: application/json
{
  "code": "INVALID_INPUT",
  "status": "400",
  "message": "[checkSimSwap.createCheckSimSwap.maxAge: must be less than or equal to 2160]"
}

If the msisdn is not managed by Orange, error code 404 is retrieved.

HTTP/1.1 404 Error: Resource Not Found
Content-Type: application/json
{
  "code": "SIM_SWAP.UNKNOWN_PHONE_NUMBER",
  "status": "404",
  "message": "SIM Swap can't be checked because the phone number is unknown."
}

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": "UNAUTHORIZED",
  "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": "FORBIDDEN",
  "message": "Operation not allowed: ..."
}

Go up

History of document

Go up