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

# Endpoints

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

Summary of the Eligibility endpoints. Full request and response schemas live in the API Reference.

| Method | Path                                           | Purpose                                                                                    |
| ------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `GET`  | `/v1/eligibility/phone-numbers/{phone_number}` | Eligibility for a specific MSISDN. MNO resolved via HLR lookup.                            |
| `GET`  | `/v1/eligibility/device-ips/{ip}`              | Eligibility for a specific mobile IP address. MNO resolved via IDlayr's IP-routing tables. |

Both endpoints return synchronously. There is no GET-list endpoint — Eligibility queries are not check resources to be retrieved later.

## Common requirements

Both endpoints require:

* HTTPS.
* An OAuth2 Bearer token with the `eligibility` scope on the `Authorization` header.
* The `{data_residency}` host prefix matching your workspace region (`eu.api.idlayr.com` or `us.api.idlayr.com`). See [Data residency](/get-started/concepts/data-residency.md).

## Common response

Both endpoints return:

* The **matched network** — the MNO and country the input resolved to.
* The **list of eligible IDlayr products** — Secure SNA, SIM Swap, Reverse SMS, Discovery — for which all three eligibility gates (connectivity, authorisation, product support — see [How it works](/products/eligibility/how-it-works.md)) pass.

The exact JSON shape — field names, types, optional fields — is documented in the API Reference.

## Common response headers

* `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` — see Rate limits in the API Reference.
* On `429`, a `Retry-After` header indicates seconds before retrying.

## Common error responses

`400` invalid phone number or IP, `401` unauthorized, `404` not found (number not associated with an active subscriber, or IP not resolvable to a known network), `412` not a mobile IP (device-IP endpoint), `429` rate limit reached. See [Error codes](/products/eligibility/error-codes.md) for the full taxonomy.

## Country Coverage and public Device IP — removed in v1

Two legacy endpoints are removed in the v1 surface:

* `GET /coverage/v0.1/countries/{country_code}` — country-level coverage.
* `GET /coverage/v0.1/device_ip` (no IP arg) — the public-Device-IP lookup.

If you used either under v0.x, see the [migration guide](/guides/migration.md) for the recommended v1 alternative.

## See also

* The [Integration page](/products/eligibility/integration.md) walks through both endpoints with cURL, including the device-assisted IP pattern.
* The full API Reference will carry the complete request/response schemas (linked from here once published).


---

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