> 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/number-verification/secure-sna/how-it-works.md).

# How it works

{% hint style="info" %}
**Device API** · NV 1.0 · GA
{% endhint %}

Three parties participate in a Secure SNA verification: your **backend**, the user's **device**, and the **IDlayr platform**. One round trip resolves the verification.

## The flow

1. **Backend decides verification is needed** and has a claimed MSISDN (from user input, a stored profile, or session context).
2. **Backend mints an OAuth2 access token** scoped to Secure SNA. See [Authentication](/get-started/authentication.md).
3. **Backend creates a check** by POSTing the claimed MSISDN to IDlayr. The response includes a `check_id` and a device-facing verification `url`.
4. **Backend passes only the `url` to the device** (over your own application API). The OAuth2 access token never leaves the backend — the device-side redirect chain is plain HTTP and doesn't require an `Authorization` header.
5. **Device follows the verification URL over cellular data.** On iOS the SDK pins the request to the cellular interface using `NWConnection`; on Android the SDK forces traffic over the cellular network. The MNO attributes the live data session to a phone number during this round trip.
6. **IDlayr completes the check internally** based on what the MNO returned and surfaces a verification code at the end of the redirect chain.
7. **Backend redeems the code with POST** to resolve `match`. The response carries `match: true` (the network-attached number matched the claimed number) or `match: false` (it didn't).

```mermaid
sequenceDiagram
    participant App as Client App (IDlayr SDK)
    participant CBE as Client Backend
    participant IDL as IDlayr Platform
    participant MNO as Mobile Network Operator

    App->>CBE: User enters phone number
    CBE->>IDL: GET /v1/eligibility/phone-numbers/{number}  (pre-flight)
    alt SNA not supported for this number
        IDL-->>CBE: products list excludes Secure SNA
        CBE-->>App: route to fallback (Reverse SMS or SMS OTP)
    else SNA supported
        CBE->>IDL: POST /v1/number-verification/secure-sna-checks
        IDL-->>CBE: check_id + url
        CBE->>App: url
        App->>App: SDK pins request to cellular interface
        App->>MNO: follows url + redirects (over cellular)
        MNO-->>App: redirect with code
        App->>CBE: code
        CBE->>IDL: PATCH /v1/number-verification/secure-sna-checks/{check_id} (code)
        IDL->>MNO: resolve result
        IDL-->>CBE: match: true/false
        CBE-->>App: number verified — no OTP shown
    end
```

## Why cellular data is required

Under Number Verification 1.0 — the transport Secure SNA currently uses — the MNO can only attribute the session to a phone number when the device is on its cellular data network. Wi-Fi requests route through the home network's ISP, which the MNO has no view of. The verification fails on Wi-Fi.

The mobile SDK enforces this. If the device is on Wi-Fi at the moment of the call, the SDK either fails the request with `sdk_no_data_connectivity` or pins the underlying connection to the cellular interface (depending on platform support).

Number Verification 2.1 — in active rollout — uses carrier entitlement servers and widens this constraint. Endpoints will be marked with their NV version on the API reference as 2.1 lands per carrier.

## Roles, at a glance

| Party           | Holds                                  | Does                                                                             |
| --------------- | -------------------------------------- | -------------------------------------------------------------------------------- |
| Your backend    | OAuth2 `client_id` and `client_secret` | Mints tokens, creates the check, redeems the verification code to get the result |
| User's device   | The SDK + the verification `url`       | Follows the verification `url` over cellular; surfaces the verification code     |
| IDlayr platform | The integration with the MNO           | Performs the network attribution; produces the `match`                           |

## What's returned

* During the device-side step, the SDK returns the verification code (or an error code if the request failed before completing).
* After the backend redeems the code for the check, the response is the final SecureSNACheck resource, including `match`, `status` (`COMPLETED` / `EXPIRED` / `ERROR`), `network_id`, and — where the check ended in an error or expiry — an `error_code` carrying the reason.

See the Secure SNA endpoints page for the exact response shape and the canonical errors table for the full `error_code` taxonomy.

## What happens when SNA isn't available

If the MNO doesn't support SNA for the target number, the device is on Wi-Fi with no cellular path, or coverage gaps prevent the check, Secure SNA returns an error rather than a `match` value. Common patterns:

* Pre-check with [Eligibility](/products/eligibility.md) to detect support before triggering SNA.
* Fall back to [Reverse SMS](/products/number-verification/reverse-sms.md) — same product family, SMS channel, no cellular-data constraint.


---

# 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/number-verification/secure-sna/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.