Form Screens - frankieone

Overview

The Form module consists of 13 screens that guide users through the verification flow. Each screen emits events following a consistent naming pattern.

Event Naming Convention

All screen events follow the pattern:

form:{screen_id}:{stage}

For example: form:welcome:ready, form:review:success, form:result:pending

Event Stages

Stage	Description	Emitted By
`ready`	User pressed the screen’s CTA (call-to-action) button, completing the screen	All screens
`loaded`	Screen has been rendered and is interactive	All screens
`failed`	Screen failed to load or an error occurred	All screens (except result — see below)
`success`	CTA pressed on a SUCCESS-state result screen, or verification succeeded (review with `customResult` only)	review, result, doc_upload
`partial`	CTA pressed on a PARTIAL-state result screen, or partial verification result (review with `customResult` only)	review, result
`pending`	CTA pressed on a PENDING-state result screen, or verification pending (review with `customResult` only)	review, result
`back`	User navigated back from screen	document
`navigate`	User navigated to another screen	document, doc_upload

Event Payload

All screen events emit an EventPayload object:

{
  componentName?: string;     // Module name
  provider?: string;          // Provider name ('react')
  inputInfo: {
    name?: string;            // Screen ID (e.g., 'welcome', 'review')
    type?: string;            // Config type ('ocr', 'manual', 'doc_upload')
    documentType?: string;    // Document type if applicable
    index?: number;           // Document index if applicable
  }
}

Screen Reference

All examples below assume the SDK has been initialized:

const sdk = await OneSdk({
  session: { token: 'your-token' },
  recipe: {
    form: {
      provider: {
        name: 'react',
        googleApiKey: 'your-google-api-key'
      }
    }
  }
});

Welcome

The first screen shown to users. Introduces the verification process and provides a call-to-action to begin. Screen ID: welcome Events:

Event	Description
`form:welcome:ready`	User pressed the CTA on the welcome screen
`form:welcome:loaded`	Welcome screen has been rendered
`form:welcome:failed`	Welcome screen failed to load

Example:

const welcome = sdk.component('form', {
  name: 'WELCOME',
  type: 'manual'
});

welcome.on('form:welcome:loaded', (payload) => {
  console.log('Welcome screen shown');
});

await welcome.mount('#form-container');

Start

Entry point screen for certain flows. Allows configuration of the initial verification step. Screen ID: start Events:

Event	Description
`form:start:ready`	User pressed the CTA on the start screen
`form:start:loaded`	Start screen has been rendered
`form:start:failed`	Start screen failed to load

Collects user consent for identity verification and data processing. Screen ID: consent Events:

Event	Description
`form:consent:ready`	User accepted consent and pressed the CTA
`form:consent:loaded`	Consent screen has been rendered
`form:consent:failed`	Consent screen failed to load

Example:

const consent = sdk.component('form', {
  name: 'CONSENT',
  type: 'manual'
});

consent.on('form:consent:loaded', (payload) => {
  console.log('Consent screen displayed');
});

await consent.mount('#form-container');

Document Selection

Allows users to select which identity document(s) they want to use for verification (e.g., driver’s licence, passport, national ID, Medicare card). Used in manual and doc_upload flows.

In OCR mode, the Document Selection screen is a legacy feature tied to headless OCR flows. Modern integrations use the IDV flow for document capture and the form Review screen to display extracted data.

Screen ID: document Supported Document Types:

DRIVERS_LICENCE - Driver’s licence
PASSPORT - Passport
NATIONAL_ID - National identity card
NATIONAL_HEALTH_ID - National health ID / Medicare card

Events:

Event	Description
`form:document:ready`	User completed document selection and pressed the CTA
`form:document:loaded`	Document selection screen has been rendered
`form:document:failed`	Document selection screen failed to load
`form:document:back`	User navigated back from filling document detail to document selection
`form:document:navigate`	User selected a document and is navigating forward

Example:

