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:
Parameter | Description | Location | Type | Constraints |
---|---|---|---|---|
Authorization | Bearer authentication token | header | string | Mandatory |
user_id_type | Type of the end-user's identifier | query | string | Required - Only MSISDN is supported. |
user_id | Unique identifier allowing to identify the end-user | query | string | Required - MSISDN in international format (E.164), without "+": 33611223344 . |
age | Delay in hours between current time and simswap date | query | string | Required - Positive integer. |
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.
Parameters | Description | Location | Type | Constraints |
---|---|---|---|---|
X-OAPI-Request-Id | An identifier of the request | header | string | Mandatory. To be logged |
swapped | Indicates whether the SIM card has been swapped during the delay | body (JSON) | string | Mandatory - Enum : ["true", "false"] |
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.