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

# Integration

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

A typical Eligibility call is a single synchronous request from your backend. Both endpoints are `GET` and return the matched network plus the list of eligible IDlayr products.

There's also a device-captured-IP pattern for the IP endpoint, where the SDK on the device captures the real cellular IP and sends it back to your backend, which then calls IDlayr. Covered in section 4. The OAuth2 access token stays on your backend throughout.

## 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=eligibility"
```

Response:

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

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

## 2. Query by phone number

Use when you have a claimed MSISDN and want to know what IDlayr products are eligible for that number. Resolves the MNO via HLR lookup.

```bash
curl https://{data_residency}.api.idlayr.com/v1/eligibility/phone-numbers/+447700900000 \
  -H "Authorization: Bearer {access_token}"
```

The response is synchronous and contains the matched network and the list of eligible IDlayr products. The exact response shape is in the [Endpoints page](/products/eligibility/endpoints.md) and the API Reference.

## 3. Query by mobile IP address (server-observed)

Use when you have observed the device's IP from your inbound traffic and want to know what's eligible on that network. Resolves the MNO via IDlayr's proprietary IP-routing tables.

```bash
curl https://{data_residency}.api.idlayr.com/v1/eligibility/device-ips/192.0.2.42 \
  -H "Authorization: Bearer {access_token}"
```

The response carries the matched network and the eligible products — or, if the IP isn't from a mobile carrier (e.g. Wi-Fi, VPN, hosting provider), an error indicating "not a mobile IP". See [Error codes](/products/eligibility/error-codes.md).

{% hint style="info" %}
A server-observed IP may not be the device's real cellular IP — NAT, proxies, and CDN edges all obscure it. For more reliable mobile-IP resolution, use the device-assisted pattern below.
{% endhint %}

## 4. Query by mobile IP address (device-captured IP)

Use when you want to be sure the IP is the **real cellular IP** of the device — for example, when you specifically want to know "is the device on cellular right now, on a supported network?" or when the server-observed IP isn't reliable.

The IDlayr API call stays **backend-to-backend** — the device only contributes the IP. The device never holds an OAuth2 access token; only your backend does.

The flow:

1. **The device captures its real cellular IP via the IDlayr SDK.** On iOS, `IDlayrKit` exposes this; on Android, `idlayr-sdk-android`. The SDK pins the lookup to the cellular interface so the captured IP is the carrier-assigned one, not a NAT'd Wi-Fi address.
2. **The device sends the captured IP back to your backend** over your own application API.
3. **Your backend calls the Eligibility endpoint** with that IP:

   ```bash
   curl https://{data_residency}.api.idlayr.com/v1/eligibility/device-ips/{cellular_ip} \
     -H "Authorization: Bearer {access_token}"
   ```
4. **Your backend forwards the result to the device** (or acts on it directly — for example, deciding whether to trigger a Secure SNA flow).

The OAuth2 access token never leaves your backend. The device contributes only the IP it observed; your backend remains the only party authorised against the IDlayr API.

## 5. Read the result

A successful response indicates:

* **The matched network** — the MNO (and country) IDlayr resolved the input to.
* **The list of eligible products** — which IDlayr products are available for that network for your project, after the three gates (connectivity, authorisation, product support — see [How it works](/products/eligibility/how-it-works.md)).

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

## 6. Branch on the result

A typical decision tree:

* **All needed products eligible** → proceed with your planned verification flow.
* **Some products eligible, others not** → route to the available alternative (e.g. SNA unavailable → fall back to Reverse SMS).
* **No products eligible** → skip the verification and route to a backup path (typed entry, document upload, alternative factor).
* **Error response** → IDlayr couldn't determine eligibility. Treat differently from "no products eligible" — see [Error codes](/products/eligibility/error-codes.md).

## Production patterns

* **Cache access tokens** until they expire.
* **Cache eligibility results briefly** when calling for the same input multiple times in quick succession (e.g. 1–5 minutes). Carrier coverage changes rarely, and the result is stable on short timescales.
* **Don't pre-check on every single user** when you'd attempt the verification regardless. Pre-check is most valuable in flows where the cost of a failed verification (UX, support escalation, billing) is high.
* **Sandbox vs production**: same endpoints, different project. See [Testing in sandbox](/products/eligibility/testing.md).
* **Rate limits** apply on both the token endpoint and the eligibility endpoints.
* **Treat "no products eligible" as a normal answer**, not a failure. Errors mean we couldn't determine; "no products" means we determined and the answer is none.


---

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