const document = sdk.component('form', {
  name: 'DOCUMENT',
  type: 'manual',
  numberOfIDs: 2
});

document.on('form:document:loaded', (payload) => {
  console.log('Document selection screen displayed');
});

document.on('form:document:navigate', (payload) => {
  console.log('User selected:', payload.inputInfo.documentType);
});

await document.mount('#form-container');

Personal Details

Collects personal information such as name, date of birth, and address. Screen ID: personal Events:

Event	Description
`form:personal:ready`	User completed personal details and pressed the CTA
`form:personal:loaded`	Personal details screen has been rendered
`form:personal:failed`	Personal details screen failed to load

Example:

const personal = sdk.component('form', {
  name: 'PERSONAL',
  type: 'manual'
});

personal.on('form:personal:loaded', (payload) => {
  console.log('Personal details form displayed');
});

await personal.mount('#form-container');

Review

Displays collected data for user review before submission. In manual mode with verify: true, submits the data for verification and navigates to the appropriate result screen automatically. When customResult: true is also set, the form emits review-level result events instead of navigating to result screens, giving you full control over result handling. Screen ID: review Events:

Event	Description
`form:review:ready`	User pressed the CTA on the review screen
`form:review:loaded`	Review screen has been rendered
`form:review:failed`	Entity doesn’t pass verification
`form:review:success`	Verification completed successfully
`form:review:partial`	Partial match — some data verified, some needs attention
`form:review:pending`	Verification submitted but result is pending

form:review:failed/success/partial/pending require customResult: true in manual mode.These four events are only emitted when customResult: true is set on the review component in manual mode. When customResult is false (the default), the form automatically navigates to the configured result screen — these review-level result events are not emitted. In OCR mode, the only review event is form:review:ready.See verify and customResult in the configuration reference.

Example (with customResult: true):

const review = sdk.component('form', {
  name: 'REVIEW',
  type: 'manual',
  verify: true,
  customResult: true
});

review.on('form:review:loaded', (payload) => {
  console.log('Review screen displayed');
});

review.on('form:review:success', (payload) => {
  console.log('Verification passed — show custom success UI');
});

review.on('form:review:partial', (payload) => {
  console.log('Partial match — show retry or custom UI');
});

review.on('form:review:pending', (payload) => {
  console.log('Verification pending — show custom pending UI');
});

review.on('form:review:failed', (payload) => {
  console.log('Verification failed — show custom failure UI');
});

await review.mount('#form-container');

Loading

Displayed while verification is being processed. Screen ID: loading This screen is managed internally by the form module and typically does not require event handling.

Result

Displays the final verification result to the user. Shows success, failure, partial match, or pending status. Screen ID: result Result States:

State	Description
`SUCCESS`	Verification passed
`FAIL`	Verification failed
`PENDING`	Verification pending manual review
`PARTIAL`	Partial match - some checks passed
`UPLOAD_SUCCESS`	Document upload completed
`UPLOAD_FAIL`	Document upload failed
`PROVIDER_ERROR`	Provider encountered an error
`TIMEOUT`	Verification attempt timed out

Events:

Event	Description
`form:result:ready`	User pressed the CTA on the result screen
`form:result:loaded`	Result screen has been rendered
`form:result:failed`	User pressed the CTA on a FAIL-state result screen
`form:result:success`	User pressed the CTA on a SUCCESS-state result screen
`form:result:partial`	User pressed the CTA on a PARTIAL-state result screen
`form:result:pending`	User pressed the CTA on a PENDING-state result screen
`form:result:timeout`	User pressed the CTA on a TIMEOUT-state result screen
`form:result:info`	Informational, non-fatal event. Emitted when a custom `resultImage` fails to load, just before the screen falls back to the default state icon.

Example:

const resultSuccess = sdk.component('form', {
  name: 'RESULT',
  type: 'manual',
  state: 'SUCCESS',
  title: { label: 'Complete' },
  descriptions: [{ label: 'Process is now complete.' }],
  cta: { label: 'Done' }
});

