sim_swap
sim_swap tells you how recently the SIM card behind a phone
number was changed. In a SIM swap fraud, the victim's number is moved to a
new SIM controlled by the fraudster, who then receives the victim's calls
and one-time codes. A recent SIM change is therefore a strong signal to
ask for extra verification before a password reset, a payment or any
other sensitive action.
SIM changes also happen for legitimate reasons, such as a lost phone or a new SIM format. Use the signal to raise the level of checks, not as a verdict on its own.
The data comes in real time from the mobile network, either directly from the operator or through a regional aggregator, depending on the route available for the number. Operators report SIM changes in different ways, and Plumma® Connect returns them all in the same format.
Request
{
"number": "+393273339145",
"commands": ["sim_swap"]
}No other input is needed. Plumma® Connect asks the operator for the date of the last SIM change. When the operator does not give the date, it asks instead whether a change happened in the last 240 hours (10 days). Either way you get one block and are charged once.
Response
The result is in the simswap block:
{
"status": 0,
"status_message": "Response from one supplier",
"simswap": {
"last_day": 0,
"risk_indicator": 3,
"simswap_min_threshold": 72,
"simswap_max_threshold": 720,
"date": "2026-09-20T11:00:00.000Z",
"swapped": false,
"swapped_max_age": 240
},
"version": "..."
}| Field | Type | Meaning |
|---|---|---|
risk_indicator |
integer | How recent the last SIM change is, as a risk level. See the table below. Read this field first. |
date |
string | When the last SIM change happened, ISO 8601 in UTC, for example
2026-09-20T11:00:00.000Z. Present only when the
operator gives the date, which several networks do not. |
last_day |
integer | 1 if the last change was less than 24 hours ago,
0 if it was not. Absent when this cannot be said: when
the operator only confirmed a change somewhere within the last 240
hours, and when risk_indicator is negative. |
simswap_min_threshold |
integer (hours) | The lower bound of the window the last change falls in:
24, 72 or 720. Absent when
the change is less than 24 hours old, and when there is no change
to place. |
simswap_max_threshold |
integer (hours) | The upper bound of that window: 24,
72 or 720, or 240 when the
operator only confirmed a change within the last 240 hours. Absent
when the change is more than 720 hours old, and when there is no
change to place. |
swapped |
boolean | Whether a SIM change happened within the last
swapped_max_age hours. Absent when it could not be
established, and when risk_indicator is
negative. |
swapped_max_age |
integer (hours) | The window swapped refers to: 240 on
every route. Present whenever swapped is. |
Fields that cannot be stated are left out, never sent as
null. An absent field means the operator's answer did not
support it.
risk_indicator values
| Value | Meaning | Thresholds (min / max) |
|---|---|---|
1 | Very high risk: change less than 24 hours ago. | none / 24 |
2 | High risk: change 24 to 72 hours ago. | 24 / 72 |
3 | Medium risk: change 72 to 720 hours (30 days) ago, or a change confirmed only as "within the last 240 hours". | 72 / 720, or none / 240 |
4 | Low risk: change more than 720 hours ago. Given only when the operator's own records cover at least 720 hours. | 720 / none |
0 | Lowest risk: the operator found no SIM change in the period it covers. This is not a statement about a date. | none / none |
-1 | No data: the operator answered that it has nothing it can give for this number, for example because the number is not one of its subscribers or the service does not apply to it. | none / none |
-2 | Reserved for an operator that declines to answer for a specific number. No route returns it today. | none / none |
Treat negative values as "no signal", never as low risk. They describe what the operator could tell you, not the subscriber.
When there is no simswap block
If the operator could not be reached or did not answer, for example
because the request was not authorized on its side, the response has no
simswap block. The status is 4,
and the status_message names sim_swap among the
commands that returned no data. If the number's country is not covered
for sim_swap, the status is 2, or
4 when other commands were served.
Coverage and billing
A covered country does not mean that every operator in it releases the
data. risk_indicator: -1 is an answer from the operator and
is charged like any other result. A request with no
simswap block is not charged.
Before committing to a country, test a sample of numbers and look at the
share of -1 answers for each operator, not only at the share
of requests that got a response. A route can answer every request and
still give little usable signal.