> 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/discovery/how-it-works.md).

# How it works

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

Discovery runs on the same infrastructure as Secure SNA and follows the same shape of flow. The only differences are on the API surface: on Create, Discovery does not take a `phone_number` claim (that's what it discovers), and on completion the response returns the discovered `phone_number`.

If you already know how Secure SNA works, you know how Discovery works.

## The flow

1. **Backend decides Discovery is needed** (e.g. the user has tapped "use my phone number" on your signup form).
2. **Backend mints an OAuth2 access token** scoped to Discovery. See [Authentication](/get-started/authentication.md).
3. **Backend creates a check** — POSTing to IDlayr with no MSISDN in the payload. 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.** The SDK pins the request to the cellular interface. The carrier attributes the active data session to a phone number; IDlayr captures the MSISDN.
6. **SDK receives a code** at the end of the redirect chain and hands it to your app.
7. **App passes the code to your backend** over your own application API. The device does not talk to IDlayr's completion endpoint directly.
8. **Backend submits the code** by POSTing to the check's `/code` sub-resource with its OAuth2 token. IDlayr responds with the completed Check including the discovered `phone_number`.

The device never sees the MSISDN. Only your backend does. If you want to display the number to the user, your backend passes it back down to the app after step 8.

## Why cellular data is required

Same constraint as Secure SNA. Under Number Verification 1.0, the MNO can only attribute the session to a phone number when the device is on cellular data. Wi-Fi breaks the trust path. The SDK pins the verification request to the cellular interface.

NV 2.1 — in active rollout — uses carrier entitlement servers to widen this constraint. NV 2.1 also introduces a carrier-enforced user-confirmation step at the entitlement server; that is not present under NV 1.0.

## Discovery vs. Secure SNA at a glance

|                               | Secure SNA                               | Discovery                                  |
| ----------------------------- | ---------------------------------------- | ------------------------------------------ |
| Create payload                | Includes claimed `phone_number`          | No `phone_number` — Discovery discovers it |
| Question the platform answers | "Is this claimed number on this device?" | "What number is on this device?"           |
| Response on completion        | `match: true / false`                    | `phone_number` (E.164)                     |
| Infrastructure                | Shared with Discovery                    | Shared with Secure SNA                     |
| Transport                     | NV 1.0 over cellular data                | NV 1.0 over cellular data                  |
| SDK role                      | Pins to cellular; drives redirect        | Pins to cellular; drives redirect          |

## Roles, at a glance

| Party           | Does                                                                                                            |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| Your backend    | Mints tokens, creates the check, receives the code from the app, submits it, and receives the discovered MSISDN |
| Your app        | Hands the `url` to the SDK, receives the code back, forwards the code to your backend                           |
| SDK             | Pins to cellular; follows the redirect chain; returns the code to your app                                      |
| Carrier         | Attributes the active data session to an MSISDN                                                                 |
| IDlayr platform | Captures the MSISDN and returns it in the code-submission response and callback                                 |

## What's returned

The DiscoveryCheck resource carries `phone_number` (the discovered MSISDN in E.164), `status` (`COMPLETED`, `EXPIRED`, or `ERROR`), and an `error_code` where applicable.

See [Endpoints](/products/number-verification/discovery/endpoints.md) and [Error codes](/products/number-verification/discovery/error-codes.md) for the response shape.

## When Discovery isn't available

* The MNO doesn't support Discovery for the device.
* The device is on Wi-Fi only at the moment of the request.
* The check expires (TTL elapsed before the device completed the redirect).

Use [Eligibility](/products/eligibility.md) to detect MNO support before triggering Discovery.

## Displaying the discovered number to the user

Discovery does not include an IDlayr-side step where the user is shown the number or asked to confirm. The device never sees the MSISDN at all — that value only exists on your backend, after the code-submission response. If your integration wants to display the number for the user's benefit — for example asking "is this your number?" as part of your onboarding — your backend passes the MSISDN back down to your app for display. See [Discovery → User consent and displaying the number](/products/number-verification/discovery.md#user-consent-and-displaying-the-number) on the product page for common patterns.


---

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