resultSuccess.on('form:result:success', (payload) => {
  console.log('User dismissed the success screen');
});

await resultSuccess.mount('#form-container');

Retry

Shown when verification returns a partial result and the user can retry. Allows re-entry of data that failed verification and intelligently adapts the retry flow based on the type of failure. Screen ID: retry Events:

Event	Description
`form:retry:loaded`	Retry screen mounted
`form:retry:ready`	User completed the retry form
`form:retry:failed`	Retry screen failed to load

Example:

const retry = sdk.component('form', {
  name: 'RETRY',
  type: 'manual'
});

retry.on('form:retry:loaded', (payload) => {
  console.log('Retry screen displayed - user can correct data');
});

await retry.mount('#form-container');

Smart Retry Behavior

The Retry screen intelligently adapts based on the type of verification failure. When verification returns a partial match, the SDK analyzes the failure type and presents the appropriate retry flow.

Previous Address Request

Triggered when: Verification returns a partial alert on personal details (e.g., address could not be confirmed against records).What happens: The Retry screen displays the personal details form with an additional toggle asking “Have you been at your current residential address for less than 6 months?” When the user enables this toggle, a previous address field appears prompting them to enter their prior residential address.Purpose: Helps resolve address verification failures by providing additional residential history that the verification provider can use to confirm the user’s identity.

Additional ID Request

Triggered when: Primary ID verification fails with a 404 alert (e.g., the submitted document could not be verified against records).What happens: The Retry screen displays additional document types that have not been submitted yet, prompting the user to select and fill in an alternative form of ID. Documents already submitted are filtered out from the selection list.Purpose: Provides a fallback path when the initial document cannot be verified, allowing the user to supply a different identity document for verification.

Retry Flow:

Initial verification is submitted from the Review screen
Verification returns a partial result (via partial or 404 alert)
The SDK determines the failure type: personal details failure (VERIFICATION_FAILED_IDS.NAME) or document failure (VERIFICATION_FAILED_IDS.ID)
The Retry screen presents the appropriate fields based on the failure type
The user provides additional information (previous address or alternative ID)
The flow transitions to the Review screen for re-submission

Example with retry limit:

const retry = sdk.component('form', {
  name: 'RETRY',
  type: 'manual'
});

const resultFail = sdk.component('form', {
  name: 'RESULT',
  type: 'manual',
  state: 'FAIL',
  title: { label: 'Max attempts reached' },
  descriptions: [
    { label: 'You have reached the maximum number of attempts.' }
  ],
  cta: { label: 'Close' }
});

let retryCount = 0;

// Fires when user presses CTA on PARTIAL result screen
review.on('form:result:partial', async () => {
  if (retryCount < 2) {
    retry.mount('#form-container');
    retryCount += 1;
  } else {
    resultFail.mount('#form-container');
  }
});

retry.on('form:retry:loaded', (payload) => {
  console.log('Retry screen displayed - attempt', retryCount);
});

Document Upload

Main document upload screen for uploading supporting documents. Screen ID: doc_upload Events:

Event	Description
`form:doc_upload:ready`	User pressed the CTA on the upload screen
`form:doc_upload:loaded`	Upload screen has been rendered
`form:doc_upload:success`	Document uploaded successfully
`form:doc_upload:failed`	Document upload failed
`form:doc_upload:navigate`	User navigated from upload screen

Example:

const docUpload = sdk.component('form', {
  name: 'DOC_UPLOAD',
  type: 'doc_upload'
});

docUpload.on('form:doc_upload:success', (payload) => {
  console.log('Document uploaded successfully');
});

docUpload.on('form:doc_upload:failed', (payload) => {
  console.log('Upload failed');
});

await docUpload.mount('#form-container');

Required Document Upload

Displays documents that are required for verification and must be uploaded. Screen ID: required_document_upload Events:

