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

# Backend

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

The backend role in a Discovery integration: mint OAuth2 tokens, create the check, hand the verification URL to the device, and receive the discovered MSISDN once the device completes the redirect and submits the code.

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

Response:

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

See [Authentication](/get-started/authentication.md).

## 2. Create the check

POST to create a Discovery check. Unlike Secure SNA, you do not supply a claimed `phone_number` — Discovery's purpose is to retrieve it.

```bash
curl -X POST https://{data_residency}.api.idlayr.com/v1/number-verification/discovery-checks \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://your.app/callbacks/discovery"
  }'
```

Request fields:

* `callback_url` *(optional)* — receives the terminal-status notification.
* `reference_id` *(optional)* — your own identifier, echoed back.

Response includes:

* `check_id` — for correlation.
* `url` — the device-facing verification URL.
* `status` — initially `ACCEPTED`.
* `ttl` — seconds until the check expires.

## 3. Hand the verification URL to the device

Pass **only the `url`** to your iOS or Android app, over your own application API. The OAuth2 access token never leaves your backend — the SDK doesn't need it. See [iOS integration](/products/number-verification/discovery/integration/ios.md) or [Android integration](/products/number-verification/discovery/integration/android.md).

## 4. Receive the code from the device

The SDK follows the redirect chain and returns a `code` to your app. Your app forwards the `code` to your backend over your own application API (alongside the `check_id` so you can correlate).

## 5. Submit the code to IDlayr

POST the code to the check's `/code` sub-resource. This is the call that returns the discovered MSISDN.

```bash
curl -X POST https://{data_residency}.api.idlayr.com/v1/number-verification/discovery-checks/{check_id}/code \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "code": "abc123def456" }'
```

The response returns the completed DiscoveryCheck:

* `status` — `COMPLETED` on success; `ERROR` if the platform can't complete (MNO-side or platform-side failure). If the TTL had already elapsed before submission, you'll get a `404` or `409` on this call — see [Error codes](/products/number-verification/discovery/error-codes.md).
* `phone_number` — the discovered MSISDN in E.164. Present when `status` is `COMPLETED`.
* `error_code` — present when `status` is `ERROR`. See [Error codes](/products/number-verification/discovery/error-codes.md).

## 6. Receive callbacks (optional)

If you supplied a `callback_url` in step 2, IDlayr POSTs the terminal-state DiscoveryCheck to it in addition to returning the result on the code-submission response. See [Callbacks](/products/number-verification/discovery/callbacks.md). Callbacks are useful if you want the terminal-state notification to reach a different service from the one that called `/code`, or as an at-least-once redundant path.

If you did not supply a `callback_url`, you can also read the terminal-state Check by polling:

```bash
curl https://{data_residency}.api.idlayr.com/v1/number-verification/discovery-checks/{check_id} \
  -H "Authorization: Bearer {access_token}"
```

## Production patterns

* **Consent first.** Obtain user consent for retrieving and using the MSISDN before invoking Discovery.
* **Plan for unavailable outcomes.** Some devices won't complete: MNO not supported, Wi-Fi at the moment of the call, TTL elapsed. Have a fallback in place (typed-number entry, alternative verification, or skipping the step).
* **Cache access tokens.** Don't mint per request.
* **Verify callback signatures.** A device-side dispatch confirmation is not the authoritative result.
* **Sandbox vs production**: same endpoint, different project.
* **Data minimisation**: store the discovered MSISDN only as long as needed for the use case.
* **User-facing UX is your choice.** If you want to show the discovered number to the user for confirmation, or display a masked view of it, that lives in your application code. See [User consent and displaying the number](/products/number-verification/discovery.md#user-consent-and-displaying-the-number).


---

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