> For the complete documentation index, see [llms.txt](https://docs.idlayr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.idlayr.com/products/risk/sim-swap/how-it-works.md).

# How it works

{% hint style="info" %}
**Backend API** · GA
{% endhint %}

SIM Swap is a two-party flow: your backend, and the IDlayr platform (which fans out to the relevant mobile network operator). There is no device-side component and no user interaction.

## The flow

1. **Backend decides a SIM Swap check is needed** — typically before a sensitive action like a password reset, a high-value transaction, or SMS OTP delivery.
2. **Backend mints an OAuth2 access token** scoped to SIM Swap. See [Authentication](/get-started/authentication.md).
3. **Backend POSTs the phone number** to `/v1/sim-swap-checks`. Single required field: the MSISDN in E.164.
4. **IDlayr identifies the MNO** for that number and queries the MNO's live subscriber record.
5. **MNO returns SIM change data** to IDlayr. IDlayr normalises the response across operators so the customer sees a consistent shape regardless of which MNO served the subscriber.
6. **IDlayr returns the check result** synchronously on the same POST response — including `no_sim_change`, `check_id`, `status`, and timestamps.

## Why it's synchronous

SIM Swap data is held in the MNO's live subscriber systems. IDlayr queries on demand and returns the result on the same HTTP response. There is no async-and-wait pattern; no callback to receive; no completion step to PATCH.

Typical latency is sub-second on supported networks. Actual latency varies by MNO, market, and current load.

## Why there's no device involvement

SIM change data lives on the carrier side, not the device side. The MNO knows whether the SIM associated with a number has changed; the device doesn't need to participate. This is what makes SIM Swap channel-agnostic — it works equally well for native app, mobile web, desktop, IVR, or any server-only flow.

## Data handling

* **Real-time only.** IDlayr does not cache SIM change data. Each request hits the MNO's live record.
* **MSISDN not stored beyond the call.** The phone number you submit is held only for the duration of the API call. Only the `check_id`, result, and metadata are retained for audit.

## Cross-MNO normalisation

Operator implementations vary — different response formats, different definitions of "recent", different prepaid handling. IDlayr translates these into one normalised result so your backend sees a consistent shape regardless of which MNO actually served the subscriber.

## When SIM Swap isn't available

* The MNO doesn't support SIM Swap (returns `mno_not_supported`).
* The number is on a prepaid line where the operator doesn't expose SIM change data.
* The number isn't associated with any active subscriber.

Use [Eligibility](/products/eligibility.md) as a pre-check to know whether SIM Swap can be called for a given number, before the call.

## Combining with Secure SNA

SIM Swap and Secure SNA address different attack vectors. Used together:

* **SNA alone** proves the device currently holds the number — but a fraudster with a fresh SIM swap would also pass SNA.
* **SIM Swap alone** detects the recent SIM change — but doesn't confirm the device holds the number.
* **SNA + SIM Swap** requires both signals to hold. This is the canonical high-assurance pattern for authentication and fraud-sensitive flows.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.idlayr.com/products/risk/sim-swap/how-it-works.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.