Event	Description
`form:required_document_upload:ready`	User completed required uploads and pressed the CTA
`form:required_document_upload:loaded`	Required upload screen has been rendered
`form:required_document_upload:failed`	Required upload screen failed to load

Partial Document Upload

Displays a list of documents where a minimum number must be uploaded (e.g., “upload at least 2 of these 4 documents”). Screen ID: partial_document_upload Events:

Event	Description
`form:partial_document_upload:ready`	User completed partial uploads and pressed the CTA
`form:partial_document_upload:loaded`	Partial upload screen has been rendered
`form:partial_document_upload:failed`	Partial upload screen failed to load

Optional Document Upload

Displays optional documents that users can upload to strengthen their verification. Screen ID: optional_document_upload Events:

Event	Description
`form:optional_document_upload:ready`	User completed optional uploads and pressed the CTA
`form:optional_document_upload:loaded`	Optional upload screen has been rendered
`form:optional_document_upload:failed`	Optional upload screen failed to load

Typical Screen Flow

OCR Flow (with IDV)

[IDV Capture] → Review (type: 'ocr') → Result

The IDV flow handles document capture. The form module provides the Review screen to display extracted data for user confirmation.

Manual Flow

Welcome → Consent → Personal Details → Document Selection → Review → Loading → Result → [Retry if failed]

Document Upload Flow

Welcome → Consent → Required Uploads → Partial Uploads → Optional Uploads → Review → Result

Screen-Level Event Listening Example

const sdk = await OneSdk({
  session: { token: 'your-token' },
  recipe: {
    form: {
      provider: {
        name: 'react',
        googleApiKey: 'your-google-api-key'
      }
    }
  }
});

const formComponent = sdk.component('form', {
  name: 'WELCOME',
  mode: 'individual',
  type: 'manual'
});

// Track every screen transition
const screens = [
  'welcome', 'start', 'consent', 'document',
  'personal', 'review', 'loading', 'result', 'retry',
  'doc_upload', 'required_document_upload',
  'partial_document_upload', 'optional_document_upload'
];

screens.forEach(screen => {
  formComponent.on(`form:${screen}:ready`, (payload) => {
    console.log(`[${screen}] ready`);
  });

  formComponent.on(`form:${screen}:loaded`, (payload) => {
    console.log(`[${screen}] loaded`);
  });

  formComponent.on(`form:${screen}:failed`, (payload) => {
    console.error(`[${screen}] failed`);
  });
});

// Handle verification outcomes
// Review-level result events (only with customResult: true in manual mode)
formComponent.on('form:review:success', () => {
  console.log('Verification passed — handle custom result UI');
});

// Result screen CTA events (fired when user presses CTA on result screens)
formComponent.on('form:result:success', () => {
  console.log('User pressed CTA on SUCCESS result screen');
});

formComponent.on('form:result:partial', () => {
  console.log('User pressed CTA on PARTIAL result screen');
});

formComponent.on('form:result:pending', () => {
  console.log('User pressed CTA on PENDING result screen');
});

await formComponent.mount('#form-container');

​Overview

​Event Naming Convention

​Event Stages

​Event Payload

​Screen Reference

​Welcome

​Start

​Consent

​Document Selection

​Personal Details

​Review

​Loading

​Result

​Retry

​Smart Retry Behavior

​Document Upload

​Required Document Upload

​Partial Document Upload

​Optional Document Upload

​Typical Screen Flow

​OCR Flow (with IDV)

​Manual Flow

​Document Upload Flow

​Screen-Level Event Listening Example

​Related

Overview

Event Naming Convention

Event Stages

Event Payload

Screen Reference

Welcome

Start

Consent

Document Selection

Personal Details

Review

Loading

Result

Retry

Smart Retry Behavior

Document Upload

Required Document Upload

Partial Document Upload

Optional Document Upload

Typical Screen Flow

OCR Flow (with IDV)

Manual Flow

Document Upload Flow

Screen-Level Event Listening Example

Related