API reference, Phone number input

Initiate Silent Network Authentication (SNA)

POSThttps://demo-api.incodesmile.com/omni/sna/initiate

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.

Headers

api-versionstringrequiredDefaults to 1.0

Request body

application/json

phoneNumberstring

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

Response body (application/json)

successboolean

`true` when an SNA check was started and `checkUrl` must be opened on the device.

methodstring

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`.

enumSNA
checkIdstring

Identifier of the SNA check. Send it to `POST /omni/sna/complete` and `GET /omni/sna/status/{checkId}`. Absent when `success` is `false`.

checkUrlstring

URL the device must open over its mobile data connection to prove it owns the number. Absent when `success` is `false`.

statusstring

Provider status of the check right after creation. Absent when `success` is `false`.

enumACCEPTEDPENDING
messagestring

Human readable outcome, for logging. Not meant to be shown to the end user.

requiresUserActionboolean

Reserved. Currently always `false`; decide on `success` and `checkUrl` instead.

fallbackReasonstring

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`.

phoneNumberstring

Phone number that was resolved and stored on the session, in international format. Absent when the request failed with `errorCode`.

phoneSourcestring

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`.

enumUSER_INPUTSESSION_PHONECUSTOM_FIELDFORM_ANSWERLOGIN_HINT
errorCodestring

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.

enumPHONE_REQUIREDINVALID_PHONEINTERVIEW_NOT_FOUNDINITIATION_ERROR