> 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/guides/your-first-api-call.md).

# Your first IDlayr API call

A smoke test for a new IDlayr integration: prove your project credentials work, your OAuth2 flow returns a token, and a real API call comes back with a real response. **No SDK, no device, no mobile data path.** Just `curl` and a shell.

## When to use this

* You've just received your project's `client_id` and `client_secret` from the Enterprise Portal and want to confirm they work before writing integration code.
* You're debugging an integration that isn't behaving and want to isolate "credentials and auth" from the rest of your stack.
* You want to run an Eligibility pre-flight check ad-hoc against a specific phone number to see which IDlayr products are supported for it.

This guide takes about five minutes.

## What you'll verify

* Your backend can authenticate to IDlayr using the OAuth2 client-credentials flow.
* Your access token works against the IDlayr API.
* You can query [Eligibility](/products/eligibility.md) — a representative backend API — and parse the response.

## Prerequisites

* An IDlayr project with the `eligibility` scope on its OAuth2 credentials. Create one in the [Enterprise Portal](/enterprise-portal/projects.md) if you don't have one yet.
* The project's `client_id` and `client_secret` — see [Credentials](/enterprise-portal/credentials.md).
* A phone number to check, in E.164 format (e.g. `+447700900000`).
* `curl` installed.

## 1. Obtain 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"
```

Capture the `access_token` from the response. Tokens are short-lived (typically one hour); for production you'd cache them until expiry. See [Authentication](/get-started/authentication.md) for the full token-lifecycle model.

## 2. Check eligibility

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

The response indicates whether IDlayr products are available for that number — Secure SNA, SIM Swap, Reverse SMS, Discovery, or some subset. See [Eligibility](/products/eligibility.md) for the full response shape.

## What you've just done

* Authenticated your backend to IDlayr using OAuth2 client credentials.
* Queried whether IDlayr products are available for a specific phone number.
* Proven the platform-level shape of your integration: token mint → API call → response parse.

This is the same call you'd run as a pre-flight check before triggering Secure SNA, SIM Swap, Reverse SMS, or Discovery — Eligibility tells you whether to attempt the verification or route the user to an alternative path.

## Troubleshooting

* **`401 unauthorized` on the token mint** — `client_id` / `client_secret` mismatch, or the project doesn't have the `eligibility` scope. Verify in the [Enterprise Portal](/enterprise-portal/credentials.md).
* **`401 unauthorized` on the eligibility call** — the access token has expired, or the scope you requested didn't include `eligibility`. Mint a fresh token with the right scope and retry.
* **`404 not_found`** — the number isn't associated with an active subscriber that IDlayr can resolve. Try a number you know is active.
* **No response at all** — verify the host matches your data-residency region (`eu.api.idlayr.com` or `us.api.idlayr.com`). See [Data residency](/get-started/concepts/data-residency.md).

## What's next

* For a device-API integration (Secure SNA, Discovery), see [Quickstart](/get-started/quickstart.md) — an end-to-end iOS walkthrough.
* For other backend-only products (SIM Swap, Reverse SMS), the call shape is similar — see the relevant page in [Products](/products/products.md).
* For more on Eligibility specifically, including the device-IP endpoint variant, see [Eligibility](/products/eligibility.md).


---

# 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/guides/your-first-api-call.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.