The SIM Verify API gives you information whether a SIM change has occurred recently for a user, reducing fraud risk. It is applicable to any mass-market Orange France mobile customer, and includes SOSH customers.

Before starting

Our SIM Verify API requires a 2-legged authentication with our OAuth 2.0 Authorization Server. Please follow the method described here.

Retrieve Orange customer's information

You need to provide a valid access token in the HTTP Authorization header to invoke the SIM Verify API. You also need to provide information about the end-user's identifier:

As an example:

curl -X GET \
     -H "Authorization: Bearer zkp7zQcsWc3lTUQkTZ6hbXMwgGkT" \
     "https://api.orange.com/simverify/fr/v1/checksimswap?user_id_type=MSISDN&user_id=33611223344&age=5" 

a/ If the transaction succeed

On success, the SIM Verify API returns a 200 OK HTTP status code with JSON data indicating whether the SIM card has been swapped recently, i.e. between the current time and the delay represented by the "age" parameter.

As an example:

HTTP/1.1 200 OK
Content-Type: application/json
X-OAPI-Request-Id: opapccballrt05-10415-506430364-1

{
  "swapped": "false"
}

b/ If the transaction failed

In case of error, the SIM Verify API returns an error response (JSON format) with the following information:

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

If the 'user_id_type' parameter is missing, a 400 (Bad Request) HTTP status code is returned with the following JSON response:

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

{
  "error": "invalid_request",
  "error_description": "REQUIRED parameter user_id_type is missing."
}

If the 'user_id_type' parameter's value is invalid, a 400 (Bad Request) HTTP status code is returned with the following JSON response:

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

{
  "error": "invalid_request",
  "error_description": "REQUIRED parameter user_id_type is invalid."
}

If the 'user_id' parameter is missing, a 400 (Bad Request) HTTP status code is returned with the following JSON response:

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

{
  "error": "invalid_request",
  "error_description": "REQUIRED parameter user_id is missing."
}

If the 'user_id' parameter's value is invalid (not compliant with E.164 format), a 400 (Bad Request) HTTP status code is returned with the following JSON response:

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

{
  "error": "invalid_request",
  "error_description": "REQUIRED parameter user_id is invalid: MSISDN must follow E.164 format, with Country Code without the +."
}

If the user is not eligible for the SIM Verify API, a 400 (Bad Request) HTTP status code is returned with the following JSON response:

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

{
  "error": "access_denied",
  "error_description": "The eligibility of the user cannot be verified."
}

If the 'age' parameters's value is invalid (must be a positive integer), a 400 (Bad Request) HTTP status code is returned with the following JSON response:

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

{
  "error": "invalid_request",
  "error_description": "REQUIRED parameter age is invalid: must be a positive integer."
}

If an internal error occurred, a 500 (Internal Server Error) HTTP status code is returned with the following JSON response::

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8

{
   "error": "server_error",
   "error_description": "Internal Server Error"
}

Please note that common errors which format is not fully compliant with OpenID Connect standard may also be returned.

If the access_token is missing (e.g. No Authorization header, Authorizaation header is present but without Bearer prefix) or invalid, a 401 (Unauthorized) HTTP status code is returned with the common error code N°41. 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": "Missing credentials",
  "description": "The requested service needs credentials, but the ones provided were invalid"
}

If the access_token is expired, a 401 (Unauthorized) HTTP status code is returned with the common error code N°42. In that case, you'll have to renew the access token.

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

{
  "code": 42,
  "message": "Expired credentials",
  "description": "The requested service needs credentials, and the ones provided were out-of-date"
}

If the requested resource doesn't exist, a 404 (Not Found) HTTP status code is returned with the common error code N°60.

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
    "code": 60,
    "message": "Resource not found",
    "description": "The requested URI does not exist."
}

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

We will always be there to support you if needed.