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

# How it works

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

Eligibility runs a single REST query and returns a synchronous response. No callbacks, no async pattern, no device-side step (except optionally the SDK-captured IP for the IP endpoint).

## The three gates

For each IDlayr product on the response, Eligibility evaluates three conditions:

1. **Connectivity** — does IDlayr have integration to the user's MNO at all?
2. **Authorisation** — is your project approved to use that MNO, and is the corresponding [allowed network](/get-started/concepts/allowed-networks.md) in place?
3. **Product support** — does the MNO (or MVNO) support the IDlayr product in question?

A product is reported as **eligible** only when all three are true. If any gate fails, the product is reported as unavailable. This keeps Eligibility consistent with what would actually happen if you tried the verification.

## Two endpoints, two sources of truth

Both endpoints answer the same question — *which IDlayr products is this user eligible for?* — but they start from different inputs and use different routing logic to resolve the MNO.

| Endpoint                                           | Input             | How the MNO is resolved                                                                                         |
| -------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------- |
| `GET /v1/eligibility/phone-numbers/{phone_number}` | MSISDN            | **HLR lookup** — the carrier-side Home Location Register is the authoritative source for MSISDN-to-MNO mapping. |
| `GET /v1/eligibility/device-ips/{ip}`              | Mobile IP address | **IDlayr's proprietary IP-routing tables** — internal mappings of IP ranges to MNOs, refreshed continuously.    |

The phone-number endpoint can be run at any moment server-side; you don't need the device involved.

The IP endpoint resolves the IP to an MNO using IDlayr's own tables. The accuracy of that resolution depends on the IP being a **real mobile carrier IP**, not a NAT'd IP from a corporate proxy or a residential ISP. For that reason, the IP endpoint is most useful when the IP is captured **from the device itself**, ideally via the [IDlayr SDK](/get-started/sdks.md) which exposes the real cellular IP rather than whatever the host network observed.

## The flow

1. **Your backend has a phone number or a mobile IP** (for the IP endpoint, the IP is typically captured by the device via the SDK and sent back to your backend — the API call itself stays backend-to-backend).
2. **A caller mints an OAuth2 access token** scoped to `eligibility`. See [Authentication](/get-started/authentication.md).
3. **The caller calls the eligibility endpoint** for the input it has.
4. **IDlayr resolves the network** — HLR for MSISDN, IP-routing tables for IP — and evaluates the three gates against the resolved MNO.
5. **IDlayr returns a synchronous response** containing the matched network and the list of eligible IDlayr products for it.

## What's returned

At a high level, both endpoints return:

* The **matched network** — the MNO (and country) that the input resolved to.
* A **list of eligible products** — the IDlayr products available for that network, after the three gates have been evaluated.

The exact response shape is in [Endpoints](/products/eligibility/endpoints.md) and the API Reference.

## When the answer is "no products available"

If none of the three gates pass for any IDlayr product, the response is a **successful 200** that happens to carry an empty product list. That's not an error — it's an answer. Your code should route to the no-IDlayr fallback path and not retry.

Errors mean IDlayr couldn't determine eligibility (bad input, no subscriber found, internal failure). "No products available" means IDlayr determined eligibility and the answer is none. Treat them differently. See [Error codes](/products/eligibility/error-codes.md).

## When not to use Eligibility

* For checks you'd run on every single user, when you'd attempt the verification regardless. Eligibility costs latency too — even if low. Skip the pre-check when its answer doesn't change your action.
* For market-level coverage planning. Eligibility answers per-MSISDN or per-IP, not per-market. For market-level coverage, talk to your IDlayr account team.

## Why it's commercial as well as technical

A product is eligible only when both the **technical** path (IDlayr has the MNO connectivity, the MNO supports the product) and the **commercial** path (your project is approved and has the allowed network) line up. A carrier IDlayr supports but your project isn't authorised for will be reported as unavailable — even if a different project on the same workspace could use it.

This keeps the answer honest. If a verification call would fail for a commercial reason, Eligibility tells you so up-front rather than letting the call fail downstream.


---

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