device_swap
device_swap tells you how recently the phone number moved to
a different device, according to the mobile operator's records. A recent
device change on an account that has not been used from that device before
can point to account takeover.
It complements sim_swap. sim_swap looks at the
SIM card behind the number, and device_swap looks at the
handset the number is used on. Both can be requested in the same call, and
both return their result in the same shape.
Request
Send the number and device_swap in commands. No
other input is needed.
{
"number": "+393273339145",
"commands": ["device_swap"]
}
Plumma® Connect first asks the operator for the date of the last device
change. If the date cannot be obtained, it then asks whether a change
happened in the last 240 hours (10 days). Either way you get a single
device_swap block and are charged once.
device_swap is not available in every country. Where it is
not available, see Billing.
Response
{
"status": 0,
"status_message": "Response from one supplier",
"device_swap": {
"last_day": 0,
"risk_indicator": 2,
"deviceswap_min_threshold": 24,
"deviceswap_max_threshold": 72,
"date": "2026-09-29T14:05:00.000Z",
"swapped": true,
"swapped_max_age": 240
},
"version": "..."
}| Field | Type | Meaning |
|---|---|---|
risk_indicator |
integer | How recent the last device change is, as a risk level. See the table below. Always present when the block is present. |
date |
string | When the last device change happened, ISO 8601 in UTC. Present only when the operator gives the date. |
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 a window
longer than 24 hours, and when risk_indicator is
-1 or -2. |
deviceswap_min_threshold |
integer (hours) | The lower bound of the window the last change falls in:
24, 72 or 720. Absent when
there is no lower bound. |
deviceswap_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 there is no upper bound. |
swapped |
boolean | Whether a device change happened within the last
swapped_max_age hours. Absent when it could not be
established. |
swapped_max_age |
integer (hours) | The window swapped refers to, currently
240. Present whenever swapped is. |
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 records cover at least 720 hours. | 720 / none |
0 | Lowest risk: the operator found no device change in the period it covers. | none / none |
-1 | The operator answered that it has no data it can give for this number, for example because the number is not one of its subscribers. | none / none |
-2 | Reserved for an operator that declines to answer for a specific number. No route returns it today. | none / none |
-1 is an answer from the operator, so the command counts as
served and is charged. See Billing.
When there is no device_swap 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 device_swap block. The status is
4, and the status_message names
device_swap among the commands that returned no data. The
command is not charged.
Using it with sim_swap
Request both in one call to compare the two signals:
- Recent device change, no recent SIM change: often a customer who moved to a new phone. Consider light extra verification for high-value operations.
- Recent device change and recent SIM change: the pattern of a SIM moved into another person's device. Consider step-up authentication or holding the operation.
- Neither: the customer is on their usual SIM and device.
Base these rules on risk_indicator rather than on
swapped alone. swapped only covers the last 240
hours and can be absent.