Simswap - ID Mobile API
Use this endpoint to check whether the SIM card associated with a phone number has been swapped within a specified period.
Related ID Mobile documentation:
Prerequisite - Simswap requires a
token
obtained beforehand from the ID Mobile Access Token endpoint.
Call ACCESS_TOKEN first and pass the returned
access_token value as the token parameter
below.
simswap
Request
Both GET and POST are supported.
{SERVER_ADDRESS} and {LICENCE_CODE}
are provided by DQE upon account creation. Contact your DQE account
manager to obtain these credentials.
GEThttps://{SERVER_ADDRESS}/IDMOBILE/?number={NUM}&token={TOKEN}&licence={LICENCE_CODE}&scope=simswap&period={PERIOD}&name={NAME}
Code examples
Check for a SIM swap on a phone number
curl "https://{SERVER_ADDRESS}/IDMOBILE/?number={NUM}&token={TOKEN}&licence={LICENCE_CODE}&scope=simswap&period={PERIOD}&name={NAME}"
fetch("https://{SERVER_ADDRESS}/IDMOBILE/?" +
new URLSearchParams({
number: "{NUM}",
token: "{TOKEN}",
licence: "{LICENCE_CODE}",
scope: "simswap",
period: "{PERIOD}",
name: "{NAME}"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/IDMOBILE/",
params={
"number": "{NUM}",
"token": "{TOKEN}",
"licence": "{LICENCE_CODE}",
"scope": "simswap",
"period": "{PERIOD}",
"name": "{NAME}",
},
)
print(response.json())
<?php
$params = http_build_query([
'number' => '{NUM}',
'token' => '{TOKEN}',
'licence' => '{LICENCE_CODE}',
'scope' => 'simswap',
'period' => '{PERIOD}',
'name' => '{NAME}',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/IDMOBILE/?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
axios.get('https://{SERVER_ADDRESS}/IDMOBILE/',
{
params: {
number: '{NUM}',
token: '{TOKEN}',
licence: '{LICENCE_CODE}',
scope: 'simswap',
period: '{PERIOD}',
name: '{NAME}'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/IDMOBILE/"
+ "?number={NUM}&token={TOKEN}&licence={LICENCE_CODE}&scope=simswap&period={PERIOD}&name={NAME}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.GET()
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var url = "https://{SERVER_ADDRESS}/IDMOBILE/"
+
"?number={NUM}&token={TOKEN}&licence={LICENCE_CODE}&scope=simswap&period={PERIOD}&name={NAME}";
var response = await client.GetAsync(url);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://{SERVER_ADDRESS}/IDMOBILE/" +
"?number={NUM}&token={TOKEN}&licence={LICENCE_CODE}&scope=simswap&period={PERIOD}&name={NAME}"
resp, err := http.Get(url)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
POSThttps://{SERVER_ADDRESS}/IDMOBILE/
Add the following parameters in the request body using
Content-Type: application/x-www-form-urlencoded.
Code examples
Check for a SIM swap on a phone number
curl -X POST "https://{SERVER_ADDRESS}/IDMOBILE/"
\
-H "Content-Type: application/x-www-form-urlencoded"
\
-d "licence={LICENCE_CODE}" \
-d "number={NUM}" \
-d "token={TOKEN}" \
-d "scope=simswap" \
-d "period={PERIOD}" \
-d "name={NAME}"
fetch("https://{SERVER_ADDRESS}/IDMOBILE/", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded"
},
body: new URLSearchParams({
licence: "{LICENCE_CODE}",
number: "{NUM}",
token: "{TOKEN}",
scope: "simswap",
period: "{PERIOD}",
name: "{NAME}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/IDMOBILE/",
data={
"licence": "{LICENCE_CODE}",
"number": "{NUM}",
"token": "{TOKEN}",
"scope": "simswap",
"period": "{PERIOD}",
"name": "{NAME}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/IDMOBILE/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'licence' => '{LICENCE_CODE}',
'number' => '{NUM}',
'token' => '{TOKEN}',
'scope' => 'simswap',
'period' => '{PERIOD}',
'name' => '{NAME}',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
const qs = require('querystring');
axios.post('https://{SERVER_ADDRESS}/IDMOBILE/',
qs.stringify({
licence: '{LICENCE_CODE}',
number: '{NUM}',
token: '{TOKEN}',
scope: 'simswap',
period: '{PERIOD}',
name: '{NAME}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "licence={LICENCE_CODE}&number={NUM}&token={TOKEN}&scope=simswap&period={PERIOD}&name={NAME}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/IDMOBILE/"))
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(form))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var form = new Dictionary<string, string>
{
["licence"] = "{LICENCE_CODE}",
["number"] = "{NUM}",
["token"] = "{TOKEN}",
["scope"] = "simswap",
["period"] = "{PERIOD}",
["name"] = "{NAME}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/IDMOBILE/",
new FormUrlEncodedContent(form));
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
form := url.Values{}
form.Set("licence", "{LICENCE_CODE}")
form.Set("number", "{NUM}")
form.Set("token", "{TOKEN}")
form.Set("scope", "simswap")
form.Set("period", "{PERIOD}")
form.Set("name", "{NAME}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/IDMOBILE/",
form)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
Parameters
| Parameter | Description | Mand / Opt |
|---|---|---|
| SERVER_ADDRESS | Address of the DQE server that will process the data. | Mandatory |
| licence | Number assigned to you as your licence code. | Mandatory |
| number | Phone number. | Mandatory |
| token | Token retrieved through authentication. | Mandatory |
| scope |
Static value. Must be simswap for this
scope.
Fixed value: simswap
|
Mandatory |
| period | Past period during which the SIM swap check is performed. Value in hours. | Mandatory |
| name | Customer name in the DQE database. | Mandatory |
Combining scopes —
simswap can
be combined with matching_notp (fraud scoring) in
a single request, e.g. scope=simswap,matching_notp,
and with info (phone number intelligence) in any
combination, e.g. scope=simswap,info. See the
info fields below. Contact your DQE account manager
for guidance on the full combined `simswap`+`matching_notp` response
shape.
info add-on fields — returned in addition to this
endpoint's own fields when info is included in
scope:
| Field | Description | Example |
|---|---|---|
| telorigine | Phone number in the request. |
0600000000
|
| tel | Phone number, formatted. |
+33600000000
|
| geolocation | Geographic situation of the phone number. |
FRANCE
|
| operator | Current operator of the phone number, if subscribed. |
ORANGE
|
| oldoperator | Previous operator of the phone number. |
SFR
|
| ported | Indicates if the phone number is ported, if subscribed. |
Y
|
| type | Type of the phone number. |
MOBILE
|
| iderror |
Error code of the check (0 or 1).
|
1
|
Response
The API returns a JSON object containing the following keys.
| Key | Description | Type |
|---|---|---|
| status | Request status label. | String |
| operator | Phone number operator. | String |
| swapped |
Indicates whether the SIM card has been swapped:
true or false.
|
String |
Response example
Example simswap response
{
"status":
"success",
"operator":
"Orange",
"swapped": "false"
}
Errors
These error codes are shared across ID Mobile scopes — the API keys errors by code, not by endpoint. Codes 09 and 12–17 depend on the phone number's eligibility and on the queried operator's configuration rather than on a single bad parameter; the request example shown is a syntactically valid simswap call, and the error is returned based on account/operator/number state.
| ID | Error type | Example request | Response |
|---|---|---|---|
| 01 | invalid request |
https://{SERVER_ADDRESS}/IDMOBILE/?number={NUM}&token={TOKEN}&licence={LICENCE_CODE}&period={PERIOD}&name={NAME}
|
{"status": "error", "error_type": "invalid request",
"error_id": "01"}
|
| 02 | invalid licence key |
https://{SERVER_ADDRESS}/IDMOBILE/?number={NUM}&token={TOKEN}&licence={INCORRECT_LICENCE_CODE}&scope=simswap&period={PERIOD}&name={NAME}
|
{"status": "error", "error_type": "invalid licence
key", "error_id": "02"}
|
| 04 | invalid scope |
https://{SERVER_ADDRESS}/IDMOBILE/?number={NUM}&token={TOKEN}&licence={LICENCE_CODE}&scope=unknown&period={PERIOD}&name={NAME}
|
{"status": "error", "error_type": "invalid scope",
"error_id": "04"}
|
| 05 | missing or empty parameter (user_infos) for this scope | Not triggered by Simswap's own parameters (shared platform error code) |
{"status": "error", "error_type": "missing or
empty parameter (user_infos) for this scope",
"error_id": "05"}
|
| 06 | bad parameter format (user_infos) is not a valid JSON | Not triggered by Simswap's own parameters (shared platform error code) |
{"status": "error", "error_type": "bad parameter
format (user_infos) is not a valid JSON", "error_id":
"06"}
|
| 07 | missing mandatory key in user informations (phone) | Not triggered by Simswap's own parameters (shared platform error code) |
{"status": "error", "error_type": "missing mandatory
key in user informations (phone)", "error_id":
"07"}
|
| 09 | ineligible phone number |
https://{SERVER_ADDRESS}/IDMOBILE/?number={NUM}&token={TOKEN}&licence={LICENCE_CODE}&scope=simswap&period={PERIOD}&name={NAME}
|
{"status": "error", "error_type": "ineligible
phone number", "error_id": "09"}
|
| 10 | invalid phone number |
https://{SERVER_ADDRESS}/IDMOBILE/?number={INVALID_NUM}&token={TOKEN}&licence={LICENCE_CODE}&scope=simswap&period={PERIOD}&name={NAME}
|
{"status": "error", "error_type": "invalid phone
number", "error_id": "10"}
|
| 11 | phone number is empty |
https://{SERVER_ADDRESS}/IDMOBILE/?number=&token={TOKEN}&licence={LICENCE_CODE}&scope=simswap&period={PERIOD}&name={NAME}
|
{"status": "error", "error_type": "phone number
is empty", "error_id": "11"}
|
| 12 | phone check failed |
https://{SERVER_ADDRESS}/IDMOBILE/?number={NUM}&token={TOKEN}&licence={LICENCE_CODE}&scope=simswap&period={PERIOD}&name={NAME}
|
{"status": "error", "error_type": "phone check
failed", "error_id": "12"}
|
| 13 | operator [Operator Name] not found |
https://{SERVER_ADDRESS}/IDMOBILE/?number={NUM}&token={TOKEN}&licence={LICENCE_CODE}&scope=simswap&period={PERIOD}&name={NAME}
|
{"status": "error", "error_type": "operator [Operator
Name] not found", "error_id": "13"}
|
| 14 | operator [Operator Name] not authorized for this licence |
https://{SERVER_ADDRESS}/IDMOBILE/?number={NUM}&token={TOKEN}&licence={LICENCE_CODE}&scope=simswap&period={PERIOD}&name={NAME}
|
{"status": "error", "error_type": "operator [Operator
Name] not authorized for this licence", "error_id":
"14"}
|
| 15 | operator [Operator Name] not supported yet |
https://{SERVER_ADDRESS}/IDMOBILE/?number={NUM}&token={TOKEN}&licence={LICENCE_CODE}&scope=simswap&period={PERIOD}&name={NAME}
|
{"status": "error", "error_type": "operator [Operator
Name] not supported yet", "error_id": "15"}
|
| 16 | operator [Operator Name] unreachable |
https://{SERVER_ADDRESS}/IDMOBILE/?number={NUM}&token={TOKEN}&licence={LICENCE_CODE}&scope=simswap&period={PERIOD}&name={NAME}
|
{"status": "error", "error_type": "operator [Operator
Name] unreachable", "error_id": "16"}
|
| 17 | scope not supported by this operator [Operator Name] yet |
https://{SERVER_ADDRESS}/IDMOBILE/?number={NUM}&token={TOKEN}&licence={LICENCE_CODE}&scope=simswap&period={PERIOD}&name={NAME}
|
{"status": "error", "error_type": "scope not
supported by this operator [Operator Name] yet",
"error_id": "17"}
|
| 30 | invalid or expired token |
https://{SERVER_ADDRESS}/IDMOBILE/?number={NUM}&token={EXPIRED_TOKEN}&licence={LICENCE_CODE}&scope=simswap&period={PERIOD}&name={NAME}
|
{"status": "error", "error_type": "invalid or
expired token", "error_id": "30"}
|
Test the API
Click the button below to test this endpoint live in your browser.