> 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/integration.md).

# Integration

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

SIM Swap is a single-call, synchronous, backend-to-backend integration. Mint a token, POST a phone number, read the result on the response.

## 1. Mint an access token

```bash
curl -X POST https://{data_residency}.api.idlayr.com/oauth2/token \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=client_credentials" \
  -d "scope=sim_swap"
```

Response:

```json
{
  "access_token": "...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "sim_swap"
}
```

Cache the access token until it expires. See [Authentication](/get-started/authentication.md).

## 2. Create the SIM Swap check

POST the phone number to check:

```bash
curl -X POST https://{data_residency}.api.idlayr.com/v1/sim-swap-checks \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+447700900000"}'
```

Request body:

* `phone_number` *(required)* — the MSISDN to check, in E.164. This is the only required field.
* `reference_id` *(optional)* — your own identifier, echoed back on the response.

## 3. Read the result

The result is returned synchronously on the POST response. Typical fields:

| Field           | Type     | Notes                                                                             |
| --------------- | -------- | --------------------------------------------------------------------------------- |
| `check_id`      | UUID     | Correlation and audit                                                             |
| `no_sim_change` | boolean  | `true` = SIM has not changed recently; `false` = recent change detected           |
| `status`        | string   | `COMPLETED` if the MNO returned a result; `ERROR` if the check could not complete |
| `created_at`    | ISO 8601 | When the check was created                                                        |
| `updated_at`    | ISO 8601 | When the check resolved                                                           |
| `reference_id`  | string   | Echoes whatever you supplied                                                      |
| `error_code`    | string   | Present only when `status` is `ERROR`                                             |

Typical latency is sub-second on supported networks.

## 4. Act on the signal

A `false` value for `no_sim_change` means a SIM change occurred recently. This is a risk signal, not proof of fraud — legitimate replacements happen too (upgrades, breakage, mobile-plan changes). Your business logic decides what to do:

* **Block** the action and notify the customer.
* **Step up** the verification — request additional factors before proceeding.
* **Flag for review** — let it through but surface to fraud-ops.
* **Route to an alternative path** — e.g. skip SMS OTP in favour of a different verifier.

A pair with Secure SNA: both have to hold (`no_sim_change: true` AND `match: true`) for the high-assurance signal.

## Production patterns

* **Cache access tokens** until they expire. Don't mint a fresh token per check.
* **Pre-check with Eligibility** if you'll be calling SIM Swap on numbers from new markets or carriers.
* **Sandbox vs production**: same endpoint, different project. To test, create a sandbox project with `sim_swap` scope and use the project-specific test MSISDNs.
* **Retries**: 5xx responses can be retried with exponential backoff. 4xx responses indicate a contract or input error — don't retry without changing the request.
* **Rate limits** apply on both the token endpoint and the product endpoint. Cache tokens to stay under.
* **Audit trail**: store the `check_id` and the response alongside any business decision that used the result. Useful for fraud reviews and compliance.


---

# 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/integration.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.