SIM Verify France – Mobile ID (0.1) API – Getting started

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 OpenID Connect platform. 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:

Parameter	Description	Location	Type	Constraints
Authorization	Bearer authentication token	header	String	Mandatory
`user_id_type`	Type of the end-user's identifier.	query string	string	Required - Only `MSISDN` is supported.
`user_id`	Unique identifier allowing to identify the end-user.	query string	string	Required - MSISDN in international format (E.164), without "+": `33611223344`.
`age`	Delay in hours between current time and simswap date.	query string	string	Required - Positive integer.

As an example:

curl -X GET \
	-H "Authorization: Bearer OFR_FJSyJ...Gms_a92e3fb8b16...0a75ef4" \
	"https://api.orange.com/sim_verify_france/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.

Parameters	Description	Location	Type	Constraints
X-OAPI_Request-Id	An identifier of the request	header	String	Mandatory
swapped	Indicates whether the SIM card has been swapped during the delay.	JSON body	String	Mandatory - Enum : [true, false]

As an example:

HTTP/1.1 200 OK
Content-Length: 26
Content-Type: application/json
X-OAPI-Request-Id: abZ32h66

{
  "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_code (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 access_token is expired, revoked or invalid, a 401 Unauthorized HTTP status code is returned with the invalid_token error code. In that case, you'll have to renew the access token.

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

{
	error="invalid_token", 
	error_description="The access token provided is expired, revoked, malformed, or invalid for other reasons" 
}

If the user_id_type 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

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

If the user_id_type 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

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

If the user doesn't exist, 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_code": "access_denied",
   "error_description": "The user is unknown."
}

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

{
   "code": "access_denied",
   "error_description": "The user is ineligible."
}

If an internal error occurred, a 500 Bad Request HTTP status code is returned with the following JSON response::

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

{
   "code": "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.

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.