Device Swap

Introduction

The Device Swap API performs real-time checks on the last Device Swap event, providing real-time information about whether the SIM card associated with a user's phone number has been transferred to a different physical device.

API Authentication

HTTPS requests to the REST API are protected with 2-Legged OAuth. To learn more about how Orange Developer handles authentication, please refer to our documentation.

In short, you will use your Orange Developer Authorization header as authorization_header for the Basic authentication with Orange Developer.

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

curl -X POST \
-H "Authorization: {{ authorization_header }}" \
-d "grant_type=client_credentials" \
https://api.orange.com/openidconnect/playground/v1.0/token

In response, you will get an access_token.

{
  "token_type": "Bearer",
  "access_token": "66AeYJF8eJQ...2SjkFg9LB1LePC",
  "expires_in": 3600
}

API Description

Summary of resources

This API has two resource check and retrieve-date

Summary of methods and URL

Device-Swap - Retrieve Date

This service returns the timestamp of the most recent device change, capturing the latest alteration between a specific mobile phone number (identified by the SIM card associated) and its device.

Summary of request body parameters

Request mobile device swap retrieve date (from phone number)

Request

curl -X POST "https://api.orange.com/camara/playground/api/device-swap/v0.2/retrieve-date"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
   "phoneNumber": "+33699901031",
}'

Response

a/ If the transaction succeeds

On success, the DeviceSwap API returns a 200 OK HTTP status code with JSON data including the 'latestDeviceChange' property with information about device swap change.

As an example:

200
Content-Type: application/json

{
  "latestDeviceChange": "2023-09-05T13:57:55.707Z"
}

b/ If the transaction fails

Please visit the common error responses section in this page.

Device-Swap - Check

Summary of request body parameters

Request mobile device swap check (from phone number)

Request

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

Response

a/ If the transaction succeeds

On success, the DeviceSwap API returns a 200 OK HTTP status code with JSON data including the 'swapped' property indicating if device swap has been performed during the period.

As an example:

200
Content-Type: application/json

{
  "swapped": true
}

b/ If the transaction fails

Please visit the common error responses section in this page.

Common error responses

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
{
  "status": 400,
  "code": "INVALID_INPUT",
  "message": "[checkDeviceSwap.createCheckDeviceSwap.maxAge: must be less than or equal to 2400]"
}

If the phone number is not managed by Orange lab, error code 422 is retrieved.

HTTP/1.1 422 Error: Resource Not Found
Content-Type: application/json
{
  "status": 422,
  "code": "NOT_SUPPORTED",
  "message": "Service not supported for this phoneNumber"
}

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: ..."
}