Phone

The Phone module collects a user's phone number and can confirm phone ownership by sending a one-time password (OTP) via SMS. With Silent Network Authentication (SNA), the module can confirm the number through the mobile network, without an SMS.

For an overview of this module and how it works, see Phone Number Input.

How you use this module depends on your integration pattern. In Patterns 1 and 2, you add the module to a FlowConfig in code as shown on this page. In Pattern 3, you define your modules and configuration in Dashboard as a Flow or Workflow and reference it by ID with startFlow() or startWorkflow() as shown on Run Flows Configured in Dashboard.

Add Phone

1. Add the module with addPhone() (default config) or addPhone(phone) (custom config):

flowConfigBuilder.addPhone()
// or with a configured instance:
flowConfigBuilder.addPhone(phone)

flowConfigBuilder.addPhone();
// or with a configured instance:
flowConfigBuilder.addPhone(phone);

2. If your flow also uses the AES (Advanced Electronic Signature) module, add it after Phone. AES requires Phone, along with ID Scan and Selfie Scan, to run first.

Phone ships both a v1 (legacy View) and a v2 (Jetpack Compose) capture screen; the active one depends on your Incode configuration. Contact your Incode representative to enable v2.

Example

The example below builds a Phone module with OTP verification enabled, adds it to the flow, and listens for the result through onAddPhoneCompleted().

val phone = Phone.Builder()
    .setOtpVerificationEnabled(true)
    .build()

val flowConfig = FlowConfig.Builder()
    .addPhone(phone)
    .build()

val onboardingListener = object : OnboardingListener() {
    override fun onAddPhoneCompleted(phoneNumberResult: PhoneNumberResult) {
        // Phone number captured. Process the result.
    }
}

IncodeWelcome.getInstance()
    .startOnboarding(activityContext, sessionConfig, flowConfig, onboardingListener)

Phone phone = new Phone.Builder()
    .setOtpVerificationEnabled(true)
    .build();

FlowConfig flowConfig = new FlowConfig.Builder()
    .addPhone(phone)
    .build();

IncodeWelcome.OnboardingListener onboardingListener = new IncodeWelcome.OnboardingListener() {
    @Override
    public void onAddPhoneCompleted(@NonNull PhoneNumberResult phoneNumberResult) {
        // Phone number captured. Process the result.
    }
};

IncodeWelcome.getInstance()
    .startOnboarding(activityContext, sessionConfig, flowConfig, onboardingListener);

Configuration Options

Configure the module with Phone.Builder. The table below lists the available options.

For the complete option set, see Phone.Builder in API Reference.

Enable Silent Network Authentication

Silent Network Authentication (SNA) is a phone number verification method that authenticates users through their mobile network using real-time carrier signals. You can enable SNA for the Phone module. SNA is only available in Flows in Dashboard, not Workflows.

1. Use Android SDK version 5.50.0 or higher. There is no separate -sna variant. No additional Maven repository or credentials are required.
2. In a Flow in Dashboard, turn on Enable SNA verification in the Phone Number Input module.
3. Start the onboarding flow using one of the following approaches:

   • startFlow: Specify configurationId inside SessionConfig.Builder().setConfigurationId(), and provide it as sessionConfig to startFlow.

     The Flow configuration drives SNA; no additional code is required.

   • startOnboarding or Sections (where your app builds the FlowConfig: Specify configurationId inside SessionConfig.Builder().setConfigurationId(), and provide it as sessionConfig to startOnboarding or setupOnboardingSession. Then pass the Phone module in your FlowConfig. For Sections, call startOnboardingSection with that Phone module.

     The Flow configuration enables SNA; there is no client-side API to turn it on.

Result

Phone delivers a PhoneNumberResult to the onAddPhoneCompleted(PhoneNumberResult) callback on the OnboardingListener. Key fields include:

• phone: The phone number captured from the user or verified by SNA; null when unavailable, for example when SNA could not verify the number and OTP is off.
• Fields inherited from BaseResult:
  • resultCode: The ResultCode for this result.
  • error: The Throwable associated with the result, or null if there is none.
    • ERROR result: The Throwable that caused the failure.
    • SUCCESS result: null in most cases. It is non-null in two situations:
      • OTP is on, and the organization is limited and not permitted to send or check the code: The Throwable that describes the refusal. The phone number was collected but not verified.
      • SNA could not verify the number, and OTP is off: An IncodeGenericError. In this case, phone is null.
  • deviceStats: The DeviceStats snapshot of the device state when the result was produced.
  • motionStatus: Device motion assessment during capture. One of the following:
    • UNCLEAR: Motion could not be determined; the default.
    • PASS: Device motion was within acceptable limits.
    • FAIL: Excessive device motion was detected.

Errors surface through OnboardingListener.onError(Throwable). This module does not deliver a module-specific exception subtype.

For all fields, see PhoneNumberResult in the Android API Reference.