---
title: "Initiate Silent Network Authentication (SNA)"
url: "https://developer.incode.com/api-reference/sna-initiate/"
section: "api-reference"
group: "Phone number input"
version: "v1.1"
status: "live"
endpoint: "POST /omni/sna/initiate"
---
# Initiate Silent Network Authentication (SNA)

`POST /omni/sna/initiate`

Base URL: `https://demo-api.incodesmile.com` — Incode demo environment

Silent Network Authentication verifies that the device making the request owns the phone number,
without sending an SMS code. It is available when the organization has SNA enabled and the flow's
Phone module has `snaVerification` set in `GET /omni/onboarding/flow`.

**Phone number resolution.** Send `phoneNumber` to verify the number the user just typed. When the
body is empty or absent, the number is resolved from the session in this order: the phone already
stored on the session, the `phone`/`phoneNumber` custom field, the most recent PHONE form answer,
the OAuth `loginHint`. The resolved number is stored on the session and echoed back in
`phoneNumber`, with `phoneSource` telling where it came from. A client can therefore call this
endpoint before showing the phone capture screen and skip the screen when the response carries a
`phoneNumber` (`success: true`, or `success: false` with `fallbackReason`). A response with
`errorCode` carries no phone number: show the capture screen on `PHONE_REQUIRED`, and handle the
other codes as errors.

**Outcomes.** The endpoint always answers HTTP 200; branch on the body:
- `success: true` - SNA started. Open `checkUrl` from the device over its mobile data connection
  (not Wi-Fi), capture the `code` returned by the redirect and send it to `POST /omni/sna/complete`.
- `success: false` with `fallbackReason` - SNA is not possible for this number (organization or flow
  has SNA disabled, network not covered, SIM swapped in the last 7 days, provider error). The number
  is still saved on the session. Continue with SMS OTP: `GET /omni/send/otp` then
  `GET /omni/compare/otp?code={code}` (both accept the same LIMITED token and default to SMS).
- `success: false` with `errorCode` - the request itself failed, see `errorCode`.

## Path & query parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `api-version` | header | string | yes | Default: `1.0` |

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phoneNumber` | string |  | Phone number to verify, in international format (e.g. `+5215512345678`). When present it takes precedence over any phone number already known for the session. When absent the session phone is used, see the endpoint description. |

## Responses

### 200

OK

Response body (`application/json`):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean |  | `true` when an SNA check was started and `checkUrl` must be opened on the device. |
| `method` | string |  | Always `SNA`, also when SNA could not be used; read `fallbackReason` to detect the fall back to SMS OTP. Absent when the request failed with `INITIATION_ERROR`. Enum: `SNA` |
| `checkId` | string |  | Identifier of the SNA check. Send it to `POST /omni/sna/complete` and `GET /omni/sna/status/{checkId}`. Absent when `success` is `false`. |
| `checkUrl` | string |  | URL the device must open over its mobile data connection to prove it owns the number. Absent when `success` is `false`. |
| `status` | string |  | Provider status of the check right after creation. Absent when `success` is `false`. Enum: `ACCEPTED`, `PENDING` |
| `message` | string |  | Human readable outcome, for logging. Not meant to be shown to the end user. |
| `requiresUserAction` | boolean |  | Reserved. Currently always `false`; decide on `success` and `checkUrl` instead. |
| `fallbackReason` | string |  | Present, with `success: false`, when SNA could not be used for this number and the client must continue with SMS OTP. Examples: `SNA disabled in organization settings`, `SNA disabled in phone configuration`, `SNA not supported for this network`, `SIM recently swapped - security measure`, `PhoneCheck initiation failed`. |
| `phoneNumber` | string |  | Phone number that was resolved and stored on the session, in international format. Absent when the request failed with `errorCode`. |
| `phoneSource` | string |  | Where `phoneNumber` came from. `USER_INPUT` when it was sent in the request body; otherwise the session source that provided it. Absent when the request failed with `errorCode`. Enum: `USER_INPUT`, `SESSION_PHONE`, `CUSTOM_FIELD`, `FORM_ANSWER`, `LOGIN_HINT` |
| `errorCode` | string |  | Present, with `success: false`, when the request itself failed. `PHONE_REQUIRED`: no phone in the body and none could be resolved from the session, show the phone capture screen. `INVALID_PHONE`: the phone number could not be parsed. `INTERVIEW_NOT_FOUND`: the session token does not match an existing session. `INITIATION_ERROR`: unexpected server error, retry or fall back to SMS OTP. Enum: `PHONE_REQUIRED`, `INVALID_PHONE`, `INTERVIEW_NOT_FOUND`, `INITIATION_ERROR` |

## Code samples

Generated from this endpoint's method, path, and the conventional Incode headers. The base URL is the Incode demo environment; replace `<YOUR_API_KEY>` with a key for your region.

### cURL

```bash
curl -X POST https://demo-api.incodesmile.com/omni/sna/initiate \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "X-Incode-Hardware-Id: <YOUR_INCODE_HARDWARE_ID>" \
  -H "api-version: 1.0" \
  -H "Content-Type: application/json"
```

### Node

```js
const res = await fetch("https://demo-api.incodesmile.com/omni/sna/initiate", {
  method: "POST",
  headers: {
      "x-api-key": "<YOUR_API_KEY>",
      "X-Incode-Hardware-Id": "<YOUR_INCODE_HARDWARE_ID>",
      "api-version": "1.0",
      "Content-Type": "application/json",
  },
});
const data = await res.json();
```

### Python

```python
import requests

headers = {
    "x-api-key": "<YOUR_API_KEY>",
    "X-Incode-Hardware-Id": "<YOUR_INCODE_HARDWARE_ID>",
    "api-version": "1.0",
    "Content-Type": "application/json",
}
res = requests.post("https://demo-api.incodesmile.com/omni/sna/initiate", headers=headers)
data = res.json()
```

### Java

```java
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://demo-api.incodesmile.com/omni/sna/initiate"))
    .header("x-api-key", "<YOUR_API_KEY>")
    .header("X-Incode-Hardware-Id", "<YOUR_INCODE_HARDWARE_ID>")
    .header("api-version", "1.0")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
```

### Ruby

```
require "net/http"
require "json"

uri = URI("https://demo-api.incodesmile.com/omni/sna/initiate")
req = Net::HTTP::Post.new(uri)
req["x-api-key"] = "<YOUR_API_KEY>"
req["X-Incode-Hardware-Id"] = "<YOUR_INCODE_HARDWARE_ID>"
req["api-version"] = "1.0"
req["Content-Type"] = "application/json"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
```

### PHP

```
$ch = curl_init("https://demo-api.incodesmile.com/omni/sna/initiate");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: <YOUR_API_KEY>",
    "X-Incode-Hardware-Id: <YOUR_INCODE_HARDWARE_ID>",
    "api-version: 1.0",
    "Content-Type: application/json",
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);
```

### Example response

```json
{
  "success": true,
  "method": "SNA",
  "checkId": "string",
  "checkUrl": "string",
  "status": "ACCEPTED",
  "message": "string",
  "requiresUserAction": true,
  "fallbackReason": "string",
  "phoneNumber": "string",
  "phoneSource": "USER_INPUT",
  "errorCode": "PHONE_REQUIRED"
}
```
