SIM Verify France - Mobile ID

1.0

• 1.0 (current)
• 0.1 (deprecated)

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 (client credential flow) with our OAuth 2.0 Authorization Server. Please follow the method described here to get a valid access token.

Retrieve Orange customer's information

The SIM Verify API is available with either a GET method (parameters as query strings) or a POST method (parameters in a JSON payload).

In both cases, 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 (the MSISDN values are only examples, not valid test numbers):

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

curl -X POST \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer zkp7zQcsWc3lTUQkTZ6hbXMwgGkT" \
     -d "{ \
           "user_id_type": "MSISDN", \
           "user_id": "33600000000", \
           "age": 72
         } \
     https://api.orange.com/simverify/fr/v1/checksimswap

a/ If the transaction succeed

On success, the SIM Verify API (both GET and POST methods) 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 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 user is ineligible."
}

If the eligibility of the user cannot be verified (including if the MSISDN is not recognized as an Orange one), 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 '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 (e.g. not compliant with E.164 format), a 400 (Bad Request) HTTP status code is returned with the following JSON response (the part after "REQUIRED parameter user_id is invalid:" may change according to the actual reason):

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 '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 (the part after "REQUIRED parameter age is invalid:" may change according to the actual reason):

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

If an internal error occurred during the user's eligibility verification, 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 Eligibility 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.