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:
| Parameter | Description | Location | Type | Constraints |
|---|---|---|---|---|
| Authorization | Bearer authentication token | header | string | Mandatory |
user_id_type | Type of the end-user's identifier | query (GET) or JSON body (POST) | string | Required - Only MSISDN is supported |
user_id | Unique identifier allowing to identify the end-user | query (GET) or JSON body (POST) | string | Required - MSISDN in international format (E.164), without "+": 33600000000 |
age | Delay in hours between current time and simswap date | query (GET) or JSON body (POST) | integer | Required - Positive integer |
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.
| 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 or not | 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 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.