# Configure Flows Locally and Run Step by Step

Use the Sections API when your app needs custom screens or business logic between SDK modules. You create an onboarding session, split the flow into sections, and run each section with `startOnboardingSection()`. Control returns to your host application between sections, so you can show your own screens, make decisions, or call your backend before continuing.

Use this pattern when the default flow approach does not give you enough control - for example, when you need to interleave your own UI between capture steps, or group modules into logical sections.

> **Before you start**
>
> Make sure the SDK is installed and initialized. See [Getting Started](../react-native-getting-started/index.md) for setup and initialization.

The common path is four steps: set up the onboarding session, register step listeners if you want per-step results, configure and start each section, and finish the session when all sections are complete.

### Set up an onboarding session

`sessionConfig` is optional for `setupOnboardingSession()`. If you don't need to customize the session, you can omit it.

❗{/* [SME input needed: source-level review confirmed that an empty or omitted `sessionConfig` is valid (every field is optional), but per-field default values are not documented anywhere in the SDK. Confirm defaults for each field so customers know what they're getting when they omit it. Escalation candidate: needs product/SDK-team knowledge.] */}

```ts
const session = await IncodeSdk.setupOnboardingSession({
  sessionConfig: {
    externalId: 'external-id',
  },
});

console.log(session.interviewId, session.token);
```

Useful `sessionConfig` fields include:

| Field                               | Use                                                                                                                                |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `queue`                             | Assign the session to a queue.                                                                                                     |
| `interviewId` / `token`             | Start from a backend-created session, or resume an existing session (see below).                                                   |
| `configurationId`                   | Apply a Dashboard flow configuration.                                                                                              |
| `externalId` / `externalCustomerId` | Link the Incode session to your own user/customer ID.                                                                              |
| `validationModules`                 | Select server-side validation modules.                                                                                             |
| `customFields`                      | Attach custom string data.                                                                                                         |
| `e2eEncryptionEnabled`              | Enable E2EE for the session. See [End-to-End Encryption](../react-native-getting-started/react-native-e2ee.md) for the full setup. |
| `mergeSessionRecordings`            | Merge ID and Face recordings.                                                                                                      |
| `voiceConsentLanguage`              | Set `VideoSelfie` voice consent language: `en`, `es`, `pt`, or `he`.                                                               |

Available validation modules:

- `id`
- `liveness`
- `faceRecognition`
- `governmentValidation`
- `governmentFaceValidation`
- `governmentOcrValidation`
- `videoSelfie`

Default validation modules are `id`, `liveness`, and `faceRecognition`.

#### Resume an existing onboarding session

To continue an existing onboarding session (for example, one created by your backend), pass the existing `token` or `interviewId` to `setupOnboardingSession()`:

```ts
const session = await IncodeSdk.setupOnboardingSession({
  sessionConfig: {
    token: 'YOUR_TOKEN',
  },
});
```

### Register step listeners

If you want to react to individual modules as they complete, register listeners before starting any sections. If you only need section-level outcomes, you can rely on the value returned by `startOnboardingSection()` and skip this step.

```ts
const unsubscribers = [
  IncodeSdk.onSessionCreated((session) => {
    console.log(session.interviewId);
  }),
  IncodeSdk.onStepCompleted({
    module: 'IdScanFront',
    listener: (event) => console.log(event.result),
  }),
  IncodeSdk.onStepCompleted({
    module: 'IdScanBack',
    listener: (event) => console.log(event.result),
  }),
  IncodeSdk.onStepCompleted({
    module: 'ProcessId',
    listener: (event) => console.log(event.result.extendedOcrData),
  }),
  IncodeSdk.onStepCompleted({
    module: 'SelfieScan',
    listener: (event) => console.log(event.result),
  }),
  IncodeSdk.onStepCompleted({
    module: 'FaceMatch',
    listener: (event) => console.log(event.result),
  }),
];
```

Call each unsubscriber when the screen unmounts:

```ts
React.useEffect(() => {
  const unsubscribers = setupListeners();

  return () => {
    unsubscribers.forEach((unsubscriber) => unsubscriber());
  };
}, []);
```

For the shape and fields of each result object passed to these listeners, see [Results](../react-native-results.md).

### Configure section flow

```ts
const idSectionConfig = {
  sectionTag: 'idSection',
  flowConfig: [{ module: 'IdScan' }],
};
```

`startOnboardingSection` accepts the same `flowConfig` shape and modules as `startOnboarding`. See [Modules](../react-native-modules.md) for the catalog and per-module configuration parameters.

Some modules depend on the output of other modules and must appear after them in the `flowConfig` array:

- `FaceMatch` should follow `IdScan` and `SelfieScan`.
- `ProcessId` should follow `IdScanFront` and `IdScanBack`.
- `VideoSelfie` should follow `IdScan` (in `faceMatch` mode) or `SelfieScan` (in `selfieMatch` mode).
- `Aes` should follow `Phone`, `IdScan`, and `SelfieScan`.
- `UserScore` and `Approve` should be at the end.

❗{/* [SME input needed: source-level review couldn't confirm whether module dependencies (like FaceMatch requiring IdScan and SelfieScan to have run) work across sections, or only within a single section. Confirm expected behavior. Escalation candidate: needs product/SDK-team knowledge or native-side testing.] */}

### Start onboarding section

`startOnboardingSection()` resolves with a result indicating whether the section succeeded (`status` is `success` or `userCancelled`). Use the result to decide what to do next, including running your own logic before starting the next section.

```ts
const idSection = await IncodeSdk.startOnboardingSection(idSectionConfig);

if (idSection.status === 'success') {
  await IncodeSdk.startOnboardingSection({
    sectionTag: 'selfieSection',
    flowConfig: [{ module: 'SelfieScan' }],
  });
}
```

You can start multiple sections, but only one at a time. Wait for each `startOnboardingSection()` call to resolve before starting the next.

Optionally, specify `sectionTag` to uniquely identify the section; use it to distinguish sections in listener events or logs.

### Finish onboarding session

```ts
await IncodeSdk.finishOnboardingFlow();
```

❗{/* [SME input needed: source-level review confirmed the rule that `UserScore` and `Approve` must go last in a flow, but couldn't confirm whether `Conference` has a similar ordering constraint (i.e., must `finishOnboardingFlow()` be called before or after a Conference module runs?). Confirm expected sequencing. Escalation candidate: needs product/SDK-team knowledge.] */}

To clean up local user data generated during the session, call `deleteLocalUserData()`. See [Delete Local Session Data](../react-native-getting-started/react-native-delete-local-session-data.md) for details.

## Related pages

- [Configure Flows Locally and Run End to End](react-native-configure-flows-locally-and-run-end-to-end.md): configure a single full flow locally and run it in one call.
- [Run Flows Configured Online](react-native-run-flows-configured-online.md): define the flow on the Dashboard instead of in code.
- [Modules](../react-native-modules.md): the module catalog and per-module configuration parameters.
- [Results](../react-native-results.md): result and error objects returned by listeners and section calls.
- [Common Implementation Patterns](index.md): choose the integration pattern that fits your app.
- [API Reference](../react-native-api-reference.md): full API specification.

<br />