# Introduction to OneSDK
Source: https://docs.frankieone.com/docs/about-onesdk

OneSDK is a powerful client-side JavaScript library that simplifies customer onboarding by integrating FrankieOne’s KYC (Know Your Customer) and IDV (Identity Verification) services directly into your application.

## What is OneSDK?

OneSDK is FrankieOne’s client-side JavaScript SDK that enables fast, flexible, and secure integration of KYC and Identity Verification (IDV) services into your digital onboarding experience.

It allows you to embed verification workflows directly into your product — whether through a hosted page, an iFrame, or a fully embedded integration inside your own app.

OneSDK connects your frontend to FrankieOne’s orchestration platform, giving you access to a wide ranges of global verification vendors and data sources through a single, unified SDK and API.

## Why Choose OneSDK?

<CardGroup>
  <Card title="Fast Deployments with Pre-built Flows" icon="puzzle-piece">
    Pre-built templates, modular components, and straightforward APIs help you launch verification experiences quickly and reliably.
  </Card>

  <Card title="Unified Verification Layer for KYC and IDV" icon="building">
    Access multiple vendors through FrankieOne’s orchestration layer, enabling seamless identity checks across document, biometric, and AML workflows.
  </Card>

  <Card title="Vendor-Agnostic and Future-Proof" icon="rocket">
    Easily switch, mix, or expand vendors without refactoring your code, ensuring long-term flexibility as your business and regulatory needs evolve.
  </Card>

  <Card title="Built-in Compliance and Observability" icon="shield-check">
    Gain end-to-end visibility with detailed event logs, audit trails, and analytics — all designed to maintain compliance and monitor performance with confidence.
  </Card>
</CardGroup>

## Core Components

<Tabs>
  <Tab title="Modules">
    <CardGroup>
      <Card title="Document Verification" icon="id-card">
        Capture and verify identity documents like passports, driver's licenses, and national ID cards.
      </Card>

      <Card title="Biometric Verification" icon="fingerprint">
        Implement face matching and liveness detection for enhanced security.
      </Card>

      <Card title="Fraud Detection" icon="shield-halved">
        Detect and prevent fraud through advanced risk assessment algorithms.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Workflows">
    A OneSDK workflow is a carefully orchestrated sequence of modules that work together to verify a user comprehensively. This approach provides you with a unified view of the onboarded entity.
  </Tab>
</Tabs>

## When to Use OneSDK?

Use OneSDK whenever you want to deliver a smooth, compliant, and customisable verification experience without building vendor integrations or UI from scratch.

For most businesses, Pre-Built Hosted Flows are the recommended starting point — fast to deploy, fully managed, and easily customised through the FrankieOne Portal or API.

## How does OneSDK Work?

A OneSDK integration connects your client application to the FrankieOne API and multiple verification vendors in one seamless flow.

<Steps>
  <Step title="Initialize OneSDK">
    The user starts verification from your app or link.
  </Step>

  <Step title="Capture Data">
    OneSDK handles document capture, biometrics, and form input securely in the browser.
  </Step>

  <Step title="Orchestrate Verification">
    FrankieOne orchestrates verification across connected vendors.
  </Step>

  <Step title="Return Results">
    Results are returned to your system via API or webhook.
  </Step>
</Steps>

This approach simplifies integration while maintaining flexibility — you manage the experience, and FrankieOne manages the complexity of vendor connections.

## Integration Options

OneSDK supports a range of integration approaches depending on your technical capability and UX goals.

<Callout icon="thumbtack">
  For most customers, Pre-built Hosted Flows are the fastest and most reliable way to go live — allowing you to start verifying customers in hours, not weeks.
</Callout>

| Category                   | Pre-Built Hosted Flows                                | Custom Hosted Flows                                  | Embedded Components                              | API-Only (No SDK)               |
| :------------------------- | :---------------------------------------------------- | :--------------------------------------------------- | :----------------------------------------------- | :------------------------------ |
| **Integration Effort**     | 🔵⚪️⚪️⚪️<br />No Code (Portal Only) / Single API Call | 🔵🔵⚪️⚪️<br />Some coding required                   | 🔵🔵🔵🔵<br />Most Coding (Frontend Development) | 🔵🔵🔵🔵<br />Highest           |
| **Branding Control**       | 🎨🎨<br />Logo, fonts and colours                     | 🎨🎨🎨<br />More customization                       | 🎨🎨🎨🎨<br />Extensive control                  | 🎨🎨🎨🎨<br />Extensive control |
| **Typical Time to Market** | 🚀 Within days                                        | 🚄 Usually 3-6 weeks                                 | 🚢 2 months+ subject to requirements             | Depending on requirements       |
| **Hosting**                | FrankieOne Hosted                                     | FrankieOne Hosted                                    | Your Site                                        | N/A                             |
| **Costs**                  | Monthly Hosting Fee                                   | Once-off Implementation Fee plus Monthly Hosting Fee | Once-off Implementation Fee                      | Refer to API Cost Models        |

As your requirements grow, you can easily evolve toward Custom Hosted or Embedded OneSDK integrations for deeper branding or in-app experiences.

## Best Practices

<Callout icon="star">
  ##### Optimization Tips

  * Initialize OneSDK as early as possible in your app lifecycle.
  * Implement proper error handling for each verification step.
  * Use the testing environment for development and integration.
  * Monitor verification analytics to optimize your conversion rates.
</Callout>

<Callout icon="bell">
  ##### Important Considerations

  * Always handle user consent appropriately.
  * Implement proper session management.
  * Store sensitive data securely.
  * Follow data privacy regulations in your region.
</Callout>

## Next Steps

<CardGroup>
  <Card title="Quick Start" icon="play" href="/docs/quickstart-guide">
    Get up and running with OneSDK in minutes.
  </Card>

  <Card title="API Reference" icon="book" href="/docs/reference/whats-new">
    Review detailed API documentation and examples.
  </Card>

  <Card title="Use Cases" icon="lightbulb" href="/docs/embedded-flows/overview">
    Explore common implementation scenarios.
  </Card>
</CardGroup>


# AML Screening & Monitoring
Source: https://docs.frankieone.com/docs/anti-money-laundering



Learn how FrankieOne's AML solution helps you screen against global watchlists, manage risk, and maintain ongoing compliance.

## What is AML Screening?

Anti-Money Laundering (AML) screening is a critical compliance process for identifying individuals and organizations with connections to financial crime. It involves checking customer data against global watchlists to detect risks related to money laundering, terrorism financing, sanctions violations, and political exposure.

FrankieOne's solution streamlines this process, from initial real-time screening at onboarding to continuous, automated monitoring throughout the customer lifecycle.

***

## How AML Screening Works

Our AML capabilities are integrated directly into the FrankieOne workflow engine.

<Steps>
  <Step title="1. Create an Entity">
    First, you create an `individual` entity containing the customer's personal details, such as their full name, date of birth, and country of residence.
  </Step>

  <Step title="2. Execute a Workflow">
    You then execute a workflow that has been configured with an **AML Step**. Our platform takes the entity's details and screens them against our connected data sources.
  </Step>

  <Step title="3. Receive Actionable Results">
    The workflow returns a clear result for the AML step—typically **`CLEAR`** or **`HIT`**. A `HIT` generates detailed Process Result Objects (PROs) and `issues` for any potential matches, allowing your team to investigate and classify the results.
  </Step>
</Steps>

***

## What We Screen For

Our AML solution checks against a wide array of global sources to provide a comprehensive risk profile.

* **Politically Exposed Persons (PEPs):** Identify individuals who hold prominent public functions and may present a higher risk for bribery or corruption.
* **Sanctions Lists:** Screen against lists of individuals, entities, and countries subject to economic or trade sanctions by governments and international bodies.
* **Adverse Media:** Scan global news sources for negative information linked to an individual that may indicate an elevated risk.
* **Other Regulatory & Law Enforcement Watchlists:** Check against a wide range of official lists to identify potential bad actors.

### Intelligent Matching

To increase accuracy and reduce false positives, our system uses sophisticated matching logic:

* **Name Matching**: Checks against the entity's full name, as well as known aliases.
* **Contextual Filtering**: Uses the entity's **date of birth**, **nationality**, and **country of residence** to filter out irrelevant matches from the screening results.

***

## Classifying AML Hits

When an AML screening results in a `HIT`, your compliance team needs to review the potential matches and classify them. This is a critical step in managing your AML risk.

You can update the status of one or more AML-related Process Result Objects (PROs) using the API.

**Endpoint:**

```http theme={null}
PATCH /v2/individuals/{entityId}/results/aml
```

**Request Body:**

```json theme={null}
{
  "processResults": [
    "pro_01J285FC7DH5G113KF109RJHSD",
    "pro_01J285FC6MDNE7SZPVS8D3GC7S"
  ],
  "manualStatus": "FALSE_POSITIVE",
  "comment": {
    "text": "Reviewed by compliance officer. Matches are for a different individual with a similar name."
  }
}
```

### Manual Status Options (`manualStatus`)

When classifying a hit, you can set one of the following statuses:

| Status                 | Description                                                                                                           |
| :--------------------- | :-------------------------------------------------------------------------------------------------------------------- |
| `FALSE_POSITIVE`       | The match is not the same person you are onboarding.                                                                  |
| `TRUE_POSITIVE`        | The match is the same person, but a final decision has not been made. The hit remains unresolved.                     |
| `TRUE_POSITIVE_ACCEPT` | The match is the same person, and your organization has decided to accept the risk and proceed with the relationship. |
| `TRUE_POSITIVE_REJECT` | The match is the same person, and your organization has decided to reject the relationship.                           |
| `UNKNOWN`              | It is unclear if the match is the same person. The hit remains unresolved.                                            |
| `UNKNOWN_ACCEPT`       | It is unclear if the match is the same person, but your organization has decided to accept the risk.                  |
| `UNKNOWN_REJECT`       | It is unclear if the match is the same person, and your organization has decided to reject the relationship.          |

<Callout icon="thumbtack">
  After classifying hits, it is best practice to re-run the workflow. The AML step will re-evaluate the results based on your classifications. For example, a workflow that initially resulted in a `REVIEW` status due to unresolved hits may change to `PASS` if all hits are classified as `FALSE_POSITIVE`.
</Callout>

***

## Ongoing Monitoring

Meeting your compliance obligations doesn't stop at onboarding. FrankieOne's Ongoing Monitoring feature automates the continuous screening of your customers.

Once enabled, our platform perpetually monitors the entity against our data sources and automatically alerts you by triggering a pre-configured **"monitoring workflow"** if their status changes—for example, if they are added to a sanctions list or become a PEP.

> *For a detailed guide on how to enable, disable, and manage this feature, please refer to our **[Ongoing Monitoring Documentation](/docs/ongoing-monitoring-v2)**.*

***

## Additional Resources

* [Interpreting Workflow Results](/docs/interpreting-workflows-v2)
* [Handling AML Results]()
* [Ongoing Monitoring](/docs/ongoing-monitoring-v2)


# Interpreting AML Screening Results
Source: https://docs.frankieone.com/docs/anti-money-laundering-results



A detailed guide to understanding the results of an AML check, from the high-level summary down to the details of each watchlist match.

## How to Read an AML Result

When you execute a workflow containing an AML step, the API response provides a rich set of data to help you understand the outcome. This guide provides a structured, "top-down" walkthrough of how to parse the `workflowResult` object.

<Accordion title="View Full API Response Example">
  The examples in this guide refer to a workflow execution response where a PEP match was found. Click to expand and see the full structure.

  ```json theme={null}
  {
    "requestId": "01HN9XHZN6MGXM9JXG50K59Q85",
    "workflowResult": {
      "workflowExecutionId": "wfe_01J...",
      "workflowExecutionState": "COMPLETED",
      "status": "REVIEW",
      "result": "REVIEW",
      "riskAssessment": {
          "riskLevel": "HIGH",
          "riskScore": 100,
          "riskFactors": [
              { "factor": "is_pep", "value": "true", "score": 100 }
          ]
      },
      "issues": [
          {
              "category": "AML",
              "issue": "PEP",
              "severity": "WARNING"
          }
      ],
      "workflowStepResults": [
        {
          "stepName": "AML",
          "result": "HIT",
          "summary": {
            "totalHits": 1,
            "totalUnresolved": 1,
            "numUnresolvedPEP": 1
          },
          "processResults": [
            {
              "processResultId": "pro_01J...",
              "result": "HIT",
              "class": "AML",
              "supplementaryData": {
                "type": "AML",
                "matchData": { "name": "John Doe" },
                "pepData": [
                  {
                    "level": "2",
                    "position": "Former Member of Parliament",
                    "countryCode": "AUS"
                  }
                ]
              },
              "manualStatus": "UNRESOLVED"
            }
          ]
        }
      ]
    }
  }
  ```
</Accordion>

***

## Part 1: The Overall Outcome (Final Verdict)

Always start by checking the top-level fields of the `workflowResult` object. These give you the final, authoritative outcome.

| Field                        | Importance | Description                                                                                                             |
| :--------------------------- | :--------- | :---------------------------------------------------------------------------------------------------------------------- |
| **`status`**                 | ‼️         | The conclusive recommendation (e.g., `PASS`, `FAIL`, `REVIEW`). **Base your primary business logic on this value.**     |
| **`workflowExecutionState`** | ‼️         | Confirms the workflow's technical status. **Must be `COMPLETED`**.                                                      |
| **`issues`**                 | ⚠️         | An array of problems that require manual review. If `status` is `REVIEW`, this array contains the specific reasons why. |
| **`riskAssessment`**         | ⚠️         | The final risk profile of the entity, including the `riskLevel` and `riskScore`.                                        |

In the example, the `status` is `REVIEW`, which is directly caused by the `issues` array containing a `PEP` issue.

### Understanding AML Issues

When the AML step finds a potential match, it generates an `issue` object. This is what typically drives the overall workflow `status` to `REVIEW`.

| Category | Issue       | Severity  | Trigger Condition                                           |
| :------- | :---------- | :-------- | :---------------------------------------------------------- |
| `AML`    | `PEP`       | `WARNING` | At least one valid Process Result contains `pepData`.       |
| `AML`    | `SANCTIONS` | `WARNING` | At least one valid Process Result contains `sanctionData`.  |
| `AML`    | `MEDIA`     | `WARNING` | At least one valid Process Result contains `mediaData`.     |
| `AML`    | `WATCHLIST` | `WARNING` | At least one valid Process Result contains `watchlistData`. |

***

## Part 2: The AML Step Result (`workflowStepResults`)

Next, drill down into the `workflowStepResults` array and find the object where `stepName` is **`AML`**. This object contains the specific results of the screening.

| Key Field            | Description                                                                                                                                                                             |
| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`result`**         | The most important field for the step. A `result` of **`HIT`** means at least one potential match was found and requires review. A `result` of **`CLEAR`** means no matches were found. |
| **`summary`**        | An aggregated summary of the screening results, broken down by match type.                                                                                                              |
| **`processResults`** | An array containing the detailed evidence for each individual watchlist match.                                                                                                          |

### The AML Summary Object

The `summary` object gives you a quick, quantitative overview of the screening results.

```json theme={null}
"summary": {
  "stepName": "AML",
  "totalHits": 12,
  "totalFalsePositives": 0,
  "totalTruePositives": 0,
  "totalUnresolved": 12,
  "numUnresolvedPEP": 1,
  "numUnresolvedSanction": 1,
  "numUnresolvedWatchlist": 10,
  "numUnresolvedAdverseMedia": 0,
  "providerSummaries": [...]
}
```

This summary immediately tells you the scale and severity of the results. For example, `numUnresolvedSanction` highlights if a high-risk sanctions match is present and needs immediate attention.

***

## Part 3: The Process Results (The Raw Evidence)

When an AML step returns a `HIT`, the `processResults` array will contain one or more Process Result Objects (PROs), each with `class: "AML"`. Each PRO represents a single potential match from a watchlist and contains all the data you need for your investigation.

### Anatomy of an AML PRO

The most critical part of an AML PRO is the **`supplementaryData`** object. This is where you will find the details of the matched entity.

| `supplementaryData` Field | Description                                                                                                         |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------ |
| **`matchData`**           | Core information about the matched profile (name, date of birth, countries of association).                         |
| **`pepData`**             | If the match is a Politically Exposed Person, this array contains details about their position, level, and country. |
| **`sanctionData`**        | If the match is on a Sanctions list, this array contains details about the sanction, its source, and the reason.    |
| **`watchlistData`**       | This array contains details for matches on other regulatory or law enforcement watchlists.                          |
| **`mediaData`**           | If the match is from Adverse Media, this array provides snippets and links to relevant news articles.               |
| **`referenceDocs`**       | An array of URLs to source documents for further evidence.                                                          |

<AccordionGroup>
  <Accordion title="Example: A PEP Match PRO">
    This example shows a `processResult` for a `HIT` where the individual was matched against a PEP list. The `pepData` array is populated with the specific details of the political exposure.

    ```json theme={null}
    {
      "processResultId": "pro_01J...",
      "result": "HIT",
      "class": "AML",
      "supplementaryData": {
        "type": "AML",
        "matchData": { "name": "John Citizen" },
        "pepData": [
          {
            "level": "2",
            "position": "Former Member of Parliament",
            "countryCode": "AUS",
            "listingStart": "2010-01-01"
          }
        ]
      },
      "manualStatus": "UNRESOLVED"
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Part 4: Next Steps - Classifying Hits and Re-evaluating

After your compliance team reviews the evidence in the `processResults`, they must classify each hit (e.g., as a `FALSE_POSITIVE`). This is done by updating the `manualStatus` of each PRO.

> For a detailed guide on how to perform this action via the API, please see our **[AML Screening & Monitoring Documentation](/docs/anti-money-laundering)**.

### Re-running the Workflow

Once all hits have been classified, you **must re-run the workflow** for the entity. This is a critical step for two reasons:

1. **To Update the `status`**: The overall `workflowResult.status` will only change from `REVIEW` to `PASS` or `CLEAR` after the workflow is executed again and the AML step confirms that no unresolved hits remain.
2. **To Clear `issues`**: The re-execution will cause the AML step to re-evaluate the issues. If all PROs that previously caused a `PEP` issue are now classified as `FALSE_POSITIVE`, the issue will be cleared from the workflow result.

This re-evaluation ensures your entity's compliance status is officially updated and your audit trail is accurate.


# Assessing Risk in FrankieOne
Source: https://docs.frankieone.com/docs/assessing-risk

This guide provides a comprehensive overview of how to implement and configure the Risk-Based Onboarding Engine in FrankieOne v2.0.0. It covers the core concepts of risk calculation, workflow integration, and the detailed configuration of risk factors.

## How Risk Works in Workflows

The FrankieOne v2 Risk Engine transforms static, check-based verification into a dynamic, intelligence-driven framework. This enables you to design sophisticated, risk-based user journeys where the level of due diligence is directly proportional to the calculated risk of an entity.

### Core Concepts

<AccordionGroup>
  <Accordion title="Entity">
    The subject of the risk assessment, which can be an <code>INDIVIDUAL</code> or an <code>ORGANIZATION</code>.
  </Accordion>

  <Accordion title="Service Profile">
    A container for a specific customer context (e.g., KYC Onboarding). Each service profile is assigned one and only one risk profile.
  </Accordion>

  <Accordion title="Risk Profile">
    The central JSON configuration that governs all risk calculations. It defines the risk <b>levels</b> (e.g., LOW, MEDIUM, HIGH) and the <b>factors</b> to be evaluated.
  </Accordion>

  <Accordion title="Risk Factor">
    A specific rule that extracts data, applies scoring logic, and produces a numerical score. Each factor is an independent unit of risk logic.
  </Accordion>

  <Accordion title="Risk Assessment">
    The final output of a risk evaluation generated at the end of a workflow. It contains the aggregated score, the corresponding risk level, and a detailed list of all contributing factors.
  </Accordion>
</AccordionGroup>

### The Risk Assessment Lifecycle

Risk is assessed in a multi-stage process integrated directly into the workflow execution.

<Steps>
  <Step title="Workflow Start">
    The system loads all <code>VALID</code> risk factors already associated with the entity's service profile into the workflow's context. The initial risk score is based on this pre-existing state.
  </Step>

  <Step title="Data Collection Steps">
    As the workflow progresses, steps like AML, IDV, and Onboarding Fraud checks generate <code>processResults</code>, which serve as the source data for many risk factors.
  </Step>

  <Step title="Risk Calculation">
    A dedicated <code>RISK</code> step is triggered. This step evaluates all factors defined in the risk profile, applies the configured scoring logic (<code>scoreMethod</code>), and aggregates the results to produce a final score for each factor.
  </Step>

  <Step title="Workflow Finish">
    The scores from all evaluated risk factors are summed to produce the final <code>workflowRiskScore</code>. This score is then mapped to a <code>workflowRiskLevel</code>. The complete <code>RiskAssessment</code> is added to the <code>workflowResult</code>.
  </Step>

  <Step title="Persistence">
    The new risk assessment is persisted. Any previous factors whose underlying data has changed are marked as <code>STALE</code>.
  </Step>
</Steps>

### Risk Factor Statuses

Each risk factor has a status to manage its lifecycle and ensure calculation accuracy:

| Status         | Description                                                                                                                                                                                        |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **VALID**      | The default status. The factor is current and contributes to the risk score.                                                                                                                       |
| **STALE**      | The underlying data used to generate the factor has changed (e.g., an entity's address was updated). Stale factors are excluded from future calculations and are replaced by new, `VALID` factors. |
| **OVERRIDDEN** | A user has manually overridden the factor's score. The `manualOverrideScore` will be used instead of the system-calculated score.                                                                  |
| **DISCARDED**  | The factor was generated during a workflow but later deemed irrelevant within the same execution. It is excluded from the final risk assessment.                                                   |

***

## Risk Profile Configuration

The entire risk engine is driven by the `risk_profiles.json` configuration file. Each profile defines the `levels` and `factors` for risk calculation.

### `levels` Schema

The `levels` array defines the qualitative risk bands and their corresponding numerical score ranges.

```json theme={null}
"levels": [
    {
        "label": "LOW",
        "range": { "min": 0, "max": 40 }
    },
    {
        "label": "MEDIUM",
        "range": { "min": 41, "max": 70 }
    },
    {
        "label": "HIGH",
        "range": { "min": 71, "max": 90 },
        "extra": {
            "GenerateIssue": {
                "category": "RISK",
                "issue": "RISK_THRESHOLD_HIGH",
                "severity": "REVIEW"
            }
        }
    },
    {
        "label": "UNACCEPTABLE",
        "range": { "min": 91 },
        "extra": {
            "GenerateIssue": {
                "category": "RISK",
                "issue": "RISK_THRESHOLD_UNACCEPTABLE",
                "severity": "BLOCK"
            }
        }
    }
]
```

* **label**: The name of the risk level (e.g., `LOW`, `HIGH`).
* **range**: Defines the numerical score boundaries. `min` and `max` are inclusive.
* **extra.GenerateIssue**: An optional object that instructs the engine to generate a workflow issue when the risk level is reached.

### `factors` Schema

The `factors` array lists all risk factors to be evaluated. Each factor object is a rule for calculating a specific risk score component.

```json theme={null}
{
    "name": "fraud_email",
    "description": "Fraud Email Signal",
    "default": "LOW",
    "scoreMethod": "lookup",
    "aggregate": "max",
    "defaultScore": {
        "name": "default",
        "score": 0,
        "value": "LOW",
        "flags": ["include_zero"]
    },
    "scores": [
        { "value": "LOW", "score": 0, "flags": ["include_zero"] },
        { "value": "MEDIUM", "score": 10 },
        { "value": "HIGH", "score": 20 },
        { "value": "UNACCEPTABLE", "score": 30 },
        { "value": "UNKNOWN", "score": 40 }
    ]
}
```

* **name**: The unique identifier for the risk factor (e.g., `fraud_email`).
* **description**: A human-readable description for display and auditing.
* **handler**: The name of the internal service responsible for data extraction and scoring logic (e.g., `jurisdiction_lookup`).
* **scoreMethod**: The method for assigning a score (`lookup`, `lookup_range`, `bool`).
* **aggregate**: The method for aggregating multiple scores into a single factor score (`sum`, `max`, `min`, `average`, `count`). This applies only when a handler returns multiple values.
* **scores**: An array of objects defining the value-to-score mapping.
* **defaultScore**: A fallback score to apply if the input data cannot be mapped via the `scores` array.

***

## Risk Factor Library

This section provides a comprehensive catalogue of the risk factors available in the FrankieOne platform. Each factor is designed to assess a specific element of risk during the onboarding process.

### KYC Risk Factors (Individuals)

These factors are applicable to `INDIVIDUAL` entities and focus on identity attributes, jurisdiction, and AML signals.

<AccordionGroup>
  <Accordion title="entity_age">
    Calculates risk based on the individual's age at the time of workflow execution.

    <ul>
      <li><b>Handler</b>: <code>entity\_age</code></li>
      <li><b>Score Method</b>: <code>lookup\_range</code></li>
      <li><b>Data Source</b>: <code>individual.dateOfBirth.normalized</code></li>
    </ul>

    <b>Example Configuration:</b>

    ```json theme={null}
      {
          "name": "entity_age",
          "description": "Calculates risk based on the entity's age.",
          "handler": "entity_age",
          "scoreMethod": "lookup_range",
          "scores": [
              { "name": "Minor", "range": { "max": 17 }, "score": 100 },
              { "name": "Young Adult", "range": { "min": 18, "max": 25 }, "score": 15 },
              { "name": "Standard Adult", "range": { "min": 26 }, "score": 0 }
          ],
          "defaultScore": { "value": "N/A", "score": 80 }
      }
    ```
  </Accordion>

  <Accordion title="document_type">
    Applies risk based on the type(s) of identity documents provided. It aggregates scores if multiple documents are present.

    <ul>
      <li><b>Handler</b>: <code>document\_type\_lookup</code></li>
      <li><b>Score Method</b>: <code>lookup</code></li>
      <li><b>Aggregate Method</b>: <code>max</code> (Typically used to take the score of the riskiest document)</li>
      <li><b>Data Source</b>: <code>individual.documents.IDENTITY\[].type</code></li>
    </ul>

    <b>Example Configuration:</b>

    ```json theme={null}
      {
          "name": "document_type",
          "description": "Scores risk based on the provided document type.",
          "handler": "document_type_lookup",
          "scoreMethod": "lookup",
          "aggregate": "max",
          "scores": [
              { "value": "PASSPORT", "score": 5 },
              { "value": "DRIVERS_LICENSE", "score": 10 },
              { "value": "UTILITY_BILL", "score": 40 }
          ],
          "defaultScore": { "value": "No Documents", "score": 0 }
      }
    ```
  </Accordion>

  <Accordion title="nationality_risk">
    Scores risk based on the provided nationality.

    <ul>
      <li><b>Handler</b>: <code>jurisdiction\_lookup</code></li>
      <li><b>Score Method</b>: <code>lookup</code></li>
      <li><b>Aggregate Method</b>: <code>max</code></li>
      <li><b>Data Source</b>: <code>individual.nationality</code></li>
    </ul>

    <b>Example Configuration:</b>

    ```json theme={null}
      {
          "name": "nationality_risk",
          "description": "Scores risk based on the provided nationality.",
          "handler": "jurisdiction_lookup",
          "config": { "source": "nationality" },
          "scoreMethod": "lookup",
          "aggregate": "max",
          "scores": [
              { "value": "IRN", "score": 100 },
              { "value": "RUS", "score": 50 },
              { "value": "AUS", "score": 0 }
          ],
          "defaultScore": { "value": "Other", "score": 30 }
      }
    ```
  </Accordion>

  <Accordion title="residential_country_risk">
    Scores risk based on the current residential address country.

    <ul>
      <li><b>Handler</b>: <code>jurisdiction\_lookup</code></li>
      <li><b>Score Method</b>: <code>lookup</code></li>
      <li><b>Aggregate Method</b>: <code>max</code></li>
      <li><b>Data Source</b>: <code>individual.addresses\[]</code> where <code>type</code> is <code>RESIDENTIAL</code></li>
    </ul>

    <b>Example Configuration:</b>

    ```json theme={null}
      {
          "name": "residential_country_risk",
          "description": "Risk based on the current residential address country.",
          "handler": "jurisdiction_lookup",
          "config": { "source": "address", "addressType": "RESIDENTIAL" },
          "scoreMethod": "lookup",
          "aggregate": "max",
          "scores": [
              { "value": "NGA", "score": 70 },
              { "value": "AUS", "score": 5 }
          ],
          "defaultScore": { "value": "Other", "score": 30 }
      }
    ```
  </Accordion>

  <Accordion title="AML Factors (is_pep, has_sanctions, etc.)">
    These boolean factors check for the presence of corresponding data in AML `processResults`.

    <ul>
      <li><b>Handlers</b>: <code>is\_pep</code>, <code>has\_sanctions</code>, <code>has\_adverse\_media</code>, <code>on\_watchlist</code></li>
      <li><b>Score Method</b>: <code>bool</code></li>
      <li><b>Data Source</b>: <code>processResults\[]</code> where <code>supplementaryData.type</code> is <code>AML</code></li>
    </ul>

    <b>Example Configuration (for `is_pep`):</b>

    ```json theme={null}
      {
          "name": "is_pep",
          "description": "Entity Has PEP Hits",
          "handler": "is_pep",
          "scoreMethod": "bool",
          "scores": [
              { "value": true, "score": 50 }
          ]
      }
    ```
  </Accordion>

  <Accordion title="pep_level">
    Scores risk based on the numerical PEP classification level (1-4).

    <ul>
      <li><b>Handler</b>: <code>pep\_level\_lookup</code></li>
      <li><b>Score Method</b>: <code>lookup</code></li>
      <li><b>Aggregate Method</b>: <code>max</code></li>
      <li><b>Data Source</b>: <code>processResults\[].supplementaryData.pepData\[].level</code></li>
    </ul>

    <b>Example Configuration:</b>

    ```json theme={null}
      {
          "name": "pep_level",
          "description": "Risk based on the PEP classification level",
          "handler": "pep_level_lookup",
          "scoreMethod": "lookup",
          "aggregate": "max",
          "scores": [
              { "value": "1", "score": 100 },
              { "value": "2", "score": 80 },
              { "value": "3", "score": 50 },
              { "value": "4", "score": 30 }
          ],
          "defaultScore": { "value": "N/A", "score": 0 }
      }
    ```
  </Accordion>

  <Accordion title="workflow_attempts">
    Scores risk based on the number of times an entity has executed a specific workflow.

    <ul>
      <li><b>Handler</b>: <code>workflow\_attempts\_counter</code></li>
      <li><b>Score Method</b>: <code>lookup\_range</code></li>
      <li><b>Data Source</b>: Historical workflow execution records for the entity.</li>
    </ul>

    <b>Example Configuration:</b>

    ```json theme={null}
      {
          "name": "workflow_attempts",
          "description": "Total onboarding attempts for this workflow.",
          "handler": "workflow_attempts_counter",
          "scoreMethod": "lookup_range",
          "scores": [
              { "name": "First Attempt", "range": { "max": 1 }, "score": 0 },
              { "name": "Multiple Attempts", "range": { "min": 2, "max": 3 }, "score": 30 },
              { "name": "High Attempts", "range": { "min": 4 }, "score": 70 }
          ]
      }
    ```
  </Accordion>

  <Accordion title="custom_attribute_risk">
    Scores risk based on custom key-value data provided by the client in the <code>individual.customAttributes</code> object.

    <ul>
      <li><b>Handler</b>: <code>custom\_attribute\_lookup</code></li>
      <li><b>Score Method</b>: <code>lookup</code></li>
      <li><b>Data Source</b>: <code>individual.customAttributes</code></li>
    </ul>

    <b>Example Configuration:</b>

    ```json theme={null}
      {
          "name": "product_type_risk",
          "description": "Scores risk based on the client-provided 'product_type' attribute.",
          "handler": "custom_attribute_lookup",
          "config": {
              "attributeName": "product_type"
          },
          "scoreMethod": "lookup",
          "scores": [
              { "value": "Card Present", "score": 5 },
              { "value": "Online Payments", "score": 20 }
          ],
          "defaultScore": { "value": "Other", "score": 10 }
      }
    ```
  </Accordion>

  <Accordion title="unresolved_duplicates">
    Scores risk based on the number of potential duplicate profiles for the entity that have not yet been resolved.

    <ul>
      <li><b>Handler</b>: <code>unresolved\_duplicates</code></li>
      <li><b>Score Method</b>: <code>lookup\_range</code></li>
      <li><b>Data Source</b>: Duplicate check process results.</li>
    </ul>

    <b>Example Configuration:</b>

    ```json theme={null}
      {
          "name": "unresolved_duplicates",
          "description": "Unresolved duplicates",
          "handler": "unresolved_duplicates",
          "scoreMethod": "lookup_range",
          "scores": [
              {
                  "name": "Any unresolved duplicates",
                  "range": { "min": 1 },
                  "score": 20
              }
          ]
      }
    ```
  </Accordion>

  <Accordion title="true_positive_duplicates">
    Scores risk based on the number of duplicate profiles that have been confirmed as `TRUE_POSITIVE`.

    <ul>
      <li><b>Handler</b>: <code>true\_positive\_duplicates</code></li>
      <li><b>Score Method</b>: <code>lookup\_range</code></li>
      <li><b>Data Source</b>: Duplicate check process results.</li>
    </ul>

    <b>Example Configuration:</b>

    ```json theme={null}
      {
          "name": "true_positive_duplicates",
          "description": "Resolved duplicates",
          "handler": "true_positive_duplicates",
          "scoreMethod": "lookup_range",
          "scores": [
              {
                  "name": "Any resolved duplicates",
                  "range": { "min": 1 },
                  "score": 2
              }
          ]
      }
    ```
  </Accordion>
</AccordionGroup>

### Onboarding Fraud Risk Factors

This section details the risk factors derived from Onboarding Fraud checks. These checks provide signals for device, IP address, phone number, and email address risk.

<AccordionGroup>
  <Accordion title="fraud_count_session">
    This factor scores risk based on the number of sessions used during an onboarding workflow. An excessive number of sessions can indicate suspicious behavior.

    <ul>
      <li><b>Handler</b>: <code>fraud\_count\_session</code></li>
      <li><b>Score Method</b>: <code>lookup\_range</code></li>
      <li><b>Returns</b>: A single integer value representing the session count.</li>
    </ul>

    <b>Example Configuration:</b>

    ```json theme={null}
      {
          "name": "fraud_count_session",
          "description": "Fraud Session Count",
          "scoreMethod": "lookup",
          "defaultScore": {
              "name": "Default",
              "value": "0",
              "score": 0,
              "flags": ["include_zero"]
          },
          "scores": [
              {
                  "name": "Up to 2",
                  "range": { "max": 2 },
                  "score": 0
              },
              {
                  "name": "Between 3-5",
                  "range": { "min": 3, "max": 5 },
                  "score": 10
              },
              {
                  "name": "Greater than 5",
                  "range": { "min": 6 },
                  "score": 20
              }
          ]
      }
    ```
  </Accordion>

  <Accordion title="fraud_ip_address">
    This factor aggregates risk signals from IP address checks across one or more sessions.

    <ul>
      <li><b>Handler</b>: <code>fraud\_ip\_address</code></li>
      <li><b>Score Method</b>: <code>lookup</code></li>
      <li><b>Aggregate</b>: <code>max</code> (to capture the highest risk signal from any session)</li>
      <li><b>Returns</b>: An array of risk levels (e.g., <code>\["HIGH", "LOW"]</code>).</li>
    </ul>

    <b>Example Configuration:</b>

    ```json theme={null}
      {
          "name": "fraud_ip_address",
          "description": "Fraud IP Signal",
          "aggregate": "max",
          "defaultScore": {
              "name": "default",
              "value": "LOW",
              "score": 0,
              "flags": ["include_zero"]
          },
          "scores": [
              { "value": "LOW", "score": 0, "flags": ["include_zero"]},
              { "value": "MEDIUM", "score": 10 },
              { "value": "HIGH", "score": 20 },
              { "value": "UNACCEPTABLE", "score": 30 },
              { "value": "UNKNOWN", "score": 40 }
          ]
      }
    ```
  </Accordion>

  <Accordion title="fraud_device">
    This factor aggregates risk signals from device checks across one or more sessions.

    <ul>
      <li><b>Handler</b>: <code>fraud\_device</code></li>
      <li><b>Score Method</b>: <code>lookup</code></li>
      <li><b>Aggregate</b>: <code>max</code> (to capture the highest risk signal from any device)</li>
      <li><b>Returns</b>: An array of risk levels (e.g., <code>\["HIGH", "LOW"]</code>).</li>
    </ul>

    <b>Example Configuration:</b>

    ```json theme={null}
      {
          "name": "fraud_device",
          "description": "Fraud Device Signal",
          "aggregate": "max",
          "defaultScore": {
              "name": "default",
              "score": 0,
              "value": "LOW",
              "flags": ["include_zero"]
          },
          "scores": [
              { "value": "LOW", "score": 0, "flags": ["include_zero"] },
              { "value": "MEDIUM", "score": 10 },
              { "value": "HIGH", "score": 20 },
              { "value": "UNACCEPTABLE", "score": 30 },
              { "value": "UNKNOWN", "score": 40 }
          ]
      }
    ```
  </Accordion>

  <Accordion title="fraud_email">
    This factor scores risk based on the fraud signal for the selected entity email address.

    <ul>
      <li><b>Handler</b>: <code>fraud\_email</code></li>
      <li><b>Score Method</b>: <code>lookup</code></li>
      <li><b>Returns</b>: A single risk level value (e.g., <code>"MEDIUM"</code>).</li>
    </ul>

    <b>Example Configuration:</b>

    ```json theme={null}
      {
          "name": "fraud_email",
          "description": "Fraud Email Signal",
          "defaultScore": {
              "name": "default",
              "score": 0,
              "value": "LOW",
              "flags": ["include_zero"]
          },
          "scores": [
              { "value": "LOW", "score": 0, "flags": ["include_zero"] },
              { "value": "MEDIUM", "score": 10 },
              { "value": "HIGH", "score": 20 },
              { "value": "UNACCEPTABLE", "score": 30 },
              { "value": "UNKNOWN", "score": 40 }
          ]
      }
    ```
  </Accordion>

  <Accordion title="fraud_phone_number">
    This factor scores risk based on the fraud signal for the selected entity phone number.

    <ul>
      <li><b>Handler</b>: <code>fraud\_phone\_number</code></li>
      <li><b>Score Method</b>: <code>lookup</code></li>
      <li><b>Returns</b>: A single risk level value (e.g., <code>"HIGH"</code>).</li>
    </ul>

    <b>Example Configuration:</b>

    ```json theme={null}
      {
          "name": "fraud_phone_number",
          "description": "Fraud Phone Signal",
          "defaultScore": {
              "name": "default",
              "score": 0,
              "value": "LOW",
              "flags": ["include_zero"]
          },
          "scores": [
              { "value": "LOW", "score": 0, "flags": ["include_zero"] },
              { "value": "MEDIUM", "score": 10 },
              { "value": "HIGH", "score": 20 },
              { "value": "UNACCEPTABLE", "score": 30 },
              { "value": "UNKNOWN", "score": 40 }
          ]
      }
    ```
  </Accordion>
</AccordionGroup>

***

## Risk in Workflows: The Fraud Step

The Onboarding Fraud solution is integrated into workflows via a dedicated **Fraud Step**.

### Step Results

The Fraud Step can return one of three results:

| Result        | Description                                                                                   |
| :------------ | :-------------------------------------------------------------------------------------------- |
| **CLEAR**     | All underlying checks passed without raising any concerns. No operator action is required.    |
| **HIT**       | One or more underlying checks returned results that should be reviewed by an operator.        |
| **UNCHECKED** | The step was unable to generate any results, likely due to a data validation or system issue. |

### Impact of Resolving Results on Risk Calculation

When an operator resolves a `HIT`, their action directly impacts how risk is calculated on subsequent workflow runs.

| Operator Action/Status              | Effect on Risk Calculation                                                                                                               |
| :---------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| **No manualStatus** (Unresolved)    | The risk from the provider is used as is.                                                                                                |
| <code>FALSE\_POSITIVE</code>        | The risk for the result is ignored entirely and excluded from the calculation.                                                           |
| <code>TRUE\_POSITIVE\_ACCEPT</code> | The risk for the result is forced to <code>LOW</code> to reflect that the signal is real but the risk has been accepted by the operator. |
| <code>TRUE\_POSITIVE\_REJECT</code> | The risk for the result remains as it was from the provider, reflecting that the signal is real and has been rejected by the operator.   |

***

## Advanced Configuration

### Aggregation Methods

Aggregation applies only when a factor's handler yields multiple input values (e.g., multiple device risk scores). The engine first calculates an "item score" for each value and then collapses them into a single "factor score" using one of the following methods:

| Method      | Description                                                                                                                                         |
| :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
| **max**     | The final factor score is the highest score from all evaluated items.                                                                               |
| **sum**     | The final factor score is the sum of all item scores.                                                                                               |
| **min**     | The final factor score is the lowest score from all evaluated items.                                                                                |
| **average** | The final factor score is the mathematical average of all item scores.                                                                              |
| **count**   | The final score is determined by the total number of input items, which is then mapped against the ranges defined in the <code>scores</code> array. |

### Connector-Level HIT/CLEAR Mapping

For some third-party providers, you can configure how their risk levels map to FrankieOne's `HIT` or `CLEAR` results at the connector level. This allows for fine-tuning of your risk appetite.

By default, the mapping is:

* `HIGH`, `MEDIUM`, `UNACCEPTABLE` -> **HIT**
* `LOW` -> **CLEAR**

You can override this behavior in the connector configuration. For example, to treat `MEDIUM` risk as `CLEAR`:

```json theme={null}
"connector": {
    "provider": {
        "...rest of provider config": "",
        "v2": {
            "riskLevelPROResultMapping": {
                "FRAUD_DEVICE": {
                    "MEDIUM": "CLEAR"
                },
                "FRAUD_IP_ADDRESS": {
                    "MEDIUM": "CLEAR"
                },
                "FRAUD_EMAIL_ADDRESS": {
                    "MEDIUM": "CLEAR"
                },
                "FRAUD_PHONE_NUMBER": {
                    "MEDIUM": "CLEAR"
                }
            }
        },
        "...rest of provider config": ""
    }
}
```


# Australian Documents
Source: https://docs.frankieone.com/docs/australian-documents-v2

The FrankieOne KYC v2 API supports a variety of Australian documents for identity verification. This guide provides details on how to handle these documents effectively.

## Supported Australian Documents

The FrankieOne KYC v2 API supports the following Australian documents:

| Document Name                 | Document Type        |
| :---------------------------- | :------------------- |
| Birth Certificate             | `BIRTH_CERT`         |
| Centrelink Card               | `CONCESSION`         |
| Citizenship Certificate       | `CITIZENSHIP`        |
| Immigration Card (ImmiCard)   | `IMMIGRATION`        |
| Drivers License               | `DRIVERS_LICENSE`    |
| Marriage Certificate          | `MARRIAGE_CERT`      |
| Name Change Certificate       | `NAME_CHANGE`        |
| National Health ID (Medicare) | `NATIONAL_HEALTH_ID` |
| Passport                      | `PASSPORT`           |

***

### Birth Certificates

Birth certificates are official documents issued by the government that record an individual's birth. They include details such as the individual's name, date of birth, place of birth, and parentage.

When submitting a birth certificate for verification, ensure the document is clear, complete, and issued by an official authority. All required details, as specified below, must be included:

**Required Fields**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                            |
      | :------------ | :------------ | :----------------------------------------------------------------------------------------------- |
      | Country       | `country`     | Must be set to `AUS`                                                                             |
      | Date of Birth | `dateOfBirth` | Format must be `YYYY-MM-DD`                                                                      |
      | Document Type | `type`        | Must be `BIRTH_CERT`                                                                             |
      | Name          | `name`        | Must match the birth certificate exactly (Given name, Middle name, Family name, and Other names) |
    </Tab>

    <Tab title="Certificate Details">
      | Field Name                     | Field                                    | Notes                                                                                             |
      | :----------------------------- | :--------------------------------------- | :------------------------------------------------------------------------------------------------ |
      | Certificate Number             | `secondaryIdentifier`                    | Enter in the `secondaryIdentifier` field                                                          |
      | Date of Print                  | `supplementaryData.dateOfPrint`          | Enter in Supplementary Data as `dateOfPrint`. Format: `YYYY-MM-DD`                                |
      | Registered Family Name         | `supplementaryData.registeredFamilyName` | Enter in Supplementary Data as `registeredFamilyName`                                             |
      | Registered Given Name          | `supplementaryData.registeredGivenName`  | Enter in Supplementary Data as `registeredGivenName`                                              |
      | Registered Other Given Name(s) | `supplementaryData.registeredOtherNames` | Enter in Supplementary Data as `registeredOtherNames`                                             |
      | Registration Date              | `supplementaryData.registrationDate`     | Enter in Supplementary Data as `registrationDate`. Accepts `YYYY-MM-DD` or `YYYY`                 |
      | Registration District          | `supplementaryData.registrationDistrict` | Optionally enter in Supplementary Data as `registrationDistrict` if available                     |
      | Registration Number            | `primaryIdentifier`                      | Enter in the `primaryIdentifier` field                                                            |
      | Registration State             | `subdivision`                            | Use the `subdivision` field. Accepted values: `VIC`, `NSW`, `ACT`, `WA`, `SA`, `NT`, `QLD`, `TAS` |

      <Callout icon="thumbtack">
        Always provide all available information for the most accurate verification. Matching requirements for registration number and date may vary depending on:

        * **Issuing State or Territory**
        * **Registration Date**
        * **Historical Registry Format**

        **For NSW, VIC, WA, SA, TAS, ACT, and NT:**\
        You must provide at least one of the following:

        * Registration Number (`primaryIdentifier`)
        * Certificate Number (`secondaryIdentifier`)

        **For Queensland (QLD) Only:**\
        You must provide either:

        * Registration Date (`supplementaryData.registrationDate`)
        * Certificate Number (`secondaryIdentifier`)

        Supplying both fields where available is recommended for optimal verification success.
      </Callout>
    </Tab>
  </Tabs>
</Card>

<Callout icon="star">
  Tips for Birth Certificate Verification

  For best results when processing birth certificates:

  * Provide all available fields, including optional ones
  * Use names and dates exactly as shown on the certificate
  * Pay attention to historical date formats and registration district spelling
  * Note any differences between registered and current legal names
  * **Matching requirements may vary by state, territory, or certificate age.** Supplying complete and accurate information maximizes verification success.
</Callout>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Always "IDENTITY" for identity documents
    "primaryIdentifier": "000734130", // Registration Number as shown on the birth certificate
    "secondaryIdentifier": "P0001975", // Certificate Number as shown on the birth certificate
    "type": "BIRTH_CERT", // Document type, must be "BIRTH_CERT" for birth certificates
    "subdivision": "NSW", // Registration State (e.g., VIC, NSW, ACT, WA, SA, NT, QLD, TAS)
    "country": "AUS", // Country code (ISO 3166-1 alpha-3), must be "AUS" for Australia
    "supplementaryData": { // Additional birth certificate details
      "type": "BIRTH_CERT", // Supplementary data type, must be "BIRTH_CERT"
      "registrationDate": "2000", // Registration date (format: "YYYY" or "YYYY-MM-DD" as shown on the certificate)
      "registrationDistrict": "Sydney", // Registration district (optional, if available on the certificate)
      "dateOfPrint": "2000-03-24", // Date the certificate was printed (format: "YYYY-MM-DD")
      "registeredGivenName": "Johnny", // Registered given name(s) as shown on the certificate
      "registeredOtherNames": "Hugo Boss", // Registered other given name(s), if present
      "registeredFamilyName": "Danger" // Registered family name as shown on the certificate
    }
  }
}  
```

***

### Centrelink Cards

Centrelink cards are official documents issued by the Australian government that provide access to social security and welfare benefits. These cards contain personal details such as the cardholder's name, date of birth, and Customer Reference Number (CRN).

**Required Fields**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                         |
      | :------------ | :------------ | :-------------------------------------------------------------------------------------------- |
      | Country       | `country`     | Must be set to `AUS`                                                                          |
      | Date of Birth | `dateOfBirth` | Format must be `YYYY-MM-DD`                                                                   |
      | Document Type | `type`        | Must be one of `CONCESSION`, `HEALTH_CONCESSION`, or `PENSION`                                |
      | Name          | `name`        | Must match the Centrelink card exactly (Given name, Middle name, Family name, and any others) |
    </Tab>

    <Tab title="Card Details">
      | Field Name                | Field               | Notes                                                        |
      | :------------------------ | :------------------ | :----------------------------------------------------------- |
      | Customer Reference Number | `primaryIdentifier` | Enter the Centrelink Customer Reference Number in this field |
      | Card Expiry Date          | `expiryDate`        | Enter the expiry date in this field. Format: `YYYY-MM-DD`    |

      <Callout icon="thumbtack">
        Ensure the card is valid and not expired. The `expiryDate` field must be provided in the correct format.
      </Callout>
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY",
    "expiryDate": {
      "year": "1990", // Expiry year of the Centrelink card (YYYY)
      "month": "03", // Expiry month of the Centrelink card (MM)
      "day": "27", // Expiry day of the Centrelink card (DD)
      "unstructured": "27-03-1990", // Expiry date in unstructured format (DD-MM-YYYY)
    },
    "primaryIdentifier": "000734130", // Centrelink Customer Reference Number (CRN)
    "type": "CONCESSION", // Document type: CONCESSION, HEALTH_CONCESSION, or PENSION
    "country": "AUS" // Country code (ISO 3166-1 alpha-3), must be AUS for Australia
  }
}
```

***

### Citizenship Certificates

Citizenship certificates are official documents issued by the Australian government that confirm an individual's Australian citizenship. These certificates contain personal details such as the individual's name, date of birth, and certificate (stock) number.

**Required Fields**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                      |
      | :------------ | :------------ | :----------------------------------------------------------------------------------------- |
      | Country       | `country`     | Must be set to `AUS`                                                                       |
      | Date of Birth | `dateOfBirth` | Format: `YYYY-MM-DD`                                                                       |
      | Document Type | `type`        | Must be `CITIZENSHIP`                                                                      |
      | Name          | `name`        | Must match the certificate exactly (Given name, Middle name, Family name, and Other names) |
    </Tab>

    <Tab title="Certificate Details">
      | Field Name        | Field                                | Notes                                                                               |
      | :---------------- | :----------------------------------- | :---------------------------------------------------------------------------------- |
      | Stock Number      | `primaryIdentifier`                  | Enter the certificate's stock number in this field                                  |
      | Acquisition Date  | `supplementaryData.acquisitionDate`  | Must be in `YYYY-MM-DD` format                                                      |
      | Primary Country   | `supplementaryData.primaryCountry`   | Must be `AUS` (Australian citizenship)                                              |
      | Secondary Country | `supplementaryData.secondaryCountry` | Optional for dual citizenships; must be a valid ISO 3166-1 alpha-3 code if provided |

      <Callout icon="thumbtack">
        **Ensure the certificate is valid and issued by the appropriate authority.** The `acquisitionDate` field must be provided in the correct format.
      </Callout>
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Document class, always "IDENTITY" for identity documents
    "primaryIdentifier": "000734130", // Stock Number as shown on the citizenship certificate
    "type": "CITIZENSHIP", // Document type, must be "CITIZENSHIP"
    "country": "AUS", // Country code (ISO 3166-1 alpha-3), must be "AUS" for Australia
    "supplementaryData": { // Additional certificate details
      "type": "CITIZENSHIP", // Supplementary data type, must be "CITIZENSHIP"
      "acquisitionDate": "2000-01-23", // Date citizenship was acquired, format: YYYY-MM-DD
      "primaryCountry": "AUS", // Primary country of citizenship, must be "AUS"
      "secondaryCountry": "NZL" // Optional: Secondary country for dual citizenships (ISO 3166-1 alpha-3)
    }
  }
}
```

***

### Drivers Licenses

Australian driver licences are official documents issued by Australian state or territory governments, authorizing individuals to operate vehicles. Each licence contains personal details such as the holder’s name, date of birth, licence number, and card number. Requirements and formats may vary by jurisdiction.

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                  |
      | :------------ | :------------ | :------------------------------------------------------------------------------------- |
      | Country       | `country`     | Must be set to `AUS`                                                                   |
      | Date of Birth | `dateOfBirth` | Format: `YYYY-MM-DD`                                                                   |
      | Document Type | `type`        | Must be `DRIVERS_LICENSE`                                                              |
      | Name          | `name`        | Must match the licence exactly (Given name, Middle name, Family name, and Other names) |
    </Tab>

    <Tab title="Licence Details">
      | Field Name     | Field                 | Notes                                                                                                     |
      | :------------- | :-------------------- | :-------------------------------------------------------------------------------------------------------- |
      | Licence Number | `primaryIdentifier`   | Enter the licence number as shown on the card                                                             |
      | Card Number    | `secondaryIdentifier` | Enter the card number as shown on the card. This field is mandatory for all states except Victoria (VIC). |
      | Subdivision    | `subdivision`         | State or territory of issue. Accepted values: `VIC`, `NSW`, `ACT`, `WA`, `SA`, `NT`, `QLD`, `TAS`         |

      <Callout icon="thumbtack">
        Provide both the licence number and card number where available. These may differ by state and are both required for accurate verification.
      </Callout>
    </Tab>
  </Tabs>
</Card>

<AccordionGroup>
  <Accordion title="Licence Number Formats">
    | State | Format       | Length   | Example     |
    | :---- | :----------- | :------- | :---------- |
    | ACT   | Numeric      | Up to 10 | `123456789` |
    | NT    | Numeric      | Up to 10 | `123456789` |
    | QLD   | Numeric      | 8-9      | `12345678`  |
    | NSW   | Alphanumeric | 6-8      | `N49187`    |
    | SA    | Alphanumeric | 6        | `ABC123`    |
    | TAS   | Alphanumeric | 6-8      | `A12345`    |
    | VIC   | Numeric      | Up to 10 | `123456789` |
    | WA    | Numeric      | 7        | `1234567`   |
  </Accordion>

  <Accordion title="Card Number Formats">
    | State | Format       | Length | Example      |
    | :---- | :----------- | :----- | :----------- |
    | ACT   | Alphanumeric | 10     | `ABC1234567` |
    | NT    | Numeric      | 6-8    | `123456`     |
    | QLD   | Alphanumeric | 10     | `ABC1234567` |
    | NSW   | Numeric      | 10     | `1234567890` |
    | SA    | Alphanumeric | 9      | `ABC123456`  |
    | TAS   | Alphanumeric | 9      | `ABC123456`  |
    | VIC   | Alphanumeric | 8      | `ABC12345`   |
    | WA    | Alphanumeric | 8-10   | `ABC123456`  |
  </Accordion>
</AccordionGroup>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Document class, always "IDENTITY" for identity documents
    "primaryIdentifier": "000734130", // Licence Number as shown on the driver licence
    "secondaryIdentifier": "P0001975", // Card Number as shown on the driver licence (may be required for some states)
    "type": "DRIVERS_LICENSE", // Document type, must be "DRIVERS_LICENSE"
    "subdivision": "VIC", // State or territory of issue (e.g., VIC, NSW, QLD, etc.)
    "country": "AUS" // Country code (ISO 3166-1 alpha-3), must be "AUS" for Australia
  }
}
```

<AccordionGroup>
  <Accordion title="Australian Capital Territory (ACT)">
    <Frame>
      <img alt="Australian Capital Territory Driver Licence sample - front" />
    </Frame>

    <Frame>
      <img alt="Australian Capital Territory Driver Licence sample - back" />
    </Frame>
  </Accordion>

  <Accordion title="Northern Territory (NT)">
    <Tabs>
      <Tab title="Post Nov 2020">
        <Frame>
          <img alt="Northern Territory Driver Licence - post 1 November 2020 sample - front" />
        </Frame>

        <Frame>
          <img alt="Northern Territory Driver Licence - post 1 November 2020 sample - back" />
        </Frame>
      </Tab>

      <Tab title="Pre Nov 2020">
        <Frame>
          <img alt="Northern Territory Driver Licence - pre 1 November 2020 sample - front" />
        </Frame>

        <Frame>
          <img alt="Northern Territory Driver Licence - pre 1 November 2020 sample - back" />
        </Frame>
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Queensland (QLD)">
    <Tabs>
      <Tab title="Post June 2019">
        <Frame>
          <img alt="Queensland Driver Licence – post 12 June 2019 sample - front" />
        </Frame>

        <Frame>
          <img alt="Queensland Driver Licence sample - back" />
        </Frame>
      </Tab>

      <Tab title="Pre June 2019">
        <Frame>
          <img alt="Queensland Driver Licence - pre 12 June 2019 sample - front" />
        </Frame>

        <Frame>
          <img alt="Queensland Driver Licence sample - back" />
        </Frame>
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="New South Wales (NSW)">
    <Frame>
      <img alt="New South Wales Driver Licence sample - front" />
    </Frame>

    <Frame>
      <img alt="New South Wales Driver Licence sample - back" />
    </Frame>

    <Frame>
      <img alt="New South Wales Digital Driver Licence sample" />
    </Frame>
  </Accordion>

  <Accordion title="South Australia (SA)">
    <Tabs>
      <Tab title="Physical License">
        <Frame>
          <img alt="South Australia Driver Licence sample - front" />
        </Frame>

        <Frame>
          <img alt="South Australia Driver Licence sample - back" />
        </Frame>
      </Tab>

      <Tab title="Digital License">
        <Frame>
          <img alt="South Australia Digital Driver Licence sample – Overview Tab" />
        </Frame>

        <Frame>
          <img alt="South Australia Digital Driver Licence sample – DetailsTab" />
        </Frame>
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Tasmania (TAS)">
    <Frame>
      <img alt="Tasmania Driver Licence sample - front" />
    </Frame>

    <Frame>
      <img alt="Tasmania Driver Licence sample - back" />
    </Frame>
  </Accordion>

  <Accordion title="Victoria (VIC)">
    <Tabs>
      <Tab title="Post Nov 2022">
        <Frame>
          <img alt="Victoria Driver Licence – post 7 November 2022 sample - front" />
        </Frame>

        <Frame>
          <img alt="Victoria Driver Licence - post 7 November 2022 sample - back" />
        </Frame>
      </Tab>

      <Tab title="Pre Nov 2022">
        <Frame>
          <img alt="Victoria Driver Licence - pre 7 November 2022 sample - front" />
        </Frame>

        <Frame>
          <img alt="Victoria Driver Licence – pre 7 November 2022 sample - back" />
        </Frame>
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Western Australia (WA)">
    <Frame>
      <img alt="Western Australia Driver Licence sample - front" />
    </Frame>

    <Frame>
      <img alt="Western Australia Driver Licence sample - back" />
    </Frame>
  </Accordion>
</AccordionGroup>

<Info>
  ##### Victorian Licence Verification – Card Number Handling (Effective July 1, 2023)

  Victorian driver licence card number verification is now subject to special rules:

  * For licences flagged as compromised (e.g., due to the Optus breach), the DVS will verify the current card number.
  * For non-compromised licences, the card number is not checked and may match the licence number.
  * Always collect and submit the card number, as verification requirements may change based on historical or future data breaches.
  * If you are a direct DVS user, you may see an audit log entry: “Successful Match – Card Number hasn’t been checked.”
</Info>

***

### Immigration Cards (ImmiCard)

ImmiCards are official identity documents issued by the Australian Department of Home Affairs to eligible non-citizens, including visa holders, refugees, and humanitarian entrants. Each ImmiCard contains the holder’s name, date of birth, and a unique ImmiCard number. ImmiCards are used as evidence of identity and residency status in Australia.

**Required Fields**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                   |
      | :------------ | :------------ | :-------------------------------------------------------------------------------------- |
      | Country       | `country`     | Must be set to `AUS`                                                                    |
      | Date of Birth | `dateOfBirth` | Format must be `YYYY-MM-DD`                                                             |
      | Document Type | `type`        | Must be `IMMIGRATION`                                                                   |
      | Name          | `name`        | Must match the ImmiCard exactly (Given name, Middle name, Family name, and Other names) |

      <Callout icon="thumbtack">
        For individuals with a single name, use a hyphen (`-`) in the `givenName` field. **Example:** For "Cher", use `{"givenName": "-", "familyName": "Cher"}`.
      </Callout>
    </Tab>

    <Tab title="Card Details">
      | Field Name      | Field               | Notes                                                                                                                                                            |
      | :-------------- | :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
      | ImmiCard Number | `primaryIdentifier` | Enter the ImmiCard number exactly as shown on the card. Must be 9 characters: 3 letters (A-Z, case-insensitive) followed by 6 digits (0-9). Example: `PRE123456` |
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Always "IDENTITY" for identity documents
    "primaryIdentifier": "PRE123456", // ImmiCard Number (must be 3 uppercase letters followed by 6 digits, e.g., "PRE123456")
    "type": "IMMIGRATION", // Document type, must be "IMMIGRATION" for ImmiCard
    "country": "AUS" // Country code (ISO 3166-1 alpha-3), must be "AUS" for Australia
  }
}
```

<Callout icon="bell">
  ##### Common Validation Issues

  When submitting ImmiCard documents, ensure:

  * The ImmiCard number is exactly 9 characters: 3 uppercase letters (A–Z) followed by 6 digits (0–9), e.g., `PRE123456`.
  * Name fields must match the ImmiCard exactly, including case, spelling, and spacing. For individuals with a single name, use a hyphen (`-`) for the given name (e.g., `{"givenName": "-", "familyName": "Cher"}`).
  * The date of birth must be in `YYYY-MM-DD` format.
  * Include all names as shown on the card.
  * Double-check all values for accuracy to avoid verification failures.
</Callout>

***

### Marriage Certificate

Marriage certificates are official documents that record the marriage of two individuals. They include personal details such as the names of the individuals, date of marriage, and the issuing authority.

<Callout icon="star">
  ##### Best Practices for Marriage Certificate Verification

  * Confirm the certificate format before mapping fields.
  * Use correct ISO date formats for all date fields.
  * Follow state-specific requirements, especially for Victoria.
  * Provide all available optional fields for higher verification accuracy.
  * Ensure names match the certificate exactly, including spelling and order.
</Callout>

**Required Fields**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                          |
      | :------------ | :------------ | :--------------------------------------------------------------------------------------------- |
      | Country       | `country`     | Must be set to `AUS`                                                                           |
      | Date of Birth | `dateOfBirth` | Format: `YYYY-MM-DD`                                                                           |
      | Document Type | `type`        | Must be `MARRIAGE_CERT`                                                                        |
      | Name          | `name`        | Must match the certificate exactly (Given name, Middle name, Family name, and any other names) |
    </Tab>

    <Tab title="Certificate Details">
      | Field Name            | Field                                  | Notes                                                                                        |
      | :-------------------- | :------------------------------------- | :------------------------------------------------------------------------------------------- |
      | Registration Number   | `primaryIdentifier`                    | Enter the official registration number as shown on the certificate                           |
      | Certificate Number    | `secondaryIdentifier`                  | Enter the certificate number as shown on the certificate                                     |
      | Document Type         | `type`                                 | Must be `MARRIAGE_CERT`                                                                      |
      | Registration State    | `subdivision`                          | State or territory of registration: `VIC`, `NSW`, `ACT`, `WA`, `SA`, `NT`, `QLD`, `TAS`      |
      | Registration Date     | `supplementaryData.registrationDate`   | Date the marriage was registered. Format: `YYYY-MM-DD` or `YYYY` as shown on the certificate |
      | Date of Print         | `supplementaryData.dateOfPrint`        | Date the certificate was printed. Format: `YYYY-MM-DD`                                       |
      | Marriage Date         | `supplementaryData.marriageDate`       | Date the marriage took place. Format: `YYYY-MM-DD`                                           |
      | Partner 1 Given Name  | `supplementaryData.partner1GivenName`  | Given name(s) of Partner 1 as shown on the certificate                                       |
      | Partner 1 Family Name | `supplementaryData.partner1FamilyName` | Family name of Partner 1 as shown on the certificate                                         |
      | Partner 1 Other Name  | `supplementaryData.partner1OtherName`  | Other name(s) of Partner 1, if present (optional)                                            |
      | Partner 2 Given Name  | `supplementaryData.partner2GivenName`  | Given name(s) of Partner 2 as shown on the certificate                                       |
      | Partner 2 Family Name | `supplementaryData.partner2FamilyName` | Family name of Partner 2 as shown on the certificate                                         |
      | Partner 2 Other Name  | `supplementaryData.partner2OtherName`  | Other name(s) of Partner 2, if present (optional)                                            |

      <Callout icon="thumbtack">
        Ensure the registration state matches the issuing authority on the marriage certificate. Provide all available details for the most accurate verification. **State/Territory Matching Requirements:**

        * **NSW, VIC, WA, SA, TAS, ACT, NT:**\
          You must provide at least one of the following:
          * Registration Number (`primaryIdentifier`)
          * Certificate Number (`secondaryIdentifier`)
        * **Queensland (QLD):**\
          You must provide either:
          * Registration Date (`supplementaryData.registrationDate`)
          * Certificate Number (`secondaryIdentifier`)

        Supplying both fields where available is recommended for optimal verification success.
      </Callout>
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Document class, always "IDENTITY" for identity documents
    "primaryIdentifier": "000734130", // Registration Number as shown on the marriage certificate
    "secondaryIdentifier": "P0001975", // Certificate Number as shown on the marriage certificate
    "type": "MARRIAGE_CERT", // Document type, must be "MARRIAGE_CERT" for marriage certificates
    "country": "AUS", // Country code (ISO 3166-1 alpha-3), must be "AUS" for Australia
    "subdivision": "NSW", // Registration State or Territory (e.g., VIC, NSW, ACT, WA, SA, NT, QLD, TAS)
    "supplementaryData": {
      "type": "MARRIAGE_CERT", // Supplementary data type, must be "MARRIAGE_CERT"
      "registrationDate": "2023", // Date the marriage was registered; format: "YYYY" or "YYYY-MM-DD" as shown on the certificate
      "dateOfPrint": "2023-10-01", // Date the certificate was printed; format: "YYYY-MM-DD"
      "marriageDate": "2023-10-01", // Date the marriage took place; format: "YYYY-MM-DD"
      "partner1GivenName": "John", // Given name(s) of Partner 1 as shown on the certificate
      "partner1FamilyName": "Doe", // Family name of Partner 1 as shown on the certificate
      "partner1OtherName": "Jonah", // Other name(s) of Partner 1, if present (optional)
      "partner2GivenName": "Jane", // Given name(s) of Partner 2 as shown on the certificate
      "partner2FamilyName": "Doe", // Family name of Partner 2 as shown on the certificate
      "partner2OtherName": "Jonesy" // Other name(s) of Partner 2, if present (optional)
    }
  }
}
```

<Callout icon="bell">
  ##### Victoria (VIC) State-Specific Requirements

  For marriage certificate verification in Victoria:

  * Enter the details from the left-hand column or first row as Name 2, regardless of the order on the certificate.
  * Always refer to the latest DVS specifications for Victoria and other states to ensure correct field mapping.
</Callout>

<Info>
  ##### Marriage Certificate Formats

  Australian marriage certificates may use different participant labels depending on the certificate version:

  * **Traditional:** Bride/Groom
  * **Modern:** Partner 1/Partner 2 Use the format that matches the certificate you are processing.
</Info>

***

### Name Change Certificates

Name change certificates are official documents issued by Australian state or territory authorities to record an individual's legal change of name. These certificates include details such as the person's previous name(s), new name(s), date of registration, and the issuing authority. Name change certificates are required for official identity verification when an individual has changed their legal name.

**Required Fields**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                   |
      | :------------ | :------------ | :-------------------------------------------------------------------------------------- |
      | Country       | `country`     | Must be `AUS`                                                                           |
      | Date of Birth | `dateOfBirth` | Format: `YYYY-MM-DD`                                                                    |
      | Document Type | `type`        | Must be `NAME_CHANGE`                                                                   |
      | Name          | `name`        | Must match the certificate exactly (Given, Middle, Family, and Other names, if present) |
    </Tab>

    <Tab title="Certificate Details">
      | Field Name             | Field                                         | Notes                                                                                    |
      | :--------------------- | :-------------------------------------------- | :--------------------------------------------------------------------------------------- |
      | Registration Number    | `primaryIdentifier`                           | Official registration number as shown on the certificate                                 |
      | Certificate Number     | `secondaryIdentifier`                         | Certificate number as shown on the certificate                                           |
      | Registration State     | `subdivision`                                 | State/territory of registration: `VIC`, `NSW`, `ACT`, `WA`, `SA`, `NT`, `QLD`, `TAS`     |
      | Registration Date      | `supplementaryData.registrationDate`          | Date the name change was registered (`YYYY-MM-DD` or `YYYY` as shown on the certificate) |
      | Date of Print          | `supplementaryData.dateOfPrint`               | Date the certificate was printed (`YYYY-MM-DD`)                                          |
      | Registered Family Name | `supplementaryData.registeredFamilyName`      | As shown on the certificate; may differ from current legal name                          |
      | Registered Given Name  | `supplementaryData.registeredGivenName`       | As shown on the certificate                                                              |
      | Registered Other Names | `supplementaryData.registeredOtherGivenNames` | Other given names, if present                                                            |

      <Callout icon="thumbtack">
        Provide all names exactly as shown on the certificate, including any previous names. Supplying complete and accurate information maximizes verification success.

        **State/Territory Matching Requirements:**

        * **NSW, VIC, WA, SA, TAS, ACT, NT:**\
          You must provide at least one of the following:
          * Registration Number (`primaryIdentifier`)
          * Certificate Number (`secondaryIdentifier`)
        * **Queensland (QLD):**\
          You must provide either:
          * Registration Date (`supplementaryData.registrationDate`)
          * Certificate Number (`secondaryIdentifier`)

        Supplying both fields where available is recommended for optimal verification success.
      </Callout>
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Always "IDENTITY" for identity documents
    "primaryIdentifier": "000734130", // Registration Number as shown on the name change certificate
    "secondaryIdentifier": "P0001975", // Certificate Number as shown on the name change certificate
    "type": "NAME_CHANGE", // Document type, must be "NAME_CHANGE" for name change certificates
    "country": "AUS", // Country code (ISO 3166-1 alpha-3), must be "AUS" for Australia
    "subdivision": "VIC", // Registration State or Territory (e.g., VIC, NSW, ACT, WA, SA, NT, QLD, TAS)
    "supplementaryData": {
      "type": "NAME_CHANGE", // Supplementary data type, must be "NAME_CHANGE"
      "registrationDate": "2000-01-20", // Date the name change was registered; format: "YYYY-MM-DD" or "YYYY" as shown on the certificate
      "dateOfPrint": "2000-01-20", // Date the certificate was printed; format: "YYYY-MM-DD"
      "registeredFamilyName": "Doe", // Registered family name as shown on the certificate (may differ from current legal name)
      "registeredGivenName": "John", // Registered given name(s) as shown on the certificate
      "registeredOtherGivenNames": "Chris" // Other registered given names, if present (optional)
    }
  }
}
```

***

### National Health ID (Medicare)

National Health ID cards, commonly known as Medicare cards, are issued by the Australian government to provide access to healthcare services. They include personal details such as the individual's name, date of birth, and Medicare number.

**Required Fields**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                           |
      | :------------ | :------------ | :---------------------------------------------------------------------------------------------- |
      | Country       | `country`     | Must be set to `AUS`                                                                            |
      | Date of Birth | `dateOfBirth` | Must be in `YYYY-MM-DD` format                                                                  |
      | Document Type | `type`        | Must be `NATIONAL_HEALTH_ID`                                                                    |
      | Name          | `name`        | Must match the card exactly (Given name, Middle name, Family name, and any other names present) |
    </Tab>

    <Tab title="Card Details">
      | Field Name           | Field                                                                                                                                                                                                        | Notes                                                                                                   |
      | :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ |
      | Card Number          | `primaryIdentifier`                                                                                                                                                                                          | Medicare card number as shown on the card (usually 10 digits, e.g., `1234 56789 0`)                     |
      | Card Type            | `subtype`                                                                                                                                                                                                    | Card type: `G` (Green), `B` (Blue), or `Y` (Yellow)                                                     |
      | Expiry Date          | `expiryDate`                                                                                                                                                                                                 | Card expiry date in `YYYY-MM-DD` or `YYYY-MM` format as per the card                                    |
      | Individual Reference | `supplementaryData.reference`                                                                                                                                                                                | Individual reference number (optional, as shown on the card; usually 1 digit at the end)                |
      | Name on Card         | `supplementaryData.nameOnCardLine1`,<br />`supplementaryData.nameOnCardLine2`,<br />`supplementaryData.nameOnCardLine3`,<br />`supplementaryData.nameOnCardLine4`,<br />`supplementaryData.middleNameOnCard` | Names as printed on the card, including all lines and middle name if present. Provide exactly as shown. |

      <Callout icon="thumbtack">
        #### Important Notes for Medicare Card Verification

        * The `subtype` field indicates the card type (`G` = Green, `B` = Blue, `Y` = Yellow).
        * Supplementary fields such as `nameOnCardLine1`, `nameOnCardLine2`, `nameOnCardLine3`, `nameOnCardLine4`, and `middleNameOnCard` are optional but recommended for higher verification accuracy; fill them exactly as they appear on the card.
        * The `supplementaryData.reference` (individual reference number) is optional but can assist with verification.
        * Ensure all fields are completed accurately and match the card to avoid verification issues.
        * **Optional Field** - The `subdivision` field must match the state or territory where the card was issued (e.g., VIC, NSW, QLD, etc.).
      </Callout>
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Always "IDENTITY" for identity documents
    "expiryDate": {
      "year": "1990", // Expiry year as shown on the Medicare card (YYYY)
      "month": "03", // Expiry month as shown on the Medicare card (MM)
      "day": "27", // Expiry day as shown on the Medicare card (DD)
      "unstructured": "1990-03-27", // Expiry date in unstructured format (YYYY-MM-DD), as printed on the card
      "type": "GREGORIAN" // Calendar type; use "GREGORIAN" for standard dates
    },
    "primaryIdentifier": "000734130", // Medicare card number (usually 10 digits, e.g., "1234567890")
    "type": "NATIONAL_HEALTH_ID", // Document type, must be "NATIONAL_HEALTH_ID" for Medicare cards
    "subtype": "G", // Card type: "G" (Green), "B" (Blue), or "Y" (Yellow) as indicated on the card
    "subdivision": "VIC", // State or territory of issue (e.g., VIC, NSW, QLD, etc.)
    "country": "AUS", // Country code (ISO 3166-1 alpha-3), must be "AUS" for Australia
    "supplementaryData": {
      "type": "NATIONAL_HEALTH_ID", // Supplementary data type, must be "NATIONAL_HEALTH_ID"
      "reference": "1", // Individual reference number (usually a single digit at the end of the card number)
      "nameOnCardLine1": "Johnny", // First line of the name as printed on the card
      "nameOnCardLine2": "Danger", // Second line of the name as printed on the card (if present)
      "nameOnCardLine3": "null", // Third line of the name as printed on the card (if present, otherwise "null")
      "nameOnCardLine4": "null", // Fourth line of the name as printed on the card (if present, otherwise "null")
      "middleNameOnCard": "null" // Middle name as printed on the card (if present, otherwise "null")
    }
  }
}
```

***

### Australian Passports

Australian passports are official travel documents issued by the Australian government that certify an individual's identity and citizenship. Each passport contains key personal information, including the holder's full name, date of birth, passport number, nationality, and expiration date.

When submitting an Australian passport for verification, ensure that all details are entered exactly as they appear on the passport. This includes correct spelling, capitalization, special characters, and the precise order of names. Accurate data entry is critical for successful verification.

<CardGroup>
  <Card title="Passport Verification" icon="passport">
    Verify Australian passports for citizens and permanent residents. Ensure all details match the passport exactly, including name, date of birth, and passport number.
  </Card>

  <Card title="Visa Verification" icon="id-card-clip">
    Verify Australian visas for temporary residents and visitors. Use the passport number associated with the visa and match all personal details as shown on the travel document.
  </Card>
</CardGroup>

<Callout icon="star">
  ##### Key Passport Verification Guidelines

  **Exact Name Matching**

  * Enter names exactly as shown on the passport, including capitalization, special characters, spaces, and diacritics.

  **Country Codes**

  * For Australian passports, use `AUS`.
  * For visas, use the ISO 3166-1 alpha-3 code of the passport’s issuing country.

  **Document Numbers**

  * Always provide the passport number, even for visa verification.
  * Ensure the passport number matches the one associated with the visa.
  * Incorrect or expired passport numbers will cause verification to fail.

  **Name Order for Visas**

  * For visa holders, follow the name order and format as printed on the passport, regardless of local conventions.
</Callout>

**Required Fields**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                                                                                  |
      | :------------ | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
      | Country       | `country`     | Must be set to `AUS`                                                                                                                                   |
      | Date of Birth | `dateOfBirth` | Format: `YYYY-MM-DD`                                                                                                                                   |
      | Document Type | `type`        | Must be `PASSPORT`                                                                                                                                     |
      | Name          | `name`        | Enter the full name exactly as shown on the passport (including all given, middle, family, and other names; match spelling, order, and capitalization) |
      | Gender        | `gender`      | Must be provided in the entity object as `M`, `F`, or `X`                                                                                              |
    </Tab>

    <Tab title="Passport Details">
      | Field Name       | Field               | Notes                                                      |
      | :--------------- | :------------------ | :--------------------------------------------------------- |
      | Passport Number  | `primaryIdentifier` | Enter the passport number exactly as shown on the document |
      | Document Type    | `type`              | Must be `PASSPORT`                                         |
      | Country of Issue | `country`           | Must be `AUS`                                              |
    </Tab>
  </Tabs>
</Card>

<AccordionGroup>
  <Accordion title="Passport Number Formats">
    The passport number, also known as the travel document number, must adhere to the following formats for successful validation:

    * 8 characters: 1 letter followed by 7 numbers.
    * 9 characters: 2 letters followed by 7 numbers.

    The DVS only supports Australian passports with these specified lengths and formats. Submitting a passport number that does not meet these criteria will result in a validation error.
  </Accordion>
</AccordionGroup>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Always "IDENTITY" for identity documents
    "primaryIdentifier": "N1234567", // Passport number as shown on the passport (letters and numbers, exact match)
    "type": "PASSPORT", // Document type, must be "PASSPORT" for Australian passports
    "country": "AUS" // Country code (ISO 3166-1 alpha-3), must be "AUS" for Australia
  }
}
```


# Chinese Documents
Source: https://docs.frankieone.com/docs/chinese-documents-v2



The FrankieOne KYC v2 API supports some Chinese documents for identity verification. This guide provides details on how to handle these documents effectively.

## Supported Chinese Documents

The FrankieOne KYC v2 API supports the following Chinese documents:

| Document    | Code          |
| :---------- | :------------ |
| National ID | `NATIONAL_ID` |

***

### Chinese National ID Card (身份证)

Chinese National ID Cards (身份证) are official identification documents issued by the Chinese government that confirm an individual's identity and citizenship. They include personal details such as the individual's name, date of birth, ID card number, and expiration date.

**Required Fields**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field                 | Notes                                                                                 |
      | ------------- | --------------------- | ------------------------------------------------------------------------------------- |
      | Document Type | `type`                | Must be `NATIONAL_ID`.                                                                |
      | Country       | `country`             | Must be `CHN` (China).                                                                |
      | Date of Birth | `dateOfBirth`         | Format: `YYYY-MM-DD`.                                                                 |
      | Family Name   | `familyName`          | Pinyin family name in uppercase (e.g., `ZHANG`).                                      |
      | Given Name    | `givenName`           | Pinyin given name (may include middle name), in uppercase (e.g., `WEIMING`).          |
      | Chinese Name  | `homeCountryFullName` | Full name in Chinese characters, provided in `supplementaryData.homeCountryFullName`. |

      <Callout icon="thumbtack">
        * Always provide both Pinyin and Chinese character versions of the name.
        * Maintain correct character order in both formats.
        * Use uppercase for all Pinyin names.
        * Ensure UTF-8 encoding for Chinese characters.
        * All fields must be completed accurately to avoid validation errors.
      </Callout>
    </Tab>

    <Tab title="ID Card Details">
      | Field Name  | Field               | Notes                                                    |
      | ----------- | ------------------- | -------------------------------------------------------- |
      | ID Number   | `primaryIdentifier` | 18-digit ID number, no spaces or special characters.     |
      | Document ID | `documentId`        | Unique identifier for the document in FrankieOne system. |

      <Callout icon="thumbtack">
        The `documentId` uniquely identifies the document record in our system. The `primaryIdentifier` is the official government-issued ID number.
      </Callout>
    </Tab>
  </Tabs>
</Card>

**Name Handling Guidelines:**

<AccordionGroup>
  <Accordion title="Pinyin Name Format">
    Provide the applicant's name in Pinyin using uppercase letters, matching the order on the ID card.

    ```json theme={null}
    {
      "familyName": "ZHANG",     // Family name in uppercase Pinyin
      "givenName": "WEIMING"     // Given name (and middle name, if any) in uppercase Pinyin
    }
    ```

    <Callout icon="thumbtack">
      * Use uppercase letters for all Pinyin names.
      * Ensure the order and spelling match the official ID card.
      * Do not include spaces or special characters.
    </Callout>
  </Accordion>

  <Accordion title="Chinese Name Format">
    Provide the full name in Chinese characters exactly as it appears on the ID card, using UTF-8 encoding.

    ```json theme={null}
    {
      "supplementaryData": {
        "homeCountryFullName": "张伟明" // Full name in Chinese characters
      }
    }
    ```

    <Callout icon="thumbtack">
      * The Chinese name must match the ID card precisely, including character order.
      * Place this value in `supplementaryData.homeCountryFullName`.
      * Ensure correct encoding to avoid data loss.
    </Callout>
  </Accordion>
</AccordionGroup>

***

### Chinese Name Transliteration Check (Name Validation)

For enhanced identity verification, FrankieOne offers a Chinese name transliteration check. This feature verifies that an applicant’s English/Pinyin name (e.g. “Wei Wang”) is a plausible transliteration of their name written in Chinese characters (e.g. “王伟”), helping to reduce identity fraud.

The check is supported for Chinese identity documents, including the Chinese National ID and Chinese passports.

The transliteration module is built in-house by FrankieOne. It is not a third-party integration, and applicants' name data is not passed to an external transliteration provider for this step. The matching logic is based on standard transliteration rules. As an internal FrankieOne module, it does not carry an external certification.

**Note:** This check, historically known as `namev` in V1, uses FrankieOne’s in-built transliteration and name-matching capability to assess whether two name versions are a plausible match, helping to reduce the risk of identity fraud.

**How It Works & Configuration**

The transliteration check is not enabled by default. It must be configured in your workflow by the FrankieOne team as a distinct step called **`NAME_VALIDATION`**.

1. The **anglicized (English/Pinyin) name** is taken from the primary `individual.name` object (`givenName` and `familyName`).
2. The **native script (Chinese character) name** is taken from the `document.supplementaryData.homeCountryFullName` field on supported Chinese identity documents, including `NATIONAL_ID` and `PASSPORT`.
3. The `NAME_VALIDATION` step in the workflow sends these two names to the transliteration service.
4. If the native script name (`homeCountryFullName`) is not provided, the step will be skipped and the result will be `SKIPPED`.
5. When the step is executed, its outcome is added to `workflowStepResults` in the API response, with a result of `MATCH` or `NO_MATCH`.

To enable this feature, please contact your FrankieOne representative and request the `NAME_VALIDATION` step be added to your KYC workflow.

**Example Result**

When the `NAME_VALIDATION` step is executed, a `workflowStepResult` is added to the API response. The outcome is detailed within the `processResult` object, which will have a result of `MATCH` or `NO_MATCH`.

```json theme={null}
{
  "workflowStepResults": [
    {
      "stepName": "NAME_VALIDATION",
      "result": "SUCCESS",
      "processResults": [
        {
          "provider": "Frankieone",
          "objectType": "NAME",
          "class": "KYC",
          "result": "MATCH",
          "checkDate": "2025-10-15T07:40:57.000Z",
          "data": {
            "reference": "av-ref-12345",
            "message": "Name transliteration check passed."
          }
        }
      ]
    }
  ]
}
```

***

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY",
    "documentId": "92de15f64-5717-4562-b3fc-2c963f6665a7",
    "primaryIdentifier": "110105199003077341",
    "type": "NATIONAL_ID",
    "country": "CHN"
  },
  "supplementaryData": {
    "type": "NATIONAL_ID",
    "homeCountryFullName": "张伟明"
  }
}
```

<Callout icon="bell">
  ##### Important Considerations for National ID

  The Chinese National ID number contains encoded information including region code, birth date, sequence number, and checksum digit. Ensure the full 18-digit number is provided without spaces or special characters. **Common validation issues to avoid:**

  * Using incorrect order or casing for Pinyin names
  * Omitting the Chinese character version of the name
  * Missing or incorrectly formatted date of birth (`YYYY-MM-DD`)
  * Providing an invalid or incomplete ID number (must be 18 digits)
</Callout>


# Comments
Source: https://docs.frankieone.com/docs/comments



Learn how to add, retrieve, and manage comments on entity profiles for a complete audit trail.

## What are Comments?

The Comments feature allows your operators and integrated systems to programmatically add notes and observations directly to an entity's profile (both Individuals and Organisations). This functionality is essential for maintaining a comprehensive and contextual audit trail.

Every comment is timestamped and associated with the user or API key that created it, providing crucial context for compliance reviews, manual investigations, and decision-making processes.

## How It Works

The process for adding a comment is straightforward and involves a single API call.

<Steps>
  <Step title="1. Identify the Entity">
    Determine the `entityId` of the Individual or Organisation you wish to add a comment to.
  </Step>

  <Step title="2. Call the Comments Endpoint">
    Make a `POST` request to the `/v2/comments` endpoint, providing the `entityId` and the text of your comment in the request body.
  </Step>

  <Step title="3. Comment is Recorded">
    FrankieOne saves the comment, linking it to the specified entity profile and recording the author and timestamp.
  </Step>

  <Step title="4. View the Comment">
    The comment is now visible in the entity's activity history within the FrankieOne Portal and can be retrieved via the API.
  </Step>
</Steps>

***

## API Integration Guide

### Add a Comment to an Entity

To add a comment, make a `POST` request to the `/v2/comments` endpoint.

#### Request Body

The request body must contain the ID of the entity and the content of the comment.

| Field      | Type   | Required | Description                                  |
| ---------- | ------ | -------- | -------------------------------------------- |
| `entityId` | String | Yes      | The unique identifier for the entity.        |
| `comment`  | String | Yes      | The text content of the comment to be added. |

**Example Request**

```json theme={null}
{
  "entityId": "ind-0b6110e0-c167-4e69-92b0-9d3b7a5e9f7a",
  "comment": "Operator Jane Doe confirmed source of funds via phone call on Oct 15, 2025. Follow-up required in 30 days."
}
```

#### Response Body

A successful request will return a `201 Created` status code and the full comment object, including its unique `commentId` and server-generated metadata.

**Example Response**

```json theme={null}
{
  "commentId": "cmt-a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "entityId": "ind-0b6110e0-c167-4e69-92b0-9d3b7a5e9f7a",
  "comment": "Operator Jane Doe confirmed source of funds via phone call on Oct 15, 2025. Follow-up required in 30 days.",
  "createdAt": "2025-10-15T07:10:00.000Z",
  "authorId": "user-a4b2c89-1234-5678-90ab-cdef12345678",
  "authorDisplayName": "Jane Doe"
}
```

<Callout icon="thumbtack">
  The `authorId` and `authorDisplayName` are automatically determined from the authentication context (API Key or user session) of the request.
</Callout>

***

## Common Use Cases

Adding comments via the API is useful for a variety of scenarios:

* **Documenting Manual Actions:** Record notes from offline actions, such as phone calls or in-person meetings.
* **Explaining Overrides:** Provide justification when a compliance officer manually overrides a workflow decision or an automated check result.
* **Integrating External System Data:** Push alerts or notes from third-party case management or fraud systems into the FrankieOne entity profile.
* **Case Management:** Allow operators to add notes and updates as they investigate a case, creating a running log of their findings.


# Managing Duplicate Entities
Source: https://docs.frankieone.com/docs/duplicate-checks



A detailed guide to detecting, reviewing, and resolving duplicate customer records using FrankieOne's automated workflow step.

## What are Duplicate Checks?

Duplicate checks are essential for maintaining data integrity, reducing fraud risk, and ensuring compliance. They prevent the creation of multiple records for the same individual within your system.

FrankieOne integrates this capability directly into your KYC workflow via a dedicated **`DUPLICATE`** step. This step provides:

* **Automated identification** of possible duplicates using configurable, rules-based matching logic.
* **Manual review and resolution** capabilities for operators to confirm or dismiss flagged duplicates.
* **Seamless integration** with existing KYC processes to support both operational efficiency and regulatory compliance.

<Callout icon="star">
  To implement duplicate checks, you must have the `DUPLICATE` step added to your KYC workflow. **Speak with your FrankieOne representative to configure the duplicate step and its matching rules.**
</Callout>

***

## How Duplicate Checks Work

The process is designed to flag potential duplicates during onboarding and provide your team with the tools to resolve them.

<Steps>
  <Step title="1. Workflow Execution">
    When you execute a workflow for a new or updated entity, the `DUPLICATE` step runs. It compares the entity's attributes (e.g., name, DOB, document number) against all other entities in your system based on your configured matching rules.
  </Step>

  <Step title="2. A 'HIT' is Returned">
    If a potential duplicate is found, the workflow step returns a `result` of `HIT`, and a `DUPLICATE` issue is created. This typically causes the overall workflow `status` to become `REVIEW`.
  </Step>

  <Step title="3. Detailed Results are Generated">
    For each potential duplicate found, a Process Result Object (PRO) is created. This PRO contains the granular details of the match, including which fields matched and the `entityId` of the potential duplicate.
  </Step>

  <Step title="4. Operator Review and Resolution">
    Your compliance team reviews the evidence within the PROs and makes a decision. They then resolve the match by calling the API to update the PRO's `manualStatus`.
  </Step>

  <Step title="5. State and Relationships are Updated">
    Based on the operator's resolution, the system updates the service profile states (e.g., marking one entity as `DUPLICATE`) and creates a permanent `relationship` between the two entities for future reference.
  </Step>
</Steps>

***

## Implementation and API Guide

### Step 1: Interpreting the Duplicate Check Result

When the `DUPLICATE` step returns a `HIT`, you need to parse the `processResults` within that step to understand the match. Each PRO will have `class: "DUPLICATE"`.

The most important information is in the **`supplementaryData`** object.

<Accordion title="Example: supplementaryData for a Duplicate PRO">
  ```json theme={null}
  {
      "processResultId": "01JNFWT5MKE75FMMZPWC7SDG2Z",
      "result": "HIT",
      "class": "DUPLICATE",
      "stepName": "DUPLICATE",
      "supplementaryData": {
          "type": "DUPLICATE",
          "duplicateEntityId": "98c545b6-7545-4337-85ce-30c64ef1ccff",
          "matchedFields": [
              {
                  "objectType": "NAME",
                  "objectId": "840268d6-d37e-43ad-a421-d35345472df4",
                  "duplicateObjectId": "4331b636-5cb2-46d6-bba1-03536232909b",
                  "matchStrength": 86
              },
              {
                  "objectType": "ADDRESS",
                  "objectId": "9c5fdaeb-056a-47c7-a36e-dcb59ddce5b3",
                  "duplicateObjectId": "c0d6872f-dd14-43f2-86b2-60e1e7ae24c4",
                  "matchStrength": 100
              }
          ],
          "matchedRules": [
              {
                  "name": "Given + Family name + Short form normalised address",
                  "strength": "HIGH"
              }
          ]
      }
  }
  ```
</Accordion>

**Key `supplementaryData` Fields:**

* `duplicateEntityId`: The `entityId` of the existing profile that was matched.
* `matchedFields`: An array detailing exactly which attributes matched between the two entities (e.g., `NAME`, `ADDRESS`). It includes the specific `objectId` for each attribute and the `matchStrength`.
* `matchedRules`: Shows which configured rule was triggered to create this match.

### Step 2: Resolving Duplicates

After reviewing the evidence, an operator must classify the match. This is done by sending a `PATCH` request with the `processResultId` and a `manualStatus`.

**Endpoint:**

```http theme={null}
    PATCH /v2/individuals/{entityId}/results/duplicate
```

**Understanding the Manual Statuses**
The `manualStatus` you send should reflect the operator's decision.

| Operator's Decision                                                                   | `manualStatus` to Send | Outcome                                                                               |
| :------------------------------------------------------------------------------------ | :--------------------- | :------------------------------------------------------------------------------------ |
| "This is **not a duplicate**."                                                        | `FALSE_POSITIVE`       | The potential match is dismissed. No relationship is created.                         |
| "This is a duplicate. **Keep the new entity** and mark the old one as the duplicate." | `TRUE_POSITIVE_ACCEPT` | A relationship is created. The old entity's service profile is marked as `DUPLICATE`. |
| "This is a duplicate. **Keep the old entity** and mark the new one as the duplicate." | `TRUE_POSITIVE_REJECT` | A relationship is created. The new entity's service profile is marked as `DUPLICATE`. |

<Accordion title="Example: Resolve a Duplicate as False Positive">
  ```bash theme={null}
      curl -X PATCH \
      '{{baseHost}}/v2/individuals/{{entityId}}/results/duplicate' \
      -H 'api_key: YOUR_API_KEY' \
      -H 'X-Frankie-CustomerID: YOUR_CUSTOMER_ID' \
      -d '{
          "processResults": [
              "01JNFWT5MKE75FMMZPWC7SDG2Z"
          ],
          "manualStatus": "FALSE_POSITIVE",
          "comment": {
              "text": "Reviewed by operator. Confirmed different individuals with similar names."
          }
      }'
  ```
</Accordion>

<Callout icon="thumbtack">
  After resolving all duplicate-related `issues`, you should **re-run the workflow**. The `DUPLICATE` step will re-evaluate based on your resolutions, and the overall workflow `status` can then update from `REVIEW` to `PASS`.
</Callout>

***

## Key Concepts: State and Relationships

* **Relationships**: When a duplicate is confirmed (`TRUE_POSITIVE_ACCEPT` or `TRUE_POSITIVE_REJECT`), a permanent `relationship` is created between the two entities. You can see this in the response of `GET /v2/individuals/{entityId}` under the `relationships.duplicates` array.
* **`DUPLICATE` State**: An entity's service profile is moved to the `DUPLICATE` state when a relationship identifies it as such. An entity remains a duplicate as long as at least one relationship points to it. If all such relationships are removed (e.g., by being marked as `FALSE_POSITIVE` or if the source entity is deleted), its `DUPLICATE` state will be revoked.

***

## Configuration (Reference)

The matching logic for the `DUPLICATE` step is highly configurable by the FrankieOne team.

<Accordion title="Example duplicate.json Matching Rules">
  ```json theme={null}
  {
      "ruleSets": {
          "default": {
              "rules": [
                  {
                      "name": "Document identifiers",
                      "matchFields": [ "DOC_PRIMARY_IDENTIFIER", "DOC_TYPE", "DOC_COUNTRY" ],
                      "method": "EXACT",
                      "riskFactor": "VERY_HIGH"
                  },
                  {
                      "name": "Given + Family name + Date of birth",
                      "matchFields": [ "GIVEN_NAME", "FAMILY_NAME", "DATE_OF_BIRTH" ],
                      "method": "EXACT",
                      "riskFactor": "VERY_HIGH"
                  }
              ]
          }
      }
  }
  ```
</Accordion>

### Duplicate Check Logic

FrankieOne's duplicate detection uses configurable rules to compare key attributes between entities. If any rule is matched, the entity is flagged as a potential duplicate.

**Matching Rule Examples:**

* **External Reference:** Exact match on `EXTERNAL_REFERENCE`.
* **Document Identifiers:** Exact match on all of `DOC_PRIMARY_IDENTIFIER`, `DOC_SECONDARY_IDENTIFIER`, `DOC_COUNTRY`, `DOC_SUBDIVISION`, and `DOC_TYPE`.
* **Phone Number:** Exact match on `PHONE_NUMBER`.
* **Email Address:** Exact match on `EMAIL_ADDRESS`.
* **Full Name:** Exact match on both `GIVEN_NAME` and `FAMILY_NAME`.
* **Full Name + Date of Birth:** Exact match on `GIVEN_NAME`, `FAMILY_NAME`, and `DATE_OF_BIRTH`.
* **Full Name + Normalised Address:** Exact match on `ADDR_NORM_SHORT`, `GIVEN_NAME`, and `FAMILY_NAME`.

All rules use exact matching. You can customise which rules are active and their risk levels by working with FrankieOne.


# A Detailed Guide to eKYC Rulesets
Source: https://docs.frankieone.com/docs/ekyc-rulesets



An in-depth guide to how FrankieOne’s KYC rulesets power your verification workflows and help you meet regional compliance requirements.

## What is a KYC Ruleset?

> *A KYC Ruleset is the engine that drives a verification decision within a FrankieOne workflow.* <br />
> *It’s a pre-configured set of logical conditions that defines exactly what is required for a customer’s identity to be considered verified.*

When you execute a KYC workflow, the ruleset is applied to the customer’s data. The workflow checks this data against various independent sources (like credit bureaus or government databases), and the ruleset determines if the returned matches are sufficient to meet your specific compliance and business needs.

FrankieOne provides standard, out-of-the-box rulesets designed to meet common regulatory requirements in different regions, such as **Australia’s 2+2 verification** or **Canada’s FINTRAC methods**.

***

## How Rulesets Work

At its core, a ruleset is based on two simple principles:

<Steps>
  <Step title="It defines WHAT to match">
    * **name** : The customer’s full name.
    * **dob** : The customer’s date of birth.
    * **address** : The customer’s residential address.
    * **gov\_id** : A government-issued document like a passport or driver’s licence.
  </Step>

  <Step title="It defines HOW MANY matches are needed">
    For each piece of information, the ruleset defines the **minimum number of successful matches** required from independent data sources.\
    *Example: A rule might require that the customer’s name be successfully matched against at least**two** different sources.*
  </Step>
</Steps>

By combining these conditions, rulesets can accommodate a wide range of verification scenarios — from simple identity checks to complex, multi-source regulatory requirements — ensuring workflows remain flexible and compliant.

***

## Standard Ruleset Library

Below is a detailed breakdown of the common rulesets you’ll encounter when using FrankieOne’s standard workflows.

***

### 1. Australia: `two_plus` (Standard 2+2)

> ***Purpose:** Meets AML/CTF compliance in Australia.*

* **What it does:** Verifies an individual’s identity by matching their information against at least two independent data sources. As part of the upcoming changes to AML/CTF regulation, this ‘safe harbour’ model is being phased out in favour of a risk-based approach which will also be open to biometrics and digital IDs. These changes are expected for existing entities by **31st March 2026**.
* **Logic:** Requires **2× Name Matches** **AND** a combined total of **2× Address/DOB Matches**.

<Callout icon="bell" title="For awareness">
  Australia’s AML/CTF regulations are evolving toward a risk-based approach and now recognize biometrics and digital IDs as valid verification methods. For details on upcoming changes—affecting existing entities from 31 March 2026 and new regulated entities from July 2026—refer to AUSTRAC’s official guidance.
</Callout>

#### Passing Combinations

| Combination | Name Matches | Address Matches | DOB Matches |
| :---------- | :----------- | :-------------- | :---------- |
| **1**       | 2            | 2               | 0           |
| **2**       | 2            | 0               | 2           |
| **3**       | 2            | 1               | 1           |

***

### 2. Australia: `two_plus_gov_id` (2+2 with Gov ID)

> ***Purpose:** Higher-assurance variant of 2+2, mandates successful verification of a Government ID.*

* **What it does:** Increases confidence by tying the electronic verification to a physical document.
* **Logic:** Requires **2× Name Matches** **AND** **1× Gov ID Match** **AND** a combined total of **2× Address/DOB Matches**.

#### Passing Combinations

| Combination | Name Matches | Address Matches | DOB Matches | Gov ID Matches |
| :---------- | :----------- | :-------------- | :---------- | :------------- |
| **1**       | 2            | 2               | 0           | 1              |
| **2**       | 2            | 0               | 2           | 1              |
| **3**       | 2            | 1               | 1           | 1              |

***

### 3. International: `one_plus` (Standard 1+1)

> ***Purpose:** Flexible ruleset for global use cases where a single-source verification is sufficient.*

* **What it does:** Verifies an individual’s identity against at least one reliable data source.
* **Logic:** Requires **1× Name Match** **AND** **1× Address or DOB Match**.

#### Passing Combinations

| Combination | Name Matches | Address Matches | DOB Matches |
| :---------- | :----------- | :-------------- | :---------- |
| **1**       | 1            | 1               | 0           |
| **2**       | 1            | 0               | 1           |

***

### 4. Document-centric: `gov_id_only`

> ***Purpose:** Relies solely on the verification of a government-issued document against an authoritative source.*

* **What it does:** Confirms the authenticity of a provided ID document quickly.
* **Logic:** Requires **1× Name Match** , **1× DOB Match** , **AND** **1× Gov ID Match** from the same document verification source.

#### Passing Combinations

| Combination | Name Matches | DOB Matches | Gov ID Matches |
| :---------- | :----------- | :---------- | :------------- |
| **1**       | 1            | 1           | 1              |

***

### 5. Flexible Onboarding: `gov_id_with_alternative`

> ***Purpose:** Prioritizes Government ID verification but provides the standard “2+2” check as a fallback.*

* **What it does:** Optimizes conversion rates by providing two compliant pathways for verification in a single workflow.
* **Logic:** Passes if **EITHER** of these conditions are met:
  * **Path A:** 1× Gov ID Match.
  * **OR**
  * **Path B:** 2× Name Matches **AND** 2× Address/DOB Matches.

#### Passing Combinations

| Part  | Name Matches | Address Matches | DOB Matches | Gov ID Matches |
| :---- | :----------- | :-------------- | :---------- | :------------- |
| **A** | 1            | -               | 1           | 1              |
| **B** | 2            | 2               | 0           | -              |
| **B** | 2            | 0               | 2           | -              |
| **B** | 2            | 1               | 1           | -              |

***

### 6. High Assurance: `safe_harbour_gov_id`

> ***Purpose:** High-assurance ruleset for the strictest compliance needs, mandating multiple government ID verifications.*

* **What it does:** Offers the highest level of assurance outside of a full biometric check by requiring two separate document verifications.
* **Logic:** Requires **2× Name Matches** , **2× Gov ID Matches** , **AND** **2× Address/DOB Matches**.

#### Passing Combinations

| Combination | Name Matches | Address Matches | DOB Matches | Gov ID Matches |
| :---------- | :----------- | :-------------- | :---------- | :------------- |
| **1**       | 2            | 2               | 0           | 2              |
| **2**       | 2            | 0               | 2           | 2              |
| **3**       | 2            | 1               | 1           | 2              |

***

### 7. International: `one_plus_gov_id` (1+1 with Gov ID)

> ***Purpose:** “1+1” ruleset that mandates the inclusion of a Government ID verification.*

* **What it does:** Combines the assurance of a document check with the breadth of an electronic data source check.
* **Logic:** Requires **1× Name Match** , **1× Gov ID Match** , **AND** **1× Address or DOB Match**.

#### Passing Combinations

| Combination | Name Matches | Address Matches | DOB Matches | Gov ID Matches |
| :---------- | :----------- | :-------------- | :---------- | :------------- |
| **1**       | 1            | 1               | 0           | 1              |
| **2**       | 1            | 0               | 1           | 1              |

***

### 8. Digital Services: `one_plus_dob_gov_id`

> ***Purpose:** Requires Name, DOB, and a Government ID, with no address component.*

* **What it does:** Focuses on verifying core identity (name, age) via a government document without the potential failure point of an address mismatch.
* **Logic:** Requires **1× Name Match** , **1× DOB Match** , **AND** **1× Gov ID Match**.

#### Passing Combinations

| Combination | Name Matches | DOB Matches | Gov ID Matches |
| :---------- | :----------- | :---------- | :------------- |
| **1**       | 1            | 1           | 1              |

***

### 9. Age-Restricted Services: `two_plus_age`

> ***Purpose:** Specialized ruleset to verify an individual’s age with high confidence.*

* **What it does:** Allows businesses to confidently verify a user is over a certain age. The “OR” logic provides flexibility to increase pass rates.
* **Logic:** Passes if **EITHER** of these conditions are met:
  * **Path A:** 2× Name Matches **AND** 2× DOB Matches.
  * **OR**
  * **Path B:** 2× Name Matches **AND** 1× DOB Match **AND** 1× Address Match.

<Callout icon="thumbtack">
  **Best Practice for Age Verification:** Government-issued IDs are the most reliable data source for age verification as they provide an exact match against official records. When using consumer or commercial data sources, it is critical to review fuzziness settings to ensure they are set to require an exact match for the Date of Birth to avoid false negatives.
</Callout>

#### Passing Combinations

| Part  | Name Matches | Address Matches | DOB Matches |
| :---- | :----------- | :-------------- | :---------- |
| **A** | 2            | 0               | 2           |
| **B** | 2            | 1               | 1           |

***

### 10a. Address-centric: `two_plus_address`

> ***Purpose:** Specialized ruleset to verify an individual’s address with high confidence.*

* **What it does:** Helps meet Proof of Address (POA) requirements by ensuring an address match is always part of a successful verification.
* **Logic:** Passes if **EITHER** of these conditions are met:
  * **Path A:** 2× Name Matches **AND** 1× DOB Match **AND** 1× Address Match.
  * **OR**
  * **Path B:** 2× Name Matches **AND** 2× Address Matches.

#### Passing Combinations

| Part  | Name Matches | Address Matches | DOB Matches |
| :---- | :----------- | :-------------- | :---------- |
| **A** | 2            | 1               | 1           |
| **B** | 2            | 2               | 0           |

### 10b. Address-centric: one\_plus\_address

Purpose: International use case requiring name and address verification against a single data source, where address confirmation is mandatory.

What it does: Verifies an individual's identity by matching their name and current address against at least one independent data source. Unlike the standard one\_plus ruleset — which accepts either an address or a date of birth as the secondary match — this variant specifically mandates a successful address match. A DOB match alone is not sufficient to pass.
Logic: Requires 1× Name Match AND 1× Address Match.

#### Passing Combinations

| Part  | Name Matches | Address Matches | DOB Matches |
| :---- | :----------- | :-------------- | :---------- |
| **A** | 1            | 1               | 1           |
| **B** | 1            | 1               | 0           |

***

### 11. USA: `us_onboarding`

> ***Purpose:** Standard ruleset for US-based onboarding that aligns with common Customer Identification Program (CIP) requirements.*

* **What it does:** Provides a clear pathway to meeting baseline US federal requirements for customer identity verification under the Bank Secrecy Act (BSA).
* **Logic:** Requires **1× Name Match** , **1× DOB Match** , **1× Address Match** , **AND** **1× Gov ID Match** (e.g., an SSN).

#### Passing Combinations

| Combination | Name Matches | DOB Matches | Address Matches | Gov ID Matches |
| :---------- | :----------- | :---------- | :-------------- | :------------- |
| **1**       | 1            | 1           | 1               | 1              |

***

### 12. Canada: `ca_fintrac`

> ***Purpose:** Multi-part ruleset designed to meet Canadian compliance requirements. Provides two distinct pathways for verification; a customer only needs to pass **one**.*

* **What it does:** Verifies identity using one of the methods prescribed by the Financial Transactions and Reports Analysis Centre of Canada (FINTRAC).

#### Method 1: The Credit File Method

> *Most common method. Requires matching the customer’s full name, date of birth, and address against a Canadian credit file.*

| Name Matches | DOB Matches | Address Matches | Source Requirement                                       |
| :----------- | :---------- | :-------------- | :------------------------------------------------------- |
| 1            | 1           | 1               | All must come from a single Canadian Credit Bureau file. |

#### Method 2: The Dual Process Method

> *Alternative if the customer doesn’t have a credit file. Involves matching their information against two different, reliable sources.*

| Name Matches | DOB Matches | Address Matches | Source Requirement                                       |
| :----------- | :---------- | :-------------- | :------------------------------------------------------- |
| 2            | 2           | 2               | Must be from two different and independent data sources. |

***

## Next Steps

Now that you understand the logic behind our rulesets, see our\
**[Electronic KYC with Government ID](/docs/electronic-kyc-checks)** guide for a step-by-step walkthrough of how to execute a workflow that uses one of these rulesets.


# Electronic KYC with Government ID
Source: https://docs.frankieone.com/docs/electronic-kyc-checks

A step-by-step guide to verifying a customer's identity electronically using their personal information and a government-issued ID.

## What is an Electronic KYC (eKYC) Check?

An electronic Know Your Customer (eKYC) check is the standard process for verifying a customer's identity against digital data sources. This guide focuses on a common and robust method: verifying a customer's personal information (name, DOB, address) along with a government-issued identity document.

This process is fundamental to meeting your compliance obligations under regulations like Australia's Anti-Money Laundering and Counter-Terrorism Financing (AML/CTF) Act, which requires matching customer data against reliable and independent sources.

## How It Works

The process involves two main API interactions:

<Steps>
  <Step title="1. Create an Entity Profile">
    First, you create a complete digital profile of your customer by sending their personal details and government ID information to the FrankieOne API. This creates a unique `entityId` for the customer.
  </Step>

  <Step title="2. Execute a KYC Workflow">
    Next, you trigger a pre-configured workflow using the `entityId`. This workflow takes the entity's data and securely checks it against trusted third-party sources, such as the Australian Government's Document Verification Service (DVS) and credit bureaus, to find matches.
  </Step>
</Steps>

***

## Implementation Guide

This guide will walk you through the API calls required to perform a standard eKYC verification.

### Step 1: Create an Individual with a Government ID

To begin, create an entity by calling the `POST /v2/individuals` endpoint. The request below shows how to create an individual with a name, date of birth, address, an Australian Passport, and the necessary consents.

```curl cURL theme={null}
  curl --location '[https://api.frankie.one/v2/individuals](https://api.frankie.one/v2/individuals)' \
  --header 'api_key: {{your_api_key}}' \
  --header 'X-Frankie-CustomerID: {{your_customer_id}}' \
  --header 'Content-Type: application/json' \
  --data '{
      "individual": {
          "name": {
              "givenName": "MARY",
              "familyName": "TESTFOURTEEN"
          },
          "dateOfBirth": {
              "year": "1963",
              "month": "01",
              "day": "01"
          },
          "addresses": [
              {
                  "type": "RESIDENTIAL",
                  "streetName": "NINGALOO",
                  "streetNumber": "12",
                  "streetType": "STREET",
                  "locality": "EXMOUTH",
                  "subdivision": "WA",
                  "country": "AUS",
                  "postalCode": "6707"
              }
          ],
          "documents": {
              "IDENTITY": [
                {
                  "type": "PASSPORT",
                  "primaryIdentifier": "P52184975",
                  "country": "AUS"
                }
              ]
          },
          "consents": [
              { "type": "GENERAL" },
              { "type": "DOCS" }
          ]
      }
  }'
```

A successful `201 Created` response will contain the full entity profile, including the unique `entityId`. **You must store this `entityId`** as it is required for all subsequent API calls for this individual.

### Step 2: Execute the KYC Workflow

Now, use the `entityId` from the previous step to execute your verification workflow. The `workflowName` in this example is `AUS-Basic1V-IDOnly`.

```curl HTTP  theme={null}
  curl --location --request POST '[https://api.frankie.one/v2/individuals/](https://api.frankie.one/v2/individuals/){{entityId}}/serviceprofiles/DEFAULT/workflows/AUS-Basic1V-IDOnly/execute' \
  --header 'api_key: {{your_api_key}}' \
  --header 'X-Frankie-CustomerID: {{your_customer_id}}'
```

A successful execution returns a `workflowResult` object containing the complete outcome of the verification.

### Interpreting the KYC Result

The `workflowResult` object contains rich information about the verification.

#### The High-Level Verdict

For automated decision-making, start with these top-level fields:

* **`status`**: This is the definitive recommendation. The most common values are `PASS`, `FAIL`, or `REVIEW`.
* **`workflowExecutionState`**: This must be `COMPLETED`. If it's anything else (e.g., `ERROR`, `TIMEOUT`), the workflow did not finish, and the `status` should not be trusted as final.

#### The KYC Step Details

To understand *why* the workflow passed or failed, find the `KYC` object within the `workflowStepResults` array.

* **`result`**: The outcome of the KYC step itself, typically `MATCH` or `NO_MATCH`.
* **`summary`**: A summary object explaining how the result was reached. The `matchedRules` array shows which data sources were successfully matched (`matchDetails`) and if the overall verification criteria were met (`isVerified: true`).

```json theme={null}
"workflowStepResults": [
  {
    "stepName": "KYC",
    "result": "MATCH",
    "summary": {
      "matchedRules": [
        {
          "ruleName": "gov_id_only",
          "isVerified": true,
          "matchDetails": [
            {
              "provider": "con_testbed-docs",
              "source": "au-govid1-pp",
              "attributesMatched": [ "dateOfBirth", "govId", "name" ]
            }
          ]
        }
      ]
    }
  }
]
```

***

## Best Practices for Integration

* **Trust the `status` field** as the final, authoritative outcome for your business logic.
* **Always check `workflowExecutionState`** to ensure the workflow `COMPLETED` successfully before actioning the result.
* **Log the `workflowExecutionId`** with every result. This is the key identifier for support, auditing, and debugging.
* **Build logic to handle the `REVIEW` status**. When you receive a `REVIEW`, your system should flag the case for manual investigation by a compliance officer. The `issues` array in the workflow result will tell them where to look.

## Next Steps

This guide provides a high-level overview of the eKYC result. For a complete reference of every field in the response, see the **[Interpreting Workflow Results](/docs/interpreting-workflows-v2)** guide.


# Error Handling
Source: https://docs.frankieone.com/docs/error-handling

The FrankieOne API uses a standardized error format to ensure that you can reliably handle issues that arise from bad requests, server problems, or invalid data. All non-2xx responses will return a consistent JSON error object.

This guide explains the structure of the error object, provides a full list of error codes, and offers practical advice on how to handle these errors in your frontend application.

***

## The Error Object

All errors returned from the FrankieOne API are wrapped in a standard `ErrorObject`.

| Attribute             | Type    | Description                                                                                                          |
| :-------------------- | :------ | :------------------------------------------------------------------------------------------------------------------- |
| errorCode             | string  | A unique code in the format `PREFIX-NUMBER` that identifies the error.                                               |
| errorMsg              | string  | A human-readable message summarizing the error.                                                                      |
| httpStatusCode        | integer | The standard HTTP status code for the response (e.g., 400, 404, 500).                                                |
| details               | array   | An array of issue objects providing specific context about what went wrong.                                          |
| details.issue         | string  | A detailed description of the specific issue.                                                                        |
| details.issueLocation | string  | The location in the request payload, path, or header where the issue occurred (e.g., `body.individual.dateOfBirth`). |
| requestId             | string  | The unique ID for the API request, which should be logged and provided to support if you need assistance.            |

***

### Example Error Object

Here is an example of an error returned due to an invalid date of birth format in the request body.

```json theme={null}
{
  "errorCode": "VAL-1002",
  "errorMsg": "Data supplied is incorrect/badly formatted",
  "httpStatusCode": 400,
  "details": [
    {
      "issue": "Invalid format. Must be YYYY-MM-DD",
      "issueLocation": "dateOfBirth"
    }
  ],
  "requestId": "01HN9XHZN6MGXM9JXG50K59Q85"
}
```

***

## Understanding Error Codes

The `errorCode` is a combination of a prefix (the Issue Location) and a number. This structure helps you quickly identify the source of the problem.

### Issue Location Codes (Prefix)

| Prefix | Description                                                                                                                |
| :----- | :------------------------------------------------------------------------------------------------------------------------- |
| API    | Errors in your API message, such as an incorrectly constructed URL or method.                                              |
| AUTH   | Authorization or security-related errors, like a missing or invalid API key.                                               |
| VAL    | API data validation errors. The details array will specify which fields are invalid.                                       |
| ENT    | Errors related directly to Entity functions (e.g., an entity not found).                                                   |
| DOC    | Errors related directly to Document functions.                                                                             |
| CHECK  | Errors related to Check/Verify functions. Indicates a problem with performing a check, not the result of the check itself. |
| SYS    | System-level errors on the FrankieOne side. These may be temporary.                                                        |
| CODE   | Unexpected errors detected in the code. Please contact support if you see these.                                           |
| ADMIN  | Admin API errors. Please contact developer support if you receive one.                                                     |

***

## Frontend Orchestration & Handling Errors

A robust frontend application should interpret the HTTP status code and the errorCode to present the user with a clear and helpful message.

### 400 - Bad Request (VAL-xxxx)

This is the most common error category. It means the user has provided invalid or incomplete data. Your frontend should parse the `details` array to provide specific feedback.

#### Scenario: A user submits a form with an invalid date of birth and a missing family name.

**Example Response:**

```json theme={null}
{
  "errorCode": "VAL-1001",
  "errorMsg": "Missing required field",
  "httpStatusCode": 400,
  "details": [
    {
      "issue": "The 'familyName' field is required but was not provided",
      "issueLocation": "body.individual.name.familyName"
    },
    {
      "issue": "The dateOfBirth is invalid, provide a valid date",
      "issueLocation": "dateOfBirth"
    }
  ],
  "requestId": "01HMR2ERSKCYAVXKS1FKSRT2T4"
}
```

**Frontend Action:**

* Iterate through the `details` array.
* For each issue, use the `issueLocation` to find the corresponding input field in your form.
* Display the issue message directly below that field.

This provides targeted, inline validation feedback to the user so they can easily correct their mistakes.

***

### 404 - Not Found (API-1010)

This means the resource you requested (like an entityId or workflowExecutionId) does not exist.

#### Scenario: Your application tries to fetch results for a workflow that has been deleted or whose ID is incorrect.

**Example Response:**

```json theme={null}
{
  "errorCode": "API-1010",
  "errorMsg": "Requested resource is not found",
  "httpStatusCode": 404,
  "details": [
    {
      "issue": "The specified resource '01BFJA617JMJXEW6G7TDDXNSHX' of type 'entity' does not exist",
      "issueLocation": "path"
    }
  ],
  "requestId": "01BFJA617JMJXEW6G7TDDXNSHX"
}
```

**Frontend Action:**

* Check for the 404 status code.
* Redirect the user to a "Not Found" page or display a clear message like "We could not find the record you were looking for. Please check the ID or start a new search."
* Avoid showing a generic "An error occurred" message, as this is a specific and actionable state.

***

### 5xx - Server & System Errors (SYS-xxxx)

These errors indicate a problem on FrankieOne's side. The issue may be temporary.

#### Scenario: A service provider required for a check is temporarily unavailable.

**Example Response:**

```json theme={null}
{
  "errorCode": "SYS-0007",
  "errorMsg": "No service providers available/configured. Contact developer support",
  "httpStatusCode": 503,
  "details": [
    {
      "issue": "The service is temporarily unavailable",
      "issueLocation": "server"
    }
  ],
  "requestId": "01GVEDZ0C1Q9NWQ699DBBKPE4Y"
}
```

**Frontend Action:**

* Check for any 5xx status code (500, 503, etc.).
* Display a generic, user-friendly message, such as: "We're sorry, something went wrong on our end. Please try again in a few moments."
* Do not display the technical `errorMsg` to the user.
* You may implement a retry mechanism with exponential backoff for 503 errors, as these are often transient.
* Log the full error response, including the `requestId`, so you can report it to support if the issue persists.

***

## Full List of Error Codes

<Accordion title="System Errors (0000 - 0399)">
  Returned by internal processes. Generally indicate a temporary issue, but please contact developer support if the issue persists.

  | Error Number | HTTP Error Code | Description                                                                                                               |
  | :----------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------ |
  | 0000         | 500             | Unknown internal error. Contact developer support                                                                         |
  | 0001         | 500             | Internal error. Contact developer support.                                                                                |
  | 0002         | 401             | Not authorised to perform this function                                                                                   |
  | 0003         | 500             | Internal error. Contact developer support.                                                                                |
  | 0004         | 500             | Internal error. Contact developer support.                                                                                |
  | 0005         | 500             | Internal error. Contact developer support.                                                                                |
  | 0006         | 500             | Internal error. Contact developer support.                                                                                |
  | 0007         | 503             | No service providers available/configured. Contact developer support                                                      |
  | 0008         | 503             | No document scanning service available/configured. Contact developer support                                              |
  | 0009         | 503             | No document verification service available/configured. Contact developer support                                          |
  | 0010         | 503             | No comparison service available/configured. Contact developer support                                                     |
  | 0011         | 503             | No industry service available/configured. Contact developer support                                                       |
  | 0012         | 501             | Requested service (comparison) isn't supported for your current configuration. Contact developer support.                 |
  | 0013         | 501             | Requested service (scan) isn't supported for your current configuration. Contact developer support.                       |
  | 0014         | 501             | Requested service (document verify) isn't supported for your current configuration. Contact developer support.            |
  | 0015         | 501             | Requested service (industry function) isn't supported for your current configuration. Contact developer support.          |
  | 0016         | 501             | Requested service (entity verify) isn't supported for your current configuration. Contact developer support.              |
  | 0017         | 501             | Requested service (specific entity check type) isn't supported for your current configuration. Contact developer support. |
  | 0018         | 503             | No entity verification service available/configured. Contact developer support                                            |
  | 0019         | 503             | Internal error. Contact developer support.                                                                                |
  | 0020         | 500             | Internal error. Contact developer support.                                                                                |
  | 0021         | 500             | Internal error. Contact developer support.                                                                                |
  | 0022         | 500             | Internal error. Contact developer support.                                                                                |
  | 0023         | 500             | Internal error. Contact developer support.                                                                                |
  | 0024         | 500             | Internal error. Contact developer support.                                                                                |
  | 0025         | 500             | Internal error. Contact developer support.                                                                                |
  | 0026         | 500             | Internal error. Contact developer support.                                                                                |
  | 0027         | 500             | Internal error. Contact developer support.                                                                                |
  | 0028         | 500             | Internal error. Contact developer support.                                                                                |
  | 0029         | 500             | Internal error. Contact developer support.                                                                                |
  | 0030         | 500             | Internal error. Contact developer support.                                                                                |
  | 0031         | 500             | Internal error. Contact developer support.                                                                                |
  | 0032         | 500             | Cache retrieve error. Contact developer support.                                                                          |
  | 0033         | 500             | Internal error. Contact developer support.                                                                                |
  | 0034         | 500             | Internal error. Contact developer support.                                                                                |
  | 0035         | 503             | Push to mobile service not available                                                                                      |
</Accordion>

<Accordion title="Generic Errors (0400 - 0599)">
  Returned when no distinct error code is available (usually internal framework generated).

  | Error Number | HTTP Error Code | Description                                       |
  | :----------- | :-------------- | :------------------------------------------------ |
  | 400          | 400             | Generic 400 Error - See error message for details |
  | 401          | 401             | Generic 401 Error - See error message for details |
  | 404          | 404             | Generic 404 Error - See error message for details |
  | 405          | 405             | Generic 405 Error - See error message for details |
  | 415          | 415             | Generic 415 Error - See error message for details |
  | 422          | 422             | Generic 422 Error - See error message for details |
  | 429          | 429             | Generic 429 Error - See error message for details |
  | 500          | 500             | Generic 500 Error - See error message for details |
  | 501          | 501             | Generic 501 Error - See error message for details |
  | 503          | 503             | Generic 503 Error - See error message for details |
</Accordion>

<Accordion title="Header Errors (0800 - 0999)">
  The API returns these errors when it receives unsupported or missing header data.

  | Error Number | HTTP Error Code | Description                 |
  | :----------- | :-------------- | :-------------------------- |
  | 801          | 400             | Missing header: RequestID   |
  | 802          | 400             | Missing header: CheckID     |
  | 901          | 400             | Malformed header: RequestID |
  | 902          | 400             | Malformed header: CheckID   |
</Accordion>

<Accordion title="Application & Service Errors (1000 - )">
  The API returns these errors when it encounters issues with specific requests.

  | Error Number | HTTP Error Code | Description                                                                                                                                |
  | :----------- | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
  | 1001         | 400             | Blank value supplied when one needed                                                                                                       |
  | 1002         | 400             | Data supplied is incorrect/badly formatted.                                                                                                |
  | 1003         | 405             | Can't merge different documents or entities                                                                                                |
  | 1004         | 400             | Can't set document ID                                                                                                                      |
  | 1005         | 400             | Data conversion issue                                                                                                                      |
  | 1006         | 422             | Document supplied is unparsable                                                                                                            |
  | 1007         | 400             | Can't set entity ID                                                                                                                        |
  | 1008         | 400             | Entity supplied is unparsable                                                                                                              |
  | 1009         | 404             | Requested document isn't found                                                                                                             |
  | 1010         | 404             | Requested entity isn't found                                                                                                               |
  | 1011         | 422             | Not enough data supplied to perform requested check                                                                                        |
  | 1012         | 500             | Can't mark record as deleted                                                                                                               |
  | 1013         | 400             | Utility bill not supplied                                                                                                                  |
  | 1014         | 400             | Document not a PDF when PDF expected                                                                                                       |
  | 1015         | 400             | Scan data not supplied when scan expected                                                                                                  |
  | 1016         | 501             | Error response returned from utility processor                                                                                             |
  | 1017         | 202             | Verification results incomplete - expect a notification push                                                                               |
  | 1018         | 415             | Media type not supported                                                                                                                   |
  | 1019         | 400             | End date before start date                                                                                                                 |
  | 1020         | 400             | Bad page number                                                                                                                            |
  | 1021         | 400             | Bad page count request                                                                                                                     |
  | 1022         | 404             | Requested check ID not found                                                                                                               |
  | 1023         | 404             | Can't retrieve original document                                                                                                           |
  | 1024         | 404             | Cache returned a nil result                                                                                                                |
  | 1025         | 400             | Geocode empty                                                                                                                              |
  | 1026         | 400             | Multiple geocode results or inexact address match                                                                                          |
  | 1027         | 400             | Bad geocode result - Address not found                                                                                                     |
  | 1028         | 400             | Invalid country or country code                                                                                                            |
  | 1029         | 401             | Attempt to access unauthorised data                                                                                                        |
  | 1030         | 400             | Entity state precludes requested flag setting                                                                                              |
  | 1041         | 400             | Identity document required                                                                                                                 |
  | 1042         | 400             | Incorrect ID type                                                                                                                          |
  | 1043         | 400             | Missing mobile number                                                                                                                      |
  | 1044         | 400             | Missing name                                                                                                                               |
  | 1045         | 400             | Empty name                                                                                                                                 |
  | 1046         | 400             | Entity ineligible for service or in unsupported jurisdiction                                                                               |
  | 1047         | 400             | Push to Mobile service returned PTM service offline                                                                                        |
  | 1048         | 404             | PTM service couldn't find the token requested                                                                                              |
  | 1049         | 404             | Internal error. Contact developer support.                                                                                                 |
  | 1050         | 503             | No business query service available at this time.                                                                                          |
  | 1051         | 503             | Failed to schedule background job                                                                                                          |
  | 1052         | 500             | Business processor returned empty result set                                                                                               |
  | 1053         | 400             | Supplied entity isn't of a suitable type                                                                                                   |
  | 1054         | 400             | The requested operation amounted to no work                                                                                                |
  | 1055         | 400             | A required prior result has expired                                                                                                        |
  | 1056         | 500             | The background operation couldn't continue because required data was modified                                                              |
  | 1057         | 500             | The background operation couldn't continue because required data was missing                                                               |
  | 1058         | 500             | No result was obtained in a reasonable time                                                                                                |
  | 1059         | 500             | Inconsistent result from business processor                                                                                                |
  | 1060         | 400             | Mismatch between ownership request and ABR response                                                                                        |
  | 1061         | 400             | Can't change status of check result                                                                                                        |
  | 1062         | 403             | Operation not permitted, entity is in inactive state                                                                                       |
  | 1063         | 500             | Report service exists but failed to generate a report or we couldn't save the result                                                       |
  | 1064         | 400             | Document not owned by entity requested in document/verify function                                                                         |
  | 1065         | 400             | Named entity profile not configured                                                                                                        |
  | 1066         | 400             | Entity doesn't have an assigned profile                                                                                                    |
  | 1067         | 400             | Entity profiles aren't enabled for customer                                                                                                |
  | 1068         | 400             | Missing application id or referrer when requesting an IDV token                                                                            |
  | 1069         | 400             | Invalid request to token service for a token                                                                                               |
  | 1070         | 422             | Invalid request (unprocessable) to token service for a token                                                                               |
  | 1072         | 400             | Refresh token with mismatch applicant id                                                                                                   |
  | 1073         | 500             | The expected or default policy isn't configured                                                                                            |
  | 1074         | 500             | Attempt to toggle entity monitoring failed                                                                                                 |
  | 1075         | 422             | Importing past results failed                                                                                                              |
  | 1076         | 400             | Unknown business reportType                                                                                                                |
  | 1077         | 503             | No intl business service available                                                                                                         |
  | 1078         | 400             | No intl business search/profile criteria provided                                                                                          |
  | 1079         | 400             | Intl business service rejected request                                                                                                     |
  | 1080         | 400             | No shared blocklist                                                                                                                        |
  | 1081         | 400             | No shared blocklist reason                                                                                                                 |
  | 1082         | 500             | Shared blocklist internal error                                                                                                            |
  | 1083         | 500             | Failed to get JWT signer or JWK key set                                                                                                    |
  | 1084         | 400             | Entity not in valid state for setting a manual state                                                                                       |
  | 1085         | 404             | Requested entity isn't retrievable at this time. NOTE: This is USUALLY transient, so wait 5 seconds and then retry                         |
  | 1086         | 404             | Requested association doesn't exist                                                                                                        |
  | 1087         | 400             | Requested association isn't allowed                                                                                                        |
  | 1088         | 400             | Object not found from non-primary key search                                                                                               |
  | 1089         | 500             | Internal error. Contact developer support.                                                                                                 |
  | 1090         | 400             | Device data supplied is either missing or incorrectly formatted                                                                            |
  | 1091         | 500             | Internal service error - please contact technical support                                                                                  |
  | 1092         | 404             | Organisation can't be found in the requested country's registry                                                                            |
  | 1093         | 400             | The request contains an invalid parameter or argument                                                                                      |
  | 1094         | 400             | Search criteria too broad and returned too many results. Please retry with narrower search criteria                                        |
  | 1095         | 400             | Incorrectly formatted organisation number                                                                                                  |
  | 1096         | 400             | The requested country registry is incorrect. Please ensure you have the right country registry code                                        |
  | 1097         | 503             | Unknown response from the registry                                                                                                         |
  | 1098         | 400             | No company registry for the requested country is available to query. This is often due to local regulations not making this data available |
  | 1099         | 400             | Search by organisation\_number not available for the jurisdiction                                                                          |
</Accordion>


# Executing a workflow
Source: https://docs.frankieone.com/docs/executing-workflows

A step-by-step guide to executing a verification workflow and interpreting the results.

## Overview

Executing a workflow is the core action in the FrankieOne platform. It takes an `entityId` and runs it through a pre-configured series of checks (e.g., KYC, AML, IDV) to return a final verification status. This is the central mechanism for assessing risk and making onboarding decisions.

This guide covers the primary methods for executing a workflow and provides a high-level overview of how to handle the response.

***

## Workflow Execution Patterns

There are two primary patterns for executing a workflow, depending on whether the individual already exists in your system.

### 1. Execute for an Existing Entity

This is the most common pattern. If you have already created an `individual` and have their `entityId`, you can execute a workflow against them at any time.

**Use Cases:**

* Running an initial KYC check after a user has signed up.
* Re-running a workflow after a user has updated their information.
* Performing periodic or event-driven reviews.

<Steps>
  <Step title="You Initiate the Workflow">
    You send a `POST` request to the `/execute` endpoint for a specific entity and workflow. This tells FrankieOne to begin the verification process.
  </Step>

  <Step title="FrankieOne Performs the Checks">
    Our platform contacts all the necessary third-party data sources (e.g., government databases, credit bureaus, watchlist providers) as defined in your workflow rules.
  </Step>

  <Step title="You Receive the Result">
    The API response to your initial `POST` request contains the complete `workflowResult` object, which holds the final `status` and all detailed outcomes.
  </Step>
</Steps>

### 2. Create and Execute for a New Entity

For new user onboarding, you can create the `individual` entity and execute a workflow in a single API call. This is a highly efficient pattern that streamlines the initial verification process.

**Use Cases:**

* Onboarding a new customer who has just filled out a registration form.
* Verifying a user for the first time as part of a single, atomic transaction.

***

## Implementation Guide

### Prerequisites

Before executing a workflow, ensure you have:

* The `entityId` for the individual (unless using the “Create and Execute” pattern).
* The `serviceName` of the Service Profile they are being assessed against (e.g., `DEFAULT`).
* The `workflowName` of the specific workflow you want to run (e.g., `Standard-KYC-AU`).

### Step 1: Execute the Workflow

Choose the endpoint that matches your execution pattern.

#### For an Existing Entity:

Make a `POST` request to the `execute` endpoint, including the `entityId`, `serviceName`, and `workflowName` in the path.

```cURL cURL theme={null}
    curl --location --request POST '[https://api.frankie.one/v2/individuals/](https://api.frankie.one/v2/individuals/){{entityId}}/serviceprofiles/{{serviceName}}/workflows/{{workflowName}}/execute'
    --header 'api_key: {{your_api_key}}'
    --header 'X-Frankie-CustomerID: {{your_customer_id}}'  
```

#### For a New Entity:

Make a `POST` request to the `new` execute endpoint, providing the `individual`’s data in the request body.

```cURL cURL theme={null}
    curl --location --request POST '[https://api.frankie.one/v2/individuals/new/serviceprofiles/](https://api.frankie.one/v2/individuals/new/serviceprofiles/){{serviceName}}/workflows/{{workflowName}}/execute' 
    --header 'api_key: {{your_api_key}}'
    --header 'X-Frankie-CustomerID: {{your_customer_id}}'
    --data '{  
        "individual": {  
            "name": { "givenName": "John", "familyName": "Doe" },  
            "dateOfBirth": { "year": "1990", "month": "01", "day": "25" },  
            "..." : "..."  
        }  
    }'  
```

### Advanced: Passing Execution Variables

Some workflows accept runtime inputs that are not part of the individual entity's persistent data. You supply these through the `executionVariables` field in the request body. It is a key-value object, and the variables a workflow accepts are defined by that workflow's configuration.

Today no individual (KYC) workflow uses `executionVariables`. The only workflow that uses it is the KYB [Trust Analyzer](/docs/kyb/trust-analyzer), which takes the `documentId` of an uploaded trust deed.

### Step 2: Interpret the High-Level Response

The API response will contain the `workflowResult` object. For automated decision-making, you should parse these key top-level fields:

* **`workflowExecutionState`** : This **`must beCOMPLETED`**. If it shows `ERROR` or `TIMEOUT`, the workflow did not finish, and the `status` should not be trusted.
* **`status`** : This is the **most important field**. The most common values are `PASS`, `FAIL`, or `REVIEW`. This field incorporates any manual overrides and represents the final, authoritative state.
* **`result`** : This represents the original, automated outcome of the workflow before any manual changes. It’s useful for auditing.

### Advanced: Asynchronous Execution

For workflows that may take longer to complete, you can request asynchronous execution by including the `X-Frankie-Background: 1` header.

* The API will immediately respond with a `202 Accepted` status and a `requestId`.
* The workflow will continue to process in the background.
* You will be notified of the final result via a configured webhook.

This pattern is useful for preventing timeouts in client-facing applications.

### Advanced: Overriding a Result

In some cases, a compliance officer may need to manually override a workflow’s automated result. This is achieved by making a `PATCH` request to the specific workflow execution.

```HTTP HTTP theme={null}
    PATCH /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions/{workflowExecutionId}  
```

Provide the new `status` and an optional `comment` to explain the reason for the change. This action is fully audited.

```JSON JSON Request theme={null}
    {  
      "status": "PASS",  
      "comment": {  
        "text": "Manually approved by compliance officer John Doe after reviewing supporting documents."  
      }  
    }  
```

***

## Next Steps

Once you have successfully executed a workflow, the next critical step is to parse the rich `workflowResult` object to understand the outcome of every check.

For a complete breakdown of every field in the response, refer to our detailed guide: [**Interpreting Workflow Results**](/docs/interpreting-workflows-v2).

***

## Additional Resources

* [FrankieOne API Reference](/docs/reference/whats-new)
* [FrankieOne Support](/docs/contacting-developer-support)


# Introduction to FrankieOne & KYC
Source: https://docs.frankieone.com/docs/frankieone-introduction-to-kyc

Discover the fundamentals of Know Your Customer (KYC) and see how FrankieOne’s unified platform empowers you to build trust, ensure compliance, and create seamless onboarding experiences.

## The Cornerstone of Digital Trust

In today's global and digital economy, establishing trust is paramount. Know Your Customer (KYC) is the foundational process that enables businesses to verify the identity of their customers, creating a secure environment for everyone. It’s not just a regulatory hurdle; it’s a critical framework for preventing financial crime and building lasting, trusted relationships.

<Accordion title="What is KYC?">
  Know Your Customer (KYC) is the mandatory process of identifying and verifying the identity of a client. It's a cornerstone of regulatory compliance for any business involved in financial services, gaming, and other regulated sectors. The core principle of KYC is to establish with confidence that a customer is who they claim to be, which is the first and most critical step in preventing identity theft, financial fraud, money laundering, and the financing of terrorism (ML/TF).
</Accordion>

<Accordion title="Why is KYC a Business Imperative?">
  A robust KYC strategy is a competitive advantage that protects your business, your customers, and your reputation. Its importance extends far beyond simple compliance.

  * **Prevent Financial Crime and Protect Your Reputation:** KYC processes are your first line of defense against illicit activities. By thoroughly verifying customer identities, you can detect and deter criminals, safeguarding your business from being exploited for money laundering or terrorist financing.
  * **Navigate Global Regulatory Complexity with Confidence:** Governments and financial authorities worldwide, guided by bodies like the Financial Action Task Force (FATF), mandate strict KYC and Anti-Money Laundering (AML) regulations. Non-compliance leads to severe fines, sanctions, and reputational ruin.
  * **Enable Intelligent Risk Management:** KYC allows you to build a comprehensive risk profile for each customer. Understanding who your customers are and their expected behaviour enables you to make informed decisions, tailor your security measures, and manage risk effectively.
  * **Build and Maintain Customer Trust:** Demonstrating a strong commitment to security and compliance shows customers that you are a professional and trustworthy organization. This builds confidence, enhances your brand reputation, and fosters long-term loyalty.
</Accordion>

<Accordion title="The KYC Journey: A Four-Stage Process">
  The KYC process is a continuous journey, not a one-time check. It can be broken down into four essential stages that create a comprehensive compliance framework.

  <Steps>
    <Step title="Customer Identification Program (CIP)">
      The initial stage where you collect key identifying information from a customer. For individuals, this includes name, date of birth, and address. For businesses, it involves gathering corporate registration details and identifying the ultimate beneficial owners (UBOs).
    </Step>

    <Step title="Customer Due Diligence (CDD)">
      This is the verification stage. After collecting information, you perform due diligence to validate it against trusted, independent data sources. The goal is to confirm the customer's identity and assess their initial risk profile.
    </Step>

    <Step title="Enhanced Due Diligence (EDD)">
      For high-risk customers, standard due diligence is not enough. EDD involves a deeper investigation into their background, source of wealth, and business relationships to mitigate elevated risks.
    </Step>

    <Step title="Ongoing Monitoring">
      KYC is not a one-and-done process. Continuous monitoring of customer activity and periodic reviews ensure that any changes in risk profile are detected and managed promptly.
    </Step>
  </Steps>
</Accordion>

## How FrankieOne Delivers a Unified Solution

FrankieOne replaces complexity with a single, intelligent platform. We provide the infrastructure to connect to hundreds of global data sources and compliance tools through one API and one unified back-office portal.

* **Effortless Global Onboarding:** Integrate once and gain access to a world of identity verification providers. Our flexible integration options—including our low-code Onboarding Journeys, SDKs, and a powerful API—allow you to onboard customers from anywhere, efficiently and securely.
* **Automated and Risk-Based Workflows:** Automate data collection and verification to eliminate manual errors, reduce operational overhead, and accelerate onboarding. Configure dynamic, risk-based workflows that automatically escalate high-risk customers for enhanced due diligence while fast-tracking legitimate users.
* **Always-On Compliance:** The regulatory landscape is constantly changing. FrankieOne is a fully managed solution that stays current with the latest regulatory requirements and industry best practices, significantly reducing your compliance burden and risk.

## Our Unified Product Suite

FrankieOne offers a comprehensive suite of products designed to work together, providing complete coverage across the entire KYC and fraud prevention lifecycle.

<CardGroup>
  <Card title="KYC Checks" icon="user-check" href="/docs/electronic-kyc-checks">
    Our core engine for verifying individual and business identities against hundreds of trusted global data sources.
  </Card>

  <Card title="AML Screening & Monitoring" icon="shield-check" href="/docs/anti-money-laundering">
    Screen customers against global PEP, Sanctions, and Adverse Media watchlists, with options for continuous monitoring.
  </Card>

  <Card title="ID Verification & OCR" icon="id-card" href="/docs/idv-biometrics-guide">
    Instantly capture and verify government-issued ID documents using advanced OCR and authenticity analysis.
  </Card>

  <Card title="Liveness & Facial Comparison" icon="camera" href="/docs/idv-biometrics-guide">
    Prevent spoofing and fraud with leading biometric technology that confirms a customer is genuinely present and matches their ID document.
  </Card>

  <Card title="Onboarding Fraud Checks" icon="user-secret" href="/docs/fraud-checks-guide">
    Assess risk during onboarding using real-time signals from device, IP, email, and phone data.
  </Card>

  <Card title="Risk Assessment" icon="scale-balanced" href="/docs/core-product-deep-dive#individual-risk-assessment">
    Dynamically calculate a holistic risk score for each customer based on configurable risk factors and real-time data.
  </Card>

  <Card title="Blocklist Management" icon="ban" href="/docs/matchlists-checks">
    Create and manage internal blocklists to proactively prevent engagement with known high-risk individuals or entities.
  </Card>

  <Card title="Duplicate Detection" icon="copy" href="/docs/duplicate-checks">
    Maintain a single customer view and prevent fraud by identifying and flagging linked or duplicate accounts.
  </Card>
</CardGroup>

### The Future of Compliance: Coming Soon

We are continuously innovating to address the next generation of compliance and fraud challenges. The following capabilities are in active development for upcoming releases.

<CardGroup>
  <Card title="Self-Service Onboarding Journeys" icon="user-plus" href="/docs/welcome-to-frankie">
    Deploy beautiful, low-code, and fully-hosted onboarding flows in minutes, customized to your brand and risk policies.
  </Card>

  <Card title="Transaction Monitoring" icon="chart-line">
    Monitor customer transactions in real-time to detect suspicious patterns and automate regulatory reporting.
  </Card>

  <Card title="AI-Powered AML Investigation" icon="robot">
    Leverage generative AI to automate the investigation of AML alerts, providing plain-language summaries and recommendations.
  </Card>

  <Card title="Digital Identity Verification" icon="id-card-clip">
    Verify digital identities using secure and reliable methods to enhance customer trust and security.
  </Card>
</CardGroup>

<Check icon="circle-check">
  ##### Ready to Get Started?

  FrankieOne's team of compliance and integration experts are ready to help you design and deploy a world-class KYC and onboarding solution.  or dive into our  to learn more. FrankieOne's team of compliance and integration experts are ready to help you design and deploy a world-class KYC and onboarding solution.
</Check>

## Understanding Your Regulatory Obligations

As a business providing regulated services, you are likely considered a **“Reporting Entity”** (or “Obligated Entity”) under AML/CTF legislation. This requires you to establish and implement a robust AML/CTF Program, where Customer Identification Procedures (KYC) are a core component.

The goal is to be satisfied that:

* An **individual customer** is who they claim to be.
* A **non-individual customer** (e.g., a company, trust, or partnership) is a real entity, and you have identified its beneficial owners.

<Callout icon="bell">
  ##### Consult with Legal and Compliance Experts

  AML/CTF regulations are complex and vary by jurisdiction and industry. The information provided here is for educational purposes only. Always consult with a qualified legal expert or compliance officer to ensure your AML/CTF Program meets all necessary legal requirements for the regions in which you operate.
</Callout>

#### Key Regulatory Bodies and Guidance

| Jurisdiction       | Regulatory Body                                                        | Key Reference / Legislation                                                                                                                                                                        |
| :----------------- | :--------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Australia**      | Australian Transaction Reports and Analysis Centre (AUSTRAC)           | [Customer identification and verification ](https://www.austrac.gov.au/business/core-guidance/customer-identification-and-verification)<Icon icon="arrow-up-right-from-square" />                  |
| **Canada**         | Financial Transactions and Reports Analysis Centre of Canada (FINTRAC) | [Guide to Client Identification Requirements ](https://fintrac-canafe.canada.ca/guidance-directives/client-clientele/Guide11/11-eng#annex5)<Icon icon="arrow-up-right-from-square" />              |
| **European Union** | European Banking Authority (EBA)                                       | [Anti-Money Laundering Directives (AMLD) ](https://www.eba.europa.eu/regulation-and-policy/anti-money-laundering-and-countering-financing-terrorism)<Icon icon="arrow-up-right-from-square" />     |
| **Global**         | Financial Action Task Force (FATF)                                     | [FATF Recommendations](https://www.fatf-gafi.org/en/topics/fatf-recommendations.html)<Icon icon="arrow-up-right-from-square" />                                                                    |
| **New Zealand**    | Financial Markets Authority (FMA)                                      | [AML/CTF Guidance ](https://www.fma.govt.nz/business/focus-areas/amlcft/)<Icon icon="arrow-up-right-from-square" />                                                                                |
| **United Kingdom** | Financial Conduct Authority (FCA)                                      | [Financial crime: a guide for firms ](https://www.fca.org.uk/firms/financial-crime)<Icon icon="arrow-up-right-from-square" />                                                                      |
| **United States**  | Financial Crimes Enforcement Network (FinCEN)                          | [Customer Due Diligence Final Rule ](https://www.fincen.gov/resources/statutes-regulations/federal-register-notices/customer-due-diligence-requirements)<Icon icon="arrow-up-right-from-square" /> |


# Onboarding Fraud Checks
Source: https://docs.frankieone.com/docs/fraud-checks-guide



Learn how to implement Onboarding Fraud Checks to assess risk using device, IP, email, and phone signals.

## Introduction

FrankieOne's Onboarding Fraud solution enables you to build a risk-based onboarding workflow by incorporating powerful fraud signals. By analyzing signals from an applicant's device, IP address, phone number, and email address, you can optimize your onboarding process—introducing more robust checks for high-risk applicants while ensuring a smooth journey for legitimate users.

This allows you to effectively reject bad actors showing strong fraudulent indicators while safely onboarding genuine customers.

## Key Capabilities

<CardGroup>
  <Card title="Device Risk" icon="mobile">
    Analyze device characteristics to identify suspicious setups like emulators or jailbroken devices.
  </Card>

  <Card title="IP Risk" icon="globe">
    Assess the risk associated with an IP address, detecting usage of VPNs or proxies.
  </Card>

  <Card title="Email Address Risk" icon="desktop">
    Verify email addresses to uncover potential fraud indicators.
  </Card>

  <Card title="Phone Number Risk" icon="phone">
    Validate phone numbers and identify associated risk signals.
  </Card>
</CardGroup>

## The End-to-End Fraud Check Flow

The fraud verification process involves a sequence of API calls to create an entity, register a device session (if applicable), and execute a workflow to get a result.

<Steps>
  <Step title="Create an Individual Entity">
    Before you can perform a fraud check, you need an `entityId` for the user. If you don't already have one, create an individual entity by making a server-side call to the API. Ensure you provide email and phone details if you intend to check those signals.

    ```bash theme={null}
    POST /v2/individuals
    ```

    This request creates the user's profile in the FrankieOne system and returns the essential `entityId` that will be used in all subsequent steps.
  </Step>

  <Step title="Register a Session (For Device & IP Checks)">
    To obtain device and IP signals, your application must integrate our oneSDK (either hosted or embedded). The oneSDK captures device data and establishes a session. This session must be registered with FrankieOne.

    Make a server-side call to register the session against the entity. This step is only necessary if you require device and IP checks.

    ```bash theme={null}
    POST /v2/individuals/{entityId}/sessions
    ```

    This ensures that when the fraud check workflow is executed, FrankieOne can retrieve and analyze the data captured during that specific user session.
  </Step>

  <Step title="Execute Workflow">
    Once the entity is created (and a session is registered, if needed), you can execute the onboarding workflow. The workflow must be configured to include the `FRAUD` step to perform the checks.

    ```bash theme={null}
    POST /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/execute
    ```

    This triggers the Fraud step, which analyzes the available signals (Email, Phone, Device, IP) and generates the results.
  </Step>

  <Step title="Get and Resolve Results">
    The workflow execution response will contain the results of the fraud checks. The overall step result will indicate a `HIT` or `CLEAR` based on the process results for each signal. You can then investigate any hits and resolve them.

    To learn how to analyze the detailed outcomes, please see our dedicated guide:\
    <a href="/docs/fraud-checks-guide-results"><strong>Understanding Fraud Check Results</strong></a>
  </Step>
</Steps>

## Limitations

Please be aware of the following limitations:

* **oneSDK Requirement:** To get device and IP signals, you must implement oneSDK. Without it, only email and phone signals can be used.
* **Single Provider per Step:** The fraud step is designed to support only one provider at a time. If you need to use different providers for different signals, you must configure separate fraud steps.
* **Supported Connectors:** To find out which connectors are available for the v2 fraud step, please consult your implementation support manager.


# Understanding Fraud Check Results
Source: https://docs.frankieone.com/docs/fraud-checks-guide-results



Learn how to locate and interpret the results from Onboarding Fraud Checks.

## Locating Fraud Check Results

Once a workflow containing a `FRAUD` step has been executed, the detailed results are nested within the `workflowResult` object. To find the specific outcomes of the fraud checks, navigate the JSON response structure as follows:

1. **Start with `workflowStepResults`:** In the `workflowResult`, find the `workflowStepResults` array.
2. **Identify the FRAUD Step:** Look for the object where `stepName` is `FRAUD`.
3. **Examine `processResults`:** Inside this step result is a `processResults` array. Each object in this array is a Process Result Object (PRO) containing granular data for a specific check (e.g., one PRO for email, one for phone).
4. **Drill into `supplementaryData`:** The richest details are in the `supplementaryData` object within each PRO. The `type` field here is crucial as it defines the structure and meaning of the data.

## Decoding `supplementaryData` for Fraud Checks

The structure of the `supplementaryData` object is determined by its `type`. For fraud checks, you will encounter the following types:

### Type: `FRAUD_EMAIL_ADDRESS`

This object contains the results of the risk analysis for an individual's email address.

<Accordion title="Example: supplementaryData for FRAUD_EMAIL_ADDRESS">
  ```json theme={null}
  "supplementaryData": {
    "type": "FRAUD_EMAIL_ADDRESS",
    "emailAddressId": "239db6d7-90be-4368-bc35-23194f13eae5",
    "riskLevel": "UNACCEPTABLE",
    "reference": {
      "name": "sardine",
      "reference": "https://dashboard.sandbox.sardine.ai/...",
      "type": "URL"
    },
    "indicators": [
      {
        "name": "emailLevel",
        "value": "very_high",
        "rules": [
          {
            "isActive": true,
            "name": "Forced very high email risk",
            "reference": "30"
          }
        ]
      }
    ]
  }
  ```
</Accordion>

**Key Fields:**

* `emailAddressId`: The unique ID of the email address that was checked.
* `riskLevel`: The risk level assessed by the provider (e.g., LOW, MEDIUM, HIGH, UNACCEPTABLE).
* `indicators`: An array of specific signals or rules that were triggered during the check.
* `reference`: A link or reference to the provider's system for more details.

### Type: `FRAUD_PHONE_NUMBER`

This object provides the results of the risk analysis for a phone number.

<Accordion title="Example: supplementaryData for FRAUD_PHONE_NUMBER">
  ```json theme={null}
  "supplementaryData": {
    "type": "FRAUD_PHONE_NUMBER",
    "phoneNumberId": "a6ba094e-77ec-44bc-8b1c-5152b158276a",
    "riskLevel": "LOW",
    "reference": {
      "name": "sardine",
      "reference": "https://dashboard.sandbox.sardine.ai/...",
      "type": "URL"
    },
    "indicators": [
      {
        "name": "phoneLevel",
        "value": "low"
      }
    ]
  }
  ```
</Accordion>

**Key Fields:**

* `phoneNumberId`: The unique ID of the phone number that was checked.
* `riskLevel`: The risk level assessed by the provider.
* `indicators`: An array of specific signals or rules that were triggered.

### Type: `FRAUD_DEVICE` & `FRAUD_IP_ADDRESS`

These objects contain the risk analysis for the device and IP address associated with a user's session. They share a similar structure.

<Accordion title="Example: supplementaryData for FRAUD_DEVICE">
  ```json theme={null}
  "supplementaryData": {
    "type": "FRAUD_DEVICE",
    "riskLevel": "HIGH",
    "session": {
      "token": "40508276-14d3-4a51-b59a-343a54e39f93"
    },
    "device": {
      "deviceId": "1d9566b0-9699-460f-8d25-59179155f10e",
      "os": "Windows",
      "browser": "Chrome",
      "isEmulated": true,
      "reputation": "medium_risk",
      "vpnLikelihood": "HIGH"
    },
    "indicators": [
      {
        "name": "deviceLevel",
        "value": "high"
      }
    ]
  }
  ```
</Accordion>

**Key Fields:**

* `riskLevel`: The risk level assessed by the provider.
* `session`: Contains the provider's session token.
* `device`: An object containing detailed device characteristics, such as OS, browser, and fraud indicators like `isEmulated` or `vpnLikelihood`.
* `ipAddressInformation`: (For `FRAUD_IP_ADDRESS` type) An object containing IP details like `v4Address` and `connectionType`.

## Fraud Issues and Risk Factors

The fraud checks directly influence the workflow's outcome by generating issues and risk factors.

* **Issues:** When a check returns a `HIT` result, a corresponding issue is created. For example, a high-risk email will generate an issue with `category: FRAUD` and `issue: FRAUD_EMAIL_ADDRESS`.
* **Risk Factors:** The `riskLevel` from each check is converted into a risk factor (e.g., `fraud_email`, `fraud_device`) which contributes to the entity's overall risk score.

## Resolving and Invalidating Results

### Resolving a HIT

If a fraud check results in a `HIT`, an operator can manually review and resolve it. This is done by changing the `manualStatus` of the corresponding Process Result Object (PRO).

Call the following endpoint with the `processResultId` of the PRO to be updated:

```bash theme={null}
PATCH /v2/individuals/{entityId}/results/fraud
```

**Manual Status Options:**

* `FALSE_POSITIVE`: The signal is incorrect and not a sign of fraud.
* `TRUE_POSITIVE_ACCEPT`: The signal is correct, but the risk is acceptable for onboarding.
* `TRUE_POSITIVE_REJECT`: The signal is correct, and the applicant should be rejected.

Once resolved, re-executing the workflow will take the manual override into account, potentially resulting in a `CLEAR` or `PASS` status.

### Invalidation of Results

Fraud check results are tied to specific data points and can be automatically invalidated if that data changes:

* **MARKED\_INVALID:** If an email or phone number that was checked is modified or deleted, the associated result's `systemStatus` is set to `MARKED_INVALID`.
* **STALE:** If a new email or phone with a higher precedence is added to the entity and the workflow is re-run, the old result is marked as `STALE`.


# Fraud Prevention and Risk-Based Onboarding Overview
Source: https://docs.frankieone.com/docs/fraud-prevention-risk-based-onboarding-1

Integrate FrankieOne's fraud signals and risk-based decisioning into your onboarding flow with OneSDK and our KYC API.

## Introduction

A significant challenge faced by many businesses today is balancing fraudulent account opening risk with a smooth user experience during onboarding. This often leads to high friction for low-risk users and not enough scrutiny for high-risk profiles.

The FrankieOne solution adapts the verification process to each user's unique risk profile, ensuring low-risk users enjoy a fast, frictionless journey while high-risk applicants undergo additional, necessary identity checks.

Onboarding fraud checks apply to individual entities only. Organization entity (KYB) onboarding does not currently include fraud checks.

### How Risk-Based Onboarding Works

<Frame>
  <img alt="Flowchart showing risk-based onboarding: initial fraud signal assessment, risk score determination, and dynamic verification paths for low-risk, medium/high-risk, and very high-risk users" />
</Frame>

Our risk-based onboarding model assigns each user a real-time risk score, categorizing them as low, medium, high or very high risk. This allows you to apply the right level of verification at every step, blocking fraud early without adding friction for genuine customers.

<Steps>
  <Step title="Initial Fraud Signal Assessment">
    As a customer submits their details, our solution assesses fraud risk in the background using real-time intelligence from device, phone, and email signals. This happens instantly without disrupting the user's experience.
  </Step>

  <Step title="Determine Risk Score">
    Based on the initial signals, a risk score is calculated to determine if the user is Low, Medium/High, or Very High Risk.
  </Step>

  <Step>
    **Apply Dynamic Verification**

    The user's journey adapts based on their risk level.

    <span /> **Low Risk** users proceed with minimal checks and can be onboarded quickly.

    <span /> **Medium or High Risk** users are prompted for additional verification steps, such as KYC checks, ID validation, or biometrics.

    <span /> **Very High Risk** applications can be rejected immediately, stopping bad actors before they create an account.
  </Step>
</Steps>

### Key Features and Signals

Our solution leverages best-in-class providers to assess risk in real-time, using a powerful combination of device intelligence and behavioral biometrics to filter out bad actors.

<Card title="Device Intelligence" icon="mobile-screen-button">
  Identifies devices through cookies and device fingerprinting to flag suspicious sessions. Signals include:

  <div><svg><path /></svg> Emulator, Proxy, and VPN detection</div>

  <div><svg><path /></svg> Browser fingerprinting and Device ID</div>

  <div><svg><path /></svg> Remote desktop detection</div>
</Card>

<Card title="Behavioral Signals" icon="brain">
  Detects fraudsters through their intrinsic behaviors and patterns during the onboarding process. Signals include:

  <div><svg><path /></svg> Typing and mouse signals</div>

  <div><svg><path /></svg> Use of copy, paste, and autofill functions</div>

  <div><svg><path /></svg> Hesitation, distraction, and context switching</div>
</Card>

<Card title="Contact and Location Intelligence" icon="location-dot">
  Validates user-provided information against trusted data sources.

  <div><svg><path /></svg> **Email Risk Assessment:** Checks email age, domain risk, and associated account behavior.</div>

  <div><svg><path /></svg> **Phone Risk Assessment:** Determines if a phone is VOIP or a landline and analyzes its behavior.</div>

  <div><svg><path /></svg> **IP Location Intelligence:** Detects proxy use and analyzes risk based on IP country, city, and timezone.</div>
</Card>

## Integration essentials

<Columns>
  <Card title="KYC API" icon="code">
    Use our [**KYC API**](/docs/fraud-checks-guide) to perform email and phone checks, and retrieve combined risk scores.

    [**Learn more** …](/docs/fraud-checks-guide)
  </Card>

  <Card title="OneSDK" icon="mobile-screen-button">
    Capture device and behavioral biometrics data with our [**OneSDK**](/docs/sdk-reference/device-module) for web and mobile platforms.

    [**Learn more** …](/docs/sdk-reference/device-module)
  </Card>

  <Card title="Portal" icon="desktop">
    Access fraud insights and manage results through our user-friendly portal.

    [**Learn more** …](/docs/fraud-checks)
  </Card>
</Columns>


# Fraud Prevention and Risk-Based Onboarding Features
Source: https://docs.frankieone.com/docs/fraud-v2-features

Explore the key features and fraud signals that power FrankieOne's Risk-based Onboarding solution.

The following sections outline the key features and fraud signals that power FrankieOne's Risk-based Onboarding solution.

<Card title="Fraud checks" icon="shield-check">
  FrankieOne provides the following solutions that customers can use to prevent fraud when using Onboarding Fraud Checks.

  <Card title="Email check" icon="envelope-open-text">
    Assesses whether the email is disposable, numeric, contains similarities to the user’s name, how old it is, how risky the domain is, and its general risk in our fraud provider networks.
  </Card>

  <Card title="Phone check" icon="phone">
    Assesses whether the number is associated with a risky line type like VoIP (Voice over Internet Protocol), the risk of the carrier, whether the phone name matches the user’s profile with their telco, or if it’s reported as fraudulent.
  </Card>

  <Card title="Device signals" icon="mobile-screen-button">
    Uses cookies and device fingerprinting to detect suspicious devices (like emulators or scripts) and sessions (such as proxies or remote desktops). Flags devices or IPs linked to multiple users to identify potential synthetic accounts and session relationships.
  </Card>

  <Card title="Behavioral biometrics" icon="brain">
    Analyzes mouse and typing patterns to detect fraud, such as frequent copy-pasting, rapid input, and unnatural mouse movements.
  </Card>

  <Card title="Location check" icon="location-dot">
    Assesses whether the user is located where they say they are, is using a VPN, or is in a high-risk location.
  </Card>
</Card>

## Rules

### Creating rules

We provide a highly versatile risk rule engine that allows you to create rules using a wide range of user, phone, email, device, and location signals.

<img alt="Screenshot showing the rule configuration interface with signal types and conditions" />

### Shadow mode

If a rule is in Shadow mode, that means it will run and capture metrics, but it won't update the risk level of a session. Running rules in Shadow mode initially is an easy way to start to get additional data about each session and experiment with what risk signals are most associated with fraud.

## Results in the Portal

In the Portal, you can view fraud check results alongside your KYC checks in a single view.

When a user is run through a workflow with onboarding fraud checks enabled, and it fails for any reason, you can see the specific risks associated with the failure on the overview page. If an email or phone number is modified or deleted after a fraud check has been completed, the associated fraud check results are marked as invalid. You can view invalidated results in the FrankieOne Portal.

<img alt="Screenshot of the FrankieOne Portal showing fraud check results with risk details for email and phone signals" />


# Getting Started with Fraud Prevention and Risk-Based Onboarding
Source: https://docs.frankieone.com/docs/fraud-v2-getting-started

Integrate FrankieOne's fraud signals and risk-based decisioning into your onboarding flow with OneSDK and the KYC API.

This guide is for developers integrating onboarding fraud checks into their application. By the end of this guide, you will have configured FrankieOne OneSDK or the KYC API to collect fraud signals, and you will be able to review fraud check results in the FrankieOne Portal.

## Getting Started with Onboarding Fraud

Check out the [integration](/docs/tm/integration) page for an overview of the implementation process.

### 1: Use OneSDK

To use device and behavioural biometric checks, your FrankieOne OneSDK integration must be configured to enable device data collection. Contact your Customer Success Manager to enable this.

If you only want to use phone and email checks, you can skip the OneSDK integration.

<Steps>
  <Step title="Integrate OneSDK">
    [Use OneSDK](/docs/quickstart-guide) if you want to capture device signals from your user session, along with email and phone checks.
  </Step>

  <Step title="Configure the OneSDK for Fraud checks">
    Follow [these steps](/docs/sdk-reference/device-module) to set up the OneSDK to collect device, email, and phone signals during your user's onboarding.
  </Step>
</Steps>

### 2: Use the KYC API

If you only want to use phone and email checks, you can skip the OneSDK integration and use the FrankieOne KYC API to collect email and phone signals.

The KYC API is also required for device and behavioral biometric checks.

<Steps>
  <Step title="Verify customers using FrankieOne KYC API">
    To use phone and email screening, you need to use the FrankieOne KYC API. Follow the steps to [verify customers](/docs/fraud-checks-guide) through our KYC API.
  </Step>

  <Step title="Add email and phone details as documents">
    When creating a verification session, include the user's email and phone number as identity documents.
  </Step>
</Steps>

### 3: Review and Manage Fraud Checks results in the Portal

Review your fraud rules and check results alongside your KYC checks via the [API](/docs/fraud-checks-guide-results) or in the [FrankieOne Portal](/docs/fraud-checks). Use the information to make informed decisions about onboarding users.

<Callout icon="thumbtack">
  ##### Need Help?

  For technical support or to enable fraud detection features, contact your FrankieOne Customer Success representative or [visit our support portal](https://frankieone.atlassian.net/servicedesk/customer/portal/3/group/17).
</Callout>


# Fraud and Transaction Monitoring Use Cases
Source: https://docs.frankieone.com/docs/fraud-v2-use-cases

Explore common use cases for FrankieOne’s Fraud and Transaction Monitoring solutions.

<Card title="Identity fraud" icon="id-card-clip">
  Fraudsters use fake, stolen, or synthetic identity documents to open new accounts and exploit organizations. In some cases, they combine real and fabricated personal information to create entirely new identities that do not belong to any single real person.

  FrankieOne detects identity fraud during onboarding by screening email addresses and phone numbers against known fraud networks, and by analyzing device and behavioral signals for patterns associated with fraudulent identities. For example, a mismatch between email age and phone registration date, combined with a device flagged for emulator use, would raise the entity's risk score. Cross-referencing multiple signals helps identify synthetic identities that may pass individual data checks.

  **Relevant signals:** Email check, Phone check, Device signals, Behavioral biometrics, Location check
</Card>

<Card title="Account takeover" icon="user-shield">
  Criminals use stolen credentials to impersonate legitimate customers and gain unauthorized control of their accounts.

  FrankieOne identifies account takeover attempts by comparing device fingerprints and behavioral biometrics against the entity's established patterns. Unusual typing cadence, unfamiliar devices, or sessions originating from high-risk IP addresses trigger additional verification or manual review.

  **Relevant signals:** Device signals, Behavioral biometrics, Location check, Activity monitoring
</Card>

<Card title="Fraud farms and automated account creation" icon="users-rectangle">
  Organized crime rings use automated scripts, bots, and coordinated human operators to rapidly create large numbers of fraudulent accounts.

  FrankieOne flags fraud farm activity by detecting multiple accounts linked to the same device or IP address, identifying emulator, remote desktop, and headless browser usage, and recognising automated input patterns. Behavioral biometrics detect bot-driven sessions through signals such as unnaturally consistent typing speed, absence of mouse hesitation, and rapid form completion across multiple sessions.

  **Relevant signals:** Device signals, Behavioral biometrics, Location check
</Card>

<Card title="Money mule accounts" icon="user-injured">
  Accounts are created by recruited individuals to illegally transfer or launder money on behalf of criminals.

  FrankieOne helps identify potential money mule accounts by screening contact details against fraud provider networks and assessing risk signals at onboarding. High-risk phone numbers (such as VoIP lines), disposable email addresses, and device signals associated with known fraud rings contribute to elevated risk scores that trigger manual review before onboarding is completed.

  **Relevant signals:** Email check, Phone check, Device signals, Transaction monitoring, Activity monitoring
</Card>

<Card title="Loan and credit application fraud" icon="file-invoice-dollar">
  Loan and credit application fraud occurs when fraudsters apply for loans or credit using false information or stolen identities. They may manipulate financial details or misrepresent their income and employment.

  FrankieOne helps detect application fraud at onboarding by validating contact details against fraud provider networks and identifying suspicious device and behavioral signals during the application session. Device intelligence flags emulators, VPN usage, and devices linked to multiple applications.

  **Relevant signals:** Email check, Phone check, Device signals, Behavioral biometrics
</Card>

<Card title="Scams" icon="hand-holding-dollar">
  Scams are a form of social engineering fraud where criminals manipulate people into sharing sensitive information or transferring funds directly to the criminal. Methods include phishing emails, fake investment schemes, and impersonation.

  While onboarding fraud checks do not directly detect social engineering, activity monitoring can identify unusual session behavior after a scam has been initiated — such as login from an unfamiliar device, rapid changes to account details, or atypical fund transfer patterns.

  **Relevant signals:** Device signals, Behavioral biometrics, Transaction monitoring, activity monitoring
</Card>

<Card title="Promo abuse and multiple account creation" icon="users-between-lines">
  Individuals create multiple accounts to exploit sign-up bonuses, referral rewards, or promotional offers. This is common in gaming, wagering, and fintech platforms.

  FrankieOne identifies multi-accounting by detecting multiple sessions or accounts linked to the same device fingerprint or IP address. Device intelligence flags shared devices, emulators, and VPN usage that are commonly associated with promo abuse at scale.

  **Relevant signals:** Device signals, Location check
</Card>


# Getting Started: Your First API Call
Source: https://docs.frankieone.com/docs/getting-started



This guide will walk you through setting up your environment, authenticating, and making your first successful API call to the FrankieOne platform.

Welcome to the FrankieOne API! This guide provides the essential information to get you up and running. Our goal is to help you make your first successful API call in minutes.

### Your FrankieOne Starter Pack

When you partner with FrankieOne, your Customer Success Manager will provide you with a starter pack containing everything you need for each environment. You should have the following:

| Resource         | UAT / Sandbox                    | Production                         |
| :--------------- | :------------------------------- | :--------------------------------- |
| **Portal URL**   | `https://portal.uat.frankie.one` | `https://portal.frankie.one`       |
| **API Base URL** | `https://api.uat.frankie.one/v2` | `https://api.frankie.one/v2`       |
| **Customer ID**  | Your unique UAT Customer ID      | Your unique Production Customer ID |
| **API Key**      | Your secret UAT API Key          | Your secret Production API Key     |

***

## Authentication Headers

All API requests to FrankieOne must be authenticated. You'll use the credentials from your starter pack in the request headers.

| Header                 | Required | Description                                                                                                      |
| :--------------------- | :------- | :--------------------------------------------------------------------------------------------------------------- |
| `api_key`              | **Yes**  | Your secret API key for the specific environment (UAT or Production).                                            |
| `X-Frankie-CustomerID` | **Yes**  | The unique identifier for your account.                                                                          |
| `X-Frankie-Username`   | No       | The email address or identifier of the operator performing the action. Highly recommended for auditing purposes. |
| `X-Frankie-Channel`    | No       | The channel the request originates from (e.g., `API`, `PORTAL`, `ONESDK`). Useful for analytics and routing.     |

<Callout icon="bell">
  ##### Keep Your API Key Secure

  Your `api_key` is a secret and should be treated like a password. Store it securely on your backend and never expose it in client-side code or public repositories. If you suspect a key has been compromised, contact support immediately.
</Callout>

***

## Quickstart in 3 Steps

Follow these steps to ensure your credentials are correct and your environment is ready for integration.

<Steps>
  <Step title="Test Your Connection">
    The easiest way to verify that your credentials and connection are working is to call our simple health check endpoint: `/ruok`. This endpoint doesn’t require a request body and is used purely to confirm successful authentication.

    ```cURL theme={null}
        curl --location '[https://api.uat.frankie.one/v2/kyc/ruok](https://api.uat.frankie.one/v2/kyc/ruok)'
        --header 'api_key: {{your_uat_api_key}}' 
        --header 'X-Frankie-CustomerID: {{your_uat_customer_id}}'  
    ```

    A successful request will return a `200 OK` status and the following JSON response, confirming your keys are valid.

    ```Response theme={null}
        {   
           "status": "OK"  
        }  
    ```
  </Step>

  <Step title="Confirm Your Workflow Setup">
    Before you can start verifying customers, your account needs to be configured with at least one workflow and one service profile. Your Customer Success Manager typically sets these up for you.
    You can confirm your setup by calling the `GET /v2/workflows` endpoint. This will list all the executable workflows available to you.

    ```cURL theme={null}
        curl --location '[https://api.uat.frankie.one/v2/workflows](https://api.uat.frankie.one/v2/workflows)'
        --header 'api_key: {{your_uat_api_key}}'
        --header 'X-Frankie-CustomerID: {{your_uat_customer_id}}'  
    ```

    You should receive a `200 OK` response with a `workflows` array. If the array is empty, please contact your Customer Success Manager to get your workflows published.

    ```Response theme={null}
        {  
            "requestId": "req_01J...",  
            "workflows": [  
                {  
                    "serviceName": "DEFAULT",  
                    "workflowId": "wf_01J...",  
                    "workflowName": "Standard-KYC-AU",  
                    "type": "SYSTEM",  
                    "lifecyclePhase": "ONBOARDING"  
                }  
            ]  
        }  
    ```
  </Step>

  <Step title="Make Your First Verification Call">
    Now you're ready to perform your first check. The most fundamental call is to create an individual and execute a workflow in a single request. This is the fastest way to verify a new customer.

    You will need the `serviceName` and `workflowName` from the previous step.

    > *For a detailed guide on this process, see our **[Electronic KYC with Government ID](/docs/electronic-kyc-checks)** guide.*
  </Step>
</Steps>

***

## Next Steps

You've successfully authenticated and confirmed your setup.
Now you're ready to start building.
Follow our implementation guides for common use cases.

<CardGroup>
  <Card title="Creating & Managing Individuals" href="/docs/managing-individuals" icon="user-plus">
    Learn the complete lifecycle of an 'individual' entity, from creation and retrieval to updates and deletion.
  </Card>

  <Card title="Executing a Workflow" href="/docs/executing-workflows" icon="play">
    A step-by-step guide to executing a verification workflow against an existing entity.
  </Card>

  <Card title="API Reference" href="/docs/reference/whats-new" icon="book-open">
    Dive deep into every endpoint, parameter, and response object in our comprehensive API Reference.
  </Card>
</CardGroup>


# Global KYC
Source: https://docs.frankieone.com/docs/global-kyc-guide

Verify a wide range of international and domestic identity documents through a single, standardized API.

## Introduction

FrankieOne's Global KYC feature is a core component of the V2 platform, designed to provide a unified and extensible solution for verifying identity documents from around the world. It introduces a standardized data model for handling various document types and an intelligent routing mechanism to direct verification requests to the most appropriate data provider.

This solution allows you to build a comprehensive and scalable onboarding process, validating documents from dozens of countries through a single, consistent API interface.

**Key Business Goals**

* **Unified API for Global Documents:** Verify a wide range of government-issued identity documents using the same standardized `document` object structure, reducing integration complexity.
* **Intelligent Routing:** The platform automatically inspects a document's `type` and `country` to route the verification request to the most suitable downstream data source, such as a national document verification service or transport authority.
* **Extensive Country Coverage:** Leverage our expanding network of data sources across Asia-Pacific (APAC), Europe, Middle East & Africa (EMEA), and the Americas.
* **Flexible & Extensible Data Model:** Our schema uses a `supplementaryData` object to handle unique, country-specific document requirements without cluttering the primary API structure.

***

## The End-to-End Verification Flow

The verification process is seamlessly integrated into the standard entity and workflow execution flow. It involves creating an entity, attaching structured document data, and executing a workflow.

<Steps>
  <Step title="Step 1: Create an Individual with Documents">
    First, create an individual entity and attach one or more `document` objects within the `documents.IDENTITY` array. Each object should contain the individual's PII and the specific identifiers for that document, conforming to the standardized schema.

    ```http theme={null}
    POST /v2/individuals
    ```

    This single request populates the user's profile with all the necessary information for verification.
  </Step>

  <Step title="Step 2: Execute a KYC Workflow">
    Next, execute a pre-configured workflow that contains a KYC step for the relevant service profile.

    ```http theme={null}
    POST /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/execute
    ```
  </Step>

  <Step title="Step 3: Intelligent Routing and Verification">
    The KYC workflow step automatically inspects each document's `country` and `type`. Based on these fields, it determines the correct downstream data source for verification. The system validates the data against the source's specific requirements and transforms the V2 schema into the format needed by the provider's API.
  </Step>

  <Step title="Step 4: Receive Normalized Results">
    The response from the data source is received and normalized into a standard V2 Process Result Object (PRO). This standardized result can then be used by your workflow's decisioning logic to determine an outcome, such as `PASS` or `REVIEW`.
  </Step>
</Steps>

***

## Core Concepts: The Document Object

Understanding the standardized `document` object and the role of `supplementaryData` is key to leveraging the Global KYC feature.

### Standardized Document Fields

The `Document-Information` object is the primary container for all document details. It uses a consistent structure regardless of the country of origin.

| Field                 | Data Type     | Requirement  | Description                                                                                                                     |
| :-------------------- | :------------ | :----------- | :------------------------------------------------------------------------------------------------------------------------------ |
| `type`                | String (Enum) | **Required** | The standardized type of the document (e.g., `DRIVERS_LICENSE`, `PASSPORT`). Must be a valid `Document-Type` enum value.        |
| `country`             | String        | **Required** | The ISO 3166-1 alpha-3 code of the issuing country (e.g., `AUS`, `NZL`). This is a key field for routing.                       |
| `primaryIdentifier`   | String        | **Required** | The main number or identifier on the document (e.g., Licence Number, Passport Number).                                          |
| `secondaryIdentifier` | String        | Optional     | An additional identifier, often used for conditional requirements (e.g., the Card Number on some Australian Driver's Licences). |
| `subdivision`         | String        | Optional     | The abbreviated state, province, or territory of issue where applicable (e.g., "VIC" for Victoria, "NSW" for New South Wales).  |
| `issueDate`           | Date Object   | Optional     | The document's date of issue.                                                                                                   |
| `expiryDate`          | Date Object   | Optional     | The document's expiration date.                                                                                                 |
| `supplementaryData`   | Object        | Optional     | A flexible object for storing document-specific data that doesn't fit into the standard fields. See details below.              |
| `documentId`          | String (UUID) | Read-only    | A unique identifier assigned by FrankieOne when a document is created.                                                          |

### Handling Country-Specific Data with `supplementaryData`

The `supplementaryData` object is the key to our extensible model, allowing us to support unique data points for specific documents without altering the core schema. When you submit a document with supplementary data, the `supplementaryData.type` **must** match the main `document.type`.

Here are a few key examples:

* **Australian Medicare Card (`NATIONAL_HEALTH_ID`):** Requires the 1-digit `reference` number that appears to the left of the individual's name on the card.
* **Chinese National ID (`NATIONAL_ID`):** Supports a `homeCountryFullName` field to capture the individual's name in native Chinese characters.
* **Australian Citizenship Certificate (`CITIZENSHIP_CERTIFICATE`):** Requires the `acquisitionDate`.
* **Australian Marriage Certificate (`MARRIAGE_CERT`):** Requires the `marriageDate` and the full name of the second partner (`partner2GivenName`, `partner2FamilyName`).

***

## API Request Examples

### Example 1: Simple Document (Australian Passport)

This is a straightforward verification using only the common document fields.

```json theme={null}
{
  "individual": {
    "name": {
      "givenName": "Jane",
      "familyName": "Citizen"
    },
    "dateOfBirth": {
      "year": "1990",
      "month": "01",
      "day": "15"
    },
    "documents": {
      "IDENTITY": [
        {
          "type": "PASSPORT",
          "country": "AUS",
          "primaryIdentifier": "E1234567"
        }
      ]
    }
  }
}
```

### Example 2: Document with Conditional Fields (NSW Driver's Licence)

For an Australian Driver's Licence issued in New South Wales (and all states/territories except Victoria), the `secondaryIdentifier` (Card Number) is **mandatory**.

```json theme={null}
{
  "individual": {
    "name": {
      "givenName": "John",
      "familyName": "Smith"
    },
    "dateOfBirth": {
      "year": "1985",
      "month": "05",
      "day": "20"
    },
    "documents": {
      "IDENTITY": [
        {
          "type": "DRIVERS_LICENSE",
          "country": "AUS",
          "subdivision": "NSW",
          "primaryIdentifier": "98765432",
          "secondaryIdentifier": "1234567890"
        }
      ]
    }
  }
}
```

### Example 3: Document with Supplementary Data (Australian Marriage Certificate)

This example shows how to use the `supplementaryData` object to provide the extra information needed to verify an Australian Marriage Certificate from Victoria.

```json theme={null}
{
  "individual": {
    "name": {
      "givenName": "Jane",
      "familyName": "Citizen"
    },
    "documents": {
      "IDENTITY": [
        {
          "type": "MARRIAGE_CERT",
          "country": "AUS",
          "subdivision": "VIC",
          "primaryIdentifier": "98765/1990",
          "supplementaryData": {
            "type": "MARRIAGE_CERT",
            "marriageDate": "1990-12-15",
            "partner2GivenName": "John",
            "partner2FamilyName": "Doe"
          }
        }
      ]
    }
  }
}
```

***

## Country and Document Coverage

Our Global KYC services span across multiple regions. The tables below provide a detailed breakdown of supported documents and their API codes for each country.

### Supported Documents by Country

| Country        | Document                                                   | Code                                         |
| :------------- | :--------------------------------------------------------- | :------------------------------------------- |
| Australia (AU) | Birth Certificate                                          | `BIRTH_CERT`                                 |
|                | Centrelink Card                                            | `CONCESSION`, `PENSION`, `HEALTH_CONCESSION` |
|                | Citizenship Certificate                                    | `CITIZENSHIP`                                |
|                | Death Certificate                                          | `DEATH_CERT`                                 |
|                | Immigration Card (ImmiCard)                                | `IMMIGRATION_CARD`                           |
|                | Drivers License                                            | `DRIVERS_LICENSE`                            |
|                | Marriage Certificate                                       | `MARRIAGE_CERT`                              |
|                | Name Change Certificate                                    | `NAME_CHANGE`                                |
|                | National Health ID (Medicare)                              | `NATIONAL_HEALTH_ID`                         |
|                | National ID                                                | `NATIONAL_ID`                                |
|                | Passport                                                   | `PASSPORT`                                   |
| Brazil         | CNPJ (Cadastro Nacional de Pessoas Jurídicas)              | `NATIONAL_ID`                                |
|                | CPF (Cadastro de Pessoas Físicas)                          | `NATIONAL_ID`                                |
| Canada         | SIN (Social Insurance Number)                              | `NATIONAL_ID`                                |
| Chile          | RUT (Rol Único Tributario)                                 | `TAX_ID`                                     |
|                | RUN (Rol Único Nacional)                                   | `NATIONAL_ID`                                |
| China          | National ID (Resident Identity Card Number)                | `NATIONAL_ID`                                |
|                | Passport                                                   | `PASSPORT`                                   |
| Colombia       | CPIN (Colombian Personal Identification Number)            | `NATIONAL_ID`                                |
| Czech Republic | NID (Rodné číslo)                                          | `NATIONAL_ID`                                |
| Denmark        | CPR (Central Person Register)                              | `NATIONAL_ID`                                |
| Finland        | Personal Identity Code                                     | `NATIONAL_ID`                                |
| Ghana          | SSNIT (Social Security and National Insurance Trust)       | `NATIONAL_ID`                                |
|                | Voter ID                                                   | `NATIONAL_ID`                                |
| Hong Kong      | HKID (Hong Kong Identification Number)                     | `NATIONAL_ID`                                |
| India          | Aadhar                                                     | `NATIONAL_ID`                                |
|                | EPIC - Voter ID                                            | `NATIONAL_ID`                                |
|                | License                                                    | `DRIVERS_LICENSE`                            |
|                | PAN (Permanent Account Number)                             | `NATIONAL_ID`                                |
|                | Passport                                                   | `PASSPORT`                                   |
| Indonesia      | NIK (Nomor Induk Kependudukan)                             | `NATIONAL_ID`                                |
| Italy          | Codice Fiscale                                             | `TAX_ID`                                     |
| Japan          | My number                                                  | `TAX_ID`                                     |
| Jordan         | Civil Identification Number                                | `NATIONAL_ID`                                |
| Kenya          | Alien Card (Foreign ID)                                    | `NATIONAL_ID`                                |
|                | License                                                    | `DRIVERS_LICENSE`                            |
|                | National ID (Huduma Namba)                                 | `NATIONAL_ID`                                |
|                | Passport                                                   | `PASSPORT`                                   |
| Luxembourg     | Social Security                                            | `NATIONAL_ID`                                |
| Malaysia       | NRIC (National Registration Identity Card)                 | `NATIONAL_ID`                                |
| Mexico         | CURP (Clave Única de Registro de Población)                | `NATIONAL_ID`                                |
|                | RFC (Registro Federal de Contribuyentes)                   | `TAX_ID`                                     |
| Nigeria        | BVN (Bank Verification Number)                             | `NATIONAL_ID`                                |
|                | CAC (Corporate Affairs Commission)                         | `NATIONAL_ID`                                |
|                | License                                                    | `DRIVERS_LICENSE`                            |
|                | NIN (National Identification Number)                       | `NATIONAL_ID`                                |
|                | TIN (Tax Identification Number)                            | `TAX_ID`                                     |
|                | Voter ID                                                   | `NATIONAL_ID`                                |
| New Zealand    | Birth Certificate                                          | `BIRTH_CERT`                                 |
|                | License                                                    | `DRIVERS_LICENSE`                            |
|                | Passport                                                   | `PASSPORT`                                   |
| Philippines    | PCN (PhilSys Card Number)                                  | `NATIONAL_ID`                                |
|                | Passport                                                   | `PASSPORT`                                   |
| Poland         | PESEL (Powszechny Elektroniczny System Ewidencji Ludności) | `NATIONAL_ID`                                |
| Portugal       | Tax number (Número de Identificação Fiscal)                | `TAX_ID`                                     |
| Romania        | CNP (Cod Numeric Personal)                                 | `NATIONAL_ID`                                |
| Russia         | Internal Passport Number                                   | `PASSPORT`                                   |
|                | Tax ID Number                                              | `TAX_ID`                                     |
| South Africa   | National ID                                                | `NATIONAL_ID`                                |
| Spain          | DNI (Documento Nacional de Identidad)                      | `NATIONAL_ID`                                |
|                | NIF (Número de Identificación Fiscal)                      | `TAX_ID`                                     |
|                | NIE (Número de Identificación de Extranjero)               | `NATIONAL_ID`                                |
| Sweden         | PIN (Personal Identification Number)                       | `NATIONAL_ID`                                |
| Thailand       | National Identity Card                                     | `NATIONAL_ID`                                |
| Turkey         | TIN (Turkish Identification Number)                        | `TAX_ID`                                     |
| USA            | SSN (Social Security Number)                               | `NATIONAL_ID`                                |
| International  | Passport                                                   | `PASSPORT`                                   |
|                | Tax ID                                                     | `TAX_ID`                                     |

<Accordion title="Common Abbreviations">
  This section provides a list of common abbreviations used for various identification documents across different countries. These abbreviations are often used in KYC processes and can help streamline document handling.

  * **Aadhar**: Unique Identification Number (India)
  * **ASIC/MSIC**: Aviation/Maritime Security Identification Card (Australia)
  * **BVN**: Bank Verification Number (Nigeria)
  * **CAC**: Corporate Affairs Commission (Nigeria)
  * **CNPJ**: Cadastro Nacional de Pessoas Jurídicas (Brazil)
  * **CPF**: Cadastro de Pessoas Físicas (Brazil)
  * **CPIN**: Colombian Personal Identification Number (Colombia)
  * **CNP**: Cod Numeric Personal (Romania)
  * **CURP**: Clave Única de Registro de Población (Mexico)
  * **DNI**: Documento Nacional de Identidad (Spain)
  * **EPIC**: Electors Photo Identity Card (India)
  * **HKID**: Hong Kong Identification Number (Hong Kong)
  * **ImmiCard**: Immigration Card (Australia)
  * **NID**: National Identification Number (Czech Republic)
  * **NIE**: Número de Identificación de Extranjero (Spain)
  * **NIF**: Número de Identificación Fiscal (Spain)
  * **NIK**: Nomor Induk Kependudukan (Indonesia)
  * **NRIC**: National Registration Identity Card (Malaysia)
  * **PAN**: Permanent Account Number (India)
  * **PCN**: PhilSys Card Number (Philippines)
  * **PESEL**: Powszechny Elektroniczny System Ewidencji Ludności (Poland)
  * **PIN**: Personal Identification Number (Sweden)
  * **RFC**: Registro Federal de Contribuyentes (Mexico)
  * **RUT**: Rol Único Tributario (Chile)
  * **RUN**: Rol Único Nacional (Chile)
  * **SIN**: Social Insurance Number (Canada)
  * **SSN**: Social Security Number (USA)
  * **SSNIT**: Social Security and National Insurance Trust (Ghana)
  * **TIN**: Tax Identification Number (Nigeria, Turkey)
</Accordion>

<Danger>
  **For KYC checks, all tax identification documents must be submitted as document type `NATIONAL_ID` in the FrankieOne KYC v2 API to verify entity details.**
</Danger>

<Callout icon="bell">
  ##### Important Notes

  The document codes above are used in the FrankieOne KYC v2 API. Ensure you use the correct code for each document type when making API requests.

  * **Not all document types are available in every country.** Refer to the specific country documentation for details.
  * **Not all document types are supported in the FrankieOne Portal.** If you need to use a document type not listed here, please contact FrankieOne support.
</Callout>

***

## Integration Best Practices

* **Understand Local Requirements**: Each country may require different document types for KYC. Review the documentation for the countries you support.
* **Use Correct Document Codes**: Always use the exact `Document Code` specified in the table above when submitting documents via the API to ensure correct routing and processing.
* **Handle Supplementary Data**: For documents that require additional details (such as Australian Medicare or Marriage Certificates), ensure you populate the `supplementaryData` object correctly.
* **Validation & Error Handling**: Handle API errors gracefully by interpreting error messages and providing clear feedback to users.
* **Testing & Monitoring**: Test your integration thoroughly before going live. Monitor document handling workflows to quickly identify and resolve issues.

For detailed field requirements and valid values for different document types, please refer to the specific country-level documentation pages.


# Hosted Flow Templates
Source: https://docs.frankieone.com/docs/hosted-common-use-cases



## What are Flow Templates

Flow Templates are pre-configured, production-ready verification journeys built and maintained by FrankieOne.

Each template contains the complete onboarding workflow — data collection, verification logic, vendor orchestration, and results delivery — so you can go live quickly without designing screens or managing vendor SDKs.

All Pre-Built Flows share these qualities:

* **Managed & compliant**: Always up-to-date with the latest regulatory and vendor requirements.

* **Hosted by FrankieOne**: No need to deploy or maintain front-end infrastructure.

* **Essential Customisation**: Add your logo, colours, and on-screen messaging.

* **Scalable**: Enable different flows for different regions, risk levels, or customer types.

Most customers start with one of the three standard templates below.

## IDV (VOI) Flow

The **IDV Flow** is a full identity-verification experience using document scanning (OCR) and selfie capture (biometrics) to confirm the user’s identity.

Best for workflows where document and biometric verification are mandatory.

<Tabs>
  <Tab title="IDV Only User Journey">
    <img />

    ### Typical Journey

    1. Customer scans a government ID (e.g. passport, licence, national ID).

    2. Customer takes a selfie for liveness and face matching.

    3. Vendor performs OCR, ID document checks and biometric comparison.

    4. Data is validated through connected sources upon submission based on your recipes and workflows.

    5. Results are returned to your Portal or via API.

    6. Entity information, risk scores and status are updated automatically.
  </Tab>

  <Tab title="Generating Hosted OneSDK Link with IDV Only Flow">
    Creating a POST Request with following headers and request Body

    ```shell theme={null}
            curl --location 'https://api.frankie.one/v2/individuals/hostedUrl' \ 
    		--header 'X-Frankie-Customerid: CUSTOMER_ID' \
    		--header 'api_key: API_KEY' \
    		--header 'Content-Type: application/json' \
    		--data '{
    				"customerRef": "YOUR_CUSTOMER_ID_OR_RANDOM_STRING",
    				"consent": true,
    				"oneSDKFlowId": "idv"
    		}'
    ```

    will return object:

    ```json theme={null}
        {
        	"entityId": "998a9d13-994b-4533-8a18-95208165cc9f",
        	"requestId": "01K1EWDQZRT7XPEGGWHJR1ZR4V",
        	"status": "success",
        	"url": "https://verify.uat.frankie.one/v2/?t=7MnbsKqvvXGucHxyy9p6cH",
        	"urlExpiry": "2025-08-02T23:59:32.081184475Z"
        }
    ```

    where `url` will contain the link to our Hosted OneSDK Solution. To read more, go <a href="/api-reference/provide-onboarding-url-for-hosted-onesdk">here.</a>
  </Tab>
</Tabs>

### Key Features

1. OCR extracting document information

2. Selfie comparison with portrait image on ID document

3. Built-in document fraud detection, selfie capture and liveness detection

4. Access Image of ID docs and Selfie on FrankieOne Portal or via API

5. FrankieOne provides integration with the most popular IDV vendors on the market

## OCR Only Flow

The **OCR-Only Flow** focuses on quick document validation without biometric capture.

It’s ideal for lower-risk onboarding, identity pre-checks, or use cases where a selfie step is unnecessary. Faster completion times and higher conversion.

<Tabs>
  <Tab title="IDV Only User Journey">
    <img />
  </Tab>

  <Tab title="Generating Hosted OneSDK Link with IDV Only Flow">
    Creating a POST Request with following headers and request Body

    ```shell theme={null}
    		curl --location 'https://api.frankie.one/v2/individuals/hostedUrl' \            
    		--header 'X-Frankie-Customerid: CUSTOMER_ID' \
    		--header 'api_key: API_KEY' \
    		--header 'Content-Type: application/json' \
    		--data '{
    				"customerRef": "YOUR_CUSTOMER_ID_OR_RANDOM_STRING",
    				"consent": true,
    				"oneSDKFlowId": "idv_review"
    		}'
    ```

    will return object:

    ```json theme={null}
        {
        	"entityId": "998a9d13-994b-4533-8a18-95208165cc9f",
        	"requestId": "01K1EWDQZRT7XPEGGWHJR1ZR4V",
        	"status": "success",
        	"url": "https://verify.uat.frankie.one/v2/?t=7MnbsKqvvXGucHxyy9p6cH",
        	"urlExpiry": "2025-08-02T23:59:32.081184475Z"
        }
    ```

    where`url` will contain the link to our Hosted OneSDK Solution. To read more, go <a href="/api-reference/provide-onboarding-url-for-hosted-onesdk">here.</a>
  </Tab>
</Tabs>

## eKYC Forms Flow

The eKYC Forms Flow on the Hosted OneSDK allow customers to embed or send their end-users a link with a fixed set of forms that allow PII data to be captured and used for KYC. Customers will gain access to the following screens in sequence with no ability to make any modifications.

<Tabs>
  <Tab title="eKYC Forms Flow User Journey">
    <img />

    ### Typical Journey

    1. Customer fills in personal details (name, DOB, address).

    2. Data is validated through connected sources upon submission based on your recipes and workflows.

    3. Results are returned to your Portal or via API.

    4. Entity information, risk scores and status are updated automatically
  </Tab>

  <Tab title="Generating Hosted OneSDK Link with eKYC Forms Flow">
    Creating a POST Request with following headers and request Body

    ```shell theme={null}
    		curl --location 'https://api.frankie.one/v2/individuals/hostedUrl' \
    		--header 'X-Frankie-Customerid: CUSTOMER_ID' \
    		--header 'api_key: API_KEY' \
    		--header 'Content-Type: application/json' \
    		--data '{
    				"customerRef": "YOUR_CUSTOMER_ID_OR_RANDOM_STRING",
    				"consent": true,
    				"oneSDKFlowId": "manual_kyc"
    		}'
    ```

    will return object:

    ```json theme={null}
        {
        	"entityId": "998a9d13-994b-4533-8a18-95208165cc9f",
        	"requestId": "01K1EWDQZRT7XPEGGWHJR1ZR4V",
        	"status": "success",
        	"url": "https://verify.uat.frankie.one/v2/?t=7MnbsKqvvXGucHxyy9p6cH",
        	"urlExpiry": "2025-08-02T23:59:32.081184475Z"
        }
    ```

    where `url` will contain the link to our Hosted OneSDK Solution. To read more, go <a href="/api-reference/provide-onboarding-url-for-hosted-onesdk">here.</a>
  </Tab>
</Tabs>

### Key Features

1. Manual entry of PII (personal identity information), document information

2. One-click submission to FrankieOne KYC checks with DVS, PEP and AML options


# IDV & Biometrics
Source: https://docs.frankieone.com/docs/idv-biometrics-guide



Learn how to implement IDV and Biometrics in your KYC processes.

## Introduction

FrankieOne's Identity Verification (IDV) and Biometrics services are designed to accurately identify and onboard genuine individuals while effectively preventing fraud from falsified or stolen identification documents.

By integrating advanced document analysis, Optical Character Recognition (OCR), and biometric checks like facial comparison and liveness detection, you can build a robust, secure, and compliant onboarding workflow.

This guide will walk you through the end-to-end process of implementing our IDV and Biometrics solution, from creating an entity to initiating the verification workflow.

**Key Features**

* **Global Document Verification:** Validate a wide range of government-issued identity documents from around the world.
* **Advanced Biometric Authentication:** Secure your platform with facial recognition and liveness detection to prevent spoofing and ensure the user is physically present.
* **Automated Data Extraction (OCR):** Reduce manual entry and errors by automatically extracting information from identity documents.
* **Configurable Workflows:** Tailor the verification steps and logic to match your specific risk appetite and compliance requirements.
* **Streamlined Integration:** Use our Hosted URL for the quickest integration or leverage our SDKs for a more customized user experience.

***

## The End-to-End IDV Flow

The verification process involves a sequence of API calls to create an entity, initiate a capture session, process the captured data, and finally execute a workflow to get a result.

<Steps>
  <Step title="Step 1: Create an Individual Entity">
    Before you can perform an IDV check, you need an `entityId` for the user. If you don't already have one, create an individual entity by making a server-side call to the API.

    ```BASH theme={null}
    POST /v2/individuals
    ```

    This request creates the user's profile in the FrankieOne system and returns the essential `entityId` that will be used in all subsequent steps.
  </Step>

  <Step title="Step 2: Initiate the Capture Session">
    Once you have an `entityId`, you can start the data capture process where the user will submit their document and a selfie. We offer two primary integration paths.

    #### Option A: Hosted Flow (Recommended)

    The simplest way to integrate is by using our Hosted URL. This provides a secure, FrankieOne-hosted webpage that guides the user through the entire capture process.

    Make a server-side call to generate a unique, single-use URL for the user's session.

    ```BASH theme={null}
    POST /v2/individuals/hostedUrl
    ```

    You can then redirect the user to this URL. You can even configure it to send the link directly to the user via SMS by setting `sendSMS` to `true` in your request.

    #### Option B: Direct SDK Integration (Advanced)

    For a more deeply integrated, native experience within your own application, you can use an IDV provider's SDK. To initialize it, you first need to retrieve a session token from our API.

    ```BASH theme={null}
    POST /v2/individuals/{entityId}/actions/idv/token
    ```

    This token authorizes the provider's SDK to conduct the capture session on behalf of the specified `entityId`.
  </Step>

  <Step title="Step 3: Trigger Data Processing">
    After the user successfully completes the document and selfie capture in the Hosted Flow or provider SDK, your backend must instruct FrankieOne to retrieve and process the captured data.

    ```BASH theme={null}
    POST /v2/individuals/{entityId}/actions/idv/process
    ```

    This call signals that the capture is complete and triggers FrankieOne to fetch the results from the IDV vendor, including the OCR data and biometric information.
  </Step>

  <Step title="Step 4: Execute Workflow and Get Results">
    Upon successful data processing, the IDV service will automatically execute the workflow configured for the entity's service profile (e.g., `DEFAULT`). This workflow runs the necessary verification steps and generates the final results.

    To learn how to analyze the detailed outcomes of these checks, please see our dedicated guide:
    **[Understanding IDV & Biometrics Results](/docs/idv-biometrics-guide-results)**.
  </Step>
</Steps>

***

## Understanding the Verification Checks

The IDV workflow orchestrates several powerful checks to ensure the integrity of the verification.

* **Document Authenticity**: The system analyzes the document for signs of tampering, fraud, and inconsistencies, verifying security features and comparing it against known templates. Checks include `visual_authenticity` and `image_integrity`.
* **Biometric Verification**: This involves two key checks:
  * **Facial Liveness**: Confirms the user is a real, live person and not a spoof attempt (e.g., a photo of a photo or a deepfake).
  * **Facial Comparison**: Matches the user's live selfie against the photo on the identity document with a quantifiable `confidence` score.
* **OCR Data Comparison**: After extracting data from the document via OCR, the system compares it against the information stored in the user's entity profile. This crucial step flags discrepancies between what the user provided and what is on their official document.

<Note>
  FrankieOne uses fuzzy matching logic (the Levenshtein distance algorithm) to handle minor OCR errors or typos in names and numbers. This reduces false negatives from insignificant discrepancies. For example, by default, a name is allowed a Levenshtein distance of 2 before it is flagged as `SUSPECTED`.
</Note>


# Understanding IDV & Biometrics
Source: https://docs.frankieone.com/docs/idv-biometrics-guide-results



## Locating IDV & Biometrics Results

Once a workflow has been executed, the detailed results are nested within the overall `workflowResult` object. To find the specific outcomes of IDV and Biometric checks, you must navigate the JSON structure.

1. **Start with `workflowStepResults`**: In the `workflowResult`, find the `workflowStepResults` array.
2. **Identify IDV Steps**: Look for steps with names (`stepName`) like `IDV_DOCUMENT_CHECK`, `IDV_FACIAL_COMPARISON`, `IDV_FACIAL_LIVENESS`, and `IDV_OCR_COMPARISON`.
3. **Examine `processResults`**: Inside each relevant step result is a `processResults` array. Each object here is a Process Result Object (PRO) containing granular data.
4. **Drill into `supplementaryData`**: The richest details are in the `supplementaryData` object within a PRO. The `type` field here is crucial as it defines the structure and meaning of the data.

### Decoding `supplementaryData` for IDV Checks

The structure of the `supplementaryData` object is determined by its `type`. For IDV and Biometrics, you will encounter several key types.

***

#### Type: `IDV_DOCUMENT`

This object contains the results of the automated analysis of a submitted identity document, assessing its authenticity and integrity.

<Accordion title="Example: supplementaryData for IDV-Document">
  ```json theme={null}
  "supplementaryData": {
    "type": "IDV_DOCUMENT",
    "outcomeRaw": "clear",
    "resultMap": {
      "visual_authenticity": { "resultNormalized": "clear" },
      "image_integrity": { "resultNormalized": "clear" },
      "data_validation": { "resultNormalized": "clear" },
      "compromised_document": { "resultNormalized": "clear" }
    },
    "detectedDocumentType": "DRIVERS_LICENSE",
    "detectedDocumentCountry": "AUS"
  }
  ```
</Accordion>

**Key Fields:**

* `outcomeRaw`: The original, unprocessed result from the IDV service provider.
* `resultMap`: A map containing the results of specific checks. Keys like `visual_authenticity`, `image_integrity`, and `data_validation` indicate the status of different verification aspects.
* `detectedDocumentType`: The type of document the system identified (e.g., `DRIVERS_LICENSE`, `PASSPORT`).
* `detectedDocumentCountry`: The ISO 3166-1 alpha-3 country code of the document as detected by the provider.

***

#### Type: `IDV_FACIAL_COMPARISON`

This object provides the results of comparing a user's selfie with the photo on their identity document to confirm they are the same person.

<Accordion title="Example: supplementaryData for IDV-Facial-Comparison">
  ```json theme={null}
  "supplementaryData": {
    "type": "IDV_FACIAL_COMPARISON",
    "outcomeRaw": "clear",
    "resultMap": {
      "face_comparison": {
          "confidence": 99.99,
          "resultNormalized": "clear"
      }
    },
    "comparedDocumentId": "92de15f6-5717-4562-b3fc-2c963f6665a7",
    "comparedSelfieId": "58e0a7e3-0c3f-4e20-95af-0a4a8332d383"
  }
  ```
</Accordion>

**Key Fields:**

* `resultMap`: Contains metrics from the comparison. The `face_comparison` key often includes a `confidence` score.
* `comparedDocumentId`: The unique ID of the identity document used.
* `comparedSelfieId`: The unique ID of the selfie document used.

***

#### Type: `IDV_FACIAL_LIVENESS`

This object contains the results of the liveness check, which verifies that the selfie was captured from a live person and not a spoof attempt (e.g., a photo of a photo).

<Accordion title="Example: supplementaryData for IDV-Facial-Liveness">
  ```json theme={null}
  "supplementaryData": {
    "type": "IDV_FACIAL_LIVENESS",
    "outcomeRaw": "clear",
    "resultMap": {
      "liveness_detection": {
          "confidence": 98.7,
          "resultNormalized": "clear"
      }
    },
    "comparedSelfieId": "58e0a7e3-0c3f-4e20-95af-0a4a8332d383"
  }
  ```
</Accordion>

**Key Fields:**

* `resultMap`: Contains the outcome of the liveness test. The `liveness_detection` key will often have a `confidence` score.
* `comparedSelfieId`: The unique ID of the selfie document that was analyzed.

***

#### Types: `IDV_OCR` & `IDV_OCR_COMPARISON`

The Optical Character Recognition (OCR) process is crucial for extracting data and verifying it against user-provided information. This typically generates two distinct PROs.

1. **`IDV_OCR`**: This object holds the raw data extracted directly from the identity document image. The `resultMap` will contain key-value pairs of the fields read from the document, such as `full_name`, `document_number`, and `date_of_birth`.

2. **`IDV_OCR_COMPARISON`**: This object compares the data extracted via OCR with the data already present on the entity. It is used to flag discrepancies.

<Accordion title="Example: supplementaryData for IDV-OCR-Comparison">
  ```json theme={null}
  "supplementaryData": {
    "type": "IDV_OCR_COMPARISON",
    "outcomeRaw": "suspected",
    "resultMap": {
      "last_name_match": { "resultNormalized": "clear" },
      "date_of_birth_match": { "resultNormalized": "clear" }
    },
    "mismatchMap": {
      "first_name_match": {
        "originalData": "Jon",
        "reviewedData": "John",
        "resultNormalized": "suspected"
      }
    },
    "comparisonSource": "ENTITY"
  }
  ```
</Accordion>

**Key `IDV_OCR_COMPARISON` Fields:**

* `resultMap`: Indicates which fields matched successfully.
* `mismatchMap`: **Crucially**, this highlights any fields that did not align, showing the original vs. the OCR-extracted data.
* `comparisonSource`: Specifies what the OCR data was compared against, either `ENTITY` data or `OCR_UPDATE` data.

<Callout icon="star">
  FrankieOne employs fuzzy matching logic (Levenshtein distance) for OCR comparison to account for minor typos or OCR errors. For example, a Levenshtein distance of 1 or 2 might be allowed for names before a mismatch is flagged as `SUSPECTED`.
</Callout>

## IDV Issues and Risk Factors

The results from the `supplementaryData` objects are used to generate specific **issues** and **risk factors** that help in decision-making.

* **Issues**: When a check result is `SUSPECTED` or `REJECTED`, a corresponding issue is typically created. For example, a `REJECTED` `IDV_FACIAL_LIVENESS` result will generate a `LIVENESS_DETECTION` issue with a `WARNING` severity.
* **Risk Factors**: The status of each check (`CLEAR`, `SUSPECTED`, `REJECTED`) is also converted into a risk factor (e.g., `idv_document_result`, `idv_facial_comparison_result`) which contributes to the entity's overall risk score.

## Overriding and Invalidating Results

* **Overriding**: If you disagree with an automated result (e.g., a `SUSPECTED` OCR mismatch), you can manually override it. By calling `PATCH /v2/individuals/{entityId}/results/idv` and providing the `processResultId` of the relevant PRO, you can change its `manualStatus` to `CLEAR`.
* **Invalidation**: IDV results can be automatically invalidated. For example, if an entity's name or date of birth is updated *after* a successful OCR check, the original OCR PRO's `systemStatus` will be changed from `VALID` to `STALE` or `MARKED_INVALID` to indicate that the result is no longer based on the most current entity data.


# IDV & Biometrics: OCR Comparison
Source: https://docs.frankieone.com/docs/idv-biometrics-ocr-comparison

A deep dive into how FrankieOne compares OCR data with user-provided information to ensure data consistency and prevent fraud.

## What is OCR Comparison?

Optical Character Recognition (OCR) is the process of extracting text data from an image, such as a driver's license or passport. The **OCR Comparison** is a critical security step within the IDV workflow where FrankieOne verifies that the data extracted from the document matches the information provided by the user or already stored on their entity profile.

The primary objective is to ensure the details on the government-issued ID match the entity profile being submitted for verification, preventing "bait-and-switch" fraud scenarios.

## How OCR Comparison Works

The comparison logic is triggered in two primary scenarios:

1. **Manual Input First**: If a user manually enters their details (e.g., name, DOB) *before* the document scan, the OCR comparison is triggered immediately after the scan to check for discrepancies.
2. **Biometrics First / Post-Verification Updates**: If the IDV process happens first, an entity is created using the initial OCR data. If the user later updates key fields (name, DOB, ID number) on their profile, the system re-runs the OCR comparison logic to check if the changes invalidate the original verification.

### The `IDV_OCR_COMPARISON` Supplementary Data

The result of this check is found within a Process Result Object (PRO) where the `supplementaryData` object has a `type` of `IDV_OCR_COMPARISON`.

<Accordion title="Example: supplementaryData for IDV-OCR-Comparison">
  ```json theme={null}
  "supplementaryData": {
    "type": "IDV_OCR_COMPARISON",
    "outcomeRaw": "suspected",
    "resultMap": {
      "last_name_match": { "resultNormalized": "clear" },
      "date_of_birth_match": { "resultNormalized": "clear" }
    },
    "mismatchMap": {
      "first_name_match": {
        "originalData": "Jon",
        "reviewedData": "John",
        "resultNormalized": "suspected"
      }
    },
    "ocrResultId": "pro_01J...",
    "comparisonSource": "ENTITY"
  }
  ```
</Accordion>

**Key Fields:**

* `resultMap`: An object showing which fields **matched successfully**.
* `mismatchMap`: An object that highlights the specific fields that **did not match**. This is crucial for debugging `SUSPECTED` results, as it shows the discrepancy (e.g., original "Jon" vs. OCR "John").
* `comparisonSource`: Indicates what the OCR data was compared against. This will be `ENTITY` (for existing entity data) or `OCR_UPDATE` (for data updated post-scan). \[cite: 2975-2979]
* `ocrResultId`: The ID of the `IDV_OCR` Process Result Object that this comparison is based on.

***

## Matching Logic and Fuzziness

To account for minor OCR inaccuracies or common typos, the comparison does not always require an exact match. FrankieOne uses the **Levenshtein distance** algorithm to measure the difference between the user-provided string and the OCR-extracted string.

This "fuzziness" is configurable. The default configuration allows for small discrepancies before a field is flagged as `SUSPECTED`.

| Field              | Default Levenshtein Distance |
| :----------------- | :--------------------------- |
| First Name         | 2                            |
| Last Name          | 2                            |
| Date of Birth      | 1                            |
| Document ID Number | 2                            |

There is also a `compare_ocr_max_mismatch_levenshtein_distance` which, by default, allows for up to 2 characters to be mismatched across all fields before the overall result is marked as `SUSPECTED`.

***

## Result Invalidation

A key security feature of the OCR comparison is the re-check that occurs if a user updates their profile information *after* the initial IDV process. This is to protect against a scenario where a fraudster:

1. Uses their real ID and face to pass an IDV check.
2. Later, changes the name, DOB, or ID number on their profile to match the details of a stolen identity.
3. Attempts to use this fraudulent profile to pass other checks like KYC or AML.

If the system detects that a change to a key field exceeds the configured Levenshtein distance (e.g., `fuzzy_logic_idv_allowed_distance_family_name`), the original OCR and IDV results will be invalidated by having their `systemStatus` changed to `STALE` or `MARKED_INVALID`.

## Best Practices

* **Check the `mismatchMap`**: When you receive an OCR comparison result of `SUSPECTED`, always inspect the `mismatchMap` to understand exactly which field caused the issue.
* **Understand Configuration**: Be aware that the definition of a "mismatch" is configurable. A `SUSPECTED` result does not necessarily mean fraud; it could be a minor OCR error that falls within your organization's acceptable risk tolerance.
* **Secure Profile Updates**: Be mindful of the result invalidation logic. If you allow users to freely edit their profile details after a successful IDV check, it may trigger an invalidation, requiring them to re-verify.

## Additional Resources

* [Interpreting Workflow Results](/docs/interpreting-workflows-v2)
* [Understanding IDV & Biometrics Results](/docs/idv-biometrics-guide-results)
* [FrankieOne API Reference](/docs/reference/whats-new)


# Indian Documents
Source: https://docs.frankieone.com/docs/indian-documents-v2



The FrankieOne KYC v2 API supports Indian documents for identity verification. This guide outlines the requirements and best practices for handling these documents.

## Supported Indian Documents

The FrankieOne KYC v2 API currently supports the following Indian documents for identity verification:

| Document                       | Code              |
| :----------------------------- | :---------------- |
| Aadhaar                        | `NATIONAL_ID`     |
| PAN (Permanent Account Number) | `NATIONAL_ID`     |
| Voter ID (EPIC)                | `NATIONAL_ID`     |
| Driver's License               | `DRIVERS_LICENSE` |
| Passport                       | `PASSPORT`        |

***

### Passports

Indian passports are official travel documents issued by the Indian government that confirm an individual's identity and citizenship. They include personal details such as the individual's name, date of birth, passport number, and file number.

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                                           |
      | :------------ | :------------ | :-------------------------------------------------------------------------------------------------------------- |
      | Document Type | `type`        | Must be `PASSPORT` for Indian passports.                                                                        |
      | Country       | `country`     | Must be `IND` (India).                                                                                          |
      | Date of Birth | `dateOfBirth` | Format: `YYYY-MM-DD`. Must match the date of birth as shown on the passport.                                    |
      | Name          | `name`        | Enter the full name exactly as shown on the passport, including capitalization, special characters, and spaces. |
    </Tab>

    <Tab title="Passport Details">
      | Field Name      | Field                 | Notes                                                                                                                  |
      | :-------------- | :-------------------- | :--------------------------------------------------------------------------------------------------------------------- |
      | Passport Number | `primaryIdentifier`   | Enter exactly as shown on the passport. Format: One uppercase letter followed by 7 digits (e.g., `J1234567`).          |
      | File Number     | `secondaryIdentifier` | Enter exactly as shown on the passport. Format: Two uppercase letters followed by 13 digits (e.g., `DL1234567890123`). |
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Document class must be 'IDENTITY' for KYC verification
    "primaryIdentifier": "J1234567", // Passport Number: One uppercase letter followed by 7 digits (e.g., 'J1234567')
    "secondaryIdentifier": "DL1234567890123", // File Number: Two uppercase letters followed by 13 digits (e.g., 'DL1234567890123')
    "type": "PASSPORT", // Document type must be 'PASSPORT' for Indian passports
    "country": "IND" // Country code must be 'IND' for India
  }
}
```

### Field Requirements

<AccordionGroup>
  <Accordion title="Passport Number">
    <Card title="Format Requirements">
      * Must consist of one uppercase letter followed by 7 digits
      * Example: `J1234567`
      * Case sensitive: only uppercase letters are accepted
      * Enter exactly as shown on the passport
    </Card>
  </Accordion>

  <Accordion title="File Number">
    <Card title="Format Requirements">
      * Must consist of two uppercase letters (typically the state code) followed by 13 digits
      * Example: `DL1234567890123`
      * Should be provided in the `secondaryIdentifier` field
      * Enter exactly as it appears on the passport
    </Card>
  </Accordion>

  <Accordion title="Name Format">
    <Card title="Name Requirements">
      * Given name and family name are required; middle name is optional
      * Names must match the passport exactly, including capitalization, special characters, and spaces
      * Include the display name exactly as shown on the passport
    </Card>
  </Accordion>
</AccordionGroup>

***

### Aadhaar (National ID)

Aadhaar is a 12-digit unique identification number issued by the Unique Identification Authority of India (UIDAI). It serves as a proof of identity and address for Indian residents and is widely used for identity verification purposes.

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                                               |
      | :------------ | :------------ | :------------------------------------------------------------------------------------------------------------------ |
      | Document Type | `type`        | Must be `NATIONAL_ID` for Aadhaar.                                                                                  |
      | Country       | `country`     | Must be `IND` (India).                                                                                              |
      | Date of Birth | `dateOfBirth` | Format: `YYYY-MM-DD`. Must match the date of birth as shown on the Aadhaar card.                                    |
      | Name          | `name`        | Enter the full name exactly as shown on the Aadhaar card, including capitalization, special characters, and spaces. |
    </Tab>

    <Tab title="Aadhaar Details">
      | Field Name     | Field               | Notes                                                                                                |
      | :------------- | :------------------ | :--------------------------------------------------------------------------------------------------- |
      | Aadhaar Number | `primaryIdentifier` | Enter exactly as shown on the Aadhaar card. Format: 12 digits without dashes (e.g., `304365000000`). |
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Document class must be 'IDENTITY' for KYC verification
    "primaryIdentifier": "304365000000", // Aadhaar Number: 12 digits without dashes
    "type": "NATIONAL_ID", // Document type must be 'NATIONAL_ID' for Aadhaar
    "country": "IND" // Country code must be 'IND' for India
  }
}
```

<Note>
  **Sandbox Testing:** To test Aadhaar verification in the sandbox environment, use the number `304365000000`, which will return a successful (pass) result.
</Note>

### Field Requirements

<AccordionGroup>
  <Accordion title="Aadhaar Number">
    <Card title="Format Requirements">
      * Must consist of exactly 12 digits
      * Example: `304365000000`
      * Do not include dashes or spaces
      * Enter exactly as shown on the Aadhaar card
    </Card>
  </Accordion>

  <Accordion title="Name Format">
    <Card title="Name Requirements">
      * Given name and family name are required; middle name is optional
      * Names must match the Aadhaar card exactly, including capitalization, special characters, and spaces
      * Include the display name exactly as shown on the Aadhaar card
    </Card>
  </Accordion>
</AccordionGroup>

***

### PAN (Permanent Account Number)

PAN is a ten-character alphanumeric identifier issued by the Indian Income Tax Department. It is used for tracking financial transactions and serves as an important identity document.

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                                    |
      | :------------ | :------------ | :------------------------------------------------------------------------------------------------------- |
      | Document Type | `type`        | Must be `NATIONAL_ID` for PAN.                                                                           |
      | Country       | `country`     | Must be `IND` (India).                                                                                   |
      | Date of Birth | `dateOfBirth` | Format: `YYYY-MM-DD`. Must match the date of birth associated with the PAN.                              |
      | Name          | `name`        | Enter the full name exactly as registered with the PAN, including capitalization and special characters. |
    </Tab>

    <Tab title="PAN Details">
      | Field Name | Field               | Notes                                                                                                  |
      | :--------- | :------------------ | :----------------------------------------------------------------------------------------------------- |
      | PAN Number | `primaryIdentifier` | Format: 5 uppercase letters + 4 digits + 1 uppercase letter (e.g., `AAAPL1234C`). Total 10 characters. |
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Document class must be 'IDENTITY' for KYC verification
    "primaryIdentifier": "AAAPL1234C", // PAN Number: 5 letters + 4 digits + 1 letter (10 characters)
    "type": "NATIONAL_ID", // Document type must be 'NATIONAL_ID' for PAN
    "country": "IND" // Country code must be 'IND' for India
  }
}
```

### Field Requirements

<AccordionGroup>
  <Accordion title="PAN Number">
    <Card title="Format Requirements">
      * Must be exactly 10 characters
      * First 5 characters are uppercase letters
      * Next 4 characters are digits
      * Last character is an uppercase letter
      * Example: `AAAPL1234C`
      * Enter exactly as shown on the PAN card
    </Card>
  </Accordion>

  <Accordion title="Name Format">
    <Card title="Name Requirements">
      * Given name and family name are required; middle name is optional
      * Names must match the PAN registration exactly, including capitalization and special characters
    </Card>
  </Accordion>
</AccordionGroup>

***

### Voter ID (EPIC)

The Electors Photo Identity Card (EPIC) is issued by the Election Commission of India. It serves as a primary proof of identity and is widely accepted for identity verification.

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                                  |
      | :------------ | :------------ | :----------------------------------------------------------------------------------------------------- |
      | Document Type | `type`        | Must be `NATIONAL_ID` for Voter ID.                                                                    |
      | Country       | `country`     | Must be `IND` (India).                                                                                 |
      | Date of Birth | `dateOfBirth` | Format: `YYYY-MM-DD`. Must match the date of birth as shown on the Voter ID.                           |
      | Name          | `name`        | Enter the full name exactly as shown on the Voter ID, including capitalization and special characters. |
    </Tab>

    <Tab title="Voter ID Details">
      | Field Name  | Field               | Notes                                                                                       |
      | :---------- | :------------------ | :------------------------------------------------------------------------------------------ |
      | EPIC Number | `primaryIdentifier` | Format: 3 uppercase letters followed by 7 digits (e.g., `ABC0000000`). Total 10 characters. |
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Document class must be 'IDENTITY' for KYC verification
    "primaryIdentifier": "ABC0000000", // EPIC Number: 3 letters + 7 digits (10 characters)
    "type": "NATIONAL_ID", // Document type must be 'NATIONAL_ID' for Voter ID
    "country": "IND" // Country code must be 'IND' for India
  }
}
```

### Field Requirements

<AccordionGroup>
  <Accordion title="EPIC Number">
    <Card title="Format Requirements">
      * Must be exactly 10 characters
      * First 3 characters are uppercase letters
      * Last 7 characters are digits
      * Example: `ABC0000000`
      * Enter exactly as shown on the Voter ID card
    </Card>
  </Accordion>

  <Accordion title="Name Format">
    <Card title="Name Requirements">
      * Given name and family name are required; middle name is optional
      * Names must match the Voter ID exactly, including capitalization and special characters
    </Card>
  </Accordion>
</AccordionGroup>

***

### Driver's License

Indian driver's licenses are issued by the Regional Transport Office (RTO) in each state. They contain a unique license number that encodes the state, RTO, and year of issue.

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                                          |
      | :------------ | :------------ | :------------------------------------------------------------------------------------------------------------- |
      | Document Type | `type`        | Must be `DRIVERS_LICENSE` for Indian driver's licenses.                                                        |
      | Country       | `country`     | Must be `IND` (India).                                                                                         |
      | Date of Birth | `dateOfBirth` | Format: `YYYY-MM-DD`. Must match the date of birth as shown on the license.                                    |
      | Name          | `name`        | Enter the full name exactly as shown on the license, including capitalization, special characters, and spaces. |
    </Tab>

    <Tab title="License Details">
      | Field Name     | Field               | Notes                                                                                                                                                                                   |
      | :------------- | :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
      | License Number | `primaryIdentifier` | Format: 16 characters total. 2 letters (state code) + 2 digits (RTO code) + 4 digits (year) + 7 digits. May include a hyphen or space (e.g., `HR-0619850034761` or `HR06 19850034761`). |
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Document class must be 'IDENTITY' for KYC verification
    "primaryIdentifier": "HR-0619850034761", // License Number: 16 characters (including hyphen or space)
    "type": "DRIVERS_LICENSE", // Document type must be 'DRIVERS_LICENSE' for Indian licenses
    "country": "IND" // Country code must be 'IND' for India
  }
}
```

### Field Requirements

<AccordionGroup>
  <Accordion title="License Number">
    <Card title="Format Requirements">
      * Must be 16 characters long (including space or hyphen)
      * First 2 characters: uppercase letters representing the state code (e.g., `HR` for Haryana, `DL` for Delhi)
      * Next 2 characters: digits representing the RTO code
      * Next 4 characters: digits representing the year the license was issued
      * Last 7 characters: digits (0-9)
      * May include a hyphen or space separator (e.g., `HR-0619850034761` or `HR06 19850034761`)
      * Enter exactly as shown on the license
    </Card>
  </Accordion>

  <Accordion title="Name Format">
    <Card title="Name Requirements">
      * Given name and family name are required; middle name is optional
      * Names must match the driver's license exactly, including capitalization, special characters, and spaces
    </Card>
  </Accordion>
</AccordionGroup>

***

<Callout icon="star">
  ##### Key Guidelines for Indian Document Verification

  **Name Matching**

  * Ensure the name matches the document exactly, including capitalization, special characters, spaces, and diacritical marks.
  * Enter the full name as displayed on the document.

  **Country Code**

  * For all Indian documents, set the country code to `IND`.

  **Document Numbers**

  * **Aadhaar:** 12 digits without dashes or spaces (e.g., `304365000000`).
  * **PAN:** 5 uppercase letters + 4 digits + 1 uppercase letter (e.g., `AAAPL1234C`).
  * **Voter ID (EPIC):** 3 uppercase letters + 7 digits (e.g., `ABC0000000`).
  * **Driver's License:** 16 characters — state code + RTO code + year + 7 digits (e.g., `HR-0619850034761`).
  * **Passport:** 1 uppercase letter + 7 digits (e.g., `R1234567`). File number in `secondaryIdentifier`.
  * Incorrect or expired document numbers will result in verification failure.

  **Date of Birth**

  * Use the ISO date format (`YYYY-MM-DD`) for the date of birth.

  **Best Practices**

  * Provide all available optional fields to improve verification accuracy.
  * Always include `class: "IDENTITY"` on all identity documents.
</Callout>


# International Documents
Source: https://docs.frankieone.com/docs/international-documents-v2



The FrankieOne KYC v2 API supports some International documents for identity verification. This guide provides details on how to handle these documents effectively.

## Supported International Documents

The FrankieOne KYC v2 API supports the following International documents:

| Document    | Code          |
| :---------- | :------------ |
| National ID | `NATIONAL_ID` |
| Passport    | `PASSPORT`    |

***

### International National ID Card (INE/IFE)

International National ID Cards are official identification documents issued by the government that confirm an individual's identity. They include personal details such as the individual's name, date of birth and ID card number.

**Required Fields**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                     |
      | :------------ | :------------ | :---------------------------------------------------------------------------------------- |
      | Country       | `country`     | Must be set to the ISO-3166-alpha3 country code (e.g. `CHN`, `MEX`)                       |
      | Date of Birth | `dateOfBirth` | Format must be `YYYY-MM-DD`                                                               |
      | Document Type | `type`        | Must be `NATIONAL_ID`                                                                     |
      | Name          | `name`        | Must match the National ID exactly (Given name, Middle name, Family name, and any others) |
    </Tab>

    <Tab title="ID Details">
      | Field Name           | Field                 | Notes                                                                                                               |
      | :------------------- | :-------------------- | :------------------------------------------------------------------------------------------------------------------ |
      | Primary Identifier   | `primaryIdentifier`   | Enter the full ID number exactly as it appears on the document, including all leading zeros and special characters. |
      | Secondary Identifier | `secondaryIdentifier` | Optional. If provided, include any additional identifiers such as a laser code or file number.                      |
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY",
    "documentId": "92de15f64-5717-4562-b3fc-2c963f6665a7",
    "primaryIdentifier": "000734130", // ID Number
    "secondaryIdentifier": "q12313124", // Laser Code or File Number when applicable
    "type": "NATIONAL_ID",
    "country": "CHN",
    },
    "supplementaryData": {
      "type": "NATIONAL_ID",
      "homeCountryFullName": "张伟明", // Full name in Foreign characters when applicable
      "paternalFamilyName": "MENDOZA", // LATAM IDs when applicable
      "maternalFamilyName": "GARCIA" // LATAM IDs when applicable
  }
}
```

**Name Handling Guidelines:**

<AccordionGroup>
  <Accordion title="Pinyin Name Format">
    ```json theme={null}
    {
      "familyName": "ZHANG",     // Family name in CAPS
      "givenName": "WEIMING"     // Given and middle name can be combined
    }
    ```
  </Accordion>

  <Accordion title="Chinese Name Format">
    ```json theme={null}
    {
      "document": {
        "supplementaryData": {
          "homeCountryFullName": "张伟明", // Full name in Chinese characters 
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="LATAM Name Format">
    ```json theme={null}
    {
      "document": {
        "supplementaryData": {
          "paternalFamilyName": "MENDOZA", // Paternal family name
          "maternalFamilyName": "GARCIA"   // Maternal family name
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

<Callout icon="bell">
  ##### Important Considerations for National ID

  Please ensure the following:

  * Names must match exactly as they appear on the ID, including all components and order
  * Date of birth must be in the `YYYY-MM-DD` format
  * Country code must use the ISO-3166-alpha3 standard (e.g., `CHN`, `MEX`)
  * ID number must include all leading zeros and special characters exactly as shown on the document
</Callout>

***

### International Passports

International passports are official travel documents issued by the government that confirm an individual's identity and citizenship. They include personal details such as the individual's name, date of birth and passport number.

**Required Fields**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                                     |
      | :------------ | :------------ | :-------------------------------------------------------------------------------------------------------- |
      | Country       | `country`     | Must be the ISO-3166-alpha3 country code of passport issuance (e.g., `AUS`, `GBR`).                       |
      | Date of Birth | `dateOfBirth` | Format: `YYYY-MM-DD`. Must match the date of birth on the passport.                                       |
      | Document Type | `type`        | Must be `PASSPORT`.                                                                                       |
      | Name          | `name`        | Enter the full name exactly as it appears on the passport, including all given, middle, and family names. |
    </Tab>

    <Tab title="Passport Details">
      | Field Name           | Field                 | Notes                                                                                                        |
      | :------------------- | :-------------------- | :----------------------------------------------------------------------------------------------------------- |
      | Primary Identifier   | `primaryIdentifier`   | Enter the complete passport number exactly as shown, including all leading zeros.                            |
      | Secondary Identifier | `secondaryIdentifier` | Optional. Include any additional identifiers such as a file number or laser code if present on the passport. |
      | Expiry Date          | `expiryDate`          | Must be in `YYYY-MM-DD` format if available. Ensure the passport is valid and not expired.                   |
    </Tab>
  </Tabs>
</Card>

<Accordion title="Passport Number Formats">
  International passport numbers vary significantly by country in length and format. Our system supports alphanumeric characters with a length of up to 14 characters to accommodate a wide range of international standards.

  * **Length:** 1 to 14 characters.
  * **Format:** Alphanumeric (`[A-Za-z0-9]*`). No special characters are supported.
  * **Guideline:** Always enter the passport number exactly as it appears on the document, including any leading zeros. \[cite: 3459]
</Accordion>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Document class, always "IDENTITY" for passports
    "expiryDate": {
      "year": "1990", // Expiry year as four digits
      "month": "03", // Expiry month as two digits
      "day": "27", // Expiry day as two digits
      "unstructured": "1990-03-27", // Expiry date in ISO format (YYYY-MM-DD)
      "type": "GREGORIAN" // Calendar type, typically "GREGORIAN"
    },
    "primaryIdentifier": "000734130", // Passport number, include all leading zeros exactly as shown
    "secondaryIdentifier": "q12313124", // Optional. File number, laser code, or other secondary identifier if present
    "type": "PASSPORT", // Document type, must be "PASSPORT"
    "country": "AUS", // Country of issuance, ISO-3166-alpha3 code (e.g., "AUS" for Australia)
    "supplementaryData": {
      "type": "PASSPORT", // Repeats document type for supplementary data
      "homeCountryFullName": "张伟明" // Full name in native script, if applicable (e.g., Chinese characters)
    }
  }
}
```

<Callout icon="star">
  ##### Passport Number Guidelines

  * Passport numbers are typically alphanumeric and 8–9 characters long, but formats vary by country.
  * Most do not include special characters, though some legacy documents may.
  * Always enter the passport number exactly as shown, including all leading zeros.
</Callout>

<Callout icon="bell">
  ##### Common Validation Issues

  * Expired passports or invalid expiry dates
  * Incorrect country codes (must be ISO-3166-alpha3, e.g., `AUS`, `GBR`)
  * Name does not match the passport exactly (including all components and order)
  * Incorrect date formats (must be `YYYY-MM-DD`)
</Callout>

<Info>
  ##### Best Practices for Name Handling

  * Use the Machine Readable Zone (MRZ) spelling if available.
  * Remove diacritical marks and convert names to uppercase.
  * Follow ICAO transliteration rules for special characters.
  * Enter all name components exactly as they appear on the passport.
</Info>


# Interpreting Workflows
Source: https://docs.frankieone.com/docs/interpreting-workflows-v2

A developer's guide to parsing the workflowResult object, from the overall status down to the granular details of each check.

## Understanding the Workflow Response

After executing a workflow, the API returns a comprehensive `workflowResult` object. This object is the key to understanding the outcome of every check performed. This guide provides a structured, top-down walkthrough of how to parse this response, explaining each key object from the final verdict down to the granular evidence.

<Accordion title="View Full API Response Example">
  The examples in this guide refer to the following API response for workflow execution `01JZHEX5FQA4DJB0MMJFZR26JS`. Click to expand and see the full structure

  ```JSON theme={null}
      {  
          "individual": {  
              "entityId": "99f16410-2613-4181-8cf1-048625900013",  
              "name": { "displayName": "MARY TESTFOURTEEN", "...": "..." },  
              "...": "..."  
          },  
          "requestId": "01JZHEX0WX2QEM6EY139D5NNP1",  
          "workflowResult": {  
              "workflowExecutionId": "01JZHEX5FQA4DJB0MMJFZR26JS",  
              "workflowExecutionState": "COMPLETED",  
              "status": "PASS",  
              "result": "PASS",  
              "riskAssessment": {  
                  "riskLevel": "LOW",  
                  "riskScore": 12,  
                  "riskFactors": [ { "factor": "entity_type", "value": "INDIVIDUAL", "score": 2 }, { "factor": "entity_age", "value": "62", "score": 10 } ]  
              },  
              "steps": {  
                  "passed": [ "START", "MATCHLIST", "KYC", "AML", "DECISION", "FINISH" ],  
                  "failed": [ "IDV" ],  
                  "order": [ "START", "MATCHLIST", "KYC", "IDV", "AML", "TOGGLE_MONITORING", "DECISION", "FINISH" ],  
                  "...": "..."  
              },  
              "issues": [],  
              "workflowStepResults": [  
                  {  
                      "stepName": "KYC",  
                      "result": "MATCH",  
                      "processResults": [  
                          {  
                              "processResultId": "01JZ4H0P59KGQR9DZCWZ6JQRY0",  
                              "class": "KYC",  
                              "objectType": "NAME",  
                              "result": "MATCH",  
                              "state": "COMPLETED",  
                              "systemStatus": "VALID",  
                              "providerResult": {  
                                  "name": "con_testbed-docs",  
                                  "source": "au-govid1-pp"  
                              },  
                              "supplementaryData": {  
                                  "type": "KYC_NAME",  
                                  "matchStrengths": {  
                                      "fullName": 75,  
                                      "familyName": 75,  
                                      "givenName": 75  
                                  }  
                              }  
                          }  
                      ],  
                      "summary": {  
                          "matchedRules": [  
                              {  
                                  "ruleName": "gov_id_only",  
                                  "isVerified": true,  
                                  "matchDetails": [  
                                      {  
                                          "provider": "con_testbed-docs",  
                                          "source": "au-govid1-pp",  
                                          "attributesMatched": [ "dateOfBirth", "govId", "name" ]  
                                      }  
                                  ]  
                              }  
                          ]  
                      },  
                      "...": "..."  
                  }  
              ]  
          }  
      }
  ```
</Accordion>

***

## Part 1: The Overall Outcome (The Final Verdict)

Start by examining the top-level fields of the `workflowResult` object. These provide the final, authoritative outcome of the entire workflow execution.

| Field Name               | Importance | Description                                                                                                                                                                  |
| :----------------------- | :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`                 | ‼️         | **This is the most important field.** It represents the conclusive recommendation and accounts for any manual overrides. **Base your primary business logic on this value.** |
| `workflowExecutionState` | ‼️         | This confirms the workflow’s technical status. It **`must beCOMPLETED`** for the `status` to be considered final.                                                            |
| `result`                 | ⚠️         | This field holds the original, automated outcome of the workflow *before* any manual changes. It is useful for auditing.                                                     |
| `issues`                 | ⚠️         | An array of problems that may require manual review. If the `status` is `REVIEW`, this array will contain the specific reasons why.                                          |

### Workflow Execution States (`workflowExecutionState`)

This field tells you if the workflow ran to completion.

| State         | Description                                                           |
| :------------ | :-------------------------------------------------------------------- |
| `COMPLETED`   | The workflow executed successfully from start to finish.              |
| `IN_PROGRESS` | The workflow is still running.                                        |
| `ERROR`       | The workflow encountered an unrecoverable error and could not finish. |
| `TIMEOUT`     | The workflow exceeded its maximum execution time.                     |
| `CANCELED`    | The workflow was manually canceled before completion.                 |
| `TERMINATED`  | The workflow was terminated by the system before completion.          |

### When Each Execution State Occurs

#### COMPLETED

The workflow ran to completion. This is the expected state for most synchronous workflows.

* **Next step:** Check `workflowResult.status` for the verification outcome (PASS, FAIL, REVIEW, etc.)

#### IN\_PROGRESS

The workflow is still executing and has not yet reached a terminal state. This occurs when:

| Scenario                             | Example                                              |
| ------------------------------------ | ---------------------------------------------------- |
| Workflow includes asynchronous steps | IDV document verification, biometric/liveness checks |
| External provider is processing      | Third-party identity verification pending            |
| Waiting for user action              | Document upload or selfie capture in progress        |

**Handling IN\_PROGRESS responses:**

1. **Configure webhooks** (recommended) - Listen for completion events:
   * `RESULTS_RETRIEVED` - Verification results are ready
   * `FF_EXTERNAL_IDV_CHECK_COMPLETED` - IDV/biometric submission complete
2. **Poll for results** - Call `GET  /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}` to retrieve updated results
3. **Use the retrieve endpoint** - Call `/retrieve/{requestID}` with the `requestID` from the original response

> **Note:** Biometric checks are asynchronous and can take up to 5 minutes to complete. Do not treat `IN_PROGRESS`\
> as a failure.

#### ERROR

An unrecoverable error occurred during workflow execution. Common causes:

* Internal system error
* Invalid workflow configuration
* Data source connector failure

**Recommended action:** Log the `workflowExecutionId` and retry the request. If persistent, contact\
[support@frankieone.com](mailto:support@frankieone.com).

#### TIMEOUT

The workflow exceeded the maximum allowed execution time. Common causes:

* External data source unavailable or slow
* Network connectivity issues
* High system load

**Recommended action:** Retry with exponential backoff. Check [FrankieOne Status](https://status.frankieone.com) for service availability.

#### CANCELED

The workflow was manually canceled before completion. This can occur when:

* The request was explicitly canceled via API
* A dependent process was terminated

#### TERMINATED

The workflow was forcefully stopped by the system. This may indicate:

* System-level intervention
* Resource limits exceeded
* Security policy triggered

**Recommended action:** Contact [help@frankieone.com](mailto:support@frankieone.com) with the `workflowExecutionId` to investigate.

### Workflow Statuses (`status` and `result`)

This is the final recommendation of the workflow.

| Status                    | Description                                                                                    |
| :------------------------ | :--------------------------------------------------------------------------------------------- |
| `PASS`                    | The entity successfully met the workflow’s criteria.                                           |
| `FAIL`                    | The entity did not meet the workflow’s criteria.                                               |
| `REVIEW`                  | The workflow produced results that require manual review.                                      |
| `CLEAR`                   | Often used for monitoring, indicates no negative information was found.                        |
| `HIT`                     | Often used for monitoring, indicates negative information (e.g., a watchlist match) was found. |
| `URGENT`                  | A critical issue was found (e.g., a sanctions match) that requires immediate attention.        |
| `COMPLETE` / `INCOMPLETE` | The workflow finished, but a pass/fail determination was not applicable.                       |

### Detecting Manual Overrides

It’s crucial to know if a workflow’s result was changed by a person. When an operator manually changes the `status` (e.g., from `FAIL` to `PASS`), the following fields are populated:

* `statusOverrideRequestId`: The unique ID of the override request.
* `statusOverrideBy`: The user who performed the override.
* `statusOverrideAt`: The timestamp of the override.

**`To detect an override, check ifstatusOverrideRequestId exists and is not empty.`**

***

## Part 2: The Step-by-Step Breakdown (`workflowStepResults`)

The `workflowStepResults` array is a log of each individual check, explaining *how* the overall `status` was reached. Each object in this array corresponds to a step configured in your workflow (e.g., KYC, AML, IDV).

| Field Name       | Description                                                                                                           |
| :--------------- | :-------------------------------------------------------------------------------------------------------------------- |
| `stepName`       | The name of the step (e.g., `KYC`, `AML`).                                                                            |
| `result`         | The outcome of this specific step. See the table below for all possible values.                                       |
| `summary`        | A concise, human-readable summary of the step’s outcome. For a KYC step, this includes which matching rules were met. |
| `processResults` | An array of Process Result Objects (PROs) providing the granular evidence for this step’s result.                     |
| `risk`           | The risk assessment specific to this step, including the score it contributed to the overall risk.                    |

### Workflow Step Results (`result`)

| Result                      | Applicable Steps          | Description                                                                                                         |
| :-------------------------- | :------------------------ | :------------------------------------------------------------------------------------------------------------------ |
| MATCH / NO\_MATCH / PARTIAL | KYC, IDV, VISA            | The step produced a successful, unsuccessful, or partially successful match against data sources.                   |
| CLEAR / HIT                 | AML, MATCHLIST, DUPLICATE | The step checked against a negative list (e.g., AML watchlist) and found no matches (CLEAR) or found a match (HIT). |
| PASS / FAIL                 | DECISION, Manual KYC      | The step completed and met (PASS) or did not meet (FAIL) its required binary criteria.                              |
| COMPLETE / INCOMPLETE       | START, FINISH, RISK       | The step finished, but a pass/fail scenario was not applicable.                                                     |
| SKIPPED                     | Any Step                  | The step was skipped because it was not required to run.                                                            |
| MISSING\_DATA               | Any Step                  | The step could not run because it requires additional data.                                                         |
| ERROR                       | Any Step                  | The step encountered an unrecoverable technical error.                                                              |

***

## Part 3: The Granular Evidence (`processResults`)

For the deepest level of detail, look inside a `workflowStepResult` at its `processResults` array. A **Process Result Object (PRO)** is the raw evidence from a single check against a single data source.

| Field Name          | Description                                                                                                                                                                |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `processResultId`   | A unique identifier for this specific piece of evidence.                                                                                                                   |
| `class`             | The high-level category of the check. See the table below for details.                                                                                                     |
| `objectType`        | The specific data element that was checked (e.g., `NAME`, `ADDRESS`, `DOCUMENT`).                                                                                          |
| `result`            | The outcome of this specific check (e.g., `MATCH`, `HIT`, `CLEAR`).                                                                                                        |
| `providerResult`    | An object containing details from the downstream data provider, including the `source` of the data.                                                                        |
| `systemStatus`      | The lifecycle status of this PRO (e.g., `VALID`, `STALE`, `MARKED_INVALID`). A `STALE` status means the underlying entity data has changed since this check was performed. |
| `manualStatus`      | If an operator has manually reviewed this specific PRO, their conclusion (e.g., `TRUE_POSITIVE`, `FALSE_POSITIVE`) is recorded here.                                       |
| `supplementaryData` | A rich, context-specific object containing detailed metrics, like match scores or extracted OCR data.                                                                      |

### Process Result Classes (`class`)

| Class       | Description                                                                           |
| :---------- | :------------------------------------------------------------------------------------ |
| `KYC`       | An electronic Know Your Customer check against a data source.                         |
| `IDV`       | An Identity Verification check, typically involving biometrics and document analysis. |
| `AML`       | An Anti-Money Laundering screening against watchlists, sanctions, and PEP lists.      |
| `MATCHLIST` | A check against a custom internal or shared blocklist/allowlist.                      |
| `DUPLICATE` | A check to see if the entity is a duplicate of an existing entity.                    |
| `FRAUD`     | A fraud check, often related to device, IP, or behavioral signals.                    |

## Best Practices for Integration

* **`CheckworkflowExecutionState first`**: Always confirm the workflow is `COMPLETED` before trusting the `status`.
* **`Automate based onstatus`**: Use the top-level `status` field for your primary business logic (e.g., approve account, flag for review).
* **`Debug withworkflowStepResults`**: When you get an unexpected `FAIL` or `REVIEW`, loop through the `workflowStepResults` to find which `stepName` has a non-passing `result`. The `summary` and `processResults` within that step will tell you why.
* **`Log theworkflowExecutionId`**: This ID is your key for auditing, support queries, and correlating results.

## Synchronous vs Asynchronous Workflows

Workflow behavior depends on the types of checks configured in your workflow.

### Synchronous Workflows

Workflows containing only synchronous steps return `COMPLETED` immediately with the final result.

**Synchronous step types:**

* KYC data source checks (government databases, credit bureaus)
* AML/PEP/Sanctions screening
* Watchlist checks
* Duplicate detection

**Example response:**

```json theme={null}
{                                                                                                                   
  "workflowResult": {                                                                                               
    "workflowExecutionState": "COMPLETED",                                                                          
    "workflowExecutionId": "wfe_abc123",                                                                            
    "status": "PASS",                                                                                               
    "result": "PASS"                                                                                                
  }                                                                                                                 
}                                                                                                                   
                                                                                                                    
Asynchronous Workflows                                                                                              
                                                                                                                    
Workflows containing asynchronous steps may return IN_PROGRESS initially.                                           
                                                                                                                    
Asynchronous step types:                                                                                            
- IDV (Identity Document Verification)                                                                              
- Biometric verification / Liveness detection                                                                       
- Manual review steps                                                                                               
- Some third-party provider integrations                                                                            
                                                                                                                    
Example response:                                                                                                   
{                                                                                                                   
  "workflowResult": {                                                                                               
    "workflowExecutionState": "IN_PROGRESS",                                                                        
    "workflowExecutionId": "wfe_xyz789",                                                                            
    "status": null                                                                                                  
  }                                                                                                                 
}                                                                                                                   
                                                                                                                    
Determining Your Workflow Type                                                                                      
                                                                                                                    
To check if your workflow includes asynchronous steps:                                                              
1. Call GET /v2/workflows to list your configured workflows                                                         
2. Review the step configuration with your Customer Success Manager                                                 
3. Test in sandbox environment to observe response behavior                                                         
                                                                
```


# Introduction to FrankieOne & KYB
Source: https://docs.frankieone.com/docs/introduction-to-kyb

Discover the fundamentals of Know Your Business (KYB) and see how FrankieOne's unified platform empowers you to build trust, ensure compliance, and create seamless onboarding experiences for your business customers.

## The Cornerstone of Digital Trust

In today's global and digital economy, establishing trust is paramount. Know Your Business (KYB) is the foundational process that enables organizations to verify the legitimacy of the companies they engage with, ensuring they are dealing with real, trustworthy entities. It is a critical framework for preventing corporate fraud, reducing exposure to financial crime, and creating lasting, trusted business relationships.

<Accordion title="What is KYB?">
  Know Your Business (KYB) is the process of verifying and validating a business entity before entering into a financial or commercial relationship. It involves confirming the company’s registration, ownership structure, and overall legitimacy. A crucial part of KYB also includes identifying and verifying the key individuals who own or control the business, known as beneficial owners, ensuring full visibility of both the entity and the people behind it.
</Accordion>

<Accordion title="Why KYB is a Business Imperative?">
  A robust KYB strategy is a competitive advantage that protects your business, your customers, and your reputation. Its importance extends far beyond simple compliance.

  * **Mitigate Corporate Fraud:** Uncover shell companies and fraudulent structures to protect your organization from financial and reputational harm.
  * **Navigate Global Regulations:** Confidently meet requirements from AUSTRAC, FATF, FINCEN, and other global regulators.
  * **Meet AML/CTF Obligations:** Ensure the businesses you engage with are not used as conduits for illegal activity.
  * **Build and Maintain Customer Trust:** Demonstrating a strong commitment to security and compliance shows customers that you are a professional and trustworthy organization.
</Accordion>

<Accordion title="The KYB Journey: A Three-Stage Process">
  The KYB process can be broken down into three essential stages that create a comprehensive compliance framework.

  <Steps>
    <Step title="1. Business Identification">
      Confirm core entity information, such as registered name, incorporation details, and business identifiers (e.g., ABN/ACN in Australia).
    </Step>

    <Step title="2. UBO Verification">
      Identify and verify ultimate beneficial owners (UBOs) to ensure real ownership is disclosed, eliminating the risk of hidden or proxy structures.
    </Step>

    <Step title="3. Risk Assessment & Screening">
      Evaluate the business based on jurisdiction, industry, and structure. Screen both the entity and its associated individuals against sanctions, PEP lists, and adverse media.
    </Step>
  </Steps>
</Accordion>

## How FrankieOne Delivers a Unified Solution

FrankieOne replaces complexity with a single, intelligent platform. We provide the infrastructure to connect to global business registries and compliance tools through one API and one unified back-office portal.

* **Effortless Global Onboarding:** Integrate once and gain access to business registries and corporate data across multiple jurisdictions.
* **Automated and Risk-Based Workflows:** Automate data collection and verification to eliminate manual errors and accelerate onboarding. Configure dynamic, risk-based workflows that automatically escalate high-risk entities for enhanced due diligence.
* **Always-On Compliance:** FrankieOne is a fully managed solution that stays current with the latest regulatory requirements, significantly reducing your compliance burden.

## Our Unified KYB Product Suite

FrankieOne offers a comprehensive suite of products designed to work together, providing complete coverage across the entire KYB and fraud prevention lifecycle.

<CardGroup>
  <Card title="Business Registration Verification" icon="building-columns"> Rapidly validate entity details against authoritative sources worldwide. </Card>
  <Card title="UBO Discovery & Ownership Mapping" icon="sitemap"> Identify directors, shareholders, and ultimate beneficial owners to ensure complete visibility. </Card>
  <Card title="Watchlist & Sanctions Screening" icon="shield-check"> Screen businesses and associated individuals against global watchlists, PEP lists, and adverse media. </Card>
  <Card title="Corporate Risk Assessment" icon="balance-scale"> Evaluate risk holistically by considering jurisdiction, industry, and ownership structure. </Card>
</CardGroup>

<Check>
  Ready to Get Started?

  FrankieOne's team of compliance and integration experts are ready to help you design and deploy a world-class KYB solution. [Contact us today<Icon icon="arrow-up-right-from-square" />](https://www.frankieone.com/contactus) or dive into our [Core Product Deep Dive](/docs/core-product-deep-dive) to learn more.
</Check>


# AML Screening & Monitoring
Source: https://docs.frankieone.com/docs/kyb/anti-money-laundering

Learn how FrankieOne's AML solution helps you screen against global watchlists, manage risk, and maintain ongoing compliance.

## What is AML Screening?

Anti-Money Laundering (AML) screening is a critical compliance process for identifying individuals and organizations with connections to financial crime. It involves checking customer data against global watchlists to detect risks related to money laundering, terrorism financing, sanctions violations, and political exposure.

FrankieOne's solution streamlines this process, from initial real-time screening at onboarding to continuous, automated monitoring throughout the customer lifecycle.

***

## How AML Screening Works

Our AML capabilities are integrated directly into the FrankieOne workflow engine.

<Steps>
  <Step title="1. Create an Entity">
    First, you [/create](/api-reference/organizations/create-an-organization-entity) an `organization` entity with an `organizationToken` recorded from a lookup of the organization or you can use and `entityId` of an existing entity on which a data-fetch workflow like `ownership` or `profile` has been run using the [/execute](/api-reference/organization-workflows/execute-a-workflow-with-organization-details) endpoint.
  </Step>

  <Step title="2. Execute a Workflow">
    You then execute a workflow that has been configured with an **AML Step**. Our platform takes the entity's details and screens them against our connected data sources.
  </Step>

  <Step title="3. Receive Actionable Results">
    The workflow returns a clear result for the AML step—typically **`CLEAR`** or **`HIT`**. A `HIT` generates detailed Process Result Objects (PROs) and `issues` for any potential matches, allowing your team to investigate and classify the results.
  </Step>
</Steps>

***

## What We Screen For

Our AML solution checks against a wide array of global sources to provide a comprehensive risk profile.

* **Politically Exposed Persons (PEPs):** Identify individuals who hold prominent public functions and may present a higher risk for bribery or corruption.
* **Sanctions Lists:** Screen against lists of individuals, entities, and countries subject to economic or trade sanctions by governments and international bodies.
* **Adverse Media:** Scan global news sources for negative information linked to an individual that may indicate an elevated risk.
* **Other Regulatory & Law Enforcement Watchlists:** Check against a wide range of official lists to identify potential bad actors.

### Intelligent Matching

To increase accuracy and reduce false positives, our system uses sophisticated matching logic:

* **Name Matching**: Checks against the entity's full name, as well as known aliases.
* **Contextual Filtering**: Uses the entity's **date of birth**, **nationality**, and **country of residence** to filter out irrelevant matches from the screening results.

***

## Classifying AML Hits

When an AML screening results in a `HIT`, your compliance team needs to review the potential matches and classify them. This is a critical step in managing your AML risk.

You can update the status of one or more AML-related Process Result Objects (PROs) using the update [/results/aml](/api-reference/organization-results/update-the-status-of-aml-process-results) API.

**Request:**

```http theme={null}
PATCH /v2/organizations/{entityId}/results/aml
```

**Request Body:**

```json theme={null}
{
  "processResults": [
    "pro_01J285FC7DH5G113KF109RJHSD",
    "pro_01J285FC6MDNE7SZPVS8D3GC7S"
  ],
  "manualStatus": "FALSE_POSITIVE",
  "comment": {
    "text": "Reviewed by compliance officer. Matches are for a different individual with a similar name."
  }
}
```

### Manual Status Options (`manualStatus`)

When classifying a hit, you can set one of the following statuses:

| Status                 | Description                                                                                                           |
| :--------------------- | :-------------------------------------------------------------------------------------------------------------------- |
| `FALSE_POSITIVE`       | The match is not the same person you are onboarding.                                                                  |
| `TRUE_POSITIVE`        | The match is the same person, but a final decision has not been made. The hit remains unresolved.                     |
| `TRUE_POSITIVE_ACCEPT` | The match is the same person, and your organization has decided to accept the risk and proceed with the relationship. |
| `TRUE_POSITIVE_REJECT` | The match is the same person, and your organization has decided to reject the relationship.                           |
| `UNKNOWN`              | It is unclear if the match is the same person. The hit remains unresolved.                                            |
| `UNKNOWN_ACCEPT`       | It is unclear if the match is the same person, but your organization has decided to accept the risk.                  |
| `UNKNOWN_REJECT`       | It is unclear if the match is the same person, and your organization has decided to reject the relationship.          |

### Updating the Workflow Result After Classification

After classifying hits, the workflow needs to be updated so the entity's compliance status reflects the classifications. For example, a workflow that initially resulted in a `REVIEW` status due to unresolved hits may change to `PASS` if all hits are classified as `FALSE_POSITIVE`.

There are two ways to do this:

#### Re-evaluate the Workflow

Call the **evaluate** endpoint. This re-runs the decision and risk assessment steps using existing check results. It does **not** trigger new calls to external AML providers, so there is no additional provider cost.

```http theme={null}
POST /v2/organizations/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/evaluate
```

#### Re-run the Workflow

Call the **execute** endpoint to re-run the full workflow. This will contact external providers again (e.g., run a new AML search), which incurs additional cost and resets the aging window.

```http theme={null}
POST /v2/organizations/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/execute
```

<Callout icon="triangle-exclamation">
  Use `/evaluate` when only the decision needs updating based on changed classifications — it is faster, cheaper, and does not call external providers. Use `/execute` if the entity's underlying data has changed and fresh provider results are needed, or if existing check results have expired beyond the aging window.
</Callout>

***

## Additional Resources

* [Interpreting Workflow Results](/docs/kyb/interpreting-workflows-v2)
* [Handling AML Results](/docs/kyb/anti-money-laundering-results)


# Interpreting AML Screening Results
Source: https://docs.frankieone.com/docs/kyb/anti-money-laundering-results

A detailed guide to understanding the results of an AML check, from the high-level summary down to the details of each watchlist match.

## How to Read an AML Result

When you execute a workflow containing an AML step, the API response provides a rich set of data to help you understand the outcome. This guide provides a structured, "top-down" walkthrough of how to parse the `workflowResult` object.

<Accordion title="View Full API Response Example">
  The examples in this guide refer to a workflow execution response where Adverse Media matches were found. Click to expand and see the full structure.

  ```json theme={null}
  {
    "requestId": "01HN9XHZN6MGXM9JXG50K59Q85",
    "workflowResult": {
      "workflowExecutionId": "01K55F466SQBT41KMQ7PWGEEN3",
      "workflowExecutionState": "COMPLETED",
      "status": "REVIEW",
      "result": "REVIEW",
      "riskAssessment": {
          "riskLevel": "HIGH",
          "riskScore": 100,
          "riskFactors": [
              {
                "createdAt": "2025-09-15T01:16:45.849033Z",
                "description": "Has adverse media hits",
                "factor": "has_adverse_media",
                "riskFactorId": "b26d1a21-57f9-46ed-afc9-f7025980ad9c",
                "score": 10,
                "status": "VALID",
                "updatedAt": "2025-09-15T01:16:45.849033Z",
                "updatedRequestId": "01HN9XHZN6MGXM9JXG50K59Q85"
              }
          ]
      },
      "issues": [
        {
          "category": "AML",
          "createdAt": "2025-09-15T01:16:45.949556Z",
          "issue": "MEDIA",
          "issueId": "9e3b73c3-5050-4f42-bc4b-aa6c05a711b8",
          "severity": "WARNING",
          "workflowExecutionId": "01K55F466SQBT41KMQ7PWGEEN3"
        }
      ],
      "workflowStepResults": [
        {
          "stepName": "AML",
          "result": "HIT",
          "summary": {
            "numUnresolvedAdverseMedia": 2,
            "numUnresolvedPEP": 0,
            "numUnresolvedSanction": 0,
            "numUnresolvedWatchlist": 0,
            "providerSummaries": [
                ...
            ],
            "stepName": "AML",
            "totalFalsePositives": 0,
            "totalHits": 2,
            "totalTruePositives": 0,
            "totalUnknown": 0,
            "totalUnresolved": 2
          },
          "processResults": [
            { 
              "processResultId": "pro_01J...",
              "result": "HIT",
              "class": "AML",
              "supplementaryData": {
                "type": "AML",
                "matchData": { "name": "Test Org" },
                "mediaData": [
                  {
                    "additionalData": [
                      {
                        "key": "aml.case_id",
                        "value": "..."
                      },
                      {
                        "key": "aml.search_entity_id",
                        "value": "..."
                      }
                    ],
                    "isCurrent": true,
                    "snippet": "...",
                    "source": "...",
                    "sourceDate": "...",
                    "title": "...",
                    "url": "..."
                  }
                ],
                "manualStatus": "UNRESOLVED"
              }
            }
          ]
        }
      ]
    }
  }
  ```
</Accordion>

***

## Part 1: The Overall Outcome (Final Verdict)

Always start by checking the top-level fields of the `workflowResult` object. These give you the final, authoritative outcome.

| Field                        | Importance | Description                                                                                                             |
| :--------------------------- | :--------- | :---------------------------------------------------------------------------------------------------------------------- |
| **`status`**                 | ‼️         | The conclusive recommendation (e.g., `PASS`, `FAIL`, `REVIEW`). **Base your primary business logic on this value.**     |
| **`workflowExecutionState`** | ‼️         | Confirms the workflow's technical status. **Must be `COMPLETED`**.                                                      |
| **`issues`**                 | ⚠️         | An array of problems that require manual review. If `status` is `REVIEW`, this array contains the specific reasons why. |
| **`riskAssessment`**         | ⚠️         | The final risk profile of the entity, including the `riskLevel` and `riskScore`.                                        |

In the example, the `status` is `REVIEW`, which is directly caused by the `issues` array containing a `MEDIA` issue.

### Understanding AML Issues

When the AML step finds a potential match, it generates an `issue` object. This is what typically drives the overall workflow `status` to `REVIEW`.

| Category | Issue       | Severity  | Trigger Condition                                           |
| :------- | :---------- | :-------- | :---------------------------------------------------------- |
| `AML`    | `PEP`       | `WARNING` | At least one valid Process Result contains `pepData`.       |
| `AML`    | `SANCTIONS` | `WARNING` | At least one valid Process Result contains `sanctionData`.  |
| `AML`    | `MEDIA`     | `WARNING` | At least one valid Process Result contains `mediaData`.     |
| `AML`    | `WATCHLIST` | `WARNING` | At least one valid Process Result contains `watchlistData`. |

***

## Part 2: The AML Step Result (`workflowStepResults`)

Next, drill down into the `workflowStepResults` array and find the object where `stepName` is **`AML`**. This object contains the specific results of the screening.

| Key Field            | Description                                                                                                                                                                             |
| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`result`**         | The most important field for the step. A `result` of **`HIT`** means at least one potential match was found and requires review. A `result` of **`CLEAR`** means no matches were found. |
| **`summary`**        | An aggregated summary of the screening results, broken down by match type.                                                                                                              |
| **`processResults`** | An array containing the detailed evidence for each individual watchlist match.                                                                                                          |

### The AML Summary Object

The `summary` object gives you a quick, quantitative overview of the screening results.

```json theme={null}
"summary": {
  "numUnresolvedAdverseMedia": 2,
  "numUnresolvedPEP": 0,
  "numUnresolvedSanction": 0,
  "numUnresolvedWatchlist": 0,
  "providerSummaries": [
      {
          ...
      }
  ],
  "stepName": "AML",
  "totalFalsePositives": 0,
  "totalHits": 2,
  "totalTruePositives": 0,
  "totalUnknown": 0,
  "totalUnresolved": 2
  }
```

This summary immediately tells you the scale and severity of the results. For example, `numUnresolvedSanction` highlights if a high-risk sanctions match is present and needs immediate attention.

***

## Part 3: The Process Results (The Raw Evidence)

When an AML step returns a `HIT`, the `processResults` array will contain one or more Process Result Objects (PROs), each with `class: "AML"`. Each PRO represents a single potential match from a watchlist and contains all the data you need for your investigation.

### Anatomy of an AML PRO

The most critical part of an AML PRO is the **`supplementaryData`** object. This is where you will find the details of the matched entity.

| `supplementaryData` Field | Description                                                                                                         |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------ |
| **`matchData`**           | Core information about the matched profile (name, date of birth, countries of association).                         |
| **`pepData`**             | If the match is a Politically Exposed Person, this array contains details about their position, level, and country. |
| **`sanctionData`**        | If the match is on a Sanctions list, this array contains details about the sanction, its source, and the reason.    |
| **`watchlistData`**       | This array contains details for matches on other regulatory or law enforcement watchlists.                          |
| **`mediaData`**           | If the match is from Adverse Media, this array provides snippets and links to relevant news articles.               |
| **`referenceDocs`**       | An array of URLs to source documents for further evidence.                                                          |

<AccordionGroup>
  <Accordion title="Example: A Adverse Media Match PRO">
    This example shows a `processResult` for a `HIT` where the organization has adverse media hits. The `mediaData` array is populated with the specific details of the adverse media matches.

    ```json theme={null}
    { 
      "processResultId": "pro_01J...",
      "result": "HIT",
      "class": "AML",
      "supplementaryData": {
        "type": "AML",
        "matchData": { "name": "Test Org" },
        "mediaData": [
          {
            "additionalData": [
              {
                "key": "aml.case_id",
                "value": "..."
              },
              {
                "key": "aml.search_entity_id",
                "value": "..."
              }
            ],
            "isCurrent": true,
            "snippet": "...",
            "source": "...",
            "sourceDate": "...",
            "title": "...",
            "url": "..."
          }
        ],
        "manualStatus": "UNRESOLVED"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Part 4: Next Steps - Classifying Hits and Re-evaluating

After your compliance team reviews the evidence in the `processResults`, they must classify each hit (e.g., as a `FALSE_POSITIVE`). This is done by updating the `manualStatus` of each PRO.

> **For a detailed guide on how to perform this action via the API, please see our **[AML Screening & Monitoring Documentation](/docs/kyb/anti-money-laundering)**.**

### Updating the Workflow Result

Once all hits have been classified, the workflow needs to be reevaluated so the entity's risk and workflow status reflect the classifications. This is critical for two reasons:

1. **To Update the `status`**: The overall `workflowResult.status` will only change from `REVIEW` to `PASS` or `CLEAR` after the workflow is re-evaluated or re-run and the AML step confirms that no unresolved hits remain.
2. **To Clear `issues`**: The AML step will reassess the issues. If all PROs that previously caused a `MEDIA` issue are now classified as `FALSE_POSITIVE`, the issue will be cleared from the workflow result.

There are two ways to trigger this update:

#### Re-evaluate the Workflow

Call the **evaluate** endpoint. This re-runs the decision and risk assessment steps using existing check results, without triggering new calls to external providers. This ensures the entity's risk and workflow status are updated and the audit trail is accurate.

```http theme={null}
POST /v2/organizations/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/evaluate
```

#### Re-run the Workflow

Call the **execute** endpoint to re-run the full workflow. Unless existing results are within the aging window, this will contact external providers again (e.g., run a new AML search), which incurs additional cost and resets the aging window.

```http theme={null}
POST /v2/organizations/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/execute
```

<Callout icon="triangle-exclamation">
  Use `/evaluate` when only the decision needs updating based on changed classifications — it is faster, cheaper, and does not call external providers. It re-assesses risk using the entity's existing check results, but does not refresh them. Use `/execute` when the entity's underlying data has changed, or when you need fresh provider results because existing checks have expired beyond the aging window.
</Callout>

### Error Handling

| Scenario                           | Response                                    | Recommended Action                                       |
| :--------------------------------- | :------------------------------------------ | :------------------------------------------------------- |
| No prior workflow execution exists | `400` - "No prior workflow execution found" | Call `/execute` first to run the initial workflow        |
| Entity state is `DUPLICATE`        | `400`                                       | Call evaluate on the surviving entity, not the duplicate |
| Entity state is `BLOCKLISTED`      | `403`                                       | Resolve the blocklist status first                       |


# Business Onboarding
Source: https://docs.frankieone.com/docs/kyb/business-onboarding



Business Onboarding is a hosted flow that guides applicants through providing the information needed to verify an organisation. You generate a time‑limited URL and redirect your user to complete the steps.

<Warning>
  Business Onboarding is not enabled by default. Contact FrankieOne to enable it for your tenant and to provision your onboarding flow configuration (`flowId`).
</Warning>

***

## How it works

* **Generate a hosted URL** using your `flowId`.
* **Redirect** the applicant’s browser to the returned URL.
* The applicant completes the onboarding pages and submits.
* Verification URL for identified owners can be sent from the flow.
* **Redirect after completion** can be configured (CTA target on the End page).

***

## Generate a hosted URL

Use the Hosted URL endpoint to create a URL for a new onboarding session.

```http HTTP theme={null}
POST /v2/organizations/hostedUrl
Host: api.uat.frankie.one
```

### Headers

* `api_key`: Your FrankieOne API key
* `X-Frankie-CustomerID`: Your Customer ID
* `X-Frankie-CustomerChildID`: Child tenant identifier

### Request body

```json JSON theme={null}
{
  "flowId": "example-flow-id"
}
```

### Sample request (UAT)

```bash theme={null}
curl --request POST \
  --url https://api.uat.frankie.one/v2/organizations/hostedUrl \
  --header 'api_key: <YOUR_API_KEY>' \
  --header 'X-Frankie-CustomerID: <YOUR_CUSTOMER_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
    "flowId": "<your-flow-id>"
  }'
```

### Sample response

```json JSON theme={null}
{
  "url": "https://verify.uat.frankie.one/v2/?t=shortToken",
  "urlExpiry": "2025-01-01T00:00:00.000Z",
  "requestId": "01HN9XHZN6MGXM9JXG50K59Q85"
}
```

***

## Pages in the flow

Below are the standard pages included in the hosted flow. Availability and fields depend on your configured `flowId` and the selected organisation type.

* **Start page**
  Intro screen to begin a new application.

  <Frame>
    <img alt="Business onboarding start page" />
  </Frame>

* **Applicant details**
  Captures the applicant’s name, role, contact details, and consent. The Terms & Conditions checkbox message can be customised.

  <Frame>
    <img alt="Applicant details page" />
  </Frame>

* **Lookup**
  Search by organisation name, ABN or ACN. On submission, the flow runs an **Ownership** query on the selected organisation to determine structure and required next steps.

  <Frame>
    <img alt="Organisation lookup page" />
  </Frame>

* **Additional details**
  Fully customisable fields (labels, required/optional) for business context, e.g. source of wealth/capital, industry, purpose, contact details.

  <Frame>
    <img alt="Additional details page" />
  </Frame>

* **Organisation details**
  Prefilled from registry/profile data where available. Address fields may require confirmation/editing depending on data availability.
  Applicable to: sole trader, company, and trust organisations.

  <Frame>
    <img alt="Organisation details page" />
  </Frame>

* **Document upload**
  Fully customisable document groups and requirements. For trust organisations, the flow adds defaults for Trust Deed, Deeds of Variation, and Register of Unit Holders.
  Applicable to: company and trust organisations. Sole trader does not include this step.

  <Frame>
    <img alt="Document upload page" />
  </Frame>

* **Owners**
  Displays identified significant owners and directors for confirmation and contact details capture.
  Applicable to: sole trader and company.

  <Frame>
    <img alt="Owners page" />
  </Frame>

* **Review**
  Summary of all captured details and documents prior to submission.

  <Frame>
    <img alt="Review page" />
  </Frame>

* **End page**
  Confirmation page. The primary CTA can redirect to a configurable URL (e.g. return to your product).

  <Frame>
    <img alt="End page" />
  </Frame>

## Branding and UI customisation

* **Logo**: Replace with your brand logo.
* **Buttons**: Configure colour and border radius.
* **Copy**: Customise explanatory text and T\&C/consent copy.
* **Fields**: Add, remove, or reorder fields on Additional Details and Document Upload pages, including validations and optionality.
* **Redirects**: Configure the destination for the End page CTA.

Work with FrankieOne to define these in your flow configuration.


# Core Product Deep Dive
Source: https://docs.frankieone.com/docs/kyb/core-product-deep-dive



A detailed exploration of the powerful features within the FrankieOne KYB platform. Understand how each component maps to our API to create a secure, efficient, and compliant business verification workflow.

## Available Features

These features are available today in the FrankieOne KYB platform.

<Accordion title="Business Registration Verification">
  **What it is:** This is our core business verification engine. It validates a company’s details directly against authoritative registries worldwide, including ABN/ACN in Australia. It confirms the business name, incorporation status, and registration identifiers.

  **Key Benefits:**

  * **Ensure Counterparties are Legitimate:** Validate data against official sources to reduce the risk of fraud.
  * **Simplify Compliance Checks:** Automate registry lookups to streamline your due diligence process.

  **Mapped to API:** This information is found within the `organization.details` object, specifically in the `registrationDetails` array, which includes fields like `registeredName`, `registrationNumber`, and `status`.
</Accordion>

<Accordion title="UBO Discovery & Ownership Mapping">
  **What it is:** This feature identifies directors, shareholders, and Ultimate Beneficial Owners (UBOs) to uncover who truly controls a business. It allows you to build transparent ownership structures across jurisdictions.

  **Key Benefits:**

  * **Reveal Hidden Ownership:** Reduce exposure to shell companies and complex ownership structures.
  * **Strengthen AML/CTF Compliance:** Meet FATF requirements for identifying beneficial owners.
  * **Gain Visibility for Due Diligence:** Identify key individuals who may require further screening (e.g., PEP or sanctions checks).
    **Mapped to API:** Ownership data is structured within the `organization` object:
    `officials`: An array listing directors and other key roles.
    `shareholders`: An array detailing direct shareholders.
    `ultimateBeneficialOwners`: An array identifying the UBOs as determined by the configured ownership policy.
    `linkedIndividuals`: Contains the full entity details for individuals linked to the organization.
</Accordion>

<Accordion title="Watchlist & Sanctions Screening">
  **What it is:** This feature screens businesses and their associated individuals against thousands of global watchlists, including Sanctions lists, Politically Exposed Persons (PEPs), and Adverse Media from reputable global sources.

  **Key Benefits:**

  * **Detect High-Risk Counterparties:** Identify potential risks before entering into a business relationship.
  * **Support Global Compliance:** Ensure you meet screening requirements across multiple jurisdictions.
  * **Automate Alerts:** Configure ongoing monitoring to be alerted to any changes in a customer's status.

  **Mapped to API:** This is performed during workflow execution. Results are returned as Process-Result-Object instances with class: AML. The supplementaryData object for these results contains detailed match information, including pepData, sanctionData, and mediaData.
</Accordion>

<Accordion title="Corporate Risk Assessment">
  **What it is:** The Risk Assessment engine assigns a customisable risk score to each business entity. It analyses multiple data points in real-time, such as the business's jurisdiction, industry, and ownership complexity, to produce a holistic risk profile based on your configured rules.

  **Key Benefits:**

  * **Focus Resources on High-Risk Entities:** Build workflows that align with your risk appetite.
  * **Improve Decision-Making:** Use structured, comparable scoring to automate and streamline your review process.
  * **Auditable Compliance:** Provides a clear, data-driven trail explaining why an entity was assigned a specific risk level.

  **Mapped to API:** The `workflowResult` of an execution contains a `riskAssessment` object. This includes the overall `riskScore` and `riskLevel` (e.g., `LOW`, `MEDIUM`, `HIGH`), as well as a breakdown of the `riskFactors` that contributed to the score.
</Accordion>

<Accordion title="Trust Analyzer">
  **What it is:** The Trust Analyzer extracts and analyses trust structures from trust deeds during KYB. It ingests a trust deed PDF, classifies the trust type, extracts the named parties (trustees, settlors, beneficiaries, appointors, protectors, SMSF members), normalises their roles, and returns structured, audit-ready output with references back to the source document. Available through both the Portal and the API, for Australian trust deeds; international coverage is not yet supported.

  **Key Benefits:**

  * **Faster Reviews:** Convert unstructured deeds into structured data to cut manual review time and training effort.
  * **Enable Automation:** Consistent, structured output lets you automate more of a complex KYB process.
  * **Complete Picture:** Resolve complex entity types alongside standard KYB verification, AML, and KYC in one place.

  **Common Use Cases:** Onboarding trusts, or businesses that hold assets through trusts, at scale without adding compliance headcount.

  **Mapped to API:** Runs as the `GLB-Trust-Analysis` workflow. Pass the trust deed's `documentId` via `executionVariables` on execute, then retrieve the extracted trust structure and confirm it. See the [Trust Analyzer guide](/docs/kyb/trust-analyzer).
</Accordion>

## Coming Soon: The Future of Compliance

We are continuously innovating to address the next generation of compliance and fraud challenges. The following capabilities are in active development and will be available in upcoming releases.

<Accordion title="Ongoing KYB Monitoring">
  **What it is:** This feature allows you to continuously track changes related to a business's registration status, ownership structure, or other key risk indicators over time. You receive alerts when key details shift, ensuring continuous compliance throughout the business lifecycle.

  **Key Benefits:**

  * **Maintain Up-to-Date Due Diligence:** Reduce the risk of missing critical changes that impact compliance.
  * **Support Regulatory Obligations:** Fulfill requirements for ongoing monitoring without manual effort.
  * **Proactive Risk Management:** Be alerted when a supplier or customer changes ownership to a sanctioned or high-risk entity.

  **Common Use Cases:** For businesses that want to stay up to date with changes to their customers, or who want to eliminate costly refresh processes and introduce a real-time, as needed, customer maintenance cycle.
</Accordion>


# Error Handling
Source: https://docs.frankieone.com/docs/kyb/error-handling

The FrankieOne API uses a standardized error format to ensure that you can reliably handle issues that arise from bad requests, server problems, or invalid data. All non-2xx responses will return a consistent JSON error object.

This guide explains the structure of the error object, provides a full list of error codes, and offers practical advice on how to handle these errors in your frontend application.

***

## The Error Object

All errors returned from the FrankieOne API are wrapped in a standard `ErrorObject`.

| Attribute             | Type   | Description                                                                                                          |
| :-------------------- | :----- | :------------------------------------------------------------------------------------------------------------------- |
| errorCode             | string | A unique code in the format `PREFIX-NUMBER` that identifies the error.                                               |
| errorMsg              | string | A human-readable message summarizing the error.                                                                      |
| details               | array  | An array of issue objects providing specific context about what went wrong.                                          |
| details.issue         | string | A detailed description of the specific issue.                                                                        |
| details.issueLocation | string | The location in the request payload, path, or header where the issue occurred (e.g., `body.individual.dateOfBirth`). |
| requestId             | string | The unique ID for the API request, which should be logged and provided to support if you need assistance.            |

***

### Example Error Object

Here is an example of an error returned when an invalid entity ID is provided in the request path.

```json theme={null}
{
    "details": [
        {
            "issue": "entity with ID '019930f5-6d09-739e-82ca-e597bf0ed98c' does not exist"
        }
    ],
    "errorCode": "VAL-404",
    "errorMsg": "Not Found",
    "requestId": "01K4VRM3WDE0X6MMP83HCDEWHC"
}
```

***

## Understanding Error Codes

The `errorCode` is a combination of a prefix (the Issue Location) and a number. This structure helps you quickly identify the source of the problem.

### Issue Location Codes (Prefix)

| Prefix | Description                                                                                                                |
| :----- | :------------------------------------------------------------------------------------------------------------------------- |
| API    | Errors in your API message, such as an incorrectly constructed URL or method.                                              |
| AUTH   | Authorization or security-related errors, like a missing or invalid API key.                                               |
| VAL    | API data validation errors. The details array will specify which fields are invalid.                                       |
| ENT    | Errors related directly to Entity functions (e.g., an entity not found).                                                   |
| DOC    | Errors related directly to Document functions.                                                                             |
| CHECK  | Errors related to Check/Verify functions. Indicates a problem with performing a check, not the result of the check itself. |
| SYS    | System-level errors on the FrankieOne side. These may be temporary.                                                        |
| CODE   | Unexpected errors detected in the code. Please contact support if you see these.                                           |
| ADMIN  | Admin API errors. Please contact developer support if you receive one.                                                     |

***

## Frontend Orchestration & Handling Errors

A robust frontend application should interpret the HTTP status code and the errorCode to present the user with a clear and helpful message.

### 400 - Bad Request (VAL-xxxx)

This is the most common error category. It means the user has provided invalid or incomplete data. You should validate the request parameters and body and retry the API.
Your frontend should parse the `details` array to provide specific feedback.

**Example Response:**

```json theme={null}
{
    "details": [
        {
            "issue": "request body has an error: registrationDetails value must be an array",
            "issueLocation": "Request",
            "issueType": "Bad Request"
        }
    ],
    "errorCode": "VAL-400",
    "errorMsg": "Bad Request",
    "requestId": "01K4VSB88WT4QG03MYCZJ9AEC4"
}
```

**Frontend Action:**

* Iterate through the `details` array.
* For each issue, use the `issueLocation` to find the corresponding input field in your form.
* Display the issue message directly below that field.

This provides targeted, inline validation feedback to the user so they can easily correct their mistakes.

***

### 404 - Not Found (API-1010)

This means the resource you requested (like an entityId or workflowExecutionId) does not exist. You should validate the request parameters and retry the API.

#### Scenario: Your application tries to fetch results for a workflow that has been deleted or whose ID is incorrect.

**Example Response:**

```json theme={null}
{
  "errorCode": "API-1010",
  "errorMsg": "Requested resource is not found",
  "details": [
    {
      "issue": "The specified resource '01BFJA617JMJXEW6G7TDDXNSHX' of type 'entity' does not exist",
      "issueLocation": "path"
    }
  ],
  "requestId": "01BFJA617JMJXEW6G7TDDXNSHX"
}
```

**Frontend Action:**

* Check for the 404 status code.
* Redirect the user to a "Not Found" page or display a clear message like "We could not find the record you were looking for. Please check the ID or start a new search."
* Avoid showing a generic "An error occurred" message, as this is a specific and actionable state.

***

### 5xx - Server & System Errors (SYS-xxxx)

These errors indicate a problem on FrankieOne's side. The issue may be temporary. You can retry the API after a short delay.

#### Scenario: A service provider required for a check is temporarily unavailable.

**Example Response:**

```json theme={null}
{
  "errorCode": "SYS-0007",
  "errorMsg": "No service providers available/configured. Contact developer support",
  "httpStatusCode": 503,
  "details": [
    {
      "issue": "The service is temporarily unavailable",
      "issueLocation": "server"
    }
  ],
  "requestId": "01GVEDZ0C1Q9NWQ699DBBKPE4Y"
}
```

**Frontend Action:**

* Check for any 5xx status code (500, 503, etc.).
* Display a generic, user-friendly message, such as: "We're sorry, something went wrong on our end. Please try again in a few moments."
* Do not display the technical `errorMsg` to the user.
* You may implement a retry mechanism with exponential backoff for 503 errors, as these are often transient.
* Log the full error response, including the `requestId`, so you can report it to support if the issue persists.


# Executing a Workflow
Source: https://docs.frankieone.com/docs/kyb/executing-workflows

A step-by-step guide to executing workflows and interpreting the results.

## Overview

Executing a workflow is the core action in the FrankieOne platform. It takes an `entityId` and runs it through a pre-configured series of steps (e.g., organization data collection, ownership insights, etc.) to return a result. This is the central mechanism for fetching organization details, assessing risk and making onboarding decisions.

This guide covers the primary methods for executing a workflow and provides a high-level overview of how to handle the response.

***

## Workflow Execution Patterns

There are two primary patterns for executing a workflow, depending on whether the organization already exists in your system.

### 1. Execute a workflow using organizationToken or organization registration details

If you have searched for a business and retrieved its `organizationToken`, you can execute a workflow using that token. Alternatively, if you already know the business's registration number and type, you can execute a workflow directly with those details. This approach removes the need for a separate “create organization” step and, if an organization entity with the same registration number and type already exists in our system, we run the workflow against the existing entity—preventing the creation of duplicate entities.

**Use Cases:**

* Onboarding a new business for the first time.

### 2. Execute for an Existing Entity

If you have already created an `organization` and have their `entityId`, or have run a workflow and have the `entityId` of the organization, you can execute a workflow against them at any time.

**Use Cases:**

* Re-running a workflow to re-assess risks.
* Running a workflow for an existing entity post onboarding.
* Performing periodic or event-driven reviews.

<Steps>
  <Step title="1. Initiate the Workflow">
    You send a `POST` request to the `/execute` endpoint for a specific entity and workflow. This tells FrankieOne to initiate the workflow.
    The API response will have a status of `202 Accepted` and contain the `workflowExecutionId` which can then be used to get the results of the workflow.
  </Step>

  <Step title="2. Retrieve the Workflow Result">
    You can retrieve the workflow result by making a `GET` request to the `/executions/{workflowExecutionId}` endpoint.
    The API response will have a status of `200 OK` and contain the `workflowResult` object.
  </Step>
</Steps>

### 3. Re-evaluate an Existing Entity

If an entity has already been through a workflow and you need to update its risk and workflow status, for example, after classifying AML hits or resolving duplicates, you should call the **evaluate** endpoint instead of executing the workflow again.

The evaluate endpoint re-runs the decision and risk assessment steps using existing check results. It does **not** call external providers (e.g., CreditorWatch), which means:

* **No additional provider cost** - external data fetches are skipped entirely.
* **Faster processing** - only local computation steps are run.

**Use Cases:**

* Updating the workflow result after classifying AML hits.
* Re-assessing risk after resolving duplicate entities.
* Recalculating the decision after a risk factor override.

<Callout icon="triangle-exclamation">
  **When to use Execute instead:** If the entity's underlying data has changed and you need fresh provider data, or if existing check results have expired beyond the ageing window, use `/execute`.
</Callout>

***

## Implementation Guide

### Prerequisites

Before executing a workflow, ensure you have:

* The `organizationToken` or `registrationNumber` and `registrationType` of the organization.
* If the organization already exists in the system, the `entityId` for the organization.
* The `serviceName` of the Service Profile they are being assessed against (e.g., `DEFAULT`).
* The `workflowName` of the specific workflow you want to run (e.g., `GLB-Organization-Profile`).

### Step 1: Initiate the Workflow

#### Request

Choose the endpoint that matches your execution pattern.

##### With Organization details:

Make a `POST` request to the endpoint, providing the `organizationToken` from the search response or `registrationNumber`, `registrationType` and `country` in the request body.

<CodeGroup>
  ```bash Request - Execute Workflow with registration details theme={null}
  curl --location 'https://api.uat.frankie.one/v2/organizations/workflows/GLB-Organization-Profile/execute' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
  --header 'Content-Type: application/json' \
  --data '{
      "organization": {
          "details": {
              "registrationDetails": [
                  {
                      "number": "61623506892",
                      "type": "ABN",
                      "country": "AUS"
                  }
              ]
          }
          }
  }'
  ```

  ```bash Request - Execute Workflow with organizationToken theme={null}
  curl --location 'https://api.uat.frankie.one/v2/organizations/workflows/organization_profile/execute' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
  --header 'Content-Type: application/json' \
  --data '{
      "organizationToken": "eyJ2ZXIiOiIxLjAiLCJ0cyI6IjIwMjUtMDgtMDdUMDY6NTk6NTQuNDAzMzcxNDZaIiwib24iOlt7InJuIjoiNjE2MjM1MDY4OTIiLCJyYSI6IkFCTiJ9LHsicm4iOiI2MjM1MDY4OTIiLCJyYSI6IkFDTiJ9XSwicHJvdiI6ImNyZWRpdG9yd2F0Y2giLCJjbyI6IkFVUyJ9",
      "serviceName": "DEFAULT"
  }'
  ```
</CodeGroup>

You can pass a `comment` in the request body to provide additional context about the workflow execution. The comment will be added to the audit trail of the workflow execution.
You can also pass `serviceName` in the request body to override the default configured service profile.

#### Request Body Fields

| Field                | Type     | Required    | Description                                                                                                                                   |
| -------------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `organizationToken`  | `string` | Conditional | Token returned by a business lookup. Use this **or** `organization`, not both.                                                                |
| `organization`       | `object` | Conditional | Organization registration details. Use this **or** `organizationToken`, not both.                                                             |
| `serviceName`        | `string` | No          | Override the default service profile.                                                                                                         |
| `comment`            | `object` | No          | Audit trail comment. Pass `{ "text": "..." }`.                                                                                                |
| `executionVariables` | `object` | No          | Runtime variables consumed by workflow tasks. Keys and types are defined per workflow. See [Execution Variables](#execution-variables) below. |

#### Execution Variables

`executionVariables` is a key-value object that passes runtime inputs into a workflow's tasks without changing the entity's persistent data. The variables a workflow accepts are defined by that workflow's configuration.

Today the only workflow that uses `executionVariables` is the [Trust Analyzer](/docs/kyb/trust-analyzer) (`GLB-Trust-Analysis`), which takes the `documentId` of an uploaded trust deed.

```json Example - executionVariables for Trust Analysis theme={null}
{
    "executionVariables": {
        "documentId": "92de15f6-5717-4562-b3fc-2c963f6665a7"
    }
}
```

See the [Trust Analyzer](/docs/kyb/trust-analyzer) guide for the full flow.

##### With EntityId:

This endpoint is used to execute a workflow for an existing entity.
Make a `POST` request to the `execute` endpoint, including the `entityId`, `serviceName`, and `workflowName` in the path.

<CodeGroup>
  ```bash Request - Execute Workflow with entityId theme={null}
  curl --location 'https://api.uat.frankie.one/v2/organizations/{{entityId}}/serviceprofiles/{{serviceName}}/workflows/{{workflowName}}/execute' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
  --header 'Content-Type: application/json' \
  --data '{
      "comment": {
          "text": "Invoking Profile workflow"
      }
  }'
  ```
</CodeGroup>

##### Evaluate for an Existing Entity:

If the entity has already been through a workflow execution and you need to re-assess its risk and workflow status (e.g., after classifying AML hits), use the `evaluate` endpoint.

<CodeGroup>
  ```bash Request - Evaluate Workflow with entityId theme={null}
  curl --location --request POST 'https://api.uat.frankie.one/v2/organizations/{{entityId}}/serviceprofiles/{{serviceName}}/workflows/{{workflowName}}/evaluate' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
  --header 'Content-Type: application/json' \
  --data '{
      "comment": {
          "text": "Re-evaluating after AML hit classification"
      }
  }'
  ```
</CodeGroup>

<Callout icon="circle-info">
  The evaluate endpoint requires a prior completed workflow execution. If no prior execution exists, the API returns `400`. If the entity's underlying data has changed and existing check results have been invalidated, the evaluation may produce an incomplete assessment. In this case, use `/execute` to fetch fresh data.
</Callout>

#### Response

<CodeGroup>
  ```json Response - Execute or Evaluate Workflow with entityId theme={null}
  {
      "entityId": "01993733-cfd5-7594-9e90-ec3ad06dd490",
      "requestId": "01K4VK7KWN6HEA43AQ0F13JZPT",
      "serviceName": "DEFAULT",
      "serviceProfileId": "64ec50f2-5e69-4fee-8d97-7db77f2b71cd",
      "workflowExecutionId": "01K4VK7QDJG631AWFKWYVE85Z5"
  }
  ```
</CodeGroup>

KYB workflows are asynchronous. The API response will have a status of `202 Accepted` and contain the `workflowExecutionId` which can then be used to get the results of the workflow.
The workflow will continue to process in the background.

### Step 2: Retrieve the Workflow Result

You can retrieve the workflow result by using the `workflowExecutionId` returned in the previous step.

#### Request

<CodeGroup>
  ```bash Request - Retrieve Workflow Result theme={null}
  curl --location 'https://api.uat.frankie.one/v2/organizations/{{entityId}}/serviceprofiles/{{serviceName}}/workflows/{{workflowName}}/executions/{{workflowExecutionId}}' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
  --header 'Content-Type: application/json'
  ```
</CodeGroup>

`workflowResult.workflowExecutionState` indicates the execution state of the workflow. If it is `IN_PROGRESS`, the workflow is still running. You can poll the endpoint again to check the status.
When the workflow is completed, the `workflowResult.workflowExecutionState` will be `COMPLETED`. At this point, you can parse the `workflowResult` object to understand the outcome of every step.
Response will also contain the complete `organization` object with all the information about the business.

***

## Next Steps

Once you have successfully executed a workflow, the next critical step is to parse the rich `workflowResult` object to understand the outcome of every check.

For a complete breakdown of every field in the response, refer to our detailed guide:
**[Interpreting Workflow Results](/docs/kyb/interpreting-workflows-v2)**.

***

## Additional Resources

* [FrankieOne API Reference](/docs/reference/whats-new)
* [FrankieOne Support](/docs/contacting-developer-support)


# Getting Started: Your First API Call
Source: https://docs.frankieone.com/docs/kyb/getting-started



This guide will walk you through setting up your environment, authenticating, and making your first successful API call to the FrankieOne platform.

Welcome to the FrankieOne API! This guide provides the essential information to get you up and running. Our goal is to help you make your first successful API call in minutes.

### Your FrankieOne Starter Pack

When you partner with FrankieOne, your Customer Success Manager will provide you with a starter pack containing everything you need for each environment. You should have the following:

| Resource             | UAT / Sandbox                                  | Production                                 |
| :------------------- | :--------------------------------------------- | :----------------------------------------- |
| **Portal URL**       | `https://portal.uat.frankie.one`               | `https://portal.frankie.one`               |
| **API Base URL**     | `https://api.uat.frankie.one/v2`               | `https://api.frankie.one/v2`               |
| **KYB API Base URL** | `https://api.uat.frankie.one/v2/organizations` | `https://api.frankie.one/v2/organizations` |
| **Customer ID**      | Your unique UAT Customer ID                    | Your unique Production Customer ID         |
| **API Key**          | Your secret UAT API Key                        | Your secret Production API Key             |

***

## Authentication Headers

All API requests to FrankieOne must be authenticated. You'll use the credentials from your starter pack in the request headers.

| Header                      | Required | Description                                                                                                      |
| :-------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------- |
| `api_key`                   | **Yes**  | Your secret API key for the specific environment (UAT or Production).                                            |
| `X-Frankie-CustomerId`      | **Yes**  | The unique identifier for your account.                                                                          |
| `X-Frankie-CustomerChildId` | No       | The unique identifier for your child account.                                                                    |
| `X-Frankie-Username`        | No       | The email address or identifier of the operator performing the action. Highly recommended for auditing purposes. |
| `X-Frankie-Channel`         | No       | The channel the request originates from (e.g., `API`, `PORTAL`, `ONESDK`). Useful for analytics and routing.     |

<Callout icon="bell">
  ##### Keep Your API Key Secure

  Your `api_key` is a secret and should be treated like a password. Store it securely on your backend and never expose it in client-side code or public repositories. If you suspect a key has been compromised, contact support immediately.
</Callout>

***

## Quickstart in 3 Steps

Follow these steps to ensure your credentials are correct and your environment is ready for integration.

<Steps>
  <Step title="1. Test Your Connection">
    The easiest way to verify that your credentials and connection are working is to call our simple health check endpoint: `/ruok`. This endpoint doesn't require a request body and is used purely to confirm successful authentication.

    <CodeGroup>
      ```bash Request - Health Check theme={null}
      curl --location '[https://api.uat.frankie.one/v2/kyc/ruok](https://api.uat.frankie.one/v2/kyc/ruok)' \
      --header 'api_key: {{your_uat_api_key}}' \
      --header 'X-Frankie-CustomerId: {{your_uat_customer_id}}'
      ```
    </CodeGroup>

    A successful request will return a `200 OK` status and the following JSON response, confirming your keys are valid.

    <CodeGroup>
      ```json Response theme={null}
      {
        "status": "OK"
      }
      ```
    </CodeGroup>

    If you receive an error, double-check that your API key and Customer ID are correct and that you are using the correct base URL for the environment.
  </Step>

  <Step title="2. Confirm Your Workflow Setup">
    Before you can start verifying customers, your account needs to be configured with at least one workflow and one service profile. Your Customer Success Manager typically sets these up for you.

    You can confirm your setup by calling the `GET /v2/workflows` endpoint. This will list all the executable workflows available to you.

    <CodeGroup>
      ```curl Request - Get Workflows theme={null}
      curl --location '[https://api.uat.frankie.one/v2/workflows](https://api.uat.frankie.one/v2/workflows)' \
      --header 'api_key: {{your_uat_api_key}}' \
      --header 'X-Frankie-CustomerId: {{your_uat_customer_id}}'
      ```
    </CodeGroup>

    You should receive a `200 OK` response with a `workflows` array. If the array is empty, please contact your Customer Success Manager to get your workflows published.

    <CodeGroup>
      ```json Response - Get Workflows theme={null}
      {
          "requestId": "req_01J...",
          "workflows": [
              {
                  "serviceName": "DEFAULT",
                  "workflowId": "wf_01J...",
                  "workflowName": "GLB-Organization-Profile",
                  "type": "SYSTEM",
                  "lifecyclePhase": "ONBOARDING"
              }
          ]
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="3. Make Your First KYB Call">
    Now you're ready to onboard a business. You can start by looking up for a business and creating an `organization` entity and then execute a workflow on it.

    You will need the `serviceName` and `workflowName` from the previous step.
  </Step>
</Steps>

***

## Next Steps

You've successfully authenticated and confirmed your setup. Now you're ready to start building. Follow our implementation guides for common use cases.

<CardGroup>
  <Card title="Lookup a Business" icon="magnifying-glass" href="/docs/kyb/lookup-a-business">
    Learn how to search for a business.
  </Card>

  <Card title="Creating & Managing Organizations" icon="building-columns" href="/docs/kyb/managing-organizations">
    Learn the complete lifecycle of an 'organization' entity, from creation and retrieval to deletion.
  </Card>

  <Card title="Executing a Workflow" icon="play" href="/docs/kyb/executing-workflows">
    A step-by-step guide to executing a verification workflow against an existing entity.
  </Card>

  <Card title="API Reference" icon="book-open" href="/docs/reference/whats-new">
    Dive deep into every endpoint, parameter, and response object in our comprehensive API Reference.
  </Card>
</CardGroup>


# Interpreting Workflows
Source: https://docs.frankieone.com/docs/kyb/interpreting-workflows-v2

A developer's guide to parsing the workflowResult object, from the overall status down to the granular details of each step.

## Understanding the Workflow Response

After executing a workflow, the API returns a comprehensive `workflowResult` object. This object is the key to understanding the outcome of every step performed. This guide provides a structured, top-down walkthrough of how to parse this response, explaining each key object from the final verdict down to the granular evidence.

<Accordion title="View Full API Response Example">
  The examples in this guide refer to the following API response for workflow execution `01K4XQGV10NY0Q3SE0F73H9TJX`. Click to expand and see the full structure.

  ```json theme={null}
  {
      "organization": {
          "entityId": "99f16410-2613-4181-8cf1-048625900013",
          "details": { "name": "Frankie One", "registrationDetails": [ ... ] },
          "...": "..."
      },
      "requestId": "01JZHEX0WX2QEM6EY139D5NNP1",
      "workflowResult": {
          "createdAt": "2025-09-12T01:09:31.804846Z",
          "endedAt": "2025-09-12T01:09:36.912755Z",
          "entityId": "01993700-edfb-766f-98d2-9fe470d78825",
          "entityType": "ORGANIZATION",
          "issues": [],
          "lifecyclePhase": "ONBOARDING",
          "monitoringTypes": [],
          "requestId": "01K4XQGPNYVR9PDCZ5ESW264V3",
          "result": "COMPLETE",
          "riskAssessment": {
              "createdAt": "2025-09-12T01:09:31.857427Z",
              "entityId": "01993700-edfb-766f-98d2-9fe470d78825",
              "riskAssessmentId": "56adfe52-cdcb-414e-9819-a541953a5858",
              "riskFactors": [
                  {
                      "createdAt": "2025-09-11T04:20:59.47008Z",
                      "description": "Organization Type",
                      "factor": "organization_type",
                      "riskFactorId": "be53f30a-d1fe-4264-aec7-c798444c391d",
                      "score": 30,
                      "status": "VALID",
                      "updatedAt": "2025-09-11T04:20:59.47008Z",
                      "updatedRequestId": "01K4VG2EVV6YJEQFEWZNR4RRY7"
                  }
              ],
              "riskScore": 30,
              "serviceProfileId": "081f345f-0919-4a60-8f23-e84cdd8bcf11",
              "updatedAt": "2025-09-12T01:09:37.095762Z",
              "updatedRequestId": "01K4XQGPNYVR9PDCZ5ESW264V3",
              "workflowExecutionId": "01K4XQGV10NY0Q3SE0F73H9TJX",
              "workflowId": "62758fca-6e95-424e-85ae-2d246bb45d92",
              "workflowRiskLevel": "LOW",
              "workflowRiskScore": 30
          },
          "schemaVersion": 2,
          "serviceProfileId": "081f345f-0919-4a60-8f23-e84cdd8bcf11",
          "startedAt": "2025-09-12T01:09:31.804846Z",
          "status": "COMPLETE",
          "statusOverrideAt": "0001-01-01T00:00:00Z",
          "statusOverrideBy": "",
          "statusOverrideRequestId": "",
          "steps": {
              "failed": [],
              "incomplete": [],
              "notApplicable": [],
              "order": [
                  "START",
                  "ORGANIZATION_DATA_FETCH",
                  "ORGANIZATIONPERSIST",
                  "DECISION",
                  "FINISH"
              ],
              "passed": [
                  "START",
                  "ORGANIZATION_DATA_FETCH",
                  "ORGANIZATIONPERSIST",
                  "DECISION",
                  "FINISH"
              ]
          },
          "updatedAt": "2025-09-12T01:09:37.258784Z",
          "workflowExecutionId": "01K4XQGV10NY0Q3SE0F73H9TJX",
          "workflowExecutionState": "COMPLETED",
          "workflowId": "62758fca-6e95-424e-85ae-2d246bb45d92",
          "workflowName": "GLB-Organization-Ownership",
          "workflowStepResults": [
              {
                  "createdAt": "2025-09-12T01:09:36.891039Z",
                  "endedAt": "2025-09-12T01:09:36.912755Z",
                  "objectId": "01993700-edfb-766f-98d2-9fe470d78825",
                  "objectType": "ORGANIZATION",
                  "processResults": [],
                  "requestId": "01K4XQGPNYVR9PDCZ5ESW264V3",
                  "result": "COMPLETE",
                  "risk": {
                      "contributedScore": 0,
                      "level": "LOW",
                      "overallScore": 30
                  },
                  "schemaVersion": 2,
                  "startedAt": "2025-09-12T01:09:36.884705Z",
                  "stepName": "FINISH",
                  "stepResultId": "01K4XQGZZV1HK6RRYRPEK9HH1X",
                  "summary": {
                      "stepName": "FINISH",
                      "workflowContextId": "2e7b0cc9-0545-4399-a89a-303c63243fde"
                  },
                  "updatedAt": "2025-09-12T01:09:37.233237Z",
                  "workflowExecutionId": "01K4XQGV10NY0Q3SE0F73H9TJX"
              },
              {
                  "createdAt": "2025-09-12T01:09:36.560444Z",
                  "endedAt": "2025-09-12T01:09:36.584254Z",
                  "objectId": "01993700-edfb-766f-98d2-9fe470d78825",
                  "objectType": "ORGANIZATION",
                  "processResults": [],
                  "requestId": "01K4XQGPNYVR9PDCZ5ESW264V3",
                  "result": "COMPLETE",
                  "schemaVersion": 2,
                  "startedAt": "2025-09-12T01:09:36.54998Z",
                  "stepName": "DECISION",
                  "stepResultId": "01K4XQGZNGJC9KSH3BJ5GWHDZ2",
                  "summary": {
                      "stepName": "DECISION",
                      "workflowExecutionResult": "COMPLETE"
                  },
                  "updatedAt": "2025-09-12T01:09:36.732859Z",
                  "workflowExecutionId": "01K4XQGV10NY0Q3SE0F73H9TJX"
              },
              {
                  "createdAt": "2025-09-12T01:09:34.533563Z",
                  "endedAt": "2025-09-12T01:09:36.125729Z",
                  "objectId": "01993700-edfb-766f-98d2-9fe470d78825",
                  "objectType": "ORGANIZATION",
                  "processResults": [],
                  "requestId": "01K4XQGPNYVR9PDCZ5ESW264V3",
                  "result": "COMPLETE",
                  "risk": {
                      "contributedScore": 30,
                      "level": "LOW",
                      "overallScore": 30
                  },
                  "schemaVersion": 2,
                  "startedAt": "2025-09-12T01:09:34.527693Z",
                  "stepName": "ORGANIZATIONPERSIST",
                  "stepResultId": "01K4XQGXP5505XGKTZKJWQZAPQ",
                  "summary": {
                      "stepName": "ORGANIZATION_PERSIST"
                  },
                  "updatedAt": "2025-09-12T01:09:36.381606Z",
                  "workflowExecutionId": "01K4XQGV10NY0Q3SE0F73H9TJX"
              },
              {
                  "createdAt": "2025-09-12T01:09:32.467337Z",
                  "endedAt": "2025-09-12T01:09:33.724934Z",
                  "objectId": "01993700-edfb-766f-98d2-9fe470d78825",
                  "objectType": "ORGANIZATION",
                  "processResults": [
                      {
                          "class": "ORGANIZATION_PROFILE",
                          "createdAt": "2025-09-11T04:20:56.176612Z",
                          "entityId": "01993700-edfb-766f-98d2-9fe470d78825",
                          "objectType": "ORGANIZATION",
                          "processResultId": "01K4VG2K7GQ0FPQE1FSNRPWM53",
                          "providerResult": {
                              "name": "ABR",
                              "source": "ABR",
                              "sourceNormalized": "ABR"
                          },
                          "requestId": "01K4VG2EVV6YJEQFEWZNR4RRY7",
                          "result": "CREATED",
                          "schemaVersion": 2,
                          "state": "COMPLETED",
                          "stepName": "ORGANIZATION_DATA_FETCH",
                          "stepType": "ORGANIZATION_PROFILE",
                          "supplementaryData": {
                              "organization": {
                                  ...
                              },
                              "type": "KYB_ORGANIZATION"
                          },
                          "systemStatus": "VALID",
                          "updatedAt": "2025-09-11T04:20:56.176612Z"
                      },
                      {
                          "class": "ORGANIZATION_OWNERSHIP",
                          "createdAt": "2025-09-12T01:09:33.705433Z",
                          "entityId": "01993700-edfb-766f-98d2-9fe470d78825",
                          "objectType": "ORGANIZATION",
                          "processResultId": "01K4XQGWW9DN9H4YZF6XKK7T44",
                          "providerResult": {
                              "name": "CREDITOR_WATCH",
                              "reference": "2f3b7f30-ca8d-11eb-816f-0242ac11001b",
                              "source": "ASIC",
                              "sourceNormalized": "ASIC"
                          },
                          "requestId": "01K4XQGPNYVR9PDCZ5ESW264V3",
                          "result": "CREATED",
                          "schemaVersion": 2,
                          "state": "COMPLETED",
                          "stepName": "ORGANIZATION_DATA_FETCH",
                          "stepType": "ORGANIZATION_OWNERSHIP",
                          "supplementaryData": {
                              "organization": {
                                  ...
                              },
                              "type": "KYB_ORGANIZATION"
                          },
                          "systemStatus": "VALID",
                          "updatedAt": "2025-09-12T01:09:33.705433Z"
                      }
                  ],
                  "requestId": "01K4XQGPNYVR9PDCZ5ESW264V3",
                  "result": "COMPLETE",
                  "schemaVersion": 2,
                  "startedAt": "2025-09-12T01:09:32.457875Z",
                  "stepName": "ORGANIZATION_DATA_FETCH",
                  "stepResultId": "01K4XQGVNKJBAKMCSQ3RFE2358",
                  "summary": {
                      "provider": "CREDITORWATCH",
                      "stepName": "ORGANIZATION_DATA_FETCH"
                  },
                  "updatedAt": "2025-09-12T01:09:33.850884Z",
                  "workflowExecutionId": "01K4XQGV10NY0Q3SE0F73H9TJX"
              },
              {
                  "createdAt": "2025-09-12T01:09:31.937737Z",
                  "endedAt": "2025-09-12T01:09:31.979769Z",
                  "objectId": "01993700-edfb-766f-98d2-9fe470d78825",
                  "objectType": "ORGANIZATION",
                  "processResults": [],
                  "requestId": "01K4XQGPNYVR9PDCZ5ESW264V3",
                  "result": "COMPLETE",
                  "risk": {
                      "contributedScore": 30,
                      "level": "LOW",
                      "overallScore": 30
                  },
                  "schemaVersion": 2,
                  "startedAt": "2025-09-12T01:09:31.927456Z",
                  "stepName": "START",
                  "stepResultId": "01K4XQGV515Y9RMX9G9T85AGR3",
                  "summary": {
                      "stepName": "START",
                      "workflowContextId": "2e7b0cc9-0545-4399-a89a-303c63243fde",
                      "workflowExecutionId": "01K4XQGV10NY0Q3SE0F73H9TJX"
                  },
                  "updatedAt": "2025-09-12T01:09:32.197792Z",
                  "workflowExecutionId": "01K4XQGV10NY0Q3SE0F73H9TJX"
              }
          ]
      }
  }
  ```
</Accordion>

***

## Part 1: The Overall Outcome (The Final Verdict)

Start by examining the top-level fields of the `workflowResult` object. These provide the final, authoritative outcome of the entire workflow execution.

| Field Name               | Importance | Description                                                                                                                                                |
| :----------------------- | :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`                 | ‼️         | It represents the conclusive recommendation and accounts for any manual overrides.                                                                         |
| `workflowExecutionState` | ‼️         | This confirms the workflow's technical status. It **must be `COMPLETED`** for the `status` to be considered final and to review the `organization` object. |
| `result`                 | ⚠️         | This field holds the original, automated outcome of the workflow *before* any manual changes. It is useful for auditing.                                   |
| `issues`                 | ⚠️         | An array of problems that may require manual review. If the `status` is `REVIEW`, this array will contain the specific reasons why.                        |

### Workflow Execution States (`workflowExecutionState`)

This field tells you if the workflow ran to completion.

| State         | Description                                                           |
| :------------ | :-------------------------------------------------------------------- |
| `COMPLETED`   | The workflow executed successfully from start to finish.              |
| `IN_PROGRESS` | The workflow is still running.                                        |
| `ERROR`       | The workflow encountered an unrecoverable error and could not finish. |
| `TIMEOUT`     | The workflow exceeded its maximum execution time.                     |
| `CANCELED`    | The workflow was manually canceled before completion.                 |
| `TERMINATED`  | The workflow was terminated by the system before completion.          |

### Workflow Statuses (`status` and `result`)

This is the final recommendation of the workflow.

| Status                    | Description                                                                                    |
| :------------------------ | :--------------------------------------------------------------------------------------------- |
| `PASS`                    | The entity successfully met the workflow's criteria.                                           |
| `FAIL`                    | The entity did not meet the workflow's criteria.                                               |
| `REVIEW`                  | The workflow produced results that require manual review.                                      |
| `CLEAR`                   | Often used for monitoring, indicates no negative information was found.                        |
| `HIT`                     | Often used for monitoring, indicates negative information (e.g., a watchlist match) was found. |
| `URGENT`                  | A critical issue was found (e.g., a sanctions match) that requires immediate attention.        |
| `COMPLETE` / `INCOMPLETE` | The workflow finished, but a pass/fail determination was not applicable.                       |

### Detecting Manual Overrides

It's crucial to know if a workflow's result was changed by a person. When an operator manually changes the `status` (e.g., from `FAIL` to `PASS`), the following fields are populated:

* `statusOverrideRequestId`: The unique ID of the override request.
* `statusOverrideBy`: The user who performed the override.
* `statusOverrideAt`: The timestamp of the override.

**To detect an override, check if `statusOverrideRequestId` exists and is not empty.**

***

## Part 2: The Step-by-Step Breakdown (`workflowStepResults`)

The `workflowStepResults` array is a log of each step in the workflow, explaining *how* the overall `status` was reached. Each object in this array corresponds to a step configured in your workflow (e.g., KYC, AML, IDV).

| Field Name       | Description                                                                                        |
| :--------------- | :------------------------------------------------------------------------------------------------- |
| `stepName`       | The name of the step (e.g., `ORGANIZATION_DATA_FETCH`, `AML`).                                     |
| `result`         | The outcome of this specific step. See the table below for all possible values.                    |
| `summary`        | A concise, human-readable summary of the step's outcome.                                           |
| `processResults` | An array of Process Result Objects (PROs) providing the granular evidence for this step's result.  |
| `risk`           | The risk assessment specific to this step, including the score it contributed to the overall risk. |

### Workflow Step Results (`result`)

| Result                | Description                                                                                                   |
| :-------------------- | :------------------------------------------------------------------------------------------------------------ |
| PARTIAL               | The step produced a successful, unsuccessful, or partially successful match against data sources.             |
| CLEAR / HIT           | Indicates no negative information found (CLEAR) or negative information found (HIT), e.g., a watchlist match. |
| PASS / FAIL           | The step completed and met (PASS) or did not meet (FAIL) its required criteria.                               |
| COMPLETE / INCOMPLETE | The step finished, but a pass/fail scenario was not applicable.                                               |
| SKIPPED               | The step was skipped because it was not required to run.                                                      |
| MISSING\_DATA         | The step could not run because it requires additional data.                                                   |
| ERROR                 | The step encountered an unrecoverable technical error.                                                        |

***

## Part 3: The Granular Evidence (`processResults`)

For the deepest level of detail, look inside a `workflowStepResult` at its `processResults` array. A **Process Result Object (PRO)** is the raw evidence from a single check against a single data source.

| Field Name          | Description                                                                                                                                                                |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `processResultId`   | A unique identifier for this specific piece of evidence.                                                                                                                   |
| `class`             | The high-level category of the step. See the table below for details.                                                                                                      |
| `objectType`        | The specific data element that was checked.                                                                                                                                |
| `result`            | The outcome of this specific step (e.g., `MATCH`, `HIT`, `CLEAR`).                                                                                                         |
| `providerResult`    | An object containing details from the downstream data provider, including the `source` of the data.                                                                        |
| `systemStatus`      | The lifecycle status of this PRO (e.g., `VALID`, `STALE`, `MARKED_INVALID`). A `STALE` status means the underlying entity data has changed since this check was performed. |
| `manualStatus`      | If an operator has manually reviewed this specific PRO, their conclusion (e.g., `TRUE_POSITIVE`, `FALSE_POSITIVE`) is recorded here.                                       |
| `supplementaryData` | A rich, context-specific object containing detailed metrics, like AML hits or extracted organization data.                                                                 |

### Process Result Classes (`class`)

| Class                    | Description                                                                      |
| :----------------------- | :------------------------------------------------------------------------------- |
| `ORGANIZATION_OWNERSHIP` | Organization ownership data fetched from a data source.                          |
| `ORGANIZATION_PROFILE`   | Organization profile data fetched from a data source.                            |
| `AML`                    | An Anti-Money Laundering screening against watchlists, sanctions, and PEP lists. |

## Best Practices for Integration

* **Check `workflowExecutionState` first**: Always confirm the workflow is `COMPLETED` before trusting the `status` and the returned `organization` object.
* **Debug with `workflowStepResults`**: When you get an unexpected `FAIL` or `REVIEW`, loop through the `workflowStepResults` to find which `stepName` has a non-passing `result`. The `summary` and `processResults` within that step will tell you why.
* **Log the `workflowExecutionId`**: This ID is your key for auditing, support queries, and correlating results.

## References

For more details on specific `workflowResult` objects, please refer to our Features section.

* [Interpreting AML Results](/docs/kyb/anti-money-laundering-results)


# Lookup a Business
Source: https://docs.frankieone.com/docs/kyb/lookup-a-business



Find a business in a specific jurisdiction

You can lookup a business in authoritative registries for a given region by supplying either their name or the registration number relevant to the jurisdiction (eg: ACN in Australia).
This allows you to confirm that the organization exists, and we also fetch additional details such as their current legal status in supported regions.

The name need not be the full legal name; partial name search is supported by many regional registries.

Perform a business lookup with a partial name or number using the [/lookup](/api-reference/organizations/lookup-organizations) endpoint.

1. In the example below, replace `YOUR_CUSTOMER_ID` with your Customer ID and `YOUR_API_KEY` with your API key provided by FrankieOne.
2. Copy the resulting code into your command line, and run the command.

#### Request

<CodeGroup>
  ```bash Request - Name theme={null}
  curl --request POST \
      --url https://api.uat.frankie.one/v2/organizations/lookup \
      --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
      --header 'api_key: YOUR_API_KEY'
      --header 'content-type: application/json' \
      --data '{
          "organizationName": "FrankieOne",
          "region": {
              "country": "AUS"
          }
      }'
  ```

  ```bash Request - Number theme={null}
  curl --request POST \
      --url https://api.uat.frankie.one/v2/organizations/lookup \
      --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
      --header 'api_key: YOUR_API_KEY'
      --header 'content-type: application/json' \
      --data '{
          "organizationNumber": {
              "registrationNumber": "61623506892",
              "registryCode": "ABN"
          },
          "region": {
              "country": "AUS"
          }
      }'
  ```
</CodeGroup>

#### Response

The response will contain a list of businesses that matched against the lookup criteria supplied

<CodeGroup>
  ```json Response - Name theme={null}
  {
      "matchedOrganizations": [
          {
              "addresses": [
                  {
                      "country": "AUS",
                      "postalCode": "3000",
                      "subdivision": "VIC",
                      "type": "OFFICE_LOCALITY",
                      "unstructuredLongForm": "VIC 3000"
                  }
              ],
              "alternateNames": [
                  {
                      "name": "FRANKIE FINANCIAL PTY LTD",
                      "type": "Trading name"
                  },
                  {
                      "name": "FRANKIEONE",
                      "type": "Trading name"
                  }
              ],
              "country": "AUS",
              "name": {
                  "name": "FRANKIE FINANCIAL PTY LTD"
              },
              "organizationToken": "eyJ2ZXIiOiIxLjAiLCJ0cyI6IjIwMjUtMDktMTBUMDQ6Mzc6MDIuMDg3MDU3MzMzWiIsIm9uIjpbeyJybiI6IjYxNjIzNTA2ODkyIiwicmEiOiJBQk4ifSx7InJuIjoiNjIzNTA2ODkyIiwicmEiOiJBQ04ifV0sInByb3YiOiJjcmVkaXRvcndhdGNoIiwiY28iOiJBVVMifQ==",
              "registrationDetails": [
                  {
                      "registrationNumber": "61623506892",
                      "registrationNumberType": "ABN"
                  },
                  {
                      "registrationNumber": "623506892",
                      "registrationNumberType": "ACN"
                  }
              ],
              "status": {
                  "normalized": {
                      "code": "ACTV"
                  },
                  "unstructured": {
                      "description": "Registered"
                  }
              },
              "type": {
                  "code": "PRV",
                  "description": "Australian Private Company"
              }
          }
      ],
      "queryDetails": {
          "organizationName": "FrankieOne",
          "region": {
              "country": "AUS"
          }
      },
      "requestId": "01K4RYKAYFKYY7JJVEX234B0FN"
  }
  ```

  ```json Response - Number theme={null}
  {
      "matchedOrganizations": [
          {
              "addresses": [
                  {
                      "country": "AUS",
                      "postalCode": "3000",
                      "subdivision": "VIC",
                      "type": "OFFICE_LOCALITY",
                      "unstructuredLongForm": "VIC 3000"
                  }
              ],
              "alternateNames": [
                  {
                      "name": "FRANKIE FINANCIAL PTY LTD",
                      "type": "Trading name"
                  },
                  {
                      "name": "FRANKIEONE",
                      "type": "Trading name"
                  }
              ],
              "country": "AUS",
              "name": {
                  "name": "FRANKIE FINANCIAL PTY LTD"
              },
              "organizationToken": "eyJ2ZXIiOiIxLjAiLCJ0cyI6IjIwMjUtMDktMTBUMDQ6MzU6NDYuNTE0MTI2NzE0WiIsIm9uIjpbeyJybiI6IjYxNjIzNTA2ODkyIiwicmEiOiJBQk4ifSx7InJuIjoiNjIzNTA2ODkyIiwicmEiOiJBQ04ifV0sInByb3YiOiJjcmVkaXRvcndhdGNoIiwiY28iOiJBVVMifQ==",
              "registrationDetails": [
                  {
                      "registrationNumber": "61623506892",
                      "registrationNumberType": "ABN"
                  },
                  {
                      "registrationNumber": "623506892",
                      "registrationNumberType": "ACN"
                  }
              ],
              "status": {
                  "normalized": {
                      "code": "ACTV"
                  },
                  "unstructured": {
                      "description": "Registered"
                  }
              },
              "type": {
                  "code": "PRV",
                  "description": "Australian Private Company"
              }
          }
      ],
      "queryDetails": {
          "organizationNumber": {
              "registrationNumber": "61623506892",
              "registryCode": "ABN"
          },
          "region": {
              "country": "AUS"
          }
      },
      "requestId": "01K4RYH14PQYB7V5BD0MGAQWSS"
  }
  ```
</CodeGroup>

## Extract the organizationToken

<Check>
  ##### What's it used for?

  The organizationToken is used in subsequent steps to create an organization entity or to run a workflow.
</Check>

Lookup may return multiple matches. Each match will have some business details and a unique organizationToken. Be sure to extract the organizationToken matching the details of the organization you intend to process.

For example, extract the organizationToken for the first matched result:

```javascript Retrieving a Company code theme={null}
    const organizationToken = response["matchedOrganizations"][0]["organizationToken"];
```


# Creating & Managing Organizations
Source: https://docs.frankieone.com/docs/kyb/managing-organizations



A guide to the complete lifecycle of an 'organization' entity, from creation and retrieval to deletion.

The `organization` is a core object in the FrankieOne platform, representing a business. This guide covers the complete lifecycle of creating and managing these entities via the API.

## 1. Creating an Organization

To create an `organization` entity, send a `POST` request with the organizationToken retrieved from the [/lookup](/api-reference/organizations/lookup-organizations) endpoint. A successful request will return a `201 Created` status and the `organization` object, including a unique `entityId`.
The `entityId` returned in the response can be used for subsequent operations, such as executing a workflow.

<Callout icon="bell">
  ###### Warning: organizationToken Expiry

  The `organizationToken` retrieved from the lookup endpoint does not last forever. If your request fails indicating invalid organizationToken, you will need to perform a new lookup to retrieve a new organizationToken.
</Callout>

<Callout icon="bell">
  ###### Warning: A new entity is created for each request

  A new entity is created for each request. We do not de-duplicate entities based on organizationToken in this request.
</Callout>

### Example: Creating an Organization

This example shows a standard request to create an organization with organizationToken retrieved from the [/lookup](/api-reference/organizations/lookup-organizations) endpoint.

1. In the example below, replace `YOUR_CUSTOMER_ID` with your Customer ID and `YOUR_API_KEY` with your API key provided by FrankieOne.
2. Copy the resulting code into your command line, and run the command.

#### Request

<CodeGroup>
  ```bash Request - Create Organization theme={null}
  curl --location 'https://api.uat.frankie.one/v2/organizations' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
  --header 'Content-Type: application/json' \
  --data '{
      "organizationToken": "eyJ2ZXIiOiIxLjAiLCJ0cyI6IjIwMjUtMDktMTBUMDQ6Mzc6MDIuMDg3MDU3MzMzWiIsIm9uIjpbeyJybiI6IjYxNjIzNTA2ODkyIiwicmEiOiJBQk4ifSx7InJuIjoiNjIzNTA2ODkyIiwicmEiOiJBQ04ifV0sInByb3YiOiJjcmVkaXRvcndhdGNoIiwiY28iOiJBVVMifQ=="
  }'
  ```
</CodeGroup>

#### Response

<CodeGroup>
  ```json Response - Create Organization theme={null}
  {
      "organization": {
          "createdAt": "2025-09-10T04:53:46Z",
          "details": {
              "registrationDetails": [
                  {
                      "registrationNumber": "61623506892",
                      "registrationNumberType": "ABN",
                      "sourceId": "ec13d19f-c725-4397-a575-92c65c070f23"
                  },
                  {
                      "registrationNumber": "623506892",
                      "registrationNumberType": "ACN",
                      "sourceId": "ec13d19f-c725-4397-a575-92c65c070f23"
                  }
              ]
          },
          "entityId": "019931f9-02a2-7c87-816c-c9e6743eaae5",
          "entityType": "ORGANIZATION",
          "informationSources": {
              "ec13d19f-c725-4397-a575-92c65c070f23": {
                  "createdAt": "2025-09-10T04:53:46.674358Z",
                  "isAuthoritative": true,
                  "provider": "CREDITOR_WATCH",
                  "requestedAt": "2025-09-10T04:37:02Z",
                  "source": "ASIC",
                  "sourceId": "ec13d19f-c725-4397-a575-92c65c070f23"
              }
          },
          "schemaVersion": 2,
          "sourceId": "ec13d19f-c725-4397-a575-92c65c070f23",
          "updatedAt": "2025-09-10T04:53:46Z"
      },
      "requestId": "01K4RZJ0CGM3PWCRS5NRH4WXMA",
      "serviceProfiles": [
          {
              "createdAt": "2025-09-10T04:53:46.9539Z",
              "createdRequestId": "01K4RZJ0CGM3PWCRS5NRH4WXMA",
              "entityId": "019931f9-02a2-7c87-816c-c9e6743eaae5",
              "entityName": "FRANKIE FINANCIAL PTY LTD",
              "entityType": "ORGANIZATION",
              "serviceName": "DEFAULT",
              "serviceProfileId": "86cf3db8-a9f5-433d-b446-35927096d327",
              "state": "INIT",
              "subscriptions": [],
              "updatedAt": "2025-09-10T04:53:46.9539Z"
          }
      ]
  }
  ```
</CodeGroup>

### The `organization` Object

The `organization` object holds all the information about the business. Organization `details` holds the organization details including registration details, organization name etc.
For more details on the fields in the organization object, please refer to our [retrieve organization](/api-reference/organizations/get-an-organization-entity) API documentation.
To understand ownership structure of the organization, please refer to [understanding organization ownership](/docs/kyb/organization-ownership) documentation.

#### Information Sources

`organization` object also includes `informationSources` which is a map of information source Ids to information source objects. These objects indicate the vendor and registry from which information was retrieved, and when it was requested.
Data points in the organization object are then tagged with this sourceId.

#### Service Profiles

If a `serviceName` is passed in the Create Organization request, a service profile of that service gets created as part of the entity creation. If no `serviceName` is passed, a default service profile is created.
`serviceProfiles` is an array of service profile objects associated with the organization.

***

## 2. Retrieving an Organization

To fetch the current state of an organization entity, use a `GET` request with their unique `entityId`.

#### Request

<CodeGroup>
  ```bash Request - Retrieve Organization theme={null}
      curl --location 'https://api.uat.frankie.one/v2/organizations/019931f9-02a2-7c87-816c-c9e6743eaae5' \
      --header 'api_key: YOUR_API_KEY' \
      --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID'
  ```
</CodeGroup>

The response will contain the full `organization` object, similar to the response from the creation request. If you've retrieved additional data points for the entity, by running the profile/ownership workflows, they will also be included in the response.

***

## 3. Deleting an Organization

You can delete an organization entity using the `DELETE` endpoint with their `entityId`.

<Danger>
  Deletion is Permanent

  Deleting an entity is an irreversible action. This data cannot be recovered. Only perform deletions when you are certain the data is no longer required for any operational, audit, or compliance purpose.
</Danger>

### Deleting an Organization

To permanently remove an organization and all their associated data, use the `DELETE` endpoint with their `entityId`.

#### Request

<CodeGroup>
  ```bash Request - Delete Organization theme={null}
      curl --location --request DELETE 'https://api.uat.frankie.one/v2/organizations/019931f9-02a2-7c87-816c-c9e6743eaae5' \
      --header 'api_key: YOUR_API_KEY' \
      --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID'
  ```
</CodeGroup>


# Understanding Organization Ownership
Source: https://docs.frankieone.com/docs/kyb/organization-ownership



Learn what fields within the Organization object mean, specifically in the context of Organization Ownership.

## Summary

The `organization` object has rich details regarding the organization and its ownership structure.
You can either create an organization through our [create organization](/api-reference/organizations/create-an-organization-entity) API or by [executing a data-fetch workflow](/api-reference/organization-workflows/execute-a-workflow-with-organization-details) like `GLB-Organization-Profile` or `GLB-Organization-Ownership`.
Once you have the `entityId` of the created organization, you can fetch its details using the [retrieve organization](/api-reference/organizations/get-an-organization-entity) API.

The organization object mainly consists of:

* Details of the organization - This includes name, registration details, addresses, phone numbers, web URLs, etc. For more details on these fields, please refer to our [retrieve organization](/api-reference/organizations/get-an-organization-entity) API documentation.
* Organization ownership - This includes the ownership details of the organization, including shareholdings and ultimate beneficial owners. This page focuses on organization ownership.

## Organization Ownership

These fields are of interest to you if you want to understand the ownership details of the organization.

#### `shareCapital`

The total value of shares issued by the company to its holders. It typically includes both the nominal value of the shares as well as any premium paid by the shareholders.

#### `shareInterests`

Represents the specific equity interests held by shareholders (for example, ordinary shares, preference shares, or options) and their associated holders.

Each `shareInterest` includes:

* Members who hold the interest (supports joint holdings)
* Whether the interest is beneficial or non-beneficial
* The ownership percentage

### Associated Entities

The following are the associated entities of the organization. Each object in the array has a unique `entityId`. You can then use this to get more information about the entity in the `linkedIndividuals` or `linkedOrganizations` maps of the `organization` object.

#### `shareholders`

The shareholders of a company. It includes details such as the number of shares held by each shareholder and their ownership percentages. Look up the `entityId` in the `linkedIndividuals` or `linkedOrganizations` maps of the `organization` object to get more information about the shareholder.

#### `officials`

The entities that hold official positions or roles within a company, such as directors or company secretaries. It includes details such as their positions, appointment dates, and other relevant information. Look up the `entityId` in the `linkedIndividuals` or `linkedOrganizations` maps of the `organization` object to get more information about the official.

### Ownership Insights

We provide the following fields to draw insights into the ownership of the organization. Ownership Insights are calculated based on the ownership policy configured according to your requirements.

#### `ownershipPolicy`

Defines the configuration and specific threshold values used to identify blocking entities, UBOs, and other owners.

#### `ultimateBeneficialOwners`

UBO stands for “Ultimate Beneficial Owner.” UBO(s) are the natural person(s) who ultimately own or control a company. This provides information about the individuals who have a significant level of control or ownership in a company, either directly or indirectly.

#### `blockingEntities`

Entities linked to the parent entity that currently prevent a complete ownership picture (for example, missing filings or opaque structures) and may require further investigation.

#### `otherOwners`

The other owners of the company, who aren't necessarily UBOs.

## Traversing Ownership Tree

Use the combination of associated-entity arrays and linked-entity maps to navigate the structure:

* Associated entity arrays (on the focus organization): `officials`, `shareholders`
  * Contain summary items, each with an `entityId`
* Linked entity maps (siblings on the same object): `linkedIndividuals`, `linkedOrganizations`
  * Provide full records keyed by `entityId`

Step-by-step:

1. Start at the focus organization. Inspect its `officials` and `shareholders` arrays.
2. For each item, note the `entityId` and whether it represents an individual or organization.
3. Resolve details via:
   * Individuals → `linkedIndividuals[entityId]`
   * Organizations → `linkedOrganizations[entityId]`
4. If you land on a linked organization and need to go deeper, repeat the same process using that organization’s `officials` and `shareholders` (the details for these should be present in the top level `linkedIndividuals`/`linkedOrganizations`).
5. Stop when you reach your analysis depth, there are no more organizations to follow, or you’ve visited an entity already (to avoid cycles).

Example (simplified, based on an actual organization response):

```json theme={null}
  {
    "officials": [
      {
        "entityId": "dc5e27f9-1952-408a-9f99-082926539e69",
        "entityType": "INDIVIDUAL",
        "role": { "code": "DR", "description": "Director" }
      }
    ],
    "shareholders": [
      { "entityId": "019d6837-26bd-7639-88fc-d629519acb9a", "entityType": "ORGANIZATION" },
      { "entityId": "08916f09-fc05-4778-9899-f147d9d61071", "entityType": "INDIVIDUAL" }
    ],
    "linkedIndividuals": {
      "dc5e27f9-1952-408a-9f99-082926539e69": {
        "entityId": "dc5e27f9-1952-408a-9f99-082926539e69",
        "entityType": "INDIVIDUAL",
        "name": { "displayName": "DANIELE CATALANO" }
      },
      "08916f09-fc05-4778-9899-f147d9d61071": {
        "entityId": "08916f09-fc05-4778-9899-f147d9d61071",
        "entityType": "INDIVIDUAL",
        "name": { "displayName": "CHLOE MARIE CATALANO" }
      },
      "c0cda324-e77f-47fa-b30e-bcf4b38fd971": {
        "entityId": "c0cda324-e77f-47fa-b30e-bcf4b38fd971",
        "entityType": "INDIVIDUAL",
        "name": { "displayName": "MICHELLE ANNE CATALANO" }
      }
    },
    "linkedOrganizations": {
      "019d6837-26bd-7639-88fc-d629519acb9a": {
        "entityId": "019d6837-26bd-7639-88fc-d629519acb9a",
        "entityType": "ORGANIZATION",
        "details": { "name": { "name": "DYLCLO PTY LTD" } },
        "officials": [
          {
            "entityId": "dc5e27f9-1952-408a-9f99-082926539e69",
            "entityType": "INDIVIDUAL",
            "role": { "code": "DR", "description": "Director" }
          }
        ],
        "shareholders": [
          { "entityId": "c0cda324-e77f-47fa-b30e-bcf4b38fd971", "entityType": "INDIVIDUAL" },
          { "entityId": "dc5e27f9-1952-408a-9f99-082926539e69", "entityType": "INDIVIDUAL" }
        ]
      }
    }
  }
```

In this example, the focus organization has one official (`dc5e27f9-...`, Daniele Catalano, Director) and two shareholders: an organization (`019d6837-...`, DYLCLO PTY LTD) and an individual (`08916f09-...`, Chloe Catalano). You can resolve each entity's full details from the linked maps, and then follow DYLCLO PTY LTD's `shareholders`. This leads you to `c0cda324-...` (Michelle Catalano) and back to `dc5e27f9-...` (Daniele Catalano) — the same individual already seen as a top-level official. Since `dc5e27f9-...` has already been visited, stop traversing that branch to avoid a cycle.

You can continue this process to traverse the ownership tree.

Note:

* The `linkedIndividuals` and `linkedOrganizations` maps are flat and live at the top level of the response for the focus organization. There are no nested linked maps per linked organization—use the same top-level maps to resolve any `entityId` you encounter while traversing.
* If an `entityId` is not present in the corresponding linked map, treat it as incomplete data. You can fetch details on-demand via the API or surface a "details unavailable" state.
* To avoid cycles and overly deep traversals (for example, cross-holdings), keep a set of visited `entityId`s and consider a maximum traversal depth.


# Standard Workflows
Source: https://docs.frankieone.com/docs/kyb/standard-kyb-bundles

Explore our out-of-the-box KYB workflow solutions designed to get you started with best-practice business verification quickly.

## Out-of-the-Box Workflow Solutions

FrankieOne offers a suite of standard KYB workflows that address the most common business onboarding and compliance monitoring needs. These pre-configured workflows allow for rapid integration, enabling you to implement a best-practice business verification process without the need for custom configuration.

To run one, simply reference its **Workflow Name** when [executing a workflow](/docs/kyb/executing-workflows) via the API.

### Choosing Your Workflow Type

Our KYB workflows are categorized by the depth of the ownership picture you need:

* **Profile Workflows:** Retrieve the organization's registration details and direct ownership (immediate shareholders and officers), then run compliance checks. Suited to lower-risk onboarding where a single level of ownership is sufficient.
* **Ownership Workflows:** Retrieve the complete ownership tree, including nested entities, and derive Ultimate Beneficial Owners (UBOs). Required where you need to identify and verify the individuals who ultimately control the business.

Each type is available in a standard variant and a **Force-Refresh** variant. Standard variants reuse recently fetched provider data within a configurable ageing window; Force-Refresh variants always retrieve the latest data directly from providers.

***

## Onboarding Workflows

These workflows are executed against an organization to fetch its data and run compliance checks.

### Profile Workflows

<AccordionGroup>
  <Accordion title="Organization Profile">
    Retrieves the organization's registration details, addresses, trading names and status, along with direct shareholders and officers. Runs AML screening and risk assessment.

    * **Workflow Name:** `GLB-Organization-Profile`
    * **Use Case:** Standard business onboarding where direct ownership is sufficient.
    * **Core Checks:** Registration Lookup, Data Enrichment, AML (Sanctions & Watchlist) Screening, Associated Entities Risk.
    * **Primary Data Sources:** Business registry and data providers appropriate to the organization's jurisdiction, covering Australia, the US and international markets, plus an AML screening provider.
    * **Outputs:** A downloadable PDF Profile Report.
    * **Possible Outcomes:** `COMPLETE`, `IN_PROGRESS`, `REVIEW`, `FAIL`.
    * **Data Freshness:** Reuses recently fetched provider data within a configurable ageing window.
  </Accordion>

  <Accordion title="Organization Profile – Force Refresh">
    Identical to Organization Profile, but always fetches the latest data directly from providers rather than reusing recently fetched data.

    * **Workflow Name:** `GLB-Organization-Profile-Force-Refresh`
    * **Use Case:** Re-verification where up-to-date information is critical — for example after a known change to the business, or where previously retrieved data may be stale or incomplete.
    * **Core Checks:** Registration Lookup, Data Enrichment, AML (Sanctions & Watchlist) Screening, Associated Entities Risk.
    * **Primary Data Sources:** Business registry and data providers appropriate to the organization's jurisdiction, covering Australia, the US and international markets, plus an AML screening provider.
    * **Outputs:** A downloadable PDF Profile Report.
    * **Possible Outcomes:** `COMPLETE`, `IN_PROGRESS`, `REVIEW`, `FAIL`.
    * **Data Freshness:** Always retrieves fresh data from providers.
  </Accordion>
</AccordionGroup>

### Ownership Workflows

<AccordionGroup>
  <Accordion title="Organization Ownership">
    Retrieves the full ownership structure of an organization, including the complete shareholder and officer tree with nested entities. Derives UBOs and identifies blocking entities based on your configured ownership policy (for example, a 25% threshold).

    * **Workflow Name:** `GLB-Organization-Ownership`
    * **Use Case:** Onboarding where you must identify and verify the individuals who ultimately own or control the business.
    * **Core Checks:** Registration Lookup, Full Ownership Tree Retrieval, Ownership Insights (UBO Derivation), AML (Sanctions & Watchlist) Screening, Associated Entities Risk.
    * **Primary Data Sources:** Business registry and data providers appropriate to the organization's jurisdiction, covering Australia, the US and international markets, plus an AML screening provider.
    * **Outputs:** A downloadable PDF Ownership Report, including a UBO tree diagram.
    * **Possible Outcomes:** `COMPLETE`, `IN_PROGRESS`, `REVIEW`, `FAIL`.
    * **Data Freshness:** Reuses recently fetched provider data within a configurable ageing window.
  </Accordion>

  <Accordion title="Organization Ownership – Force Refresh">
    Identical to Organization Ownership, but always fetches the latest ownership data directly from providers.

    * **Workflow Name:** `GLB-Organization-Ownership-Force-Refresh`
    * **Use Case:** When the ownership structure may have recently changed (new shareholders, resignations), after a regulatory event requiring fresh verification, or when a previous ownership fetch returned incomplete data.
    * **Core Checks:** Registration Lookup, Full Ownership Tree Retrieval, Ownership Insights (UBO Derivation), AML (Sanctions & Watchlist) Screening, Associated Entities Risk.
    * **Primary Data Sources:** Business registry and data providers appropriate to the organization's jurisdiction, covering Australia, the US and international markets, plus an AML screening provider.
    * **Outputs:** A downloadable PDF Ownership Report, including a UBO tree diagram.
    * **Possible Outcomes:** `COMPLETE`, `IN_PROGRESS`, `REVIEW`, `FAIL`.
    * **Data Freshness:** Always retrieves fresh data from providers.
  </Accordion>
</AccordionGroup>

<Note>
  **AML screening defaults to sanctions and watchlist checks.** By default, the AML step in these workflows screens the focus organization against sanctions and watchlists only.

  **Adverse media is not included by default.** If you require adverse media screening, it must be configured — contact your account manager to have it enabled for your account.
</Note>

These workflows also manage ongoing AML monitoring for you: monitoring is enabled automatically when the AML check finds no issues, and disabled when it returns a failure. No manual intervention is required.

***

## Understanding Your Workflow Result

Onboarding workflows return one of four outcomes:

| Result        | What It Means                                                                                                      | What To Do                                                    |
| ------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
| `COMPLETE`    | The organization passed all checks, and all associated entities (UBOs) have completed their individual KYC checks. | Proceed with onboarding.                                      |
| `IN_PROGRESS` | The organization itself passed, but one or more UBOs have not yet completed their individual KYC checks.           | Complete the outstanding UBO verifications, then re-evaluate. |
| `REVIEW`      | The AML screening returned a potential match.                                                                      | Review the AML result and make a decision.                    |
| `FAIL`        | The AML screening returned a confirmed match.                                                                      | Do not proceed; follow your escalation process.               |

<Note>
  When AML screening returns a potential or confirmed match, the workflow goes straight to `REVIEW` or `FAIL` and skips the associated entities risk check. The AML outcome takes priority.
</Note>

For a full walkthrough of reading a workflow result, see [Interpreting workflow results](/docs/kyb/interpreting-workflows-v2).

***

## Workflow Comparison

| Feature                      | Profile                              | Profile Force-Refresh                | Ownership                            | Ownership Force-Refresh              |
| ---------------------------- | ------------------------------------ | ------------------------------------ | ------------------------------------ | ------------------------------------ |
| **Registration lookup**      | Yes (cached)                         | Yes (fresh)                          | Yes (cached)                         | Yes (fresh)                          |
| **Provider data**            | Direct ownership (cached)            | Direct ownership (fresh)             | Full tree (cached)                   | Full tree (fresh)                    |
| **UBO derivation**           | No                                   | No                                   | Yes                                  | Yes                                  |
| **PDF report**               | Profile Report                       | Profile Report                       | Ownership Report                     | Ownership Report                     |
| **AML screening**            | Sanctions & watchlist                | Sanctions & watchlist                | Sanctions & watchlist                | Sanctions & watchlist                |
| **Toggles AML monitoring**   | Yes                                  | Yes                                  | Yes                                  | Yes                                  |
| **Associated entities risk** | Yes (UBOs)                           | Yes (UBOs)                           | Yes (UBOs)                           | Yes (UBOs)                           |
| **Possible outcomes**        | COMPLETE, IN\_PROGRESS, REVIEW, FAIL | COMPLETE, IN\_PROGRESS, REVIEW, FAIL | COMPLETE, IN\_PROGRESS, REVIEW, FAIL | COMPLETE, IN\_PROGRESS, REVIEW, FAIL |

***

## Data Freshness and Provider Calls

Understanding when a workflow calls an external provider helps you manage cost.

* **Standard workflows** reuse previously retrieved provider data when it falls within the configurable ageing window. No new provider call is made, and no charge is incurred for that step. This is the cost-efficient default.
* **Force-Refresh workflows** always make a fresh provider call, regardless of what data is already held. A charge is incurred for each provider step on every run.

***

## Next Steps

* [Executing workflows](/docs/kyb/executing-workflows) — how to run a workflow against an organization
* [Interpreting workflow results](/docs/kyb/interpreting-workflows-v2) — reading and acting on the response
* [Organization ownership](/docs/kyb/organization-ownership) — working with UBOs and the ownership tree


# Trust Analyzer
Source: https://docs.frankieone.com/docs/kyb/trust-analyzer

Extract trust structures from trust deeds and produce audit-ready, structured output for complex KYB onboarding using the FrankieOne Trust Analyzer, through the Portal or the API.

<Callout icon="thumbtack">
  ##### Access

  The Trust Analyzer runs as the `GLB-Trust-Analysis` workflow on the V2 platform. Contact your FrankieOne representative to have it enabled for your environment.
</Callout>

## Overview

Trusts are one of the harder entity types to onboard. The information you need lives in a trust deed, a long, free-form legal document that varies in layout from one trust to the next, and reading it by hand is slow and easy to get wrong. The Trust Analyzer does that reading for you.

It ingests a trust deed PDF, classifies the trust type, extracts the named parties (trustees, settlors, beneficiaries, appointors, protectors, SMSF members), and normalises their roles into a consistent structure. Every extracted value carries a reference back to the page of the deed it came from, so your compliance team can trace and verify each field.

The result is structured, audit-ready data you can review, correct, and feed into your KYB and KYC workflows. It lets you onboard trusts, and businesses that hold assets through trusts, at scale without adding the manual review effort that deeds normally demand.

Trust Analyzer currently supports Australian trust deeds only; international coverage is not yet supported.

***

## How it Works

You can run a trust analysis either through the Portal or directly through the API. Both follow the same underlying analyse, review, confirm pattern, with a human confirmation step so a person signs off on the extracted structure before it is used for compliance.

### Via the Portal

<Steps>
  <Step title="Open the Trust Analyser tab">
    From the organization's Overview page, select the **Trust Analyser** tab.

    <Frame>
      <img alt="Trust Analyser tab on the organization Overview page" />
    </Frame>
  </Step>

  <Step title="Upload the trust deed">
    Select **Upload trust deed** and add the PDF (up to 20MB).

    <Frame>
      <img alt="Add Document dialog for uploading a trust deed" />
    </Frame>
  </Step>

  <Step title="Track progress">
    The uploaded deed appears in the Trust deeds table with its status — starting at analysis, then **To be reviewed** once ready.

    <Frame>
      <img alt="Trust deeds table showing a deed with status To be reviewed" />
    </Frame>
  </Step>

  <Step title="Review and confirm, with corrections if needed">
    Once analysis completes, the extracted structure opens in a split view: the deed on the left, extracted fields on the right. Each field carries a small reference marker (e.g. `1a`, `2a`) linking it back to its source page, so you can verify quickly without re-reading the whole document. Correct anything that needs it inline, select **I have reviewed and accept the data in this trust deed**, then select **Save**.
  </Step>

  <Step title="Associate the parties">
    Confirmed parties appear on the same screen, marked as an **Associated party**, and are linked to the organization's ownership and control structure.
  </Step>
</Steps>

### Via the API

<Steps>
  <Step title="Upload the trust deed">
    Upload the trust deed PDF as a `TRUST_DEED` document against the organization entity and keep the returned `documentId`. This is the document the workflow will analyse.
  </Step>

  <Step title="Execute the Trust Analysis workflow">
    Execute `GLB-Trust-Analysis` for the organization, passing the `documentId` via `executionVariables`. The trust type is detected from the document, so you do not supply it.
  </Step>

  <Step title="Track progress">
    The workflow runs asynchronously. Track the execution result until it reaches `REVIEW`, which signals that analysis has completed and the extracted data is ready to look at.
  </Step>

  <Step title="Retrieve and review the analysis">
    Fetch the analyses for the document. Each analysis includes the detected trust type and the extracted parties, with `references` that point back to the page in the deed each value came from.
  </Step>

  <Step title="Confirm, with corrections if needed">
    Review the extracted data, correct any field that needs it, then confirm. Confirmation records your accepted version while keeping the original analysis as an audit trail.
  </Step>

  <Step title="Associate the parties">
    Link the extracted parties to the focus organization so they form part of its ownership and control structure.
  </Step>
</Steps>

<Callout icon="code">
  Ready to integrate? The [Trust Analyzer Implementation Guide](/docs/kyb/trust-analyzer-implementation) walks the full Portal and API flow step by step, with request and response examples for each stage.
</Callout>

***

## Supported Trust Types

| Trust Type                              | Detected value            |
| --------------------------------------- | ------------------------- |
| Discretionary (family) trust            | `DISCRETIONARY`           |
| Unit trust                              | `UNIT`                    |
| Self-managed superannuation fund (SMSF) | `SELF_MANAGED_SUPER_FUND` |
| Could not be classified                 | `UNKNOWN`                 |

Every analysis returns the details common to any trust (name, establishment, certification, and execution dates, trustees, and settlors). On top of that, the shape of `typeInformation` depends on the detected type:

* **Discretionary** (`discretionary`): specified beneficiaries, general beneficiaries, appointors, and protectors.
* **Unit** (`unit`): unit holders with their holdings (as a percentage or a unit count) and the total units on issue.
* **SMSF** (`selfManagedSuperFund`): the fund's members.
* **Unknown** (`unknown`): the reasons the trust could not be classified. A trust type must be identified before you can confirm.

General beneficiaries are a class of persons defined in the deed who may receive funds; specified beneficiaries are named individuals.

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What document format is accepted?">
    The trust deed must be a PDF, up to 100 pages and 20MB. Use a text-based (machine-readable) PDF: extraction reads the document text directly, so scanned or image-only deeds may not extract reliably.
  </Accordion>

  <Accordion title="How long does analysis take?">
    Analysis is asynchronous and usually takes a couple of minutes; complex multi-schedule deeds can take a little longer.
  </Accordion>

  <Accordion title="Do I need to specify the trust type?">
    No. The trust type is detected automatically from the deed. It's returned in `type.detected` via the API and shown directly in the Portal's review screen.
  </Accordion>

  <Accordion title="What happens if the trust type cannot be detected?">
    It's returned as `UNKNOWN` (API) or shown as unclassified (Portal), with the reasons why. Trust type is inferred by the analyzer and isn't something you can manually set or override, in the Portal or via the API — a trust type must be successfully identified before the analysis can be confirmed.
  </Accordion>

  <Accordion title="Can I correct the extracted data?">
    Yes. In the Portal, correct fields inline on the review screen before selecting **Save**. Via the API, send the corrected `documentInformation` to the [analysis confirm endpoint](/api-reference/organization/document-analysis-result-confirmation). The original analysis is always retained as an audit trail.
  </Accordion>

  <Accordion title="What happens if I re-run analysis on a deed that hasn't changed?">
    Re-running analysis on an unchanged trust deed reuses the existing valid analysis rather than running a new one, and you're not charged again. If the deed's attachment is later updated or deleted, prior analyses for that document are marked stale.
  </Accordion>
</AccordionGroup>

***

## Next Steps

* [Trust Analyzer Implementation Guide](/docs/kyb/trust-analyzer-implementation) — the full Portal and API walkthrough: upload, execute, retrieve, confirm, and associate parties.
* [Executing Workflows](/docs/kyb/executing-workflows) — how `executionVariables` are passed when executing a workflow.
* [Interpreting Workflow Results](/docs/kyb/interpreting-workflows-v2) — parse the full `workflowResult` object.
* [Managing Organizations](/docs/kyb/managing-organizations) — create and manage the organization entity before running the workflow.
* [Anti-Money Laundering](/docs/kyb/anti-money-laundering) — screen the parties extracted from the trust deed.


# Trust Analyzer Implementation
Source: https://docs.frankieone.com/docs/kyb/trust-analyzer-implementation

Step-by-step walkthrough for running a trust analysis via the Portal or the API: upload the deed, run the analysis, retrieve and confirm the extracted structure, and associate the parties.

New to the Trust Analyzer? Start with the [Trust Analyzer overview](/docs/kyb/trust-analyzer) for what it does and how the flow fits together, then come back here for the full walkthrough.

This guide covers both the Portal walkthrough and the API walkthrough. Use whichever fits your team — they produce the same result. Currently supports Australian trust deeds only.

***

## Portal Walkthrough

### Prerequisites

* **An organization entity** already created in the Portal.
* **Trust Analyzer enabled** for your environment, with the workflow assigned and turned on in Ops Centre. Contact your FrankieOne representative if you don't see it yet.
* Available for Australian trust deeds only.

<Steps>
  <Step title="Open the Trust Analyser tab">
    From the organization's Overview page, select the **Trust Analyser** tab.

    <Frame>
      <img alt="Trust Analyser tab on the organization Overview page" />
    </Frame>
  </Step>

  <Step title="Upload the trust deed">
    Select **Upload trust deed**, then either drag and drop the file or select **Browse File** to choose the PDF (max 20MB).

    <Frame>
      <img alt="Add Document dialog for uploading a trust deed" />
    </Frame>
  </Step>

  <Step title="Track progress">
    The deed appears in the Trust deeds table on the same tab, with its status shown in the Status column — through analysis, then **To be reviewed** once the extracted data is ready.

    Re-uploading and re-analysing an unchanged trust deed reuses the existing valid analysis rather than running a fresh one. If the attachment is later updated or deleted, prior analyses for that document are marked stale.

    <Frame>
      <img alt="Trust deeds table showing a deed with status To be reviewed" />
    </Frame>
  </Step>

  <Step title="Review and confirm">
    Select the deed to open the review screen: the deed itself on the left, extracted fields on the right. Each field carries a small reference marker (e.g. `1a`, `1b`, `2a`) — these link back to the exact location in the deed the value was extracted from, so you can verify quickly without re-reading the whole document.

    Correct any field that needs it directly in the form. When you're satisfied, select **I have reviewed and accept the data in this trust deed** and select **Save** — review and confirmation happen on this one screen, there's no separate confirm step.

    If the trust type could not be detected, it's shown as unclassified with the reasons why. Trust type is inferred automatically and isn't something you can set or override from the Portal — the analysis can't be confirmed until the deed is successfully classified.
  </Step>

  <Step title="View associated parties">
    Once saved, confirmed parties are marked as an **Associated party** directly on the same screen, and appear as part of the organization's ownership and control structure.
  </Step>
</Steps>

***

## API Walkthrough

The examples use the UAT base URL (`https://api.uat.frankie.one`); swap in your production base URL when you go live.

### Prerequisites

Before running a trust analysis via API, make sure the following are in place:

* **The Trust Analyzer enabled.** The `GLB-Trust-Analysis` workflow has to be enabled for your environment on the V2 platform. If you don't see it yet, contact your FrankieOne representative to have it turned on.
* **An organization entity.** Trust analysis runs against an existing `organization`, the focus entity that holds or is associated with the trust. Create it first and keep its `entityId`. See [Managing Organizations](/docs/kyb/managing-organizations) for how to create one.
* **The trust deed uploaded.** The deed must already be attached to that organization as a `TRUST_DEED` document. You upload it in Step 1 below and keep the returned `documentId`, which is what the workflow analyses.
* **A service profile.** The `serviceName` of the Service Profile the organization is assessed against, for example `DEFAULT`. Your FrankieOne representative provides this when the workflow is set up.

### Step 1: Upload the Trust Deed

The Trust Analyzer works on a deed that is already attached to the organization, so upload it first. Send the PDF as a base64-encoded attachment on a `TRUST_DEED` document, and keep the `documentId` from the response. You pass that `documentId` to the workflow in the next step.

<CodeGroup>
  ```bash Request - Upload Trust Deed theme={null}
  curl --location 'https://api.uat.frankie.one/v2/organizations/{{entityId}}/documents' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
  --header 'Content-Type: application/json' \
  --data '{
      "document": {
          "type": "TRUST_DEED",
          "attachments": [
              { "data": "JVBERi0xLjQ...base64-encoded PDF..." }
          ]
      }
  }'
  ```
</CodeGroup>

### Step 2: Execute the Trust Analysis Workflow

Execute `GLB-Trust-Analysis` against the organization's `entityId`. Pass the `documentId` of the uploaded trust deed in `executionVariables`. This is the only execution variable the workflow needs; the trust type is detected from the document, so you don't supply it. The optional `comment` is recorded on the workflow's audit trail.

The response returns a `workflowExecutionId`. Keep it: you use it in the next step to track the execution.

<CodeGroup>
  ```bash Request - Execute Trust Analysis Workflow theme={null}
  curl --location 'https://api.uat.frankie.one/v2/organizations/{{entityId}}/serviceprofiles/{{serviceName}}/workflows/GLB-Trust-Analysis/execute' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
  --header 'Content-Type: application/json' \
  --data '{
      "executionVariables": {
          "documentId": "92de15f6-5717-4562-b3fc-2c963f6665a7"
      },
      "comment": {
          "text": "Initiating trust deed analysis for onboarding"
      }
  }'
  ```

  ```json Response - Execute Trust Analysis Workflow theme={null}
  {
      "entityId": "01993733-cfd5-7594-9e90-ec3ad06dd490",
      "requestId": "01K4VK7KWN6HEA43AQ0F13JZPT",
      "serviceName": "DEFAULT",
      "workflowExecutionId": "01K4VK7QDJG631AWFKWYVE85Z5"
  }
  ```
</CodeGroup>

<Callout icon="circle-info">
  Re-executing on an unchanged trust deed reuses the existing valid analysis. No new analysis is run and you are not charged again. If the deed's attachment is later updated or deleted, prior analyses for that document are marked stale.
</Callout>

### Step 3: Track the Workflow Execution

Trust analysis is asynchronous. The execute endpoint returns `202 Accepted` with a `workflowExecutionId`. Retrieve the execution result and poll until `workflowResult.workflowExecutionState` is no longer `IN_PROGRESS`. When analysis completes, the workflow result moves to `REVIEW`, indicating the extracted data is ready for you to review and confirm. Poll every 5 to 10 seconds.

<CodeGroup>
  ```bash Request - Retrieve Workflow Execution Result theme={null}
  curl --location 'https://api.uat.frankie.one/v2/organizations/{{entityId}}/serviceprofiles/{{serviceName}}/workflows/GLB-Trust-Analysis/executions/{{workflowExecutionId}}' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID'
  ```
</CodeGroup>

### Step 4: Retrieve the Analysis Results

Fetch the analyses for the document. Use the `showResults` query parameter to control which analyses are returned: `LATEST` (default), `COMPLETE`, or `CONFIRMED`.

Each analysis carries a `status` (`PROCESSING`, `FAILED`, `COMPLETE`, or `CONFIRMED`), the detected trust `type`, the extracted parties, and a `references` map that points each extracted value back to its location in the deed.

<CodeGroup>
  ```bash Request - Get Document Analyses theme={null}
  curl --location 'https://api.uat.frankie.one/v2/organizations/{{entityId}}/documents/{{documentId}}/analyses?showResults=LATEST' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID'
  ```

  ```json Response - Document Analyses (Discretionary trust) theme={null}
  {
      "entityId": "01993733-cfd5-7594-9e90-ec3ad06dd490",
      "requestId": "01HN9XHZN6MGXM9JXG50K59Q85",
      "analyses": [
          {
              "documentId": "92de15f6-5717-4562-b3fc-2c963f6665a7",
              "analysisId": "01K4VK7QDJG631AWFKWYVE85Z5",
              "status": "COMPLETE",
              "documentInformation": {
                  "type": "TRUST_DOCUMENT",
                  "trust": {
                      "name": { "value": "The Doe Family Trust", "referenceIds": ["r1"] },
                      "type": { "detected": "DISCRETIONARY" },
                      "trustees": [
                          { "entityId": "org-1", "entityType": "ORGANIZATION", "referenceIds": ["r2"] }
                      ],
                      "settlors": [
                          { "entityId": "ind-1", "entityType": "INDIVIDUAL", "referenceIds": ["r3"] }
                      ],
                      "linkedOrganizations": {
                          "org-1": {
                              "entityType": "ORGANIZATION",
                              "details": { "name": { "value": "Doe Nominees Pty Ltd" } }
                          }
                      },
                      "linkedIndividuals": {
                          "ind-1": {
                              "entityType": "INDIVIDUAL",
                              "name": { "givenName": "Jane", "familyName": "Doe" }
                          }
                      },
                      "typeInformation": {
                          "type": "DISCRETIONARY",
                          "discretionary": {
                              "appointors": [
                                  { "entityId": "ind-1", "entityType": "INDIVIDUAL", "referenceIds": ["r3"] }
                              ],
                              "generalBeneficiaries": [
                                  { "value": "The children of the settlor", "referenceIds": ["r4"] }
                              ]
                          }
                      }
                  }
              },
              "references": {
                  "r1": { "referenceId": "r1", "sourceId": "trust-deed", "location": { "page": 1 } },
                  "r2": { "referenceId": "r2", "sourceId": "trust-deed", "location": { "page": 1 } }
              }
          }
      ]
  }
  ```
</CodeGroup>

<Callout icon="triangle-exclamation">
  If the trust type cannot be classified, `type.detected` is `UNKNOWN` and the trust details include the reasons under `typeInformation.unknown`. A trust type must be identified before the analysis can be confirmed.
</Callout>

#### Understanding the result

| Field                                                               | What it tells you                                                                                                                                                               |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`                                                            | The state of this analysis: `PROCESSING`, `FAILED`, `COMPLETE` (ready to review), or `CONFIRMED` (reviewed and accepted).                                                       |
| `documentInformation.trust.type`                                    | The trust type. `detected` is what the analyzer classified from the deed; `provided` reflects a type you supplied ahead of time, if any.                                        |
| `trustees`, `settlors`                                              | The core trust roles. Each entry points to an entity in one of the `linked*` maps by its `entityId`.                                                                            |
| `linkedIndividuals`, `linkedOrganizations`, `linkedUnknownEntities` | The extracted parties, keyed by id. A party that holds more than one role (for example, a settlor who is also an appointor) appears once here and is referenced from each role. |
| `typeInformation`                                                   | Type-specific detail, keyed by the trust type. See [Supported Trust Types](/docs/kyb/trust-analyzer#supported-trust-types) on the overview page.                                |
| `references`                                                        | Maps each extracted value back to where it was found in the deed, including the page number, so every field is traceable to its source.                                         |

### Step 5: Confirm the Analysis

Confirmation is the human sign-off gate: it is how a reviewer accepts the extracted structure for compliance use. To correct any extracted field, send the corrected `documentInformation` (and any updated `references`) in the request body; to accept the analysis as-is, send it back unchanged.

Confirmation records your accepted version while keeping the original analysis as an audit trail, so you always retain what the analyzer originally produced alongside what was approved. You can confirm again later if something needs to change: the latest confirmation becomes the valid one and earlier confirmations are superseded, while the original analysis stays in place.

Confirm against the original analysis (the entry with `status: COMPLETE`) returned by Step 4.

<CodeGroup>
  ```bash Request - Confirm Analysis theme={null}
  curl --location 'https://api.uat.frankie.one/v2/organizations/{{entityId}}/documents/{{documentId}}/analyses/{{analysisId}}/confirm' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
  --header 'Content-Type: application/json' \
  --data '{
      "documentInformation": {
          "type": "TRUST_DOCUMENT",
          "trust": {
              "name": { "value": "The Doe Family Trust" },
              "type": { "detected": "DISCRETIONARY" },
              "trustees": [ { "entityId": "org-1", "entityType": "ORGANIZATION" } ],
              "settlors": [ { "entityId": "ind-1", "entityType": "INDIVIDUAL" } ]
          }
      }
  }'
  ```

  ```json Response - Confirm Analysis theme={null}
  {
      "requestId": "01HN9XHZN6MGXM9JXG50K59Q85"
  }
  ```
</CodeGroup>

Once confirmed, the workflow execution's result moves from `REVIEW` to `COMPLETE` — the organization no longer reads as work in progress once a reviewer has signed off.

### Step 6: Associate the Parties

With a confirmed analysis in hand, link the extracted parties to the focus organization through the [relationships API](/api-reference/organization-relationships/add-or-update-relationships-for-an-organization). This attaches the trustees, settlors, beneficiaries, and other parties to the organization as `individual` and `organization` relationships, so the trust's structure is represented on the entity and available to the rest of your KYB process.

***

## Next Steps

* [Trust Analyzer overview](/docs/kyb/trust-analyzer) — what the Trust Analyzer does, supported trust types, and FAQs.
* [Executing Workflows](/docs/kyb/executing-workflows) — how `executionVariables` are passed when executing a workflow.
* [Interpreting Workflow Results](/docs/kyb/interpreting-workflows-v2) — parse the full `workflowResult` object.
* [Managing Organizations](/docs/kyb/managing-organizations) — create and manage the organization entity before running the workflow.
* [Anti-Money Laundering](/docs/kyb/anti-money-laundering) — screen the parties extracted from the trust deed.


# US Business Verification
Source: https://docs.frankieone.com/docs/kyb/us-business-verification

A step-by-step guide to verifying US-registered businesses, including Secretary of State filing records and business officers.

## Overview

FrankieOne verifies US-registered businesses against authoritative US sources, returning Secretary of State filing records, the business's registered jurisdiction, and its officers.

US verification is triggered automatically by the address country — you do not need to select a different workflow or endpoint. When you create an organization with a US address, the platform routes the verification to the appropriate US data source, and the enriched data is written back onto the same organization entity.

The flow is the same four steps used for any KYB verification:

<Steps>
  <Step title="1. Create the organization">
    Submit the business's name, address and EIN to create the entity.
  </Step>

  <Step title="2. Execute a workflow">
    Run `GLB-Organization-Profile` against the returned `entityId`.
  </Step>

  <Step title="3. Poll for the result">
    Workflows run asynchronously — poll until the execution completes.
  </Step>

  <Step title="4. Get the enriched organization">
    Retrieve the organization to see the verified registration data.
  </Step>
</Steps>

***

## Implementation Guide

### Prerequisites

Before you begin, ensure you have:

* An account configured with a US-enabled KYB workflow.
* API credentials — your `api_key` and `X-Frankie-CustomerId`.
* Your `X-Frankie-CustomerChildID`, if your account is structured with child customer accounts. This header is optional; include it on every request when you need to act on behalf of a specific child account, and omit it otherwise.
* Confirmation from your Customer Success Manager that US jurisdiction support is enabled on your account.

<Note>
  The examples in this guide show the `api_key` and `X-Frankie-CustomerId` headers only. If you use child customer accounts, add `X-Frankie-CustomerChildID` to each request as well.
</Note>

### Step 1: Create a US organization

To create a US-based organization, submit at least one address with `country: "USA"` in your `POST /v2/organizations` request. US verification is triggered automatically based on the address country.

#### Request Body Fields

| Field                                                                       | Required | Description                                                 | Example                                                           |
| --------------------------------------------------------------------------- | -------- | ----------------------------------------------------------- | ----------------------------------------------------------------- |
| `organization.addresses[]`                                                  | Yes      | At least one business address, with `country` set to `USA`. | `{"country":"USA","longForm":"1100 Maple Dr, Phoenix, AZ 85001"}` |
| `organization.details.name.name`                                            | Yes      | Legal registered business name.                             | `"Acme Corp"`                                                     |
| `organization.jurisdictionalInformation.taxpayerIdentificationNumber.value` | Yes      | The business's EIN.                                         | `"55-5666777"`                                                    |
| `serviceName`                                                               | Yes      | Selects the service profile to assess against.              | `"DEFAULT"`                                                       |

#### Request

<CodeGroup>
  ```bash Request - Create US Organization theme={null}
  curl --location 'https://api.uat.frankie.one/v2/organizations' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
  --header 'Content-Type: application/json' \
  --data '{
      "organization": {
          "addresses": [
              { "country": "USA", "longForm": "1100 Maple Dr, Phoenix, AZ 85001" }
          ],
          "details": {
              "name": { "name": "Acme Corp" }
          },
          "jurisdictionalInformation": {
              "taxpayerIdentificationNumber": { "value": "55-5666777" }
          }
      },
      "serviceName": "DEFAULT"
  }'
  ```
</CodeGroup>

#### Response

A successful request returns `201 Created`.

<CodeGroup>
  ```json Response - 201 Created theme={null}
  {
      "organization": {
          "addresses": [
              {
                  "addressId": "019f3ba1-6b80-7b40-996d-a9ae88292a1b",
                  "country": "USA",
                  "longForm": "1100 Maple Dr, Phoenix, AZ 85001",
                  "sourceId": "725e6311-4b23-4be2-924a-c350bd004d03",
                  "status": "CURRENT",
                  "type": "BUSINESS"
              }
          ],
          "createdAt": "2026-07-07T08:11:02Z",
          "details": {
              "name": { "name": "Acme Corp", "sourceId": "725e6311-4b23-4be2-924a-c350bd004d03", "type": "PRIMARY" }
          },
          "entityId": "019f3ba1-6b80-7b29-8d39-b9f1fdc28db7",
          "entityType": "ORGANIZATION",
          "informationSources": {
              "725e6311-4b23-4be2-924a-c350bd004d03": {
                  "provider": "MANUAL",
                  "source": "Unknown",
                  "isAuthoritative": false
              }
          },
          "jurisdictionalInformation": {
              "taxpayerIdentificationNumber": { "value": "55-5666777", "sourceId": "725e6311-4b23-4be2-924a-c350bd004d03" }
          },
          "schemaVersion": 2
      },
      "requestId": "01KWXT2THHWJ2EWPY7G6KQKRMY",
      "serviceProfiles": [
          {
              "entityId": "019f3ba1-6b80-7b29-8d39-b9f1fdc28db7",
              "serviceName": "DEFAULT",
              "serviceProfileId": "5cfdade0-71c7-4c7a-b348-2a53959a9caa",
              "state": "INIT"
          }
      ]
  }
  ```
</CodeGroup>

<Note>
  At this point, `informationSources` reflects only what you submitted — `provider` is `MANUAL` and `isAuthoritative` is `false`. Each entry is keyed by a generated `sourceId`, one per data source contributing to the record. Verified registration data is added once you run the workflow in Step 2.
</Note>

Retain the `entityId` from the response — you need it for every subsequent call.

### Step 2: Execute the workflow

Run the `GLB-Organization-Profile` workflow against the organization's `entityId`.

#### Request

<CodeGroup>
  ```bash Request - Execute Workflow theme={null}
  curl --location 'https://api.uat.frankie.one/v2/organizations/workflows/GLB-Organization-Profile/execute' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
  --header 'Content-Type: application/json' \
  --data '{
      "entityId": "019f3ba1-6b80-7b29-8d39-b9f1fdc28db7",
      "serviceName": "DEFAULT"
  }'
  ```
</CodeGroup>

#### Response

<CodeGroup>
  ```json Response - Workflow Started theme={null}
  {
      "entityId": "019f3ba1-6b80-7b29-8d39-b9f1fdc28db7",
      "requestId": "01KWXT2VG40KSG1X0RKBJHPKZF",
      "serviceName": "DEFAULT",
      "serviceProfileId": "5cfdade0-71c7-4c7a-b348-2a53959a9caa",
      "workflowExecutionId": "01KWXT2WH7TZEZ6987AE9VB1TN"
  }
  ```
</CodeGroup>

Retain the `workflowExecutionId` — you need it to poll for the result.

### Step 3: Poll for results

Workflow executions run asynchronously. Poll for the execution status using the `workflowExecutionId` returned in Step 2.

#### Request

<CodeGroup>
  ```bash Request - Get Workflow Execution theme={null}
  curl --location 'https://api.uat.frankie.one/v2/organizations/{entityId}/serviceprofiles/DEFAULT/workflows/GLB-Organization-Profile/executions/{workflowExecutionId}' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID'
  ```
</CodeGroup>

#### Response

<CodeGroup>
  ```json Response - Execution Complete theme={null}
  {
      "workflowResult": {
          "workflowExecutionId": "01KWXT2WH7TZEZ6987AE9VB1TN",
          "workflowExecutionState": "COMPLETED",
          "status": "COMPLETE"
      }
  }
  ```
</CodeGroup>

`workflowResult.workflowExecutionState` tells you whether the execution has finished:

| State         | Meaning                                                                |
| ------------- | ---------------------------------------------------------------------- |
| `IN_PROGRESS` | Still running — keep polling every few seconds.                        |
| `COMPLETED`   | Finished. Retrieve the enriched organization and verification results. |
| `CANCELED`    | Canceled before completion.                                            |
| `TERMINATED`  | Terminated before completion.                                          |
| `ERROR`       | Encountered an error.                                                  |
| `TIMEOUT`     | Timed out.                                                             |

<Warning>
  Check both fields. `workflowExecutionState` reports whether the execution finished; `workflowResult.status` carries the verification outcome (`COMPLETE`, `REVIEW`, `PASS`, `FAIL`, and others). A `COMPLETED` execution can still return an outcome such as `REVIEW` that requires a closer look.
</Warning>

### Step 4: Get the enriched organization

Once the workflow completes, retrieve the organization to see the verified data that has been added to it.

#### Request

<CodeGroup>
  ```bash Request - Get Organization theme={null}
  curl --location 'https://api.uat.frankie.one/v2/organizations/{entityId}' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID'
  ```
</CodeGroup>

#### Response

<CodeGroup>
  ```json Response - Enriched Organization theme={null}
  {
      "organization": {
          "addresses": [
              { "addressId": "019f3ba1-6b80-7b40-996d-a9ae88292a1b", "country": "USA", "longForm": "1100 Maple Dr, Phoenix, AZ 85001", "status": "CURRENT", "type": "BUSINESS" },
              { "addressId": "019f3ba1-7c0a-76ec-bafc-25dcf3e12294", "country": "USA", "longForm": "1000 Elm St, Atlanta, GA 30301", "subdivision": "GA", "type": "OTHER" }
          ],
          "details": {
              "jurisdiction": { "country": "USA", "subdivision": "GA" },
              "name": { "name": "Acme Corp", "type": "PRIMARY" },
              "registrationDetails": [
                  {
                      "registeredName": { "name": "Acme Corp" },
                      "registeredSubdivision": "GA",
                      "registrationNumber": "FN-XXXXXXX",
                      "registrationStatus": { "unstructured": { "code": "GOOD_STANDING", "description": "Active-Good Standing" } },
                      "registry": "SOS",
                      "registryDescription": "https://ecorp.sos.ga.gov/BusinessSearch"
                  }
              ],
              "status": { "unstructured": { "code": "GOOD_STANDING", "description": "Active-Good Standing" } }
          },
          "entityId": "019f3ba1-6b80-7b29-8d39-b9f1fdc28db7",
          "informationSources": {
              "d76b9d14-3661-484d-83d0-cc45ca86688e": { "provider": "<provider>", "isAuthoritative": true, "providerReference": "d1ce51c7-8f1b-4182-ae6d-bc14c7c1f167" }
          },
          "officials": [
              { "entityId": "c8a78d65-a4b4-4471-90c3-12370b0e11cc", "entityType": "INDIVIDUAL", "role": { "code": "CE", "description": "CEO" }, "title": "CEO" }
          ]
      }
  }
  ```
</CodeGroup>

#### What Verification Adds

| Field                           | What It Contains                                                                                                                                                                                                      |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `details.jurisdiction`          | The state in which the business is registered, as `country` and `subdivision`.                                                                                                                                        |
| `details.registrationDetails[]` | The Secretary of State filing record — registered name, subdivision, registration number, status, and a link to the state registry. `registry` is `SOS`.                                                              |
| `details.status`                | The business's overall standing, for example `GOOD_STANDING`.                                                                                                                                                         |
| `officials[]`                   | The business's officers, each with an `entityId`, `role` code and `title`.                                                                                                                                            |
| `informationSources`            | Gains an entry with `isAuthoritative: true` and a `providerReference`, alongside the original `MANUAL` entry. The `provider` value identifies the verifying data source — shown as `<provider>` in the example above. |
| `addresses[]`                   | May gain additional addresses discovered during verification, distinguished by `type`.                                                                                                                                |

<Note>
  Officers returned in `officials[]` are created as `INDIVIDUAL` entities. You can run individual KYC checks against them using their `entityId`.
</Note>

***

## Next Steps

Once verification has completed, parse the `workflowResult` object to understand the outcome of every check.

For a complete breakdown of every field in the response, see **[Interpreting Workflow Results](/docs/kyb/interpreting-workflows-v2)**.

***

## Additional Resources

* [Standard Workflows](/docs/kyb/standard-kyb-bundles)
* [Executing a Workflow](/docs/kyb/executing-workflows)
* [Error Handling](/docs/kyb/error-handling)
* [FrankieOne Support](/docs/contacting-developer-support)


# Integrating with OneSDK
Source: https://docs.frankieone.com/docs/kyc-v2/features/idv-biometrics-onesdk

Learn how to integrate FrankieOne's IDV and Biometrics services using the FrankieOne SDK (OneSDK) for a streamlined and efficient implementation.

## Introduction to OneSDK

The FrankieOne SDK (OneSDK) is the recommended solution for integrating IDV and Biometrics services into your web and mobile applications. It is designed to simplify the implementation process by abstracting the complexities of direct API interactions and providing pre-built UI components to guide your users through the verification process.

**Why Use the OneSDK?**

* **Simplified Integration:** The SDK reduces development time by handling the low-level API calls for session creation, data submission, and result polling.
* **Seamless User Experience:** Pre-built UI components ensure a consistent and intuitive user journey for document capture and biometric authentication.
* **Enhanced Data Accuracy:** The SDK includes optimized workflows for capturing high-quality document images and biometric data, which improves verification success rates.
* **Robust Error Management:** Built-in error handling and reporting mechanisms simplify troubleshooting and enhance the reliability of your integration.
* **Continuous Updates and Support:** The SDK is actively maintained by FrankieOne, ensuring compatibility with the latest features, security standards, and provider updates.

***

## Implementation Steps

Integrating the OneSDK involves a four-step process: obtaining a session token from your backend, initializing the SDK on your frontend, presenting the UI to the user, and handling the results.

<Steps>
  <Step title="1. Obtain a Session Token">
    Before initializing the OneSDK on your client-side application, you must securely fetch a session token from your backend. This requires a server-to-server call to the FrankieOne authentication endpoint. **Never expose your API Key in frontend code.**

    ```javascript theme={null}
    // Example: Server-side code (Node.js) to fetch a session token
    import fetch from 'node-fetch';

    const CUSTOMER_ID = 'YOUR_CUSTOMER_ID';
    const API_KEY = 'YOUR_API_KEY';
    const AUTH_ENDPOINT = '[https://backend.kycaml.uat.frankiefinancial.io/auth/v2/machine-session](https://backend.kycaml.uat.frankiefinancial.io/auth/v2/machine-session)';

    async function fetchSessionToken() {
      try {
        const response = await fetch(AUTH_ENDPOINT, {
          method: 'POST',
          headers: {
            'authorization': 'machine ' + Buffer.from(`${CUSTOMER_ID}:${API_KEY}`).toString('base64'),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            permissions: {
              preset: 'one-sdk',
              reference: "your-unique-customer-reference", // A unique reference for the user session
            },
          }),
        });

        if (!response.ok) {
          console.error('Failed to fetch session token:', response.status);
          return null;
        }

        return await response.json();
      } catch (error) {
        console.error('Error fetching session token:', error);
        return null;
      }
    }
    ```
  </Step>

  <Step title="2. Initialize OneSDK">
    In your frontend application, use the session token obtained in the previous step to initialize the OneSDK. You can also configure the SDK with a "recipe" to define the specifics of the verification flow, such as the number of documents to capture.

    ```javascript theme={null}
    // Example: Client-side code to initialize OneSDK
    import OneSDK from '@frankieone/one-sdk';

    async function initializeOneSdk() {
      // This function should call your backend to get the session token
      const sessionTokenResult = await yourBackend.fetchSessionToken();

      if (sessionTokenResult && sessionTokenResult.session) {
        const oneSdk = await OneSDK({
          session: sessionTokenResult,
          mode: "production", // or "sandbox"
          recipe: {
            ocr: {
              maxDocumentCount: 3,
            },
          },
        });
        return oneSdk;
      } else {
        console.error('Failed to initialize OneSDK due to missing session token.');
        return null;
      }
    }
    ```
  </Step>

  <Step title="3. Present the Verification UI">
    Once the SDK is initialized, you can call its methods to launch the pre-built user interface. This UI will guide the user through all the necessary steps, such as selecting their document type, taking photos, and completing the selfie/liveness check.
  </Step>

  <Step title="4. Handle Verification Events and Results">
    The SDK emits events throughout the verification process. Your application should listen for these events to track the user's progress and handle the final outcome. Implement callbacks to manage success, error, or user cancellation scenarios. Please refer to the detailed OneSDK documentation for a complete list of events and how to handle them.
  </Step>
</Steps>

***

## Service Flows Handled by the SDK

By using the OneSDK, you abstract away the complexity of the underlying service flows. The SDK seamlessly manages:

* **Document Capture and Validation:** Ensures high-quality images are captured and submitted for analysis.
* **Selfie Capture and Facial Comparison:** Guides the user through the selfie process and matches it against the document photo.
* **Liveness Detection:** Verifies that the user is physically present, preventing spoofing attempts.
* **Integration with IDV Providers:** Manages all communication with the underlying IDV and Biometrics vendors.


# Reseller Checks with Experian AU
Source: https://docs.frankieone.com/docs/kyc-v2/implementation-guide/experian-reseller-abn

If you perform Experian AU credit header checks on behalf of another reporting entity, that entity's ABN needs to be supplied with each check. This guide shows how to pass the ABN via the individual's custom attributes.

## Overview

Some customers act as a **reseller** — they run KYC checks on behalf of another business, and that business (not the reseller) is the AML/CTF reporting entity for the check.

Experian AU requires the ABN of that end business to be supplied with every credit header check, so the enquiry can be attributed to the correct obligated entity. FrankieOne collects this ABN as a custom attribute on the individual and forwards it to Experian as `AMLObligatedEntityABN`.

<Info>
  This applies only to **Experian AU credit header checks** performed through the
  Experian v2 connector. It has no effect on other data sources, and it is not
  needed by customers who are the reporting entity for their own checks.
</Info>

***

## Enabling the feature

Reseller ABN passthrough is enabled by FrankieOne on a per-configuration basis. Enabling it does two things:

* Makes the `CustomerChannelReferenceIdentifier` custom attribute visible and mandatory in the FrankieOne Portal, so the ABN can be captured for profiles created manually.
* Makes the attribute **required** for API-created entities — a check submitted without it fails validation before it reaches Experian.

<Callout icon="star">
  Contact [help@frankieone.com <Icon icon="arrow-up-right-from-square" />](mailto:help@frankieone.com)
  to have reseller ABN passthrough turned on for your configuration. Until it has
  been enabled, the attribute is stored on the entity but not forwarded to Experian.
</Callout>

***

## Supplying the ABN

Set a custom attribute named `CustomerChannelReferenceIdentifier` on the individual, with the end business's ABN as the value.

The attribute can be set when [creating the individual](/docs/managing-individuals) or added later with an update — it simply needs to be present on the entity at the time the workflow runs.

```http HTTP Request theme={null}
POST /v2/individuals
```

```json JSON Request Body theme={null}
{
  "individual": {
    "name": {
      "givenName": "Jane",
      "familyName": "Citizen"
    },
    "dateOfBirth": {
      "year": "1992",
      "month": "08",
      "day": "15"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "streetNumber": "123",
        "streetName": "Exhibition",
        "streetType": "Street",
        "locality": "Melbourne",
        "subdivision": "VIC",
        "postalCode": "3000",
        "country": "AUS"
      }
    ],
    "customAttributes": {
      "CustomerChannelReferenceIdentifier": {
        "type": "STRING",
        "value": "11111111111"
      }
    },
    "consents": [
      {
        "type": "GENERAL"
      },
      {
        "type": "CREDITHEADER"
      }
    ]
  }
}
```

### Field reference

| Field          | Value                                | Notes                                                                                                                   |
| :------------- | :----------------------------------- | :---------------------------------------------------------------------------------------------------------------------- |
| Attribute name | `CustomerChannelReferenceIdentifier` | Case-sensitive — it needs to match exactly.                                                                             |
| `type`         | `STRING`                             | The ABN is sent to Experian as a string.                                                                                |
| `value`        | The end business's ABN               | 11 digits, no spaces. This is the ABN of the business the check is being performed **for**, not the reseller's own ABN. |

<Callout icon="bell">
  Credit header consent is still required for Experian AU checks. The reseller
  ABN is in addition to — not a replacement for — the `CREDITHEADER` consent.
  See [Creating & Managing Individuals](/docs/managing-individuals#consents).
</Callout>

***

## What FrankieOne sends to Experian

The attribute is forwarded in the request payload as an additional detail:

```xml theme={null}
<RequestData>
  <AdditionalDetail>
    <DetailName>AMLObligatedEntityABN</DetailName>
    <Detail>11111111111</Detail>
  </AdditionalDetail>
</RequestData>
```

The value sent is also recorded against the check in the audit trail.

***

## Behaviour when the ABN is missing

| Configuration                     | Attribute supplied? | Result                                                                                               |
| :-------------------------------- | :------------------ | :--------------------------------------------------------------------------------------------------- |
| Reseller passthrough **enabled**  | Yes                 | ABN forwarded to Experian as `AMLObligatedEntityABN`.                                                |
| Reseller passthrough **enabled**  | No                  | The check fails validation. No request is sent to Experian, and no credit header result is produced. |
| Reseller passthrough **disabled** | Either              | The attribute is ignored and nothing is forwarded.                                                   |

<Callout icon="thumbtack">
  Because a missing ABN stops the check before it reaches Experian, set the
  attribute on the entity **before** executing the workflow. See
  [Error Handling](/docs/error-handling) for how validation failures are surfaced.
</Callout>


# Single Name Handling
Source: https://docs.frankieone.com/docs/kyc-v2/implementation-guide/single-name-verification

Learn how to correctly format API requests to verify individuals with a single name (mononym) against various data sources, including the Australian DVS.

## Overview

In many cultures, it is common for an individual to have only a single name (a mononym). The FrankieOne platform supports these cases, but correct data mapping is crucial as requirements vary significantly between different types of verification checks.

This guide will walk you through the correct API implementation for handling single-name applicants to ensure successful verification and global compliance.

***

## General API Implementation

The recommended approach for submitting a single name via the API is to populate the `familyName` and use a placeholder for the `givenName`.

<Info>
  **Why this approach?** `familyName` is the only name field the API requires — `givenName` is optional. Many downstream data sources also have a mandatory requirement for a `familyName` or "Last Name" field. Placing the single name here ensures the request is valid and gives the highest compatibility across our network of data sources.
</Info>

```json theme={null}
{
  "individual": {
    "name": {
      "givenName": "-",
      "familyName": "Sukarno"
    }
  }
}
```

Do not submit the single name in `givenName` with an empty or omitted `familyName` — `familyName` is required, so the request will be rejected. If you have an existing integration that places the single name in `givenName` and a placeholder in `familyName`, it will still be accepted, but we recommend migrating to the format above: the critical factor is meeting the requirements of the specific end data source you are checking against, and most require a populated family name.

***

## Verification Compatibility

Support for single-name verification is **not universal**. It depends entirely on the rules of the end data source. Submitting a single name to an unsupported service will result in a "No Match" or an error.

| Verification Type                    | Single Name Support     | Notes                                                                                                                                     |
| :----------------------------------- | :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
| **Credit Bureau Checks**             | ⚠️ **Partial**          | Support for single names varies. While some checks will succeed, others require both a first and last name and will fail.                 |
| **Government ID Checks (DVS)**       | ✅ **Yes (Conditional)** | Support depends on the document type. See [Australian DVS Formatting Rules](#australian-dvs-formatting-rules) below.                      |
| **Australian Electoral Roll Checks** | ❌ **No**                | This service requires both a first and last name and will not process a single-name entry.                                                |
| **Superannuation & Payroll Checks**  | ❌ **No**                | These services have mandatory first and last name fields with no available workaround.                                                    |
| **Other KYC & AML Checks**           | **Varies**              | Compatibility depends on the specific check and region. We recommend following the standard `familyName` + hyphenated `givenName` format. |

***

## Australian DVS Formatting Rules

The Australian Document Verification Service (DVS) matches the name you submit against the name held by the issuing authority. Because DVS is an exact-match service, a single name will only verify where the document itself records the individual under a single name.

The general convention across all DVS document types is to place the single name in `familyName` and submit a placeholder in `givenName`:

* Use a hyphen (`-`) as the `givenName` placeholder. This is the default and the format we recommend.
* A full stop (`.`) is accepted as an alternative where a provider prefers it.
* FrankieOne normalises the placeholder before the request reaches DVS, submitting a blank given name rather than the literal `-` or `.` character.

| Document Type                     | `givenName` | `familyName`                                           | Notes                                                                                                                                              |
| :-------------------------------- | :---------- | :----------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Australian Passport**           | `-` or `.`  | The single name                                        | Supported. The placeholder is converted to a blank given name before the check is sent.                                                            |
| **ImmiCard** (`IMMIGRATION`)      | `-`         | The single name, exactly as printed on the card        | Supported. Match the card's case, spelling and spacing exactly.                                                                                    |
| **Driver's Licence**              | `-`         | The single name, exactly as printed on the licence     | Follows the general convention. The licence record itself must hold a single name.                                                                 |
| **National Health ID (Medicare)** | `-`         | The single name, exactly as printed on the card        | Follows the general convention. The `supplementaryData.nameOnCardLine*` fields must also match the card as printed.                                |
| **Birth Certificate**             | `-`         | The single name                                        | Follows the general convention. Apply the same convention to `supplementaryData.registeredGivenName` and `supplementaryData.registeredFamilyName`. |
| **Citizenship Certificate**       | `-`         | The single name, exactly as printed on the certificate | Follows the general convention.                                                                                                                    |
| **Centrelink Card**               | `-`         | The single name, exactly as printed on the card        | Follows the general convention.                                                                                                                    |
| **Marriage Certificate**          | `-`         | The single name                                        | Follows the general convention. Apply the same convention to the `supplementaryData.partner1*` and `supplementaryData.partner2*` name fields.      |
| **Name Change Certificate**       | `-`         | The single name                                        | Follows the general convention. Apply the same convention to `supplementaryData.registeredGivenName` and `supplementaryData.registeredFamilyName`. |

<Callout icon="bell">
  A single name will return a **No Match** if the issuing authority holds the individual under both a given and a family name. In that case, submit the name as it is recorded on the document rather than as a mononym.
</Callout>

For the full field-by-field requirements of each document type, see [Australian Documents](/docs/australian-documents-v2).


# Working With Addresses
Source: https://docs.frankieone.com/docs/kyc/feature-guides/concepts-and-definitions/addresses



## Key Requirements

<CardGroup>
  <Card title="Address ID Required for Updates" icon="id-card">
    When updating an existing address, always include the `addressId`. You can
    retrieve it from the `addresses` array in the entity response.
  </Card>

  <Card title="Country Code Required" icon="globe">
    The `country` field is mandatory and must use ISO 3166-1 alpha-3 codes
    (e.g., `AUS`, `USA`, `GBR`).
  </Card>
</CardGroup>

## V2 Address Model: What's Changed

The v2 address schema introduces two key structural changes from v1:

**1. `type` + `status` replaces `addressType`**

In v1, address purpose and history were encoded in a single `addressType` field
(e.g., `RESIDENTIAL1`, `RESIDENTIAL2`). In v2, these are separated:

* `type` — what kind of address it is (e.g., `RESIDENTIAL`, `POSTAL`)
* `status` — the temporal state of that address (`CURRENT`, `PREVIOUS`, `FUTURE`)

**2. Field names align to global address standards**

| v1 Field      | v2 Field       | Notes                                                |
| ------------- | -------------- | ---------------------------------------------------- |
| `addressType` | `type`         | See `Address-TypeEnum` below                         |
| `town`        | `locality`     | Town, suburb, village, or city                       |
| `suburb`      | `neighborhood` | Only needed when suburb differs from locality        |
| `state`       | `subdivision`  | Use ISO 3166-2 sub-division code (e.g., `VIC`, `TX`) |
| `region`      | `district`     | District, county, province, or cantonment            |

***

## Address Types

The `type` field accepts the following values:

| Value                       | Description                                                 |
| --------------------------- | ----------------------------------------------------------- |
| `RESIDENTIAL`               | Personal residential address                                |
| `POSTAL`                    | Individual mailing address                                  |
| `BUSINESS`                  | Business address                                            |
| `REGISTERED_OFFICE`         | Registered office address                                   |
| `PLACE_OF_BUSINESS`         | Principal place of business                                 |
| `OFFICIAL_CORRESPONDANCE`   | Business postal/mailing address                             |
| `PLACE_OF_BIRTH`            | Place of birth                                              |
| `OFFICE_LOCALITY`           | Office locality                                             |
| `AUTHORITATIVE_RESIDENTIAL` | Authoritative residential address returned by a data source |
| `OTHER`                     | Any other address type                                      |

Use `type` in conjunction with `status` to express address history. For example,
a current home address is `type: RESIDENTIAL, status: CURRENT`. A previous home
address is `type: RESIDENTIAL, status: PREVIOUS`.

<Callout icon="bell">
  The v1 `RESIDENTIAL1` / `RESIDENTIAL2` pattern is not used in v2. Use
  `RESIDENTIAL` with `status: CURRENT` or `PREVIOUS` instead.
</Callout>

***

## Address Status

The `status` field must be used alongside `type` to indicate the temporal state
of the address.

| Value      | Description                           |
| ---------- | ------------------------------------- |
| `CURRENT`  | The address is currently in use       |
| `PREVIOUS` | The address was used in the past      |
| `FUTURE`   | The address is planned for future use |

***

## Address Structure Options

### Option 1: Structured Address (Recommended)

<Callout icon="star">
  Providing structured address components produces better matching results and
  improved data quality than long-form input.
</Callout>

<AccordionGroup>
  <Accordion title="Address Field Reference">
    | Field          | Type   | Required     | Description                                                                             |
    | -------------- | ------ | ------------ | --------------------------------------------------------------------------------------- |
    | `addressId`    | string | For updates  | Assigned when an address is added. Must be included when modifying an existing address. |
    | `type`         | string |              | Address type. See `Address-TypeEnum`.                                                   |
    | `status`       | string |              | Address status: `CURRENT`, `PREVIOUS`, or `FUTURE`. Use with `type`.                    |
    | `unitNumber`   | string |              | Unit, apartment, flat, or suite number                                                  |
    | `buildingName` | string |              | Name of the building, apartment block, or condominium                                   |
    | `streetNumber` | string |              | Property number on the street. Can be alphanumeric (e.g., `3A`)                         |
    | `streetName`   | string |              | Name of the street. See note below on `addressLine1` input.                             |
    | `streetType`   | string |              | Street type (e.g., `Road`, `Street`, `Ave`, `Circuit`)                                  |
    | `locality`     | string |              | Town, village, suburb, or city                                                          |
    | `neighborhood` | string |              | Suburb or neighborhood — only supply if you also need a separate `locality` value       |
    | `subdivision`  | string |              | State or administrative sub-division. Use ISO 3166-2 code (e.g., `VIC`, `TX`)           |
    | `district`     | string |              | District, county, province, or cantonment                                               |
    | `postalCode`   | string |              | Postal or ZIP code                                                                      |
    | `country`      | string | **Required** | ISO 3166-1 alpha-3 country code (e.g., `AUS`, `USA`, `GBR`)                             |
    | `careOf`       | string |              | Individual or business at this address, if different from the entity name               |
    | `validFrom`    | Date   |              | Date this address first became active. Used primarily with business addresses.          |
    | `validTo`      | Date   |              | Date this address was no longer in use. Used primarily with business addresses.         |
  </Accordion>

  <Accordion title="Structured Address Example (AUS)">
    ```json theme={null}
        {
          "addresses": [
            {
              "type": "RESIDENTIAL",
              "status": "CURRENT",
              "unitNumber": "1",
              "streetNumber": "100",
              "streetName": "South",
              "streetType": "ST",
              "locality": "Sydney",
              "subdivision": "NSW",
              "postalCode": "2000",
              "country": "AUS"
            }
          ]
        }
    ```
  </Accordion>

  <Accordion title="Update Address Example (AUS)">
    When updating an existing address, include `addressId` to target the correct record.

    ```json theme={null}
        {
          "addresses": [
            {
              "addressId": "<existing-address-id>",
              "type": "RESIDENTIAL",
              "status": "CURRENT",
              "streetNumber": "123",
              "streetName": "King",
              "streetType": "Street",
              "locality": "Melbourne",
              "subdivision": "VIC",
              "postalCode": "3000",
              "country": "AUS"
            }
          ]
        }
    ```
  </Accordion>
</AccordionGroup>

***

### Option 2: Long-Form Address

<Info>
  Use this format only when structured address components are not available.
  The API will attempt to parse `longForm` into its constituent fields.
  Results are not guaranteed — ambiguous or unparsable addresses will return
  an error.
</Info>

```json theme={null}
{
  "addresses": [
    {
      "type": "RESIDENTIAL",
      "status": "CURRENT",
      "country": "AUS",
      "longForm": "LEVEL 8, 417 ST KILDA ROAD, MELBOURNE, VIC, 3004"
    }
  ]
}
```

***

## Using `streetName` for Combined Address Input

If your system stores street details in a single field (commonly called
`addressLine1`, e.g., `"42 Main Street"`), place the full value in `streetName`.
The `streetName` field can accommodate combined address elements when discrete
fields are unavailable.

<Callout icon="thumbtack">
  For best matching results, provide `streetNumber`, `streetName`, and
  `streetType` as separate fields wherever possible.

  * ✅ **Preferred:** `streetNumber: "42"`, `streetName: "Main"`, `streetType: "Street"`
  * ⚠️ **Acceptable fallback:** `streetName: "42 Main Street"` (combined `addressLine1` value)
</Callout>

***

## Read-Only Response Fields

The following address fields are returned in API responses but cannot be set
in request payloads:

| Field                  | Description                                                                                |
| ---------------------- | ------------------------------------------------------------------------------------------ |
| `addressId`            | Assigned by FrankieOne when an address is first created                                    |
| `sourceId`             | Links to the `informationSources` map — indicates which data source populated this address |
| `unstructuredLongForm` | Raw, unformatted address as received from the source. Not normalised or standardised.      |

***

## Additional Resources

<Card title="ISO Country Codes Reference" icon="globe" href="https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes">
  View the complete list of ISO 3166-1 alpha-3 country codes <Icon icon="arrow-up-right-from-square" />
</Card>


# Key Concepts
Source: https://docs.frankieone.com/docs/kyc/feature-guides/concepts-and-definitions/core-api-concepts

An overview of the fundamental building blocks of the FrankieOne platform, such as Entities, Workflows, and Risk Assessments.

This guide introduces the primary building blocks of the FrankieOne platform. Understanding these core concepts is the first step toward a successful integration.

For details on specific data structures like addresses and consent, see the [Key Data Objects](/docs/kyc/feature-guides/concepts-and-definitions/key-data-objects) page. For a full list of terms, visit the [Glossary](/docs/kyc/feature-guides/concepts-and-definitions/glossary-of-terms).

## Platform Building Blocks

These are the fundamental concepts that power the FrankieOne platform. Click on any concept to learn more.

<AccordionGroup>
  <Accordion title="Entity">
    An **Entity** is the central object in the FrankieOne platform, representing a single customer you want to verify. All information, checks, and results are linked to an entity.

    * An **Individual** is an entity type representing a single person.
    * An **Organization** is an entity type representing a business or other non-individual entity.
  </Accordion>

  <Accordion title="Workflow">
    A **Workflow** is a configurable, end-to-end process that runs a sequence of steps to verify an entity. You can design workflows to meet your specific risk and compliance requirements. A workflow is composed of steps such as KYC verifications, AML screening, IDV checks, and risk assessments.
  </Accordion>

  <Accordion title="Service Profile">
    A **Service Profile** provides an overview of an entity's verification progress and risk status in the context of a specific product or service you offer. A single entity can have multiple service profiles, allowing you to apply different rules and risk policies for different products (e.g., a credit card vs. a home loan).
  </Accordion>

  <Accordion title="Process Result">
    A **Process Result** is the raw, granular data returned from a single check against a third-party data source (e.g., a match for a name from a government database). A workflow step evaluates one or more process results to determine its outcome.
  </Accordion>

  <Accordion title="Risk Assessment">
    FrankieOne uses granular **Risk** metrics to calculate a customer's risk profile. During a workflow, an entity is scored against configurable risk factors (e.g., age, location, PEP status). The cumulative score determines the entity's overall risk level, which can trigger different actions like Enhanced Due Diligence (EDD).
  </Accordion>

  <Accordion title="Issue">
    An **Issue** is a problem raised during a workflow that requires manual review or intervention. Issues are created for significant events, such as a failed KYC check or a match on a sanctions watchlist, and provide clear guidance on the next steps.
  </Accordion>
</AccordionGroup>

<Info>
  ##### How The Concepts Connect

  A typical verification process follows this logical flow:

  1. You create an **Entity** representing your customer.
  2. You assign a **Service Profile** to the Entity for the product they are accessing.
  3. You trigger a **Workflow** to begin verification.
  4. The Workflow runs checks, generating **Process Results** from data sources.
  5. A **Risk Assessment** is performed based on the results.
  6. If problems occur, an **Issue** is created for review.
</Info>

***

## Technical Architecture

The FrankieOne API is built using the **REST (Representational State Transfer)** architectural style. This provides a simple, predictable, and scalable interface for interacting with all platform resources.

By adopting REST, FrankieOne ensures that its API is flexible and easy to learn. All communication is performed over secure HTTPS using standard HTTP methods (like `GET`, `POST`, `PATCH`) and clear, resource-oriented URLs. This unified approach allows you to interact with different parts of the platform in a consistent way, supporting robust automation and integration with your systems.


# Key Terms & Definitions
Source: https://docs.frankieone.com/docs/kyc/feature-guides/concepts-and-definitions/glossary-of-terms



## Glossary A-Z

A quick reference for other common terms.

| Term               | Explanation                                                                                                                                                                                                                              |
| :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Adverse Media      | Negative news or information about an individual or entity found in reputable media sources.                                                                                                                                             |
| AML                | **A**nti-**M**oney **L**aundering. Laws and procedures designed to combat the generation of income through illegal actions.                                                                                                              |
| AML Classification | The process of categorizing AML screening results, often involving manual review to determine if a potential match is a true positive or false positive.                                                                                 |
| AML Screening      | The process of checking an individual or entity against global watchlists, sanctions lists, and PEP lists.                                                                                                                               |
| Audit              | A record of actions performed within the platform, used for tracking and compliance purposes.                                                                                                                                            |
| Consent            | Permission given by an individual for their information to be checked against various databases and external services.                                                                                                                   |
| Decision           | A critical juncture in the workflow that determines the workflow's status—be it PASS, FAIL, or REVIEW, based on the specific actions taken during the workflow.                                                                          |
| Entity             | A single individual or organization within the FrankieOne platform that exists separately from other entities. Entities house information about the individual or organization, primarily any personally identifiable information (PII). |
| IDV                | **I**dentity **V**erification. The process of verifying an identity, often involving document scans, liveness checks, and facial comparison.                                                                                             |
| Individual         | A single person who can be verified within the FrankieOne platform. Individuals can have service profiles, workflows, and risk assessments related to them.                                                                              |
| Issue              | A problem encountered during the execution of a workflow that hinders its successful completion and necessitates manual intervention.                                                                                                    |
| KYC                | **K**now **Y**our **C**ustomer. The mandatory process of identifying and verifying the identity of clients to prevent fraud and financial crime.                                                                                         |
| Organization       | A business or non-individual entity that can be verified within the FrankieOne platform.                                                                                                                                                 |
| PEP                | **P**olitically **E**xposed **P**erson. An individual with a prominent public function, who may present a higher risk for potential bribery or corruption.                                                                               |
| Process Result     | A granular piece of information used to determine the outcome of an action or step performed during a workflow.                                                                                                                          |
| Risk               | Granular risk metrics used to determine a customer's risk profile and identify potential money laundering activities. Entities are scored on these risk factors during workflow execution.                                               |
| Sanctions          | Economic or trade restrictions imposed on specific individuals, entities, or countries by governments or international bodies.                                                                                                           |
| Service Profile    | Provides a concise overview of an entity's progress within the context of a specific product or service. These profiles encompass various risk levels, workflows, and statuses.                                                          |
| Watchlist          | A list of individuals or entities subject to scrutiny under AML and sanctions regulations.                                                                                                                                               |
| Workflow           | An end-to-end process that involves a series of steps that, when triggered, will enrich or verify stored entity information. Workflows are customizable and can be built to satisfy compliance requirements.                             |
| Workflow Step      | A specific action or check within a workflow, such as KYC verification, AML screening, or risk assessment.                                                                                                                               |


# Key Data Objects
Source: https://docs.frankieone.com/docs/kyc/feature-guides/concepts-and-definitions/key-data-objects

These are the critical data structures you will work with when using the FrankieOne API.

This guide details the primary data objects used in FrankieOne API requests and responses. Understanding these structures is essential for sending data correctly and interpreting the verification results.

<AccordionGroup>
  <Accordion title="👤 Address">
    An **Address** object contains the location details for an entity. Providing a complete, structured address is critical for successful verification against data sources.

    <Callout icon="thumbtack">
      Best Practices for Address Data

      For optimal verification results, always provide addresses using **structured fields** rather than the `longForm` string. Supplying each component—such as `streetNumber`, `streetName`, `locality`, and `country`—enables more accurate matching and validation.

      * **Break down addresses:** Always separate address components into their individual fields wherever possible. While `streetName` can combine `streetNumber`, `streetName`, and `streetType` if needed, providing each field separately yields the most accurate results.
      * **Address types:**
        * `RESIDENTIAL`: The primary address used to determine the entity’s country of residence and current living address.
        * `POSTAL`: A mailing address. If a `RESIDENTIAL` address is not provided, this will be used as the default residential address.
      * **Address status:** Use the `status` field to indicate if the address is current or future. This helps in understanding the context of the address.
      * **Updating addresses:** Always include the `addressId` (returned when the address was first added) to ensure the correct record is modified.
      * **Country codes:** Ensure the `country` field is a valid ISO-3166-1 alpha-3 code ([reference](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)).
      * **Building details:** Include any building details, such as building level, in the `buildingName` field.
    </Callout>

    #### Common Address Fields

    | Field Name        | Description                                                                                                                                                                             | Type          | Required |
    | :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------- |
    | `addressId`       | Unique identifier for the address (used for updates).                                                                                                                                   | String        | No       |
    | `country`         | The **ISO-3166-1 alpha-3** country code (e.g., `AUS`).                                                                                                                                  | String        | Yes      |
    | `type`            | The type of address, e.g., `RESIDENTIAL`, `POSTAL`. Determines how the address is used in verification.                                                                                 | String (enum) | Yes      |
    | `typeDescription` | A description of the address for reference.                                                                                                                                             | String        | No       |
    | `unitNumber`      | Unit, apartment, flat, or suite number.                                                                                                                                                 | String        | No       |
    | `streetNumber`    | The number on the street (can be alphanumeric, e.g., `3A`).                                                                                                                             | String        | No       |
    | `streetName`      | The name of the street.                                                                                                                                                                 | String        | Yes      |
    | `streetType`      | The street type, e.g., Road, St, Ave, Circuit.                                                                                                                                          | String        | No       |
    | `buildingName`    | The name of the building, apartment block, or condo. Include building level details here.                                                                                               | String        | No       |
    | `locality`        | The locality, town, village, suburb, or city.                                                                                                                                           | String        | Yes      |
    | `district`        | The district, region, county, or province.                                                                                                                                              | String        | No       |
    | `neighborhood`    | The neighborhood or suburb. Use only if `locality` is already captured and additional detail is needed.                                                                                 | String        | No       |
    | `subdivision`     | The administrative area, state, or subdivision. Abbreviations (e.g., "VIC") and full names (e.g., "Victoria") are acceptable.                                                           | String        | No       |
    | `postalCode`      | The postal or zip code.                                                                                                                                                                 | String        | Yes      |
    | `careOf`          | Name of the individual or business at this address, if different from the entity's name.                                                                                                | String        | No       |
    | `longForm`        | The full address as a single string. Use only if breaking down the address is not possible. If the separate fields are supplied, `longForm` will not be used when sending to providers. | String        | No       |
    | `status`          | The status of the address (e.g., `PREVIOUS`, `CURRENT`, `FUTURE`). Should be used together with `TYPE` to provide more context.                                                         | String (enum) | No       |
    | `validFrom`       | The date when the entity started using this address.                                                                                                                                    | Date          | No       |
    | `validTo`         | The date when the entity will stop using this address.                                                                                                                                  | Date          | No       |

    <Callout icon="thumbtack">
      ##### Maximum Lengths for NZ Addresses

      For New Zealand addresses, the following maximum lengths are recommended:

      * **Address line 1** (building name + unit number + street name + street type): 256 characters
      * **Address line 2** (distinct to Frankie): 256 characters
      * **Suburb**: 50 characters
      * **City**: 50 characters
      * **Postcode**: 15 characters
    </Callout>
  </Accordion>

  <Accordion title="📝 Consent">
    The **Consent** object is a mandatory part of any verification request. It confirms that you have permission from the user to perform the specified checks. The type of consent required depends on the data sources you intend to use.

    #### Common Consent Types

    | Consent Flag     | Description                                                                                                  |
    | :--------------- | :----------------------------------------------------------------------------------------------------------- |
    | `GENERAL`        | The user has consented to standard name, address, and date of birth checks.                                  |
    | `DOCS`           | The user has consented to having their identity documents (e.g., passport) checked against official sources. |
    | `CREDITHEADER`   | The user has consented to having their details checked against a credit bureau. This is a premium feature.   |
    | `UNDER18`        | A parent or guardian has provided consent for a user who is under 18 years of age.                           |
    | `PAYROLL`        | This consent is used to allow access to verifying an identity using payroll data.                            |
    | `INSURANCE`      | This consent is used to allow access to verifying an identity using workcover data.                          |
    | `SUPERANNUATION` | This consent is used to allow access to verifying an identity using superannuation data.                     |
  </Accordion>

  <Accordion title="🪪 Document">
    A **Document** object represents a piece of identification provided by the user, such as a passport, driver's license, or utility bill.

    <Callout icon="thumbtack">
      ##### Document Class Guidance

      When creating a document object, set the `class` field to `IDENTITY` for documents used to verify a person's identity (such as passports or driver's licenses). This ensures the document is processed correctly for identity verification checks.
    </Callout>

    #### Common Document Fields

    | Field Name            | Description                                                                          |
    | :-------------------- | :----------------------------------------------------------------------------------- |
    | `documentId`          | The unique identifier for the document object within FrankieOne.                     |
    | `type`                | The general type of document, such as `DRIVERS_LICENSE`, `PASSPORT`, `UTILITY_BILL`. |
    | `subtype`             | A more specific description of the document type.                                    |
    | `primaryIdentifier`   | The main number on the document (e.g., license number or passport number).           |
    | `secondaryIdentifier` | Any additional identifier on the document.                                           |
    | `country`             | The **ISO-3166-1 alpha-3** country code where the document was issued.               |
    | `expiryDate`          | The document's expiration date.                                                      |
    | `issueDate`           | The document's date of issue.                                                        |
  </Accordion>

  <Accordion title="❗ Issue">
    An **Issue** is created by a workflow whenever a potential problem is detected that may require manual review. Your system should be designed to handle these issues, often by flagging the case for a compliance officer.

    #### Key Issue Fields

    | Field Name  | Description                                                                 |
    | :---------- | :-------------------------------------------------------------------------- |
    | `issueId`   | The unique identifier for the issue.                                        |
    | `category`  | The general category of the issue (e.g., `AML`, `DUPLICATE`, `DOCUMENT`).   |
    | `issue`     | The specific type of issue (e.g., `SANCTION`, `DATA_COMPARISON`).           |
    | `severity`  | The severity level, such as `INFO`, `REVIEW`, or `BLOCK`.                   |
    | `isCleared` | A boolean indicating if the issue has been manually resolved in the Portal. |
  </Accordion>

  <Accordion title="⚖️ Risk Assessment">
    The **Risk Assessment** object is returned as part of a `workflowResult` and contains the calculated risk profile for the entity based on your configured policies.

    #### Key Risk Fields

    | Field Name    | Description                                                                              |
    | :------------ | :--------------------------------------------------------------------------------------- |
    | `riskLevel`   | The overall risk level assigned to the entity, such as `LOW`, `MEDIUM`, or `HIGH`.       |
    | `riskScore`   | The numerical score that corresponds to the risk level.                                  |
    | `riskFactors` | An array of the specific factors that contributed to the score (e.g., `age`, `country`). |
  </Accordion>

  <Accordion title="🚦 Result & Status Codes">
    Interpreting the status of a verification is critical. The API provides results at both the overall **workflow** level and for each individual **step**.

    #### Common Workflow Statuses (`workflowResult.status`)

    This tells you the final outcome of the entire verification process.

    | Status    | Meaning                                                                                         |
    | :-------- | :---------------------------------------------------------------------------------------------- |
    | `PASS`    | The workflow completed and the entity passed all required checks.                               |
    | `FAIL`    | The workflow completed and the entity did not pass the required checks.                         |
    | `REVIEW`  | The workflow produced results that require manual review. Check the `issues` array for details. |
    | `BLOCKED` | The workflow was blocked from completing, often due to a blocklist match.                       |

    #### Common Step Results (`workflowStepResults[].result`)

    This tells you the outcome of a specific check within the workflow.

    | Result     | Meaning                                                                                                         |
    | :--------- | :-------------------------------------------------------------------------------------------------------------- |
    | `MATCH`    | The check was successful and found a positive match.                                                            |
    | `NO_MATCH` | The check was successful but did not find a matching record.                                                    |
    | `HIT`      | A match was found against a watchlist (e.g., AML or fraud). This is a positive outcome that requires attention. |
    | `CLEAR`    | No match was found against a watchlist. This is a positive outcome.                                             |
    | `ERROR`    | The step could not be completed due to a system or provider error.                                              |
  </Accordion>
</AccordionGroup>

***


# Understanding Issues
Source: https://docs.frankieone.com/docs/kyc/feature-guides/concepts-and-definitions/kyc-issue-creation



A guide to the types of issues that can arise during KYC workflows and how to handle them.

> ***Note:***\
> *In the FrankieOne v2.0.0 API, an “issue” is a fundamental concept used to communicate problems, errors, or specific outcomes that require attention. Issues can arise from simple input validation errors to complex workflow results that require manual review.*

***

## The Structure of an Issue

<AccordionGroup>
  <Accordion title="Core Issue Object">
    An issue is typically represented as an Issue object, which contains details about what went wrong and where. While the exact structure can vary slightly depending on the context (e.g., a synchronous API error vs. a workflow result), it generally contains the following key fields:

    | Field         | Type   | Description                                                                 |
    | :------------ | :----- | :-------------------------------------------------------------------------- |
    | issue         | string | Human-readable description of the problem                                   |
    | issueLocation | string | Context/location where the issue was identified (e.g., `VALIDATE-entityId`) |
    | issueType     | string | *(Optional)* Category for the issue                                         |

    **Example: 400 Bad Request Error Response**

    ```json theme={null}
    {
      "errorCode": "API-0400",
      "errorMsg": "Multiple Errors: See Issues list",
      "details": [
        {
          "issue": "entityId in path must be of type uuid: \"test\"",
          "issueLocation": "VALIDATE-entityId"
        }
      ],
      "requestId": "01HM5XJ7VASZ3EJMB1VQGTBFJ4"
    }
    ```
  </Accordion>
</AccordionGroup>

***

## How Issues are Created

<AccordionGroup>
  <Accordion title="Direct API Error Responses">
    Synchronous errors occur when an API request cannot be fulfilled due to issues like invalid authentication, malformed requests, or server-side problems. The API returns a standard Error object with a relevant HTTP status code (e.g., 400, 401, 500).

    | Field     | Description                                            |
    | :-------- | :----------------------------------------------------- |
    | errorCode | Unique FrankieOne code for the error (e.g., AUTH-0002) |
    | errorMsg  | Summary of the error (e.g., Unauthorized)              |
    | details   | Array of Issue objects detailing each problem          |

    **Common Error Scenarios:**

    * **400 Bad Request:** Validation errors (e.g., malformed entityId)
    * **401 Unauthorized:** Missing or invalid api\_key
    * **404 Not Found:** Resource does not exist
    * **5xx Server Error:** Internal platform issues
  </Accordion>

  <Accordion title="Workflow Execution Results">
    When a workflow runs, the platform performs a series of checks. If any check produces a result that requires attention, a Workflow-Issue object is generated and included in the workflow execution summary.

    | Field     | Type    | Description                                                    |
    | :-------- | :------ | :------------------------------------------------------------- |
    | issueId   | string  | Unique identifier for the issue                                |
    | category  | string  | Broad classification (e.g., AML, KYC, FRAUD, DOCUMENT)         |
    | issue     | string  | Specific issue type (e.g., SANCTION, NOT\_FOUND)               |
    | severity  | string  | Severity level (INFO, REVIEW, BLOCK, WARNING, CRITICAL, ERROR) |
    | isCleared | boolean | Indicates if the issue has been manually addressed/resolved    |
    | createdAt | string  | Timestamp when the issue was created                           |

    **Example: Workflow-Execution-Summary with an Issue**

    ```json theme={null}
    {
      "workflowName": "kyc_onboarding",
      "workflowExecutionId": "01HNE42K1T6JXV41S8W5W8W6X8",
      "status": "REVIEW",
      "issues": [
        {
          "issueId": "01HNE42K2G4S8Z6G8Y4Y7B3A2C",
          "category": "AML",
          "issue": "SANCTION",
          "severity": "CRITICAL",
          "isCleared": false,
          "createdAt": "2024-05-15T02:18:11.365Z"
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Issue Severity Levels

| Severity | Description                                          |
| :------- | :--------------------------------------------------- |
| INFO     | Informational only, no action required               |
| REVIEW   | Requires manual review before proceeding             |
| BLOCK    | Blocks workflow completion until resolved            |
| WARNING  | Indicates a potential problem, but not blocking      |
| CRITICAL | Serious issue, typically blocks onboarding           |
| ERROR    | Error state, usually requires technical intervention |

***

## Workflow Issue Categories

<Accordion title="Issue Categories">
  This table lists the general categories that an issue can fall under.

  | Category      | Description                                                                 |
  | :------------ | :-------------------------------------------------------------------------- |
  | AML           | Anti-Money Laundering issues.                                               |
  | BAD\_DATA     | Indicates that the data provided is invalid or incorrect.                   |
  | BIOMETRICS    | Issues found during a biometrics check.                                     |
  | BLOCKLISTED   | The entity has a hit on a blocklist.                                        |
  | DECEASED      | Indicates that the entity is deceased.                                      |
  | DEVICE        | Issues found during device checks.                                          |
  | DOCUMENT      | Issues found during a document check.                                       |
  | DUPLICATE     | Indicates that the entity has duplicates.                                   |
  | EXPIRY        | Indicates that a process or document for the entity has expired.            |
  | FRAUD         | Possible fraud detected.                                                    |
  | IDV           | Issues found during an Identity Verification (IDV) process.                 |
  | INFORMATIONAL | Informational messages that are not issues but are required to be returned. |
  | KYC           | Issues found during a Know Your Customer (KYC) process.                     |
  | SYSTEM        | System-level issues.                                                        |
  | VERIFY        | Issues found during a verification process.                                 |
  | VISA          | Issues found during a visa check.                                           |
  | WATCHLIST     | Issues found during a watchlist check.                                      |
  | ACTIVITY      | Issues found during an activity process.                                    |
</Accordion>

***

## Workflow Issue Types & Descriptions

<AccordionGroup>
  <Accordion title="AML & Watchlist">
    | Issue Type      | Description                                           |
    | :-------------- | :---------------------------------------------------- |
    | PEP             | The entity has Politically Exposed Person (PEP) hits. |
    | SANCTION        | The entity has sanction hits.                         |
    | MEDIA           | The entity has adverse media hits.                    |
    | WATCHLIST       | The entity has watchlist hits.                        |
    | INTERNAL\_MATCH | The entity matched an internal watchlist.             |
    | AML\_ISSUE      | General AML issue.                                    |
  </Accordion>

  <Accordion title="Bad Data">
    | Issue Type                | Description                                        |
    | :------------------------ | :------------------------------------------------- |
    | BAD\_DATA\_NAME           | Name is required but missing or unusable.          |
    | BAD\_DATA\_DOB            | Date of Birth is required but missing or unusable. |
    | BAD\_DATA\_ADDRESS        | Address is required but missing or unusable.       |
    | BAD\_DATA\_ID             | ID is required but missing or unusable.            |
    | BAD\_DATA\_EMAIL          | Email is required but missing or unusable.         |
    | BAD\_DATA\_MOBILE         | Mobile is required but missing or unusable.        |
    | BAD\_DATA\_DEVICE         | Device is required but missing or unusable.        |
    | BAD\_DATA\_IP\_ADDRESS    | IP Address is required but missing or unusable.    |
    | BAD\_DATA\_EMAIL\_ADDRESS | Email Address is required but missing or unusable. |
  </Accordion>

  <Accordion title="Blocklist">
    | Issue Type        | Description                               |
    | :---------------- | :---------------------------------------- |
    | MATCHED\_INTERNAL | The entity matched an internal blocklist. |
    | MATCHED\_SHARED   | The entity matched a shared blocklist.    |
    | MATCHED\_EXTERNAL | The entity matched an external blocklist. |
    | BLOCKED           | General blocklist issue.                  |
  </Accordion>

  <Accordion title="Deceased">
    | Issue Type | Description                                          |
    | :--------- | :--------------------------------------------------- |
    | DECEASED   | The person whose data is being verified is deceased. |
  </Accordion>

  <Accordion title="Device & Fraud">
    | Issue Type            | Description                     |
    | :-------------------- | :------------------------------ |
    | DEVICE\_FRAUD\_MATCH  | Fraud detected on the device.   |
    | DEVICE\_INVALID       | The device is invalid.          |
    | FRAUD\_LIST           | The entity is on a fraud list.  |
    | FRAUD\_CHECK          | Fraud detected during checks.   |
    | FRAUD\_DEVICE         | Device fraud detected.          |
    | FRAUD\_IP\_ADDRESS    | IP address fraud detected.      |
    | FRAUD\_EMAIL\_ADDRESS | Email address fraud detected.   |
    | FRAUD\_PHONE\_NUMBER  | Phone number fraud detected.    |
    | FRAUD\_INCOMPLETE     | The fraud check was incomplete. |
    | FRAUD\_ISSUE          | General fraud issue.            |
  </Accordion>

  <Accordion title="Duplicate">
    | Issue Type | Description                                  |
    | :--------- | :------------------------------------------- |
    | DUPLICATE  | The entity is a duplicate of another entity. |
  </Accordion>

  <Accordion title="Expiry">
    | Issue Type     | Description                            |
    | :------------- | :------------------------------------- |
    | REQUIRES\_KYC  | KYC process needs to be re-initiated.  |
    | REQUIRES\_IDV  | IDV process needs to be re-initiated.  |
    | REQUIRES\_AML  | AML process needs to be re-initiated.  |
    | REQUIRES\_VISA | Visa process needs to be re-initiated. |
  </Accordion>

  <Accordion title="Identity & Document Verification (IDV)">
    | Issue Type            | Description                                               |
    | :-------------------- | :-------------------------------------------------------- |
    | DATA\_COMPARISON      | Data comparison issue.                                    |
    | DATA\_VALIDATION      | Data validation issue.                                    |
    | DATA\_CONSISTENCY     | Data consistency issue.                                   |
    | VISUAL\_AUTHENTICITY  | Visual authenticity issue.                                |
    | IMAGE\_INTEGRITY      | Image integrity issue.                                    |
    | COMPROMISED\_DOCUMENT | Document is compromised.                                  |
    | LIVENESS\_DETECTION   | Liveness detection failed.                                |
    | DOCUMENT\_COMPARISON  | Document comparison issue.                                |
    | OCR                   | The OCR data does not match what was entered by the user. |
  </Accordion>

  <Accordion title="Informational">
    | Issue Type     | Description                                                              |
    | :------------- | :----------------------------------------------------------------------- |
    | CREDIT\_HEADER | Credit header information was returned as part of a credit agency check. |
  </Accordion>

  <Accordion title="KYC">
    **<u>KYC Summary Issue Codes</u>**

    | Issue Type | Description                                  | Condition                                                                       |
    | :--------- | :------------------------------------------- | ------------------------------------------------------------------------------- |
    | PARTIAL    | The KYC check was only partially successful. | Some data matched, but the total results were insufficient to pass the ruleset. |
    | NOT\_FOUND | No match was found for the given data.       | The overall KYC ruleset requirements were not satisfied.                        |

    **<u>KYC Detailed Issue Codes</u>**

    | Issue Type                   | Description                                | Condition                                                                                       |
    | :--------------------------- | :----------------------------------------- | ----------------------------------------------------------------------------------------------- |
    | NO\_GOVID\_MATCH             | GovID required but no GovID match.         | A Government ID was required, but no match was found in the system.                             |
    | INSUFFICIENT\_GOVID\_MATCH   | GovID required but insufficient matches.   | Government ID matches were found, but they did not meet the required count.                     |
    | NO\_DOB\_MATCH               | DOB required but no DOB match.             | A Date of Birth check was required, but no match was found.                                     |
    | INSUFFICIENT\_DOB\_MATCH     | DOB required but insufficient matches.     | Date of Birth matches were found, but they are below the required threshold.                    |
    | NO\_ADDRESS\_MATCH           | Address required but no address match.     | An Address check was required, but no match was found.                                          |
    | INSUFFICIENT\_ADDRESS\_MATCH | Address required but insufficient matches. | Address matches were found, but they did not meet the full verification requirements.           |
    | NO\_NAME\_MATCH              | Name required but no name match.           | A Name check was required, but no match was found.                                              |
    | INSUFFICIENT\_NAME\_MATCH    | Name required but insufficient matches.    | Name matches were found, but they were fewer than the ruleset requires.                         |
    | PARTIAL\_MATCH               | General partial match.                     | Multiple fields were verified successfully, but the overall verification resulted in a failure. |

    <Callout icon="thumbtack">
      For more information on how these conditions are evaluated and configured, please refer to the [KYC Ruleset](https://docs.frankieone.com/docs/ekyc-rulesets) page.
    </Callout>
  </Accordion>

  <Accordion title="System">
    | Issue Type       | Description                                                             |
    | :--------------- | :---------------------------------------------------------------------- |
    | SERVICE\_TIMEOUT | All providers have timed out.                                           |
    | SERVICE\_ERROR   | All providers have returned an error or an internal error has occurred. |
  </Accordion>

  <Accordion title="Visa">
    | Issue Type   | Description                          |
    | :----------- | :----------------------------------- |
    | DENY\_LIST   | The entity matched a visa deny list. |
    | VISA\_FAILED | Visa check failed from the provider. |
  </Accordion>

  <Accordion title="Activity">
    | Issue Type       | Description                    |
    | :--------------- | :----------------------------- |
    | ACTIVITY\_AML    | AML-related activity issue.    |
    | ACTIVITY\_FRAUD  | Fraud-related activity issue.  |
    | ACTIVITY\_DEVICE | Device-related activity issue. |
  </Accordion>
</AccordionGroup>

***

## Workflow Issue Severity Levels

<Callout icon="thumbtack">
  Severity levels help determine the urgency and impact of an issue. Use them to drive workflow logic and user experience.
</Callout>

| Severity | Description                |
| :------- | :------------------------- |
| INFO     | Informational only.        |
| REVIEW   | Requires review.           |
| BLOCK    | Blocks further processing. |
| WARNING  | Warning, but not blocking. |
| CRITICAL | Critical issue.            |
| ERROR    | Error encountered.         |

***

## Best Practices for Handling Issues

* **Monitor the`issues` array** in workflow results to drive automated decisions or flag cases for manual review.
* **Map`issueLocation`** to specific fields in your UI for targeted feedback.
* **Use`severity`** to determine whether to block, warn, or allow user progression.
* **Log`issueId` and `requestId`** for troubleshooting and support.

> ***Tip:***\
> *By building logic around issues, you can streamline compliance, automate onboarding, and improve user experience.*

***


# Creating & Managing Individuals
Source: https://docs.frankieone.com/docs/managing-individuals

A guide to the complete lifecycle of an 'individual' entity, from creation and retrieval to updates and deletion.

The `individual` is the core object in the FrankieOne platform, representing a single customer. This guide covers the complete lifecycle of creating and managing these entities via the API.

### Video Guide

<iframe />

***

## 1. Creating an Individual

To begin any verification, you must first create an `individual` entity. This is done by sending a `POST` request with the customer's details to the `/v2/individuals` endpoint. A successful request will return a `201 Created` status and the full `individual` object, including a unique `entityId`.

<Callout icon="bell">
  ##### Warning: Capture the entityId

  The `entityId` returned in the response is critical for all subsequent operations, such as updating the entity or executing a workflow.
</Callout>

### Example: Creating a Standard Individual

This example shows a standard request to create an individual with their name, date of birth, address, and a passport document.

```http HTTP Request theme={null}
POST /v2/individuals
```

```json JSON Request Body theme={null}
{
  "individual": {
    "name": {
      "givenName": "Jane",
      "familyName": "Citizen"
    },
    "gender": {
      "gender": "FEMALE"
    },
    "dateOfBirth": {
      "year": "1992",
      "month": "08",
      "day": "15"
    },
    "nationality": "AUS",
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "streetNumber": "123",
        "streetName": "Exhibition",
        "streetType": "Street",
        "locality": "Melbourne",
        "subdivision": "VIC",
        "postalCode": "3000",
        "country": "AUS"
      }
    ],
    "documents": {
      "IDENTITY": [
        {
          "type": "PASSPORT",
          "primaryIdentifier": "E1234567",
          "country": "AUS",
          "attachments": [
            {
              "filename": "passport.jpg",
              "mimeType": "image/jpeg",
              "side": "FRONT",
              "data": {
                "base64": "R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
              }
            }
          ]
        }
      ]
    },
    "consents": [
      {
        "type": "GENERAL"
      },
      {
        "type": "DOCS"
      }
    ]
  }
}
```

### Anatomy of the `individual` Object

The `individual` object is a rich structure that holds all the information about your customer. Below is a breakdown of its key components.

#### Name

The primary legal name of the individual. You can also provide an array of `alternateNames` for other names the individual may be known by (e.g., maiden name).

<Callout icon="thumbtack">
  The primary `name` object is required, and must contain at least a `familyName`. For entries in `alternateNames`, the `familyName` is also the only mandatory field.
</Callout>

#### Date of Birth

The individual's date of birth. The `year`, `month`, and `day` should be provided.

<Callout icon="thumbtack">
  The `normalized` field in the response is read-only. The `type` field is optional and defaults to `GREGORIAN`.
</Callout>

#### Addresses & Place of Birth

An array of address objects. The `country` field (ISO 3166-1 alpha-3) is mandatory for each address. Use `status: 'PREVIOUS'` for past addresses. The `placeOfBirth` object uses the same address structure.

<Callout icon="thumbtack">
  While the `addresses` field is optional, if you include it, the `country` field within each address object is mandatory.

  * Use the `status` field to indicate if the address is `CURRENT` or `PREVIOUS`.
  * Use `type` to specify the address type, such as `RESIDENTIAL` or `BUSINESS`.
  * Both `CURRENT` and `PREVIOUS` addresses can be provided to give a complete picture of the individual's residential history.
</Callout>

#### Phone Numbers & Email Addresses

Arrays of `phoneNumbers` and `emailAddresses` objects to store contact information.

<Callout icon="thumbtack">
  Both `emailAddresses` and `phoneNumbers` are optional. If included, the `type` field is required for each entry. Use `isPreferred: true` to indicate the primary contact method.
</Callout>

#### Documents

An object containing arrays of documents, categorized by their class (e.g., `IDENTITY`, `SUPPORTING`). The `type` and `country` are required for each document.

Each document can have multiple `attachments`. The `data` field, containing the `base64` encoded file, is mandatory for each attachment.

For a full list of document types, refer to the [Country Specific Documents](/docs/v2/kyc/global-kyc-coverage/global-kyc-guide#country-and-document-coverage).

#### Consents

An array of consent objects. This is critical for compliance. You must provide the consent types relevant to the checks you will perform (e.g., `GENERAL`, `DOCS`).

<Callout icon="bell">
  Consult with your AML team and the FrankieOne team to determine the appropriate consent flags for your use case.
</Callout>

For a full list of consent types, refer to the [Consent Types](/docs/key-data-objects).

#### External References

The `externalReferences` array is used to store your own internal identifiers against the FrankieOne entityId. This is crucial for linking a user in your system to their corresponding profile in FrankieOne.

Each object in the array requires a name and a value.

```json Example: Storing an Internal Customer ID theme={null}
    "externalReferences": [  
      {  
        "type": "CUSTOMER", // Can be CUSTOMER, SYSTEM or OTHER  
        "name": "customer-id",  
        "value": "CUST-1138-90210",  
        "description": "The customer's unique identifier in our core banking system."  
      }  
    ]
```

##### `externalReferences`with`type = "ACCOUNT"`

When using FrankieOne Fraud and Transaction Monitoring, external references with type `ACCOUNT` are used to link an individual to their financial accounts. See [TM Implementation Guide — The detail object](/v2/docs/tm/implementation) for how this data is used during activity evaluation.

* The reference represents an account (for example, a bank account, wallet, loan, or trading account).
* The `value` field should contain your account ID.
* The `metadata`object holds account details (such as status and product type), which are copied into the [**activity evaluation**](/v2/docs/tm/implementation) when account enrichment is enabled for your configuration and `partyAccount` matches this reference.

#### Custom Attributes

Custom attributes on an individual entity are a flexible key-value object for storing any additional data relevant to your business that doesn't fit into the other standard fields. These attributes are stored on the entity profile, are visible in the FrankieOne Portal, and can be used as criteria in an individual's risk profile configuration.

**Note:** The activity evaluation API also accepts a separate `customAttributes` object under the `detail` object. That field passes context-specific data at the time of evaluation for use in custom rules. See [TM Implementation Guide — The detail object](/v2/docs/tm/implementation) for details.

```json theme={null}
{
  "customAttributes": {
    "accountTier": {
      "type": "STRING",
      "value": "premium"
    },
    "annualIncome": {
      "type": "NUMBER",
      "value": "95000"
    }
  }
}
```

#### Other Fields

* `gender`: The individual’s gender (e.g., `MALE`, `FEMALE`, `NON_BINARY`).
* `nationality`: The individual’s nationality as an ISO 3166-1 alpha-3 code.

***

## 2. Retrieving an Individual

To fetch the current state of an individual entity, use a `GET` request with their unique `entityId`.

```HTTP HTTP theme={null}
  GET /v2/individuals/{entityId}  
```

The response will contain the full `individual` object, identical in structure to the response from the creation request.

***

## 3. Updating an Individual

To modify an existing individual, use a `PATCH` request. This method allows for partial updates, meaning you only need to send the fields you wish to change.

<Callout icon="star">
  To update a specific element within an array (like an address or document), you must include its unique ID (e.g., `addressId`, `documentId`) in the object you send.
</Callout>

**Example:**

* **Updating an Address** This example updates an existing address by providing its `addressId` and the new field values.

````HTTP HTTP theme={null}
     PATCH /v2/individuals/{entityId}  
     ```json JSON  
     {  
       "individual": {  
         "addresses": [  
           {  
             "addressId": "adr_01HBH9XJ4Z5Y6W7R8S9T0V1A2C",  
             "postalCode": "3001"  
           }  
        ]  
      }  
    }  
````

***

## 4. Deleting an Individual & Its Elements

You can delete an entire entity or just specific pieces of information associated with it.

<Danger icon="warning">
  ##### Deletion is Permanent

  Deleting an entity or its elements is an irreversible action. This data cannot be recovered. Only perform deletions when you are certain the data is no longer required for any operational, audit, or compliance purpose.
</Danger>

### Deleting an Entire Individual

To permanently remove an individual and all their associated data, use the `DELETE` endpoint with their `entityId`.

```HTTP HTTP theme={null}
  DELETE /v2/individuals/{entityId}  
```

### Deleting Specific Elements

To remove a specific piece of information without deleting the whole entity, use the corresponding endpoint from the table below. You will need the unique ID for the element you wish to delete.

| Element to Delete   | Endpoint                                                                              |
| :------------------ | :------------------------------------------------------------------------------------ |
| Name                | `DELETE /v2/individuals/{entityId}/names/{nameId}`                                    |
| Date of Birth       | `DELETE /v2/individuals/{entityId}/datesOfBirth/{dateOfBirthId}`                      |
| Address             | `DELETE /v2/individuals/{entityId}/addresses/{addressId}`                             |
| Email Address       | `DELETE /v2/individuals/{entityId}/emailaddresses/{emailAddressId}`                   |
| Phone Number        | `DELETE /v2/individuals/{entityId}/phonenumbers/{phoneNumberId}`                      |
| Document            | `DELETE /v2/individuals/{entityId}/documents/{documentId}`                            |
| Document Attachment | `DELETE /v2/individuals/{entityId}/documents/{documentId}/attachments/{attachmentId}` |
| External Reference  | `DELETE /v2/individuals/{entityId}/externalreferences/{referenceId}`                  |
| Consent             | `DELETE /v2/individuals/{entityId}/consents/{consentType}`                            |


# Manual KYC Verification (mKYC)
Source: https://docs.frankieone.com/docs/manual-kyc-checks

A step-by-step guide to verifying an entity that has completed an in-person or offline identity check.

## What is Manual KYC?

Manual KYC (mKYC) is the process of verifying a customer's identity using physical documents that are sighted and confirmed by an authorised representative (e.g., during a face-to-face meeting).

This guide explains how to use the FrankieOne API to record the outcome of a manual verification, ensuring it is correctly reflected in your compliance workflows and audit trails.

## How It Works: The FrankieOne Approach

FrankieOne facilitates mKYC through a simple two-part process that separates the recording of the approval from the verification check itself.

<Steps>
  <Step title="1. Log the Manual Approval via API">
    You make a single API call to create special "Manual" **Process Results** for an entity. This acts as a permanent record that a trusted employee has verified the customer's identity documents in person.
  </Step>

  <Step title="2. Verify via Workflow">
    A dedicated `Manual KYC` step within your configured workflow checks for the existence of these "Manual" Process Results. If they are present and meet your configured policy, the step passes, allowing the entity to proceed through the workflow just like an electronic verification.
  </Step>
</Steps>

***

## Implementation Guide

This guide will walk you through the API calls required to perform a manual KYC verification.

### Prerequisites

Before you begin, ensure you have the following:

1. An existing `entityId` for the individual you want to verify.
2. The entity has all the necessary information and documents (e.g., name, address, date of birth, and document details with `documentId`s) already added to their profile via the API.
3. A workflow has been configured in your FrankieOne instance that includes the **`Manual KYC`** step.

### Step 1: Log the Manual Approval

First, you must log that the manual verification has taken place. You do this by calling the `POST /v2/individuals/{entityId}/results/mkyc` endpoint. This request tells FrankieOne to create the special "Manual" Process Results (PROs) that will be used as evidence in the workflow.

```bash cURL theme={null}
  curl --location 'https://api.frankie.one/v2/individuals/{{entityId}}/results/mkyc' \
  --header 'api_key: {{your_api_key}}' \
  --header 'X-Frankie-CustomerID: {{your_customer_id}}' \
  --header 'Content-Type: application/json' \
  --data '{
      "approvedBy": "Jane Doe (Officer #1234)",
      "approvedDocuments": [
          "doc_01HBFB8W6A7E8F9G0H1J2K3L4M"
      ],
      "comment": {
          "text": "Customer presented passport in person at Melbourne branch."
      }
  }'
```

**Request Body Explained:**

* `approvedBy`: (string) The name or identifier of the person who performed the manual verification. This is crucial for your audit trail.
* `approvedDocuments`: (array of strings) A list of the `documentId`s that were sighted and approved as part of the check.
* `comment`: (object, optional) A comment to add context to the approval.

A successful request will return a `200 OK` response containing the newly created PROs. Note the key fields that identify these as manual results: `providerResult.name` is set to `MANUAL` and `result` is `MATCH`.

### Step 2: Execute the Verification Workflow

With the manual approval logged, you can now execute your standard verification workflow. The `Manual KYC` step in this workflow will automatically detect the PROs created in Step 1 and pass if your configured rules are met.

```bash cURL theme={null}
  curl --location --request POST 'https://api.frankie.one/v2/individuals/{{entityId}}/serviceprofiles/{{serviceName}}/workflows/{{workflowName}}/execute' \
  --header 'api_key: {{your_api_key}}' \
  --header 'X-Frankie-CustomerID: {{your_customer_id}}'
```

In the workflow execution response, you will see the `Manual KYC` step result. Look for `provider: "MANUAL"` and a `result` of `MATCH` or `PASS` to confirm success.

### Configuring the Manual KYC Step

The logic that determines a successful manual verification is defined within the `Manual KYC` workflow step, **not** in the API call. The API call simply logs the evidence (`approvedDocuments`); the workflow step evaluates that evidence against your business rules.

Below is an example of a policy configuration within a workflow step.

```json JSON theme={null}
{
  "requirements": [
    {"name": 1, "dateOfBirth": 1, "primaryPhotographic": 1},
    {"name": 1, "address": 1, "primaryPhotographic": 1},
    {"name": 1, "dateOfBirth": 1, "address": 1, "primaryNonPhotographic": 2},
    {"name": 1, "dateOfBirth": 1, "address": 1, "primaryNonPhotographic": 1, "secondary": 1}
  ],
  "countries": {
    "AUS": [
      {
        "type": "primaryPhotographic",
        "documentTypes": ["DRIVERS_LICENSE", "PASSPORT"]
      },
      {
        "type": "primaryNonPhotographic",
        "documentTypes": ["BIRTH_CERT", "CITIZENSHIP_CERT"]
      },
      {
        "type": "secondary",
        "documentTypes": ["UTILITY_BILL", "BANK_STATEMENT"]
      }
    ]
  }
}
```

In this example, to manually approve an Australian entity, you could satisfy the first requirement by logging an approval with a single `documentId` that corresponds to a `PASSPORT`.

### Invalidating Manual Results

If you need to revert a manual approval (e.g., to perform a new electronic check), you can invalidate all existing manual results for an entity.

Call the `POST /v2/individuals/{entityId}/results/mkyc/invalidate` endpoint. This will mark all existing manual PROs as `MARKED_INVALID`, causing any subsequent `Manual KYC` workflow steps to fail until a new manual approval is logged.

```bash cURL theme={null}
  curl --location --request POST 'https://api.frankie.one/v2/individuals/{{entityId}}/results/mkyc/invalidate' \
  --header 'api_key: {{your_api_key}}' \
  --header 'X-Frankie-CustomerID: {{your_customer_id}}'
```


# Matchlists (Blocklists)
Source: https://docs.frankieone.com/docs/matchlists-checks

Learn how to manage and utilize Matchlists to enhance your KYC processes efficiently.

## What are Matchlists?

Matchlists are a sophisticated tool in the FrankieOne platform designed to screen entities against curated lists of attributes during your KYC process. They are an evolution of traditional blocklists, offering more nuanced classification and control over your risk-based decisioning.

While the primary use case is often for "blocklisting," the Matchlist framework is designed to be flexible, allowing for different actions based on your compliance policies. In the current implementation, **Blocklists** are the first type of Matchlist available.

## How Matchlists Work

The process is integrated directly into the workflow engine, allowing for automated, real-time screening at onboarding.

<Steps>
  <Step title="1. Configure a Matchlist">
    The FrankieOne team will work with you to set up your initial Matchlists. For now, a default "Blocklist" will be created with an action of `BLOCK` and a risk score.
  </Step>

  <Step title="2. Add Entries to the Matchlist">
    You populate your Matchlist with entries via the API. Each entry consists of one or more attributes (e.g., a name, email address, or document number) that you want to screen against.
  </Step>

  <Step title="3. Execute a Workflow with a Matchlist Step">
    When you execute an onboarding workflow, the dedicated **Matchlist Step** will screen the entity's data against the entries in your Matchlist.
  </Step>

  <Step title="4. Review and Classify Hits">
    If a match is found, the workflow will return a `HIT`. Your compliance team can then review the match and classify it (e.g., as a `TRUE_POSITIVE_REJECT` or `FALSE_POSITIVE`) via the API.
  </Step>
</Steps>

***

## Managing Your Matchlist and Its Entries

While you cannot create your own Matchlists yet, you have full control over managing the entries within the lists configured for you by the FrankieOne team.

### Retrieve Your Matchlist Details

Use the `GET /v2/matchlists` endpoint to retrieve the details of the Matchlists created for you. This is how you find the `matchlistName` needed for managing entries.

```http theme={null}
  GET /v2/matchlists
```

### Adding Entries to a Matchlist

You can add entries one by one or in bulk using the `POST /v2/matchlists/{matchlistName}/entries` endpoint. Each entry must contain an array of `attributes`.

```json title="Example: Adding a Batch of Entries" theme={null}
{
  "batchName": "known-fraud-list-q3",
  "entries": [
    {
      "entityId": "ent_01J...",
      "reference": "CASE-12345",
      "reasons": [ "SUSPECTED_FRAUD_EMAIL" ],
      "attributes": [
        { "type": "IND_DISPLAY_NAME", "value": "John Smith" },
        { "type": "EMAIL_ADDRESS", "value": "john.smith.fraud@example.com" }
      ]
    }
  ],
  "comment": { "text": "Added based on fraud report from Tier 2 team." }
}
```

### Preventing Duplicate Entries

To maintain data integrity, the system enforces uniqueness rules. An entry will be rejected if it is a duplicate.

* **By `entityId`**: An entry with the same `entityId` as an existing entry will be rejected.
* **By Attribute Combination**: The system also checks for uniqueness based on specific combinations of attributes, even if no `entityId` is provided.
  * **For Individuals**:
    * `IND_GIVEN_NAME` + `IND_FAMILY_NAME` + `IND_DATE_OF_BIRTH`
    * `DOC_PRIMARY_IDENTIFIER` + `DOC_TYPE`
  * **For Organizations**:
    * `ORG_NAME` + `ORG_REGISTERED_COUNTRY`

***

## Screening and Classifying Results

### The Matchlist Workflow Step

For screening to occur, your workflow must contain a **Matchlist Step**. When this step executes:

* If no match is found, the step `result` is `CLEAR`.
* If a match is found, the step `result` is `HIT`, and a `BLOCKLISTED` issue with `BLOCK` severity is generated.

### Classifying a Match

When a match is found, a compliance officer must review it and classify it using the `PATCH /v2/individuals/{entityId}/results/matchlist` endpoint.

| Manual Status          | Description                                                |
| ---------------------- | ---------------------------------------------------------- |
| `FALSE_POSITIVE`       | The match is incorrect and does not indicate a valid risk. |
| `TRUE_POSITIVE_REJECT` | The match is accurate, and the entity should be rejected.  |

<Callout icon="thumbtack">
  After classifying all hits for an entity, you should **re-run the workflow**. This will re-evaluate the Matchlist step. If all hits have been resolved as `FALSE_POSITIVE`, the step result will change to `CLEARED`, and the `BLOCKLISTED` issue will be removed.
</Callout>

***

## Managing Individual Entries via API

You can perform full CRUD (Create, Read, Update, Delete) operations on the entries within your Matchlists.

| Action               | Endpoint                                                 |
| -------------------- | -------------------------------------------------------- |
| **Retrieve Entries** | `GET /v2/matchlists/{matchlistName}/entries`             |
| **Search Entries**   | `POST /v2/search/matchlists`                             |
| **Modify an Entry**  | `PATCH /v2/matchlists/{matchlistName}/entries/{entryId}` |

<Callout icon="bell">
  Updating Entry Attributes
  You cannot directly update the `attributes` of an existing Matchlist entry. To change an attribute, you must first mark the old entry's `state` as `DELETED` and then create a new entry with the updated attributes.
</Callout>

### Adding and Removing an Entire Entity

You can also manage entries based on an `entityId`.

* **Add Entity**: `POST /v2/matchlists/{matchlistName}/entries/addEntity`
* **Remove Entity**: `PATCH /v2/matchlists/{matchlistName}/entries/removeEntity` (This sets the entry `state` to `DELETED`).

***

## Reference: Reason Codes

When adding an entry to a blocklist, you can provide one or more reason codes to add context for auditing and review.

| Reason Code               | Description                                                   |
| :------------------------ | :------------------------------------------------------------ |
| `SYNTHETIC_ID`            | The identity is suspected to be synthetic.                    |
| `SUSPECTED_FRAUD`         | Fraud is suspected.                                           |
| `SUSPECTED_ID_THEFT`      | Identity theft is suspected.                                  |
| `ID_USED_IN_KNOWN_FRAUD`  | The identity has been used in known fraud incidents.          |
| `ID_THEFT_VICTIM`         | The individual is a known victim of identity theft.           |
| `REQUESTED_BLOCK`         | A block has been requested for this entity.                   |
| `SUSPECTED_FRAUD_ADDRESS` | The address is suspected of being associated with fraud.      |
| `SUSPECTED_FRAUD_EMAIL`   | The email is suspected of being associated with fraud.        |
| `SUSPECTED_FRAUD_PHONE`   | The phone number is suspected of being associated with fraud. |
| `FREQUENT_USE_ADDRESS`    | The address is being used with unusual frequency.             |
| `FREQUENT_USE_EMAIL`      | The email is being used with unusual frequency.               |
| `FREQUENT_USE_PHONE`      | The phone number is being used with unusual frequency.        |
| `SUSPECTED_MONEY_MULE`    | The individual is suspected of being a money mule.            |
| `NON_PAYMENT`             | Non-payment is the reason for adding the entity.              |

## Configurable Attributes for Matchlist Checks

You can use any of the following attributes to create rules for matchlist checking:

| Entry Attribute Type           | Notes                                   |
| :----------------------------- | :-------------------------------------- |
| ENTITY\_TYPE                   | Maps to entity profile                  |
| EMAIL\_ADDRESS                 | Direct mapping to email object          |
| EMAIL\_DOMAIN                  | Part of email object                    |
| PHONE\_NUMBER                  | Including country and format validation |
| ADDR\_STREET\_NUMBER           | Part of address schema                  |
| ADDR\_STREET\_NAME             | Part of address schema                  |
| ADDR\_STREET\_TYPE             | Part of address schema                  |
| ADDR\_NEIGHBORHOOD             | Part of address components              |
| ADDR\_LOCALITY                 | Part of address components              |
| ADDR\_DISTRICT                 | Part of address components              |
| ADDR\_SUBDIVISION              | Part of address schema                  |
| ADDR\_COUNTRY                  | ISO-3166-1 format                       |
| ADDR\_POSTAL\_CODE             | Part of address schema                  |
| ADDR\_UNSTRUCTURED\_LONG\_FORM | Flexible address format                 |
| DOC\_CLASS                     | Document classification                 |
| DOC\_TYPE                      | Document type specification             |
| DOC\_SUBTYPE                   | Further document categorization         |
| DOC\_PRIMARY\_IDENTIFIER       | Main document identifier                |
| DOC\_SECONDARY\_IDENTIFIER     | Additional document identifier          |
| IND\_DISPLAY\_NAME             | Display name for individuals            |
| IND\_GIVEN\_NAME               | First name                              |
| IND\_FAMILY\_NAME              | Last name                               |
| IND\_MIDDLE\_NAME              | Middle name                             |
| IND\_DATE\_OF\_BIRTH           | Individual's birth date                 |
| IND\_NATIONALITY               | Country of nationality                  |


# Mexican Documents
Source: https://docs.frankieone.com/docs/mexican-documents-v2



The FrankieOne KYC v2 API supports Mexican documents for identity verification. This guide outlines the requirements and best practices for handling these documents.

## Supported Mexican Documents

The FrankieOne KYC v2 API currently supports the following Mexican document:

| Document    | Code          |
| ----------- | ------------- |
| National ID | `NATIONAL_ID` |

***

### Mexican National ID Card (INE/IFE)

The Mexican National ID Card—issued as either INE (Instituto Nacional Electoral) or IFE (Instituto Federal Electoral)—serves as an official identification document and voter ID. It contains key personal information, including the individual's full name, date of birth, unique ID number (CURP), and expiration date.

**Required Fields:**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name           | Field                | Notes                                                                            |
      | :------------------- | :------------------- | :------------------------------------------------------------------------------- |
      | Document Type        | `type`               | Must be `NATIONAL_ID` for Mexican National ID cards.                             |
      | Country              | `country`            | Must be `MEX` (Mexico).                                                          |
      | Date of Birth        | `dateOfBirth`        | Format: `YYYY-MM-DD`. Enter exactly as shown on the ID.                          |
      | Paternal Family Name | `paternalFamilyName` | Required for Mexican IDs. Use uppercase and match the spelling on the document.  |
      | Maternal Family Name | `maternalFamilyName` | Required for Mexican IDs. Use uppercase and match the spelling on the document.  |
      | Given Names          | `givenName`          | Include all given names as shown on the ID, preserving order and capitalization. |
    </Tab>

    <Tab title="ID Details">
      | Field Name | Field               | Notes                                                                                |
      | :--------- | :------------------ | :----------------------------------------------------------------------------------- |
      | ID Number  | `primaryIdentifier` | Must be provided in the `primaryIdentifier` field. Enter exactly as shown on the ID. |
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Document class should be 'IDENTITY' for KYC purposes
    "documentId": "92de15f64-5717-4562-b3fc-2c963f6665a7", // Unique identifier for this document in FrankieOne system
    "primaryIdentifier": "000734130", // ID number as shown on the Mexican National ID
    "type": "NATIONAL_ID", // Document type must be 'NATIONAL_ID' for Mexican IDs
    "country": "MEX" // Country code must be 'MEX' for Mexico
  },
  "supplementaryData": {
    "type": "NATIONAL_ID", // Reiterate document type for supplementary data
    "paternalFamilyName": "MENDOZA", // Paternal family name (first surname), uppercase, as on the ID
    "maternalFamilyName": "GARCIA" // Maternal family name (second surname), uppercase, as on the ID
  }
}
```

<Callout icon="bell">
  ##### Key Considerations for Mexican National ID

  When processing Mexican National ID cards, ensure the following to avoid common validation errors:

  * **Both paternal and maternal family names are required.** Enter them exactly as shown on the ID, using uppercase letters.
  * **Given names:** Include all given names in the correct order and with proper capitalization.
  * **Date of birth:** Use the exact format `YYYY-MM-DD` as printed on the document.
  * **ID number:** Enter the complete and correct ID number as it appears on the card.
</Callout>

<Info>
  ##### Document Number Verification

  The Mexican National ID may be issued as either:

  * INE (Instituto Nacional Electoral) — the current version
  * IFE (Instituto Federal Electoral) — the previous version

  Both INE and IFE cards are valid for verification. Ensure the document number is entered exactly as it appears on the card, regardless of version.
</Info>


# New Zealand Documents
Source: https://docs.frankieone.com/docs/new-zealand-documents-v2



The FrankieOne KYC v2 API supports some New Zealand documents for identity verification. This guide provides details on how to handle these documents effectively.

## Supported New Zealand Documents

The FrankieOne KYC v2 API supports the following New Zealand documents:

| Document          | Code              |
| :---------------- | :---------------- |
| Birth Certificate | `BIRTH_CERT`      |
| Drivers License   | `DRIVERS_LICENSE` |
| Passport          | `PASSPORT`        |

***

### Birth Certificates

Birth certificates are official documents issued by the government that record the birth of an individual. They include details such as the individual's name, date of birth, place of birth, and parentage.
When submitting a birth certificate for verification, ensure the document is clear, complete, and issued by an official authority. It must include all required details as specified below:

<Info>
  Contact your customer success manager to enable New Zealand Birth Certificate verification for your customer account.
</Info>

**Required Fields**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                           |
      | :------------ | :------------ | :---------------------------------------------------------------------------------------------- |
      | Country       | `country`     | Must be set to `NZL`                                                                            |
      | Date of Birth | `dateOfBirth` | Format must be `YYYY-MM-DD`                                                                     |
      | Document Type | `type`        | Must be `BIRTH_CERT`                                                                            |
      | Name          | `name`        | Must match the birth certificate exactly (Given name, Middle name, Family name, and any others) |
    </Tab>

    <Tab title="Certificate Details">
      | Field Name          | Field               | Notes                                     |
      | :------------------ | :------------------ | :---------------------------------------- |
      | Registration Number | `primaryIdentifier` | Provided in the `primaryIdentifier` field |
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Document classification (should always be "IDENTITY" for KYC)
    "primaryIdentifier": "000734130", // Registration Number as shown on the birth certificate
    "type": "BIRTH_CERT", // Document Type (must be "BIRTH_CERT" for birth certificates)
    "country": "NZL" // Country of issuance, ISO 3166-1 alpha-3 code for New Zealand
  }
}  
```

<Callout icon="star">
  ##### Best Practices for New Zealand Birth Certificate Verification

  When verifying New Zealand birth certificates, ensure:

  * All names match the document exactly, including order, spelling, and special characters.
  * The date of birth uses the correct format (`YYYY-MM-DD`), and historical date formats are handled appropriately.
  * All required and supplementary fields are collected, even if optional.
  * Registration numbers and district names are entered exactly as shown on the certificate.
  * Any discrepancies between the registered name and current legal name are clearly noted.
</Callout>

***

### Drivers Licenses

New Zealand Drivers Licenses are official documents issued by governments that grant individuals the right to operate a vehicle or engage in other regulated activities. They include personal details such as the individual's name, date of birth, and license number.

**Required Fields**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                          |
      | :------------ | :------------ | :--------------------------------------------------------------------------------------------- |
      | Country       | `country`     | Must be set to `NZL`                                                                           |
      | Date of Birth | `dateOfBirth` | Format must be `YYYY-MM-DD`                                                                    |
      | Document Type | `type`        | Must be `DRIVERS_LICENSE`                                                                      |
      | Name          | `name`        | Must match the driver’s license exactly (Given name, Middle name, Family name, and any others) |
    </Tab>

    <Tab title="License Details">
      | Field Name      | Field                 | Notes                                                      |
      | :-------------- | :-------------------- | :--------------------------------------------------------- |
      | License Number  | `primaryIdentifier`   | Enter the license number as shown on the driver’s license  |
      | License Version | `secondaryIdentifier` | Enter the license version as shown on the driver’s license |
      | Expiry Date     | `expiryDate`          | Must be provided in the `expiryDate` field                 |
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Document classification (should always be "IDENTITY" for KYC)
    "expiryDate": {
      "year": "1990", // Expiry year as shown on the license
      "month": "03", // Expiry month as shown on the license (two digits)
      "day": "27", // Expiry day as shown on the license (two digits)
      "unstructured": "1990-03-27", // Full expiry date in YYYY-MM-DD format
      "type": "GREGORIAN" // Calendar type (always "GREGORIAN")
    },
    "primaryIdentifier": "000734130", // License Number as shown on the driver’s license
    "secondaryIdentifier": "073", // License Version as shown on the driver’s license (e.g. "073")
    "type": "DRIVERS_LICENSE", // Document Type (must be "DRIVERS_LICENSE" for NZ driver’s licenses)
    "country": "NZL" // Country of issuance, ISO 3166-1 alpha-3 code for New Zealand
  }
}
```

***

### Passports

New Zealand passports are official travel documents issued by the New Zealand government that confirm an individual's identity and citizenship. They include personal details such as the individual's name, date of birth, passport number, and expiration date.

**Required Fields**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                                                  |
      | :------------ | :------------ | :--------------------------------------------------------------------------------------------------------------------- |
      | Country       | `country`     | Must be set to `NZL` (ISO 3166-1 alpha-3 code for New Zealand)                                                         |
      | Date of Birth | `dateOfBirth` | Must be in `YYYY-MM-DD` format                                                                                         |
      | Document Type | `type`        | Must be `PASSPORT`                                                                                                     |
      | Name          | `name`        | Must match the passport exactly, including all given, middle, family, and other names, with correct order and spelling |
    </Tab>

    <Tab title="Passport Details">
      | Field Name      | Field               | Notes                                                                                |
      | :-------------- | :------------------ | :----------------------------------------------------------------------------------- |
      | Passport Number | `primaryIdentifier` | Enter the passport number exactly as shown on the passport, including all characters |
      | Expiry Date     | `expiryDate`        | Must be provided in the `expiryDate` field in `YYYY-MM-DD` format                    |
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Document classification (should always be "IDENTITY" for KYC)
    "expiryDate": {
      "year": "1990", // Expiry year as shown on the passport
      "month": "03", // Expiry month as shown on the passport (two digits)
      "day": "27", // Expiry day as shown on the passport (two digits)
      "unstructured": "1990-03-27", // Full expiry date in YYYY-MM-DD format
      "type": "GREGORIAN" // Calendar type (always "GREGORIAN")
    },
    "primaryIdentifier": "000734130", // Passport Number as shown on the passport, including all characters
    "type": "PASSPORT", // Document Type (must be "PASSPORT" for New Zealand passports)
    "country": "NZL" // Country of issuance, ISO 3166-1 alpha-3 code for New Zealand
  }
}
```

<Callout icon="star">
  ##### Key Points for New Zealand Passport Verification

  * **Name Matching:** Ensure the name matches the passport exactly, including order, spelling, capitalization, special characters, and diacritics.
  * **Country Code:** Always use `NZL` for New Zealand passports.
  * **Passport Number:** Enter the passport number exactly as shown; incorrect or expired numbers will cause verification to fail.
  * **Name Order:** For visa holders or passports with non-standard name formats, use the name order and format as printed on the document.
</Callout>


# Find your use case
Source: https://docs.frankieone.com/docs/one-sdk-use-case

Choose the right OneSDK integration for your business — starting with the fastest, most cost-effective option.

## Overview

OneSDK offers multiple ways to integrate identity verification into your customer onboarding — from fully managed hosted flows to deeply customised embedded components.

**For the vast majority of businesses, Hosted OneSDK is the right choice.** It works across web, mobile (via WebView), and even offline channels — with minimal engineering effort, lower total cost of ownership, and the fastest time to market.

This page helps you evaluate each integration approach so you can make the right decision for your business.

## Why Start with Hosted OneSDK?

Before evaluating integration options, it's important to understand why Hosted OneSDK is the recommended starting point — not just from a technical perspective, but from a **business** one.

<CardGroup>
  <Card title="Fastest Time to Market" icon="rocket">
    Go live in **days, not months**. Hosted flows require minimal frontend work — just generate a link via the Portal or API and send it to your customers. No SDK installation, no component wiring, no release cycles.
  </Card>

  <Card title="Lower Total Cost of Ownership" icon="coins">
    FrankieOne manages hosting, uptime, security patches, vendor updates, and compliance changes. You avoid the ongoing engineering cost of maintaining a custom integration — freeing your team to focus on your core product.
  </Card>

  <Card title="Always Compliant & Up to Date" icon="shield-check">
    Hosted flows are automatically updated to meet the latest regulatory and vendor requirements. No need to redeploy your app when compliance rules change.
  </Card>

  <Card title="Works on Web & Mobile" icon="mobile">
    Hosted OneSDK runs seamlessly in browsers **and** inside native mobile apps via WebView (Android and iOS). One integration covers all your platforms — no separate mobile SDK needed.
  </Card>

  <Card title="Customisable to Your Brand" icon="palette">
    Hosted doesn't mean generic. Add your company logo, apply your brand theming (colours and fonts), toggle optional screens (welcome, consent, review), and customise copywriting on key screens — all without writing frontend code.
  </Card>
</CardGroup>

<Callout icon="thumbtack">
  **The bottom line:** Hosted OneSDK gives you the best balance of speed, cost, and reliability. Embedded or custom integrations should only be considered after hosted SDK options have been exhausted.
</Callout>

## Choose Your Integration Approach

### 1. Hosted OneSDK via Portal — No Code Required

**Best for**: Teams who want to start verifying customers immediately with zero engineering work.

Send verification links directly to your users via the FrankieOne Portal — by email, SMS, or QR code. Users complete the verification through a secure, FrankieOne-hosted flow, and results appear instantly in your Portal.

**Ideal for:**

* Manual or semi-automated onboarding teams
* Low- to medium-volume verification
* Businesses piloting or validating their onboarding process

**Business impact:** Live in **as little as 1 day** | **No engineering cost** | Fully managed by FrankieOne

### 2. Hosted OneSDK via API — Automated, Scalable

**Best for**: Businesses that want to automate onboarding at scale while keeping engineering effort low.

Through a single API call, generate verification links dynamically and deliver them via your own channels — redirect to a new tab, embed in an iframe, integrate into your CRM, or send via email/SMS.

**Ideal for:**

* Online onboarding journeys (web or mobile web)
* Platforms sending large volumes of verification links
* Teams with strong backend capabilities but limited frontend resources

**Business impact:** Live in **1–2 weeks** | **Minimal frontend cost** | Fully managed by FrankieOne

### 3. Hosted OneSDK in Mobile Apps — Via WebView

**Best for**: Mobile-first businesses that need identity verification inside their native app without building a custom UI.

Hosted OneSDK works inside Android WebView and iOS WKWebView, giving your mobile users the same fully managed verification experience — including IDV with document scanning and selfie capture. There is no need to build or maintain a native SDK integration.

**Ideal for:**

* Native mobile apps (iOS and Android) requiring in-app verification
* Teams that want to avoid the complexity and cost of a native SDK integration
* Businesses that need camera, location, and biometric capture on mobile

**Business impact:** Live in **2–4 weeks** | **No native SDK maintenance** | Same hosted reliability on mobile

#### Mobile Sample Apps

We've published complete working examples for five mobile frameworks. Each sample app loads a Hosted OneSDK URL inside a native WebView — no custom UI or SDK embedding required.

**Prerequisites**

* A **FrankieOne Customer ID** and **API Key**
* **Hosted OneSDK enabled** on your account — contact your Customer Success Manager if you haven't set this up yet

<CardGroup>
  <Card title="Android" icon="android" href="https://github.com/frankieone/frontend-onesdk-public-sample-codes/tree/main/mobile-onesdk-sample-android" />

  <Card title="iOS" icon="apple" href="https://github.com/frankieone/frontend-onesdk-public-sample-codes/tree/main/mobile-onesdk-sample-ios" />

  <Card title="React Native" icon="react" href="https://github.com/frankieone/frontend-onesdk-public-sample-codes/tree/main/mobile-onesdk-sample-react-native" />

  <Card title="Flutter" icon="mobile" href="https://github.com/frankieone/frontend-onesdk-public-sample-codes/tree/main/mobile-onesdk-sample-flutter" />

  <Card title="Expo" icon="mobile" href="https://github.com/frankieone/frontend-onesdk-public-sample-codes/tree/main/mobile-onesdk-sample-expo" />
</CardGroup>

<Callout icon="star">
  **Try it now on Android** — download the pre-built APK directly from [GitHub Releases](https://github.com/frankieone/frontend-onesdk-public-sample-codes/releases) to see Hosted OneSDK running inside a native WebView. APKs are available for Android (Kotlin), React Native, Flutter, and Expo.
</Callout>

### 4. Embedded OneSDK — Custom Integration (Enterprise Only)

<Callout icon="bell">
  This option is **not recommended for most customers**. It requires significant engineering investment and ongoing maintenance. Only consider this if hosted flows cannot meet a specific business or regulatory requirement.

  Unlike hosted flows, embedded integrations run client-side — meaning **your team is responsible for keeping the SDK up to date**, including security patches, vendor changes, and compliance updates. Falling behind on updates can introduce security vulnerabilities and break verification flows.
</Callout>

**Best for**: Enterprise teams with unique workflows, regulatory constraints, or highly branded in-app verification requirements that cannot be achieved with hosted flows.

This approach involves embedding the OneSDK JavaScript library directly into your product and building your own verification flow using SDK modules (e.g. OCR, biometrics, fraud detection).

**Consider only when:**

* Verification must be deeply embedded into a proprietary product experience
* You have highly complex UI/UX requirements that hosted templates cannot support
* Regulatory or contractual obligations require self-hosted verification flows
* You have dedicated frontend engineering resources for ongoing maintenance

**Business impact:** **2+ months** to launch | **High engineering & maintenance cost** | You own hosting, updates, and compliance

## Comparison Summary

|                         | Hosted via Portal                                                       | Hosted via API                                                          | Hosted via WebView (Mobile)                                             | Embedded SDK                |
| :---------------------- | :---------------------------------------------------------------------- | :---------------------------------------------------------------------- | :---------------------------------------------------------------------- | :-------------------------- |
| **Time to Launch**      | As little as 1 day                                                      | 1–2 weeks                                                               | 2–4 weeks                                                               | 2+ months                   |
| **Engineering Effort**  | None                                                                    | Low (backend only)                                                      | Low (WebView setup)                                                     | High (full frontend)        |
| **Ongoing Maintenance** | None — managed by FrankieOne                                            | Minimal                                                                 | Minimal                                                                 | High — you own it           |
| **Hosting**             | FrankieOne                                                              | FrankieOne                                                              | FrankieOne                                                              | Your infrastructure         |
| **Compliance Updates**  | Automatic                                                               | Automatic                                                               | Automatic                                                               | Manual redeployment         |
| **Platform Support**    | Web, mobile browser                                                     | Web, mobile browser, CRM                                                | Native iOS & Android apps                                               | Web (your app)              |
| **Customisation**       | Logo, theming, optional screens, copywriting (welcome, consent, result) | Logo, theming, optional screens, copywriting (welcome, consent, result) | Logo, theming, optional screens, copywriting (welcome, consent, result) | Full control                |
| **Who It's For**        | Operations, CX, pilot teams                                             | Backend-automated onboarding                                            | Mobile-first businesses                                                 | Bespoke enterprise projects |

## Making the Right Decision

When evaluating your options, consider these business factors:

**Total Cost of Ownership (TCO):** Embedded integrations require not just the initial build, but ongoing maintenance — SDK upgrades, vendor changes, compliance updates, bug fixes, and dedicated engineering time. Hosted flows eliminate this entirely.

**Time to Market (TTM):** Every week spent building a custom integration is a week your customers aren't being verified. Hosted flows let you go live in days and iterate from there.

**Risk:** Hosted flows are battle-tested and maintained by FrankieOne. A custom integration introduces risk around uptime, security, and compliance that your team must manage.

<Callout icon="lightbulb">
  **Our recommendation:** Start with Hosted OneSDK — whether via Portal, API, or WebView. You can always evolve to a more customised integration later if your business needs change. Most customers find that hosted flows meet their requirements long-term.
</Callout>

## What Verification Requirements Do You Have?

Regardless of your integration approach, OneSDK supports these verification types through hosted flow templates:

| Verification Requirement                     | Description                                                                 | Hosted Flow Template                            |
| :------------------------------------------- | :-------------------------------------------------------------------------- | :---------------------------------------------- |
| **IDV (OCR Document Scan + Selfie Capture)** | Verify identity through document and biometric capture.                     | IDV Template                                    |
| **Manual Data Entry for eKYC Checks**        | Collect data manually (name, DOB, address) for DVS or credit bureau checks. | eKYC Template                                   |
| **Additional Document Uploading**            | Request supporting documents such as proof of address or employment.        | Doc Upload Template                             |
| **Mixture of Verification Types**            | Combine multiple checks (e.g. OCR + AML + eKYC).                            | Custom Hosted or Embedded SDK (Enterprise Only) |

## What's Next

* **[Hosted Flow Templates](/docs/hosted-common-use-cases)** — Explore pre-configured IDV, eKYC, and document upload templates.
* **[Quick Start Guide](/docs/quickstart-guide)** — Implement your first hosted flow using either the Portal or API.
* **[Native Integration Guide](/docs/native-integration)** — Set up Hosted OneSDK inside Android or iOS WebViews.
* **[Using Hosted OneSDK](/docs/using-hosted-onesdk)** — Detailed implementation guide for hosted flows.
* **[Modifying Templates](/docs/quickstart-guide/modifying-templates)** — Customise branding, colours, and messaging on hosted flows.


# Ongoing Monitoring
Source: https://docs.frankieone.com/docs/ongoing-monitoring-v2

Learn how to use the FrankieOne API to enable continuous AML monitoring and automatically receive alerts on changes to a customer's risk profile.

## What is Ongoing Monitoring?

Meeting your Anti-Money Laundering (AML) obligations doesn't end after a customer's initial onboarding. Regulators require businesses to perform ongoing due diligence to ensure that a customer's risk profile has not changed over time.

FrankieOne's Ongoing Monitoring feature automates this entire process. Once enabled for an individual, our platform will continuously screen them against global watchlists and automatically alert you if any changes are detected, such as:

* A customer being added to a **Sanctions list**
* A customer becoming a **Politically Exposed Person (PEP)**
* New **Adverse Media** being published about the customer

***

## How Ongoing Monitoring Works

Our solution is designed as a simple "set and forget" lifecycle that is managed via the API and integrated directly into your workflow system.

<Steps>
  <Step title="1. Enable Monitoring">
    After a successful onboarding, you make a single API call to enable ongoing monitoring for an individual. This creates a "subscription" for that entity in our system for one or more monitoring types (e.g., `AML`).
  </Step>

  <Step title="2. Continuous Screening">
    Our platform takes over and perpetually monitors the entity against our global data sources. There is no further action required from you.
  </Step>

  <Step title="3. Real-Time Alerts">
    If a change is detected (e.g., a new PEP match is found), FrankieOne will automatically trigger a pre-configured "monitoring workflow".
  </Step>

  <Step title="4. Action & Review">
    The monitoring workflow runs, generating a new `workflowResult` with a `HIT`. This result can be sent to you via a webhook, allowing you to create a case in your system for your compliance team to review and action the new alert.
  </Step>
</Steps>

<Callout icon="thumbtack">
  ##### Onboarding vs. Monitoring Workflows

  Workflows in FrankieOne have a `lifecyclePhase`.<br />

  * Workflows used for initial checks are **`ONBOARDING`** workflows.<br />
  * Workflows triggered automatically by our monitoring service have a `lifecyclePhase` of **`MONITORING`**.<br />
    This allows you to create distinct logic and case management flows for handling new alerts versus initial onboarding results. \[cite: 3192-3197]
</Callout>

***

## API Integration: Managing Monitoring

You can manage an entity's monitoring status using a dedicated set of API endpoints.

### Enable or Disable Monitoring

To turn monitoring on or off for an individual, use the `PATCH` endpoint. This is a single endpoint that accepts query parameters to set the desired state.

**Endpoint:**
`PATCH /v2/individuals/{entityId}/monitor`

**Query Parameters:**

| Parameter         | Type           | Required | Description                                                           |
| :---------------- | :------------- | :------- | :-------------------------------------------------------------------- |
| `enabled`         | boolean        | Yes      | Set to `true` to enable monitoring or `false` to disable it.          |
| `monitoringTypes` | array\[string] | Yes      | Specifies which type(s) of monitoring to control. For AML, use `AML`. |

#### Example: Enabling AML Monitoring

```bash theme={null}
    curl --location --request PATCH '[https://api.frankie.one/v2/individuals/](https://api.frankie.one/v2/individuals/){{entityId}}/monitor?enabled=true&monitoringTypes=AML' \
    --header 'api_key: {{your_api_key}}' \
    --header 'X-Frankie-CustomerID: {{your_customer_id}}'
```

<Callout icon="star">
  ##### Alternative Method: Enable via Workflow

  You can also enable or disable ongoing monitoring as a step within your workflows. This allows you to automatically enroll customers into monitoring at the end of a successful onboarding workflow.
</Callout>

### Checking Monitoring Status

To check the current monitoring subscriptions for an entity, use the `GET` endpoint.

**Endpoint:**
`GET /v2/individuals/{entityId}/monitor`

A successful request will return a `200 OK` response containing a `monitoring` object that details the status of each subscription type.

#### Example Response for `GET /monitor`

```json theme={null}
{
    "requestId": "req_01J...",
    "monitoring": {
        "AML": {
            "subscriptions": [
                {
                    "serviceName": "DEFAULT",
                    "serviceProfileId": "sp_01J...",
                    "status": "ENABLED",
                    "enabledAt": "2024-08-26T05:30:00Z",
                    "enabledBy": "user@example.com",
                    "workflows": [
                        {
                            "workflowName": "AML Ongoing Monitoring",
                            "workflowId": "wf_01J...",
                            "lifecyclePhase": "MONITORING"
                        }
                    ]
                }
            ],
            "providers": [
                "complyadvantage"
            ],
            "status": "ENABLED"
        }
    }
}
```

This response shows that the entity is actively being monitored for `AML` by the `complyadvantage` provider, and any new hits will trigger the "AML Ongoing Monitoring" workflow.

***

## Automatic Disabling of Monitoring

To ensure you are only monitoring active customers and to prevent unnecessary costs, the FrankieOne platform will automatically disable ongoing monitoring for an entity if their status changes to inactive. This happens in the following scenarios:

* The entity is deleted.
* All of the entity's active Service Profiles are archived, deleted, or blocklisted.


# Performing a VEVO Visa Check
Source: https://docs.frankieone.com/docs/performing-visa-checks

A step-by-step guide to verifying an individual's Australian visa status and conditions using the VEVO check.

## What is a VEVO Visa Check?

A Visa Entitlement Verification Online (VEVO) check allows you to confirm the visa status and conditions of a non-Australian citizen, directly against the Department of Home Affairs records. It is a critical tool for ensuring a potential employee has the right to work or that a customer meets residency requirements.

FrankieOne integrates this check as a `VISA` step within our workflow engine, allowing you to automate this process as part of your standard onboarding or due diligence.

<Note>
  The first supported country for Visa Checks is Australia, where the data source is VEVO. This guide focuses on this implementation.
</Note>

### VEVO vs. DVS Passport Check

It's important to understand the distinction between a VEVO check and a DVS Passport check, as they serve different purposes.

* **Use the Document Verification Service (DVS)** to verify the **identity details** on a visa record. It confirms that the document number, name, and date of birth match the record held by the Department of Home Affairs.
* **Use the Visa Entitlement Verification Online (VEVO)** check to verify the **current visa status and conditions** (e.g., work rights, study limitations) linked to a foreign passport.

For identity verification, the DVS check is often sufficient. However, if you need to confirm the specific entitlements and conditions of the visa itself, a VEVO check is required.

***

## How It Works

The process is managed through two main API interactions integrated into a workflow.

<Steps>
  <Step title="1. Provide the Foreign Passport Data">
    First, you create or update an `individual` entity with the details of the **foreign passport** that the Australian visa is linked to.
  </Step>

  <Step title="2. Execute a Workflow">
    Next, you trigger a pre-configured workflow that contains a `VISA` step. FrankieOne securely connects to VEVO, performs the check, and returns the detailed results.
  </Step>
</Steps>

***

## Implementation Guide

### Step 1: Provide the Foreign Passport Data

The VEVO check is performed using the details of a foreign passport. You must include these details in the `documents` array when you create or update an `individual`.

* `type`: Must be `PASSPORT`.
* `primaryIdentifier`: The passport number.
* `country`: The passport's country of issue (e.g., `GBR` for Great Britain).

```json title="Example individual object with a foreign passport" theme={null}
{
    "individual": {
        "name": { "givenName": "John", "familyName": "Smith" },
        "dateOfBirth": { "year": "1990", "month": "05", "day": "15" },
        "documents": [
            {
                "class": "IDENTITY",
                "type": "PASSPORT",
                "primaryIdentifier": "E07148293",
                "country": "GBR" 
            }
        ],
        "consents": [ { "type": "DOCS" } ]
    }
}
```

### Step 2: Execute the Workflow

With the entity created, execute the workflow containing the `VISA` step.

```bash theme={null}
    POST /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/execute
```

***

## Interpreting the Visa Check Result

The outcome of the check is found within the `workflowStepResults` array, inside the object where `stepName` is `VISA`.

### The VISA Step Summary

The `summary` object gives you a high-level overview and is useful for quick decisioning based on your configured allow/deny lists.

```json title="Example VISA Step Summary" theme={null}
"summary": {
    "stepName": "VISA",
    "country": "AUS",
    "class": "Student",
    "subClass": "500",
    "hasExpired": false,
    "onAllowList": true,
    "onDenyList": false
}
```

* **`onAllowList` / `onDenyList`**: These booleans tell you if the visa's class/subclass matched the lists you configured in the workflow step. This is often all you need for automated decisioning.

### The Process Result (`supplementaryData`)

For the most detailed information, you must inspect the `supplementaryData` object within the step's `processResults`. This contains the full entitlement details returned from VEVO.

| Field                             | Description                                                                                                         |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------ |
| `class` & `subClass`              | The official class and subclass of the visa (e.g., "Student", "500").                                               |
| `entitlementStatus`               | The current status of the visa (e.g., "In effect").                                                                 |
| `grantDate` & `expiryDate`        | The dates the visa was granted and when it expires.                                                                 |
| `entitlementConditionDescription` | **Crucial Field:** A human-readable description of the visa's conditions, such as work rights or study limitations. |
| `holderType`                      | Indicates if the individual is the `PRIMARY` or `SECONDARY` holder of the visa.                                     |

***

## Workflow Configuration

The `VISA` step in your workflow can be customized with allow or deny lists based on visa classes and subclasses. This allows you to tailor the check to your specific business needs (e.g., only accepting work visas).

```json title="Example Workflow Step Configuration" theme={null}
"visaCheck": {
    "allowedVisaType": {
        "AU": {
            "classes": [
                { "class": "*", "subclass": "482" },
                { "class": "*", "subclass": "189" }
            ]
        }
    }
}
```

<Callout icon="star">
  This configuration is managed within the FrankieOne Workflow Builder. Consult with your FrankieOne account manager for assistance.
</Callout>

## Supported Visa Categories

Below is a summary of the key visa groups we support:

| Visa Category               | Examples of Subclasses                 | Status                         |
| :-------------------------- | :------------------------------------- | :----------------------------- |
| Partner & Family Visas      | 100, 101, 102, 103, 143, 804, 835–838  | ✔ Actively supported           |
| Skilled & Work Visas        | 186, 187, 189, 190, 191, 482, 491, 494 | ✔ Actively supported           |
| Business & Investor Visas   | 132, 188, 888                          | ✔ Actively supported           |
| Humanitarian Visas          | 200–204, 866                           | ✔ Actively supported           |
| Resident Return & Bridging  | 155, 157, 444 (NZ citizens)            | ✔ Actively supported           |
| Other historical subclasses | 175, 176, 885, 886, 808, 814, etc.     | ⚠ Legacy only – not issued now |

<Callout icon="star">
  \*\*Note: \*\*While many visas listed are still actively issued by the Australian Government, some subclasses have been repealed or closed to new applicants. We include these for legacy verification where the visa is still held by an individual.
</Callout>

***

## Unsupported Visa Types

The following visa types are not currently on our allow list and will result in a failed verification:

| Visa Type                                 | Subclass(es) | Reason        |
| :---------------------------------------- | :----------- | :------------ |
| Visitor visas                             | 600          | Not supported |
| Electronic Travel Authority (ETA)         | 601          | Not supported |
| eVisitor visas                            | 651          | Not supported |
| Student visas                             | 500          | Not supported |
| Working Holiday or Work and Holiday visas | 417, 462     | Not supported |
| Temporary Graduate visas                  | 485          | Not supported |

<Danger>
  If an individual holds one of these visa types, they will not pass verification as their visa subclass is not included in FrankieOne’s allowed configuration.
</Danger>


# Philippines Documents
Source: https://docs.frankieone.com/docs/philippines-documents-v2



The FrankieOne KYC v2 API supports some Philippines documents for identity verification. This guide provides details on how to handle these documents effectively.

## Supported Philippines Documents

The FrankieOne KYC v2 API supports the following Philippines documents:

| Document | Code       |
| :------- | :--------- |
| Passport | `PASSPORT` |

***

### Passports

Philippine passports are official travel documents issued by the Department of Foreign Affairs (DFA) of the Philippines. They include personal details such as the individual's name, date of birth, passport number, and other identifying information.

**Required Fields**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                                    |
      | :------------ | :------------ | :------------------------------------------------------------------------------------------------------- |
      | Country       | `country`     | Must be set to `PHL`                                                                                     |
      | Date of Birth | `dateOfBirth` | Must be in `YYYY-MM-DD` format                                                                           |
      | Document Type | `type`        | Must be `PASSPORT`                                                                                       |
      | Name          | `name`        | Enter the full name exactly as it appears on the passport, including all given, middle, and family names |
    </Tab>

    <Tab title="Passport Details">
      | Field Name      | Field               | Notes                                                                                                    |
      | :-------------- | :------------------ | :------------------------------------------------------------------------------------------------------- |
      | Passport Number | `primaryIdentifier` | Enter the passport number exactly as shown, following the format: 1 letter + 7 digits (e.g., `P1234567`) |
      | Country Code    | `country`           | Must be set to `PHL`                                                                                     |
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Document class must be "IDENTITY" for passports
    "primaryIdentifier": "P1234567", // Passport number: 1 letter + 7 digits (e.g., "P1234567")
    "type": "PASSPORT", // Document type must be "PASSPORT"
    "country": "PHL" // Country code must be "PHL" for the Philippines
  }
}
```

<Callout icon="bell">
  ##### Common Validation Issues

  Ensure the following to avoid validation failures:

  * Passport number must be exactly 8 characters: 1 letter (usually `P`) followed by 7 digits (e.g., `P1234567`)
  * Full name (given, middle, and family names) must match the passport exactly, including capitalization, spaces, special characters, and diacritical marks
  * All middle names and compound surnames must be included as shown on the passport
  * Date of birth must be in `YYYY-MM-DD` (ISO) format
  * Country code must be set to `PHL`
  * Document type must be `PASSPORT`
</Callout>

<Check>
  ##### Verification Checklist

  * Passport number format: 1 letter + 7 digits (e.g., `P1234567`)
  * Name fields match passport exactly (spelling, order, spaces, capitalization)
  * All required fields are present: `country`, `dateOfBirth`, `type`, `name`, `primaryIdentifier`
</Check>


# Modifying Templates
Source: https://docs.frankieone.com/docs/quickstart-guide/modifying-templates



## Overview

Pre-Built Hosted Flows come production-ready with FrankieOne’s standard verification logic and UI.

You can easily modify them to align with your organisation’s branding, language, and customer experience — all without writing code or rebuilding the flow.

Customisations are applied **at the configuration level**, ensuring your flows remain compliant, upgradeable, and supported by FrankieOne.

<Note>
  If you have requirements for more advanced modification, including screen orders, verification logic and additional events/webhooks, please contact us for an estimation of custom implementation tailored to your requirements.
</Note>

## FrankieOne Screens Versus IDV Vendor Screens

Hosted Flows are composed of two types of screens: **FrankieOne-managed screens and vendor-managed screens.**

### FrankieOne Screens

These include the **Launch, Welcome, Consent, Review, Result and Manual eKYC Form** pages — as well as any additional UI built directly by FrankieOne.

The level of customisation for the FrankieOne Screens is listed in this document.

### IDV Vendor Screens

Vendor screens appear when the verification step is handled directly by the integrated provider.

These screens are hosted and maintained by the vendor, and FrankieOne provides a wrapper around them to ensure a seamless user experience.

Customisation for vendor screens is **limited by each vendor’s SDK capabilities.**

You can usually:

* Configure accepted document types or capture modes.

* Adjust some language strings or colours if supported by the vendor.

However, **deep customisation** (e.g. repositioning UI elements, editing vendor messaging, or changing capture flow logic) is\*\* not supported\*\* due to compliance and vendor SDK constraints.

## Branding Control

Hosted Flows support light branding configuration so your users feel at home in your onboarding experience. Branding can be applied per flow template or across your entire FrankieOne environment.

### Logo

Upload your organisation’s logo through your Customer Success Manager. Your logo appears on the start and welcome pages and scales automatically for mobile and desktop.

#### Recommendations

* Use an SVG or PNG file with a transparent background.

* Keep file size below 500 KB for faster load times.

* Ensure adequate contrast with your theme colours.

### Colours

Define your primary and secondary colours to match your brand palette.

These colours are used for buttons, headers, and progress bars throughout the flow.

| Element          | Description                      | Example |
| ---------------- | -------------------------------- | ------- |
| Primary Colour   | Buttons, CTAs, and highlights    | #0069FF |
| Secondary Colour | Muted colours (disabled buttons) | #E8F0FF |
| Text Colour      | Standard text, labels            | #222222 |

<Note title="Tip">
  Use high-contrast colours for accessibility and WCAG compliance.
</Note>

### Font

Hosted Flows use FrankieOne’s default web-safe fonts for optimal performance.

If you’d like to apply a custom font, contact FrankieOne Support to confirm compatibility.

#### Recommended defaults:

* **Sans-serif** for readability (e.g. Helvetica, Inter, Open Sans).

* Limit to one or two font families to ensure visual consistency.

* Google Fonts are preferred for OneSDK use, otherwise please provide your font files for upload.

## Update On-Screen Messaging

You can modify the text displayed throughout the flow — including page titles, button labels, and consent or result messages. This helps align the tone of voice and clarify instructions for your customers.

The following on-scree messaging are customisable:

* Page Titles, descriptions and checkmark copy

* Consent Messaging and checkboxes

* Results messages: success, fail, warning and pending title and descriptions

* CTA button text

<Note>
  Note that we do not support adding or rearranging paragraphs or page elements at this stage. If you have these requirements, please contact our support team for an estimation of custom implementation tailored to your requirements.
</Note>

## Additional Pages

Each flow includes several optional screens that you can choose to enable or disable.

| Page    | Purpose                                                         | Can Be Disabled?                          |
| ------- | --------------------------------------------------------------- | ----------------------------------------- |
| Launch  | Introduces the verification process and sets user expectations. | ✅                                         |
| Welcome | Greets users and provides brief instructions.                   | ✅                                         |
| Consent | Captures legal or privacy consent before verification starts.   | ⚠️ Only if consent is captured elsewhere. |
| Review  | Allows users to review entered data before submission.          | ✅                                         |

<Note title="Recommendation">
  Keep the Consent page active unless your app already collects user consent in a prior step.
</Note>

## IDV Vendors, and Vendor-side Customisation

Please reach out to our support team for switching vendors and configuring any vendor-side customisation on Hosted Flows.

## Advanced Customisation (Contact Us)

For bespoke requirements — such as changing flow logic, adding new vendors, or implementing unique UI components — contact your FrankieOne Customer Success Manager.

Examples of advanced customisation include:

* Branching logic (e.g. verification type based on nationality).

* Custom analytics or event tracking integrations.

* Special regional requirements or UX approvals.

<Note>
  Advanced changes move the flow outside of the “Pre-Built” configuration and may require a Custom Hosted Flow engagement
</Note>


# Use Pre-built Pages & Hosted Flows
Source: https://docs.frankieone.com/docs/quickstart-guide/use-case-1-hosted-onesdk



<Panel>
  **Get Started**

  <br />

  You can start using Hosted Flows immediately - no SDK installation required.

  <Steps>
    <Step title="Get API Credentials">
      Request your API key and Customer ID via the [FrankieOne Support Portal](https://frankieone.atlassian.net/servicedesk/customer/portals).
    </Step>

    <Step title="Test Integration">
      Use our [test data](/docs/test-data) to verify your implementation.
    </Step>

    <Step title="Monitor Verifications">
      Track verification statuses and analytics in the Portal.
    </Step>

    <Step title="Go Live">
      Switch to production credentials and start verifying users.

      ```bash title="1. Generate Onboarding URL" theme={null}
      curl --request POST \
           --url https://api.kycaml.uat.frankiefinancial.io/idv/v2/idvalidate/onboarding-url \
           --header 'api_key: API-KEY' \
           --header 'X-Frankie-CustomerID: CUSTOMER-ID' \
           --header 'accept: application/json' \
           --header 'content-type: application/json' \
           --data-raw '{
              "customerRef": "YOUR_UNIQUE_STRING",
              "consent": true,
              "flowId": "idv"
          }'
      ```

      Or generate and send verification links manually from the FrankieOne Portal.
    </Step>
  </Steps>
</Panel>

## What are hosted flows

**Hosted Flows** are FrankieOne’s fully managed, ready-to-launch verification experiences.

They allow you to onboard customers through FrankieOne’s hosted infrastructure — without building or maintaining your own verification UI or vendor integrations.

Each Hosted Flow contains all necessary steps, from data capture to identity verification and result delivery, and can be tailored to your brand through light configuration.

They are the fastest, most compliant, and most reliable way to start using OneSDK.

### Key Benefits

* **Zero Frontend Code**: No need to build or maintain verification screens.

* **Managed Compliance**: FrankieOne ensures vendor updates, regulatory logic, and security.

* **Consistent UX**: Professionally designed flow that works across devices.

* **Scalable**: Easily expand to multiple regions and verification types as you grow.

## Features

<CardGroup>
  <Card title="Real-time Verification" icon="bolt">
    Instant document verification and liveness detection
  </Card>

  <Card title="Anti-Fraud Protection" icon="shield-check">
    Built-in protection against deepfakes and screen captures
  </Card>

  <Card title="Biometric Matching" icon="fingerprint">
    Advanced facial recognition and matching
  </Card>

  <Card title="Streamlined UX" icon="user">
    Intuitive flow for both desktop and mobile users
  </Card>
</CardGroup>

## Why use hosted flows

**Hosted Flows** are recommended for most customers because they combine speed, flexibility, and compliance with minimal engineering effort.

### Use Hosted Flows when:

* You want to start verifying customers quickly without frontend development.

* You need a fully managed, compliant onboarding experience.

* Your verification process can use standard, proven flow templates (eKYC, IDV, OCR).

* You want a consistent experience across multiple vendors and markets.

## How does hosted flow work

Hosted Flows run on FrankieOne’s infrastructure and connect directly to your account’s verification configurations and vendors.

They handle all client-side logic, event tracking, and result submission.

### Flow Overview

<Steps>
  <Step title="Start">
    The user is invited to complete verification (via link, redirect, or iframe).
  </Step>

  <Step title="Verification">
    OneSDK manages document capture, biometrics, or manual entry steps within the hosted interface.
  </Step>

  <Step title="Vendor Orchestration">
    FrankieOne routes verification requests to the selected vendor(s) and collects results.
  </Step>

  <Step title="Results">
    Verification outcomes are available in your Portal or returned via API webhook.
  </Step>
</Steps>

### Architecture

<Frame>
  <img alt="Architecture Diagram" />
</Frame>

1. Backend requests onboarding URL
2. User receives verification link
3. OneSDK handles document/biometric capture
4. Incode processes IDV data
5. FrankieOne KYC analyzes results
6. Status updates in Portal

## What’s Next

Once you’ve decided to use Hosted Flows:

1. **Choose a template** — select from our standard eKYC, IDV, or OCR-only flows.

2. **Add it to your account** — via the Portal or through FrankieOne support.

3. **Customise branding and messaging** — update logo, colours, and copy.

4. **Generate verification links** — send via Portal or API.

5. **Monitor results** — view verification outcomes in the Portal or through API webhooks.


# Risk Based Onboarding
Source: https://docs.frankieone.com/docs/risk-based-onboarding

How to implement FrankieOne's risk based onboarding

This guide explains how to implement conditional routing in your onboarding workflow. Instead of a linear verification journey, this approach dynamically adjusts friction based on real-time risk signals—routing customers to the appropriate CDD tier based on assessed risk.

This risk-based approach supports both current AUSTRAC expectations and the direction of upcoming AML/CTF reforms in Australia, which consolidate customer identification into a single, risk-based CDD obligation.

<video />

## Overview

Risk-Based Onboarding uses a three-step process:

1. **Passive Signal Collection** – Assess email, phone, and device risk invisibly
2. **Decision Gate** – Route to Simplified, Standard, or Enhanced CDD based on risk score
3. **Verification** – Execute the appropriate verification path for the CDD tier

```mermaid theme={null}
flowchart LR
    A["Collect Details"] --> B["Assess Risk Signals"]
    B --> C{"Decision Gate"}
    C -->|Low Risk| D["Simplified CDD"]
    C -->|Medium Risk| E["Standard CDD"]
    C -->|High Risk| F["Enhanced CDD"]
    D --> G["Decision"]
    E --> G
    F --> G
```

## CDD Tiers

FrankieOne's risk-based workflows support **configurable CDD tiers** (Simplified, Standard, Enhanced) that customers can align with their risk assessment and regulatory expectations:

| CDD Tier       | Risk Level | Example Use Cases                             |
| -------------- | ---------- | --------------------------------------------- |
| **Simplified** | Low        | Low-risk customers, standard products         |
| **Standard**   | Medium     | Most new account openings                     |
| **Enhanced**   | High       | PEPs, high-value products, complex structures |

### Verification Intensity by Industry

The verification checks at each CDD tier vary by industry based on regulatory requirements:

| CDD Tier       | Banking                                             | Gaming                 | Other Sectors |
| -------------- | --------------------------------------------------- | ---------------------- | ------------- |
| **Simplified** | TwoPlusID (Gov ID + credit bureau + electoral roll) | IDOnly or TwoPlus      | Configurable  |
| **Standard**   | TwoPlusID (Gov ID + screening)                      | TwoPlusID              | Configurable  |
| **Enhanced**   | TwoPlusID + biometrics + adverse media              | TwoPlusID + biometrics | Configurable  |

> **Note:** Banking has a higher regulatory floor—even Simplified CDD requires TwoPlusID verification. Other industries may use lighter verification at lower CDD tiers based on their risk assessment.

## Configuration Options

Risk-based routing can be configured at different levels depending on your needs:

| Option                  | Signals Used                                | Best For                            |
| ----------------------- | ------------------------------------------- | ----------------------------------- |
| **Full Fraud Signals**  | Email, phone, device, IP                    | Maximum fraud protection            |
| **Email + Phone Only**  | Email reputation, phone intelligence        | Lighter integration, good coverage  |
| **Business Logic Only** | Entity age, product type, transaction value | Simple routing without fraud checks |

### Option 1: Full Fraud Signals

Uses all available fraud steps: device intelligence, IP risk, email risk, and phone risk. Provides the strongest fraud detection but requires OneSDK integration for device and IP capture.

**Fraud steps included:**

* `email_risk` – Email domain, age, and reputation
* `phone_risk` – Phone type, carrier, and validity
* `device_intelligence` – Device fingerprint, velocity, and blocklist
* `ip_risk` – Geolocation, VPN/proxy detection

### Option 2: Email + Phone Only

A lighter approach that assesses risk using email and phone fraud steps. No device fingerprinting or OneSDK integration required.

**Fraud steps included:**

* `email_risk` – Evaluates email domain, age, and reputation
* `phone_risk` – Evaluates phone type, carrier, and validity

**Signals evaluated:**

* Email domain (disposable, free, corporate)
* Email age and deliverability
* Phone type (mobile, VoIP, landline)
* Phone carrier risk and number validity

### Option 3: Business Logic Only

Route based on entity attributes or transaction context without fraud signal checks. Useful when risk is determined by business factors rather than fraud indicators.

```json theme={null}
{
  "stage": "DECISION_GATE",
  "logic": "IF entity_age < 30_days OR product_type == 'HIGH_VALUE' OR transaction_value > 10000",
  "then": "ENHANCED_VERIFICATION",
  "else": "STANDARD_VERIFICATION"
}
```

**Example routing rules:**

* New customers (entity age \< 30 days) → Enhanced verification
* High-value products → Document + biometric
* Transaction value > threshold → Step-up required
* Returning verified customers → Streamlined flow

## Prerequisites

Before implementing risk-based routing, ensure you have:

* A workflow configured with conditional logic
* For fraud signals: Completed the [Fraud Checks Guide](https://docs.frankieone.com/docs/fraud-checks-guide) setup
* For device intelligence: OneSDK integration with session tracking

## Step 1: Create Entity

Create an entity profile with the data required for your chosen configuration.

```bash theme={null}
curl -X POST https://api.frankieone.com/v2/individuals \
  -H "api_key: YOUR_API_KEY" \
  -H "X-Frankie-CustomerID: YOUR_CUSTOMER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "individual": {
      "entityType": "INDIVIDUAL",
      "name": {
        "givenName": "JAMES",
        "middleName": "A",
        "familyName": "TESTONE",
        "displayName": "JAMES A TESTONE"
      },
      "dateOfBirth": {
        "year": "1990",
        "month": "05",
        "day": "15"
      },
      "nationality": "AUS",
      "addresses": [
        {
          "type": "RESIDENTIAL",
          "streetNumber": "35",
          "streetName": "CONN",
          "streetType": "STREET",
          "unitNumber": "1",
          "locality": "FERNTREE GULLY",
          "subdivision": "VIC",
          "postalCode": "3156",
          "country": "AUS",
          "unstructuredLongForm": "U 1/35 CONN STREET, FERNTREE GULLY, VIC 3156"
        }
      ],
      "emailAddresses": [
        {
          "type": "WORK",
          "email": "james.testone@example.com",
          "isPreferred": true
        }
      ],
      "phoneNumbers": [
        {
          "country": "AUS",
          "number": "0412345678",
          "isPreferred": true
        }
      ],
      "documents": {
        "IDENTITY": [
          {
            "type": "DRIVERS_LICENSE",
            "country": "AUS",
            "subdivision": "VIC",
            "primaryIdentifier": "123456789",
            "secondaryIdentifier": "P1234567",
            "class": "IDENTITY"
          }
        ]
      },
      "consents": [
        { "type": "GENERAL" },
        { "type": "DOCS" },
        { "type": "CREDITHEADER" }
      ]
    }
  }'
```

The response includes the `entityId` required for workflow execution.

> **Note:** For device and IP signals, you must implement [OneSDK](https://docs.frankieone.com/docs/onesdk) on the client side. Email and phone checks work independently without it.

## Step 2: Execute Risk-Based Workflow

Execute your workflow with risk-based routing enabled. The workflow configuration determines how signals are evaluated and which path is triggered.

```bash theme={null}
curl -X POST https://api.frankieone.com/v2/individuals/{entityId}/serviceprofiles/DEFAULT/workflows/AUS-Risk-CDD-Email-Phone-Device/execute \
  -H "api_key: YOUR_API_KEY" \
  -H "X-Frankie-CustomerID: YOUR_CUSTOMER_ID"
```

### Workflow Configuration

Risk-based workflows include fraud steps (email risk, phone risk, device intelligence) that evaluate signals before routing to the appropriate verification path.

Below is a conceptual example of the branching structure with three CDD tiers:

```json theme={null}
{
  "workflow_name": "Dynamic_Risk_Based_Onboarding",
  "stages": [
    {
      "stage": "PRE_SCREEN",
      "steps": ["email_risk", "phone_risk", "device_intelligence"]
    },
    {
      "stage": "DECISION_GATE",
      "logic": {
        "HIGH_RISK": "fraud_score > 50 OR device_risk == 'HIGH' OR pep_match == true",
        "MEDIUM_RISK": "fraud_score > 20 OR entity_age < 30_days",
        "LOW_RISK": "default"
      }
    },
    {
      "stage": "VERIFICATION",
      "branches": {
        "LOW_RISK": ["document_verification", "database_match"],
        "MEDIUM_RISK": ["document_verification", "database_match", "screening"],
        "HIGH_RISK": ["document_verification", "biometric_liveness", "database_match", "screening", "adverse_media"]
      }
    }
  ]
}
```

| CDD Tier   | Risk Score | Verification Path                                            |
| ---------- | ---------- | ------------------------------------------------------------ |
| Simplified | 0-20       | Document + database verification                             |
| Standard   | 21-50      | Document + database + screening                              |
| Enhanced   | 51+        | Document + biometrics + database + screening + adverse media |

> **Note:** This is a conceptual representation. Workflows are configured by your FrankieOne representative. Contact your representative to set up risk-based routing with the appropriate fraud steps for your use case.

### Risk Factors Evaluated

The workflow evaluates multiple risk factors, each contributing to the overall risk score:

| Risk Factor             | Description                 | Example Values             |
| ----------------------- | --------------------------- | -------------------------- |
| `fraud_email`           | Email Address Risk          | LOW, MEDIUM, HIGH          |
| `fraud_phone_number`    | Phone Number Risk           | LOW, MEDIUM, HIGH          |
| `fraud_ip_address`      | IP Address Risk             | LOW, MEDIUM, HIGH          |
| `fraud_count_session`   | Session Count Risk          | Numeric                    |
| `entity_type`           | Entity Type                 | INDIVIDUAL                 |
| `entity_age`            | Age of Entity (years)       | Numeric                    |
| `workflow_attempts`     | Number of Workflow Attempts | Numeric                    |
| `document_type`         | ID Document Type            | DRIVERS\_LICENSE, PASSPORT |
| `address_country_risk`  | Residential Address Country | Country code               |
| `document_country_risk` | Document Issuing Country    | Country code               |

### Fraud Indicators

The FRAUD step evaluates specific indicators that can trigger issues:

| Indicator            | Risk Level  | Example Triggers                        |
| -------------------- | ----------- | --------------------------------------- |
| Risky Email Domain   | HIGH        | Disposable domains, known fraud domains |
| Email Age            | MEDIUM-HIGH | Recently created email addresses        |
| VoIP Phone           | MEDIUM-HIGH | Non-mobile phone numbers                |
| Phone Carrier Risk   | MEDIUM      | High-risk carriers                      |
| IP Location Mismatch | MEDIUM      | IP doesn't match stated address         |
| VPN/Proxy Detected   | MEDIUM      | Connection anonymisation                |

## Step 3: Interpret Results

The workflow execution response contains the full verification outcome in the `workflowResult` object.

### Key Response Fields

| Field                                     | Description                                   |
| ----------------------------------------- | --------------------------------------------- |
| `workflowResult.result`                   | Overall outcome: `PASS`, `REVIEW`, or `FAIL`  |
| `workflowResult.workflowExecutionState`   | Execution state: `COMPLETED`                  |
| `workflowResult.riskAssessment.riskLevel` | Risk level: `LOW`, `MEDIUM`, or `HIGH`        |
| `workflowResult.riskAssessment.riskScore` | Numeric risk score                            |
| `workflowResult.issues`                   | Array of flagged issues                       |
| `workflowResult.steps`                    | Which steps passed, failed, or are incomplete |

### Example Response: High-Risk (Needs Review)

This example shows a high-risk result triggered by a risky email domain:

```json theme={null}
{
  "workflowResult": {
    "entityId": "155da7b9-cb8a-461a-8e58-787d65276630",
    "result": "REVIEW",
    "status": "REVIEW",
    "workflowExecutionState": "COMPLETED",
    "workflowName": "AUS-Risk-CDD-Email-Phone",
    "workflowExecutionId": "01KGJW7WXA0X5QHFC9M31AEE9Q",
    "issues": [
      {
        "category": "FRAUD",
        "issue": "FRAUD_EMAIL_ADDRESS",
        "severity": "REVIEW"
      },
      {
        "category": "RISK",
        "issue": "RISK_THRESHOLD_HIGH",
        "severity": "REVIEW"
      }
    ],
    "riskAssessment": {
      "riskLevel": "HIGH",
      "riskScore": 61,
      "riskFactors": [
        {
          "factor": "fraud_email",
          "description": "Email Address Risk",
          "value": "HIGH",
          "score": 51
        },
        {
          "factor": "fraud_phone_number",
          "description": "Phone Number Risk",
          "value": "LOW",
          "score": 1
        },
        {
          "factor": "fraud_ip_address",
          "description": "IP Address Risk",
          "value": "LOW",
          "score": 1
        },
        {
          "factor": "entity_age",
          "description": "Age of Entity",
          "value": "76",
          "score": 1
        }
      ]
    },
    "steps": {
      "passed": ["START", "MATCHLIST", "DECISION", "FINISH"],
      "failed": ["KYC", "FRAUD"],
      "incomplete": ["TOGGLE_MONITORING"],
      "order": ["START", "MATCHLIST", "KYC", "FRAUD", "TOGGLE_MONITORING", "DECISION", "FINISH"]
    }
  }
}
```

### Understanding the FRAUD Step Results

The `workflowStepResults` array contains detailed results for each step. For the FRAUD step:

```json theme={null}
{
  "stepName": "FRAUD",
  "result": "HIT",
  "summary": {
    "maximumEmailAddressRisk": "HIGH",
    "maximumPhoneNumberRisk": "LOW",
    "maximumIpAddressRisk": "LOW",
    "numberEmailAddressEvaluations": 1,
    "numberPhoneNumberEvaluations": 1
  },
  "processResults": [
    {
      "objectType": "EMAIL_ADDRESS",
      "result": "HIT",
      "supplementaryData": {
        "riskLevel": "HIGH",
        "indicators": [
          {
            "name": "emailLevel",
            "value": "high",
            "rules": [{ "name": "Risky Email Domain", "isActive": true }]
          }
        ]
      }
    },
    {
      "objectType": "PHONE_NUMBER",
      "result": "CLEAR",
      "supplementaryData": {
        "riskLevel": "LOW"
      }
    }
  ]
}
```

### Result Values

| Result   | Meaning                                  | Recommended Action     |
| -------- | ---------------------------------------- | ---------------------- |
| `PASS`   | All checks passed, risk within threshold | Auto-approve account   |
| `REVIEW` | Flags present or risk threshold exceeded | Manual review required |
| `FAIL`   | Critical failure or verification failed  | Decline registration   |

### Issue Categories

| Category | Example Issues                                              |
| -------- | ----------------------------------------------------------- |
| `FRAUD`  | `FRAUD_EMAIL_ADDRESS`, `FRAUD_PHONE_NUMBER`, `FRAUD_DEVICE` |
| `RISK`   | `RISK_THRESHOLD_HIGH`, `RISK_THRESHOLD_MEDIUM`              |
| `KYC`    | `NOT_FOUND`, `PARTIAL_MATCH`                                |

> **Note:** Even when individual fraud checks pass, the overall `result` may be `REVIEW` if the combined risk score exceeds your configured threshold. This ensures your compliance team can make the final decision with full context.

For detailed field definitions, see [Interpreting Workflow Results](https://docs.frankieone.com/docs/interpreting-workflow-results).

## Configuring Thresholds

Work with your FrankieOne representative to tune risk scoring based on your risk appetite.

### Risk Score Thresholds

The overall risk score determines the CDD tier and workflow routing:

| Risk Level | Score Range | CDD Tier       | Typical Outcome                   |
| ---------- | ----------- | -------------- | --------------------------------- |
| LOW        | 0-20        | Simplified CDD | `PASS`                            |
| MEDIUM     | 21-50       | Standard CDD   | `PASS` or `REVIEW` (configurable) |
| HIGH       | 51+         | Enhanced CDD   | `REVIEW`                          |

These thresholds can be tuned as regulatory guidance evolves (for example, where reforms call out higher-risk customer types or jurisdictions).

### Risk Factor Weights

Each risk factor contributes a weighted score. Example weights:

| Risk Factor            | LOW Score | HIGH Score |
| ---------------------- | --------- | ---------- |
| `fraud_email`          | 1         | 51         |
| `fraud_phone_number`   | 1         | 51         |
| `fraud_ip_address`     | 1         | 51         |
| `entity_type`          | 2         | 2          |
| `entity_age`           | 1         | 5          |
| `document_type`        | 1         | 3          |
| `address_country_risk` | 1         | 10         |

> **Note:** Weights are configurable. Contact your FrankieOne representative to adjust scoring for your use case.

## Best Practices

**Always log the `workflowExecutionId`** for audit trails and troubleshooting.

**Handle REVIEW outcomes** by routing to your compliance team with the full flag context rather than auto-declining.

**Monitor conversion rates** by workflow path. If step-up abandonment is high, review your biometric capture UX or threshold settings.

**Tune thresholds gradually** based on observed fraud rates and false positive feedback.

## Troubleshooting

| Issue                                 | Likely Cause                 | Resolution                                   |
| ------------------------------------- | ---------------------------- | -------------------------------------------- |
| All users getting `REVIEW` result     | Risk score threshold too low | Increase threshold or adjust factor weights  |
| `FRAUD_EMAIL_ADDRESS` false positives | Legitimate domains flagged   | Review email risk rules with FrankieOne      |
| `KYC` step showing `NOT_FOUND`        | No data source matches       | Ensure correct document details provided     |
| High `fraud_email` scores             | Risky domain patterns        | Check if corporate domains need whitelisting |
| `RISK_THRESHOLD_HIGH` on valid users  | Cumulative scores too high   | Review individual factor weights             |
| Missing `fraud_phone_number` result   | Phone format issue           | Ensure phone includes country code           |

## Ongoing CDD and Monitoring

PASS/REVIEW/FAIL outcomes can be combined with periodic reviews and ongoing monitoring rules to help customers keep pace with evolving AUSTRAC expectations around ongoing CDD.

**Consider configuring:**

* Triggers for refresh (e.g., profile changes, new PEP/adverse media hits)
* Periodic re-verification based on customer risk rating
* AML screening and fraud signals to inform ongoing risk rating over the customer lifecycle

Fraud and cyber signals are increasingly relevant to both financial crime risk and broader AML/CTF expectations and can be integrated into your overall ML/TF risk assessment.

## Regulatory Context (Australia)

This guide is designed for reporting entities operating under Australia's AML/CTF framework and is aligned to current AUSTRAC guidance.

Australian AML/CTF laws are undergoing reform, including a move to a single, risk-based customer due diligence obligation and expanded coverage of additional sectors (tranche 2).

FrankieOne does not provide legal or regulatory advice. Reporting entities should obtain their own advice and configure workflows in line with their AML/CTF programs.

## Next Steps

* Review the [Fraud Checks Guide](https://docs.frankieone.com/docs/fraud-checks-guide) for signal collection details
* See [Interpreting Workflow Results](https://docs.frankieone.com/docs/interpreting-workflow-results) for complete field reference
* Review the [KYC Banking Use Case](https://docs.frankieone.com/docs/kyc-banking) for banking-specific implementation
* Contact your FrankieOne representative to configure custom thresholds and CDD tier routing


# Standard Workflow Bundles
Source: https://docs.frankieone.com/docs/standard-kyc-bundles

Explore our out-of-the-box workflow solutions designed to get you started with best-practice compliance quickly.

## Out-of-the-Box Workflow Solutions

FrankieOne offers a suite of standard workflow bundles designed to address the most common KYC and AML compliance needs across different regions. These pre-configured workflows allow for rapid integration, enabling you to implement a best-practice verification process without the need for custom configuration.

To use a bundle, simply reference its **Workflow Name** when executing a workflow via the API.

### Choosing Your Bundle Type

Our bundles are generally categorized into two types to match your risk appetite:

* **Essential Bundles:** Designed for standard customer due diligence. These workflows provide foundational identity verification and AML screening, perfect for meeting core compliance requirements for low-to-medium risk customers.
* **Enhanced Bundles:** Designed for higher-risk environments. These workflows include more stringent checks, such as mandatory document verification, biometric checks, and screening against adverse media, providing a higher level of identity assurance.

***

## Australian (AU) Bundles

Our most comprehensive range of bundles is designed to meet Australian AML/CTF requirements.

### Essential AU Bundles

<AccordionGroup>
  <Accordion title="AU Essential Identity">
    A foundational check ideal for low-risk digital onboarding. This workflow verifies a single government ID against the DVS and performs standard AML screening.

    * **Workflow Name:** `AUS-Basic1V-IDOnly`
    * **Use Case:** Verifying customers with a government-issued ID like a passport or driver's license.
    * **Ruleset:** `gov_id_only`
    * **Core Checks:** Government ID Check, AML (PEP & Sanctions) Screening, Risk Assessment.
  </Accordion>

  <Accordion title="AU Essential Identity – Two Sources">
    A standard electronic verification workflow that matches customer data against two independent electronic sources, with an optional government ID check.

    * **Workflow Name:** `AUS-Basic2V-TwoPlus`
    * **Use Case:** Meeting standard 2+2 verification requirements without mandating a document scan.
    * **Ruleset:** `two_plus`
    * **Core Checks:** KYC (2+2), AML (PEP & Sanctions) Screening.
    * **Primary Data Sources:** Credit Bureau 1, Credit Bureau 2.
  </Accordion>

  <Accordion title="AU Essential Identity – Two Sources & ID">
    Combines a 2+2 electronic check with a mandatory government ID verification for a higher level of assurance.

    * **Workflow Name:** `AUS-Basic2V-TwoPlusID`
    * **Use Case:** Onboarding customers where both electronic data and a government ID are required.
    * **Ruleset:** `two_plus_gov_id`
    * **Core Checks:** Government ID Check, KYC (2+2), AML (PEP & Sanctions) Screening.
    * **Primary Data Sources:** Government Data Source, Credit Bureau 1, Credit Bureau 2.
  </Accordion>

  <Accordion title="AU Essential Identity – Three Sources">
    An extensive electronic check using three independent data sources for customers who may have a thinner credit file or for when a higher degree of confidence is required.

    * **Workflow Name:** `AUS-Basic3V-TwoPlus`
    * **Use Case:** Achieving a 2+2 match when the initial two sources do not yield a result.
    * **Ruleset:** `two_plus`
    * **Core Checks:** KYC (2+2), AML (PEP & Sanctions) Screening, Risk Assessment.
    * **Primary Data Sources:** Credit Bureau 1, Credit Bureau 2, Additional Data Source.
  </Accordion>
</AccordionGroup>

### Enhanced AU Bundles

<AccordionGroup>
  <Accordion title="AU Enhanced Identity">
    A robust check for higher-risk customers, mandating a Government ID verification and screening for adverse media in addition to standard AML checks.

    * **Workflow Name:** `AUS-Advanced1V-IDOnly`
    * **Use Case:** Onboarding high-value customers or those in regulated industries requiring deeper screening.
    * **Ruleset:** `gov_id_only`
    * **Core Checks:** Government ID Check, IDV (Liveness/Biometrics), Enhanced AML (Adverse Media) Screening.
  </Accordion>

  <Accordion title="AU Enhanced Identity – Three Sources & ID">
    Our most thorough verification bundle for the highest-risk scenarios. It mandates a government ID check, biometrics, enhanced AML screening, and verifies against three independent electronic sources.

    * **Workflow Name:** `AUS-Advanced3V-TwoPlusID`
    * **Use Case:** For customers requiring the highest level of due diligence and identity assurance.
    * **Ruleset:** `two_plus_gov_id`
    * **Core Checks:** Government ID Check, KYC (2+2), Biometrics, Enhanced AML (Adverse Media) Screening, Risk Assessment.
    * **Primary Data Sources:** Government Data Source, Credit Bureau 1, Credit Bureau 2, Additional Data Source.
  </Accordion>

  <Accordion title="AU Age Verification">
    A specialised workflow for age verification, designed for businesses that need to verify a customer is above a certain age (e.g., 18+) by confirming their date of birth against multiple reliable data sources.

    * **Workflow Name:** `AUS-Basic3V-AgeVerify`
    * **Use Case:** Verifying age for age-restricted products/services (gambling, alcohol, etc.)
    * **Ruleset:** `two_plus_age`
    * **Core Checks:** KYC (Age Verification), AML (PEP & Sanctions) Screening, Risk Assessment.
    * **Primary Data Sources:** Credit Bureau 1, Credit Bureau 2, Additional Data Source.
    * **Verification Logic:** Requires either **(2x Name AND 2x DOB)** OR **(2x Name AND 1x DOB AND 1x Address)**.

    **Implementation Best Practices**

    * **Fuzziness Settings:** When using age verification, ensure DOB matching fuzziness is set to 100% for accurate results.
    * **Highest Assurance:** For highest assurance, we recommend including a government ID data source which provides an exact match on Name, DOB, and ID number.
  </Accordion>
</AccordionGroup>

### Risk-Based Onboarding

FrankieOne’s Risk-Based Onboarding model assigns each user a real-time risk score, categorizing them as low, medium, or high risk. This enables you to apply the right level of verification at every step—low-risk users proceed with ease, while higher-risk profiles undergo additional checks like ID validation, biometrics, or sanctions screening.

<img alt="Risk-based onboarding" />

The FrankieOne risk engine uses the customer risk rating model to determine the overall risk a customer may pose based on a consistent set of risk factors specific to a business.

<img alt="Risk Scoring Built into Onboarding Flow" />

<br />

<AccordionGroup>
  <Accordion title="AU Risk-Based CDD – Email & Phone Signals">
    Advanced 2+2 verification with fraud signal assessment via email and phone checks, combined with biometrics and enhanced AML screening for dynamic risk-based onboarding.

    * **Workflow Name:** `AUS-Risk-CDD-Email-Phone`
    * **Use Case:** Medium-risk onboarding where you want to assess fraud signals before performing full verification. Enables step-up flows based on risk level.
    * **Ruleset:** `two_plus`
    * **Core Checks:** Onboarding Fraud (Email & Phone), Biometrics (IDV), KYC (2+2), Government ID Check, Enhanced AML (PEP & Adverse Media) Screening, Blocklist Check.
    * **Risk Assessment:** Evaluates email reputation, phone line type, and combines with KYC results for comprehensive risk scoring.
  </Accordion>

  <Accordion title="AU Risk-Based CDD – Full Fraud Signals">
    Our most comprehensive risk-based bundle including device intelligence, IP analysis, email, and phone signals combined with advanced 2+2 verification, biometrics, and enhanced AML.

    * **Workflow Name:** `AUS-Risk-CDD-Email-Phone-Device-IP`
    * **Use Case:** High-risk environments requiring maximum fraud prevention. Enables sophisticated step-up/step-down flows based on comprehensive fraud and identity signals.
    * **Ruleset:** `two_plus`
    * **Core Checks:** Onboarding Fraud (Email, Phone, Device & IP), Biometrics (IDV), KYC (2+2), Government ID Check, Enhanced AML (PEP & Adverse Media) Screening, Blocklist Check.
    * **Risk Assessment:** Comprehensive fraud detection including device fingerprinting, behavioral biometrics, IP geolocation, VPN detection, and email reputation/tenure.
    * **Requirements:** Requires OneSDK implementation for device and IP signal collection.
  </Accordion>
</AccordionGroup>

#### Understanding Risk-Based Onboarding

Risk-based onboarding workflows adapt verification requirements based on real-time risk signals, enabling you to:

* **Low-Risk Users:** Proceed with minimal friction using standard KYC and AML checks
* **Medium/High-Risk Users:** Trigger additional verification steps such as biometrics, document verification, or enhanced screening
* **Very High-Risk Users:** Block onboarding entirely to prevent fraudulent accounts These workflows assess fraud risk using pre-KYC signals (device, email, phone, IP) before performing costly verification checks, helping you optimize conversion rates while maintaining security and compliance.

***

## International & Other Bundles

### New Zealand (NZL)

<AccordionGroup>
  <Accordion title="NZ Essential Identity">
    A foundational check for New Zealand customers, verifying identity against local data sources and performing AML screening.

    * **Workflow Name:** `NZL-Basic1V-OnePlusOne`
    * **Use Case:** Onboarding customers with a New Zealand residential address.
    * **Ruleset:** `one_plus_one`
    * **Primary Data Sources:** Local Data Source.
  </Accordion>
</AccordionGroup>

### United States (USA)

<AccordionGroup>
  <Accordion title="US Bank Express">
    A streamlined onboarding flow for US customers that leverages a bank data source for fast, secure bank account-based identity verification.

    * **Workflow Name:** `USA-Express`
    * **Use Case:** Express onboarding for US customers by connecting their bank account.
    * **Ruleset:** `us_onboarding`
    * **Primary Data Sources:** Bank Data Source.
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="US One Plus">
    A streamlined onboarding flow for US customers that verifies Name, DOB, Address and or SSN.

    * **Workflow Name:** `USA-Basic1V-OnePlus`
    * **Use Case:** Express onboarding for US customers by connecting their bank account.
    * **Ruleset:** `one_plus`
    * **Primary Data Sources:** Bank Data Source.
  </Accordion>
</AccordionGroup>

### Global (GLB)

<AccordionGroup>
  <Accordion title="International Identity">
    A flexible workflow for verifying customers from various countries where a single electronic data source is sufficient.

    * **Workflow Name:** `GLB-IntlOnePlus`
    * **Use Case:** Basic identity verification for a wide range of non-Australian customers.
    * **Ruleset:** `one_plus`
  </Accordion>

  <Accordion title="Enhanced Risk Screening">
    An AML-focused workflow that screens an individual against PEP, Sanctions, and Adverse Media lists. No KYC checks are performed.

    * **Workflow Name:** `GLB-AMLMedia`
    * **Use Case:** Performing due diligence or risk screening on individuals without needing a full KYC verification.
    * **Ruleset:** `aml_only`
  </Accordion>

  <Accordion title="Address Verification">
    A simple utility workflow that verifies a customer's address against one or more data sources.

    * **Workflow Name:** `GLB-AddressVerify`
    * **Use Case:** Validating a customer's address for purposes like shipping or proof of residence.
    * **Ruleset:** `two_plus_both`
  </Accordion>
</AccordionGroup>


# Supporting Documents Review
Source: https://docs.frankieone.com/docs/supporting-documents-review

Learn how to incorporate manual review of supporting documents into your automated KYC workflows.

## What is Supporting Documents Review?

Supporting Documents Review is a feature that allows your compliance team to manually review and verify documents that fall outside of standard IDV or eKYC checks. This is useful for verifying proof of address, source of funds, or other supplementary evidence required by your compliance policies.

The process bridges manual verification with automated workflows. A compliance officer can approve or reject a document, and that decision is then automatically consumed by a workflow step to determine the outcome of the KYC process, ensuring a complete and auditable trail.

## How It Works

The process involves uploading a supporting document, having an operator review it via an API call, and then executing a workflow that checks for the review outcome.

<Steps>
  <Step title="1. Upload a Supporting Document">
    You upload a document using the standard documents endpoint, but with the `class` set to `SUPPORTING`. When you do this, FrankieOne automatically creates a corresponding check for this document with an initial status of `PENDING_REVIEW`.
  </Step>

  <Step title="2. A Compliance Officer Reviews the Document">
    Your internal compliance team reviews the document. Once they make a decision, your system calls the `PATCH /v2/individuals/{entityId}/documents/{documentId}/status` endpoint to update the document's status to either `APPROVED` or `REJECTED`.
  </Step>

  <Step title="3. Execute a Workflow with the 'Supporting Documents' Step">
    Your workflow must contain the `SUPPORTING_DOCUMENTS_REVIEW` step. When executed, this step checks if at least one supporting document for the entity has been `APPROVED`.
  </Step>

  <Step title="4. Receive the Workflow Outcome">
    The workflow step will return `SUCCESS` if an approved document is found. If no documents are approved, it will return `FAILURE`. This result can then be used to automate the decisioning for the entity's profile.
  </Step>
</Steps>

***

## API Integration Guide

Integrating the Supporting Documents Review feature involves two main API calls: uploading the document and submitting the review decision.

### 1. Uploading a Supporting Document

To begin the process, create a document with the `class` specified as `SUPPORTING`. This is done by making a `POST` request to the `/v2/individuals/{individualId}/documents` endpoint.

The `type` field should specify the kind of supporting document being uploaded. See the table below for supported types.

**Example Request: Uploading a Utility Bill**

```json theme={null}
{
  "document": {
    "class": "SUPPORTING",
    "documentId": "doc-supp-12345-utility-bill",
    "type": "UTILITY_BILL",
    "country": "AUS"
  }
}
```

<Callout icon="thumbtack">
  When this call is successful, a `Process-Result-Object` (PRO) with the class `SUPPORTING_DOC` is automatically created with a `result` of `PENDING_REVIEW`.
</Callout>

<Callout icon="bell">
  **Maximum File Size** Each document attached to an entity can be up to 20MB. Files exceeding this size will be rejected by the system.

  **Supported File Types** When uploading supporting documents, the following file types are supported: `jpeg`, `png`, `gif`, `webp`, `tiff`, `bmp`, `pdf`.
</Callout>

### 2. Submitting a Review Decision

After an internal review, you must submit the decision using the `PATCH /v2/individuals/{entityId}/documents/{documentId}/status` endpoint. This call updates the status of the document's corresponding check.

You must provide the `entityId` and `documentId` in the URL path, and a request body containing a `status` of either `APPROVED` or `REJECTED`, and an optional `reason`.

**Example Request: Approving a Document**

Call `PATCH /v2/individuals/ind-abc-123/documents/doc-supp-12345-utility-bill/status` with the following body:

```json theme={null}
{
  "status": "APPROVED",
  "reason": "Document is clear and details match entity profile."
}
```

***

## Workflow Step Configuration

To use the review decision in your automated checks, you must add the `SUPPORTING_DOCUMENTS_REVIEW` step to your workflow.

* **Logic**: This step checks for any `SUPPORTING_DOC` checks associated with the entity.
* **Success Condition**: The step will return `SUCCESS` if **at least one** supporting document has been `APPROVED`.
* **Failure Condition**: If no documents have been approved (i.e., they are all `PENDING_REVIEW` or `REJECTED`), the step will return `FAILURE`.
* **Skipped Condition**: If no supporting documents have been uploaded for the entity, the step will be `SKIPPED`.

### Example Workflow Result

Here is an example of the `workflowStepResult` object you would receive after a workflow containing the `SUPPORTING_DOCUMENTS_REVIEW` step has been executed for an entity with an approved document.

```json theme={null}
{
  "workflowStepResults": [
    {
      "stepName": "SUPPORTING_DOCUMENTS_REVIEW",
      "result": "SUCCESS",
      "processResults": [
        {
          "provider": "MANUAL",
          "objectType": "SUPPORTING_DOC",
          "class": "KYC",
          "result": "APPROVED",
          "checkDate": "2025-10-15T08:15:30.000Z",
          "data": {
            "documentId": "doc-supp-12345-utility-bill",
            "reason": "Document is clear and details match entity profile."
          }
        }
      ]
    }
  ]
}
```

### Supported Document Types

The `type` field for `SUPPORTING` class documents can be one of the following values:

| Document Type      | Code                 |
| ------------------ | -------------------- |
| Utility Bill       | `UTILITY_BILL`       |
| Bank Statement     | `BANK_STATEMENT`     |
| Tenancy Agreement  | `TENANCY_AGREEMENT`  |
| Correspondence     | `CORRESPONDENCE`     |
| Certified Document | `CERTIFIED_DOCUMENT` |
| Other              | `OTHER`              |

<Callout icon="bell">
  ##### Workflow Issues

  * If a document is `REJECTED`, an issue with the code `SUPPORTING_DOCUMENT_REJECTED` is raised on the entity profile.
  * If documents have been uploaded but are awaiting review when the workflow is run, an issue with the code `SUPPORTING_DOCUMENT_PENDING` is raised.
</Callout>


# Thai Documents
Source: https://docs.frankieone.com/docs/thai-documents-v2



The FrankieOne KYC v2 API supports some Thai documents for identity verification. This guide provides details on how to handle these documents effectively.

## Supported Thai Documents

The FrankieOne KYC v2 API supports the following Thai documents:

| Document    | Code          |
| :---------- | :------------ |
| National ID | `NATIONAL_ID` |

***

### National ID (บัตรประจำตัวประชาชน)

National ID Cards (บัตรประจำตัวประชาชน) are official identification documents issued by the Thai government that confirm an individual's identity and citizenship. They include personal details such as the individual's name, date of birth, ID card number, and expiration date.

**Required Fields**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                                             |
      | :------------ | :------------ | :---------------------------------------------------------------------------------------------------------------- |
      | Country       | `country`     | Must be set to `THA`                                                                                              |
      | Date of Birth | `dateOfBirth` | Must be in `YYYY-MM-DD` format                                                                                    |
      | Document Type | `type`        | Must be `NATIONAL_ID`                                                                                             |
      | Name          | `name`        | Enter the full name exactly as it appears on the National ID card, including all given, middle, and family names. |
    </Tab>

    <Tab title="ID Details">
      | Field Name     | Field                 | Notes                                                                                        |
      | :------------- | :-------------------- | :------------------------------------------------------------------------------------------- |
      | Thai ID Number | `primaryIdentifier`   | Enter the 13-digit Thai National ID number exactly as shown on the card.                     |
      | Laser Code     | `secondaryIdentifier` | Enter the laser code exactly as shown on the back of the card. This value is case-sensitive. |
    </Tab>
  </Tabs>
</Card>

<AccordionGroup>
  <Accordion title="Thai National ID Number Format">
    Thai National ID numbers are 13 digits long and follow a specific structure:

    * **1st digit:** Registration category
    * **2nd–5th digits:** Province or office code
    * **6th–12th digits:** Personal unique number
    * **13th digit:** Check digit (used for validation)

    **Example:** `1-2345-67890-12-3`
  </Accordion>

  <Accordion title="Laser Code Details">
    The laser code is an alphanumeric identifier printed on the back of the Thai National ID card. It is used as an additional security feature and must be entered exactly as shown, including case sensitivity.

    **Example:** `JT0-1234567-89`
  </Accordion>
</AccordionGroup>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Document class must be 'IDENTITY' for KYC checks
    "documentId": "92de15f64-5717-4562-b3fc-2c963f6665a7", // Unique identifier for this document in FrankieOne system
    "primaryIdentifier": "000734130", // 13-digit Thai National ID number (must match the card exactly)
    "secondaryIdentifier": "q12313124", // Laser code from the back of the card (case-sensitive, must match exactly)
    "type": "NATIONAL_ID", // Document type code for Thai National ID
    "country": "THA" // Country code for Thailand (ISO 3166-1 alpha-3)
  }
}
```

<Callout icon="bell">
  ##### Important Considerations for Thai National ID

  To ensure successful verification, pay attention to these common issues:

  * The **ID number** must be exactly 13 digits and pass the official checksum validation.
  * **Names** must match the ID card exactly, including spelling, order, and spacing. Support Thai characters to prevent transcription errors.
  * The **date of birth** must be in `YYYY-MM-DD` format.
  * The **laser code** must be entered exactly as shown on the back of the card, including case sensitivity.
</Callout>


# United States Documents
Source: https://docs.frankieone.com/docs/usa-documents-v2



The FrankieOne KYC v2 API supports some United States documents for identity verification. This guide provides details on how to handle these documents effectively.

## Supported United States Documents

The FrankieOne KYC v2 API supports the following United States documents:

| Document    | Code          |
| :---------- | :------------ |
| National ID | `NATIONAL_ID` |

***

### US National ID Card (SSN)

United States National ID Cards are official identification documents issued by the United States government that confirm an individual's identity and citizenship. They include personal details such as the individual's name, date of birth, ID card number, and expiration date.

<Info>
  ##### Note on National ID in the USA

  For the United States, the NATIONAL\_ID document type in the FrankieOne KYC v2 API primarily facilitates the verification of a Social Security Number (SSN), as the U.S. does not issue a single, standardized physical 'National ID Card.' This type is used when the SSN is provided for identity corroboration.

  * **Social Security Number (SSN):** While not a physical ID card, the SSN is a unique nine-digit number essential for employment, taxation, and accessing government or financial services.
</Info>

**Required Fields**

<Card>
  <Tabs>
    <Tab title="Basic Information">
      | Field Name    | Field         | Notes                                                                                                       |
      | ------------- | ------------- | ----------------------------------------------------------------------------------------------------------- |
      | Country       | `country`     | Must be set to `USA`.                                                                                       |
      | Date of Birth | `dateOfBirth` | Required. Format must be `YYYY-MM-DD`.                                                                      |
      | Document Type | `type`        | Must be `NATIONAL_ID`.                                                                                      |
      | Name          | `name`        | Enter the full legal name as shown on the official document, including all given, middle, and family names. |
      | Email         | `email`       | Optional. If provided, must be a valid email address in standard format.                                    |
      | Phone Number  | `phoneNumber` | Optional. If provided, must be a valid US phone number, including area code.                                |
      | Address       | `address`     | Optional. If provided, include street, city, state, and ZIP code as listed on the document.                 |
    </Tab>

    <Tab title="ID Details">
      | Field Name         | Field               | Notes                                                                                                          |
      | ------------------ | ------------------- | -------------------------------------------------------------------------------------------------------------- |
      | Primary Identifier | `primaryIdentifier` | Enter the full Social Security Number (SSN) or other official ID number exactly as it appears on the document. |
    </Tab>
  </Tabs>
</Card>

**Example Document Structure**

```json theme={null}
{
  "document": {
    "class": "IDENTITY", // Document classification type
    "documentId": "92de15f64-5717-4562-b3fc-2c963f6665a7", // Unique document identifier in FrankieOne system
    "primaryIdentifier": "000734130", // Social Security Number (SSN) or official ID number
    "type": "NATIONAL_ID", // Document type code
    "country": "USA" // Country code
  }
}
```

<Callout icon="bell">
  ##### Important Considerations for National ID

  **Common validation issues to avoid:**

  * Incorrect order or casing of names
  * Missing or improperly formatted date of birth (`YYYY-MM-DD`)
  * Providing an invalid or incomplete Social Security Number (SSN) or ID number
</Callout>


# Classify activities and alerts
Source: https://docs.frankieone.com/v2/docs/tm/classifying-activities-and-alerts

This guide explains the two classification operations in the Transaction and Activity Monitoring API: classifying an activity by applying tags to it, and resolving an alert by setting its manual status together with the tags. It is written for developers and for fraud or compliance teams building against the API.

## Activity classification compared with alert classification

These are two separate operations. Use the one that matches your intent. Applying a tag to an activity is not the same as resolving the alert that the activity raised.

| Operation                | What you act on                                                        | What it records                                                                                                                                             |
| ------------------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Classify an activity** | The activity itself                                                    | Applies one or more `ACTIVITY`-domain tags (for example, a fraud typology) and sends feedback to the monitoring provider. Does not set a resolution status. |
| **Resolve an alert**     | A flagged [Process Result (PRO)](/v2/docs/tm/concepts-and-definitions) | To resolve an alert and set its manual status, see [Resolve alerts and re-evaluate](/v2/docs/tm/implementation-resolve-reevaluate).                         |

### How activity classification works

Some rules apply to both operations; others are specific to resolving an alert or to classifying an activity. Tags are applied from the FrankieOne-managed catalogue — you cannot create, rename, or delete catalogue tags through this API, and only active tags can be applied.

<Note>
  The rules below cover both operations for reference. The endpoint on this page is **Classify an activity** only. For the alert resolution endpoint, see [Resolve alerts and re-evaluate](/v2/docs/tm/implementation-resolve-reevaluate).
</Note>

When you classify an activity, FrankieOne sends the outcome to the monitoring provider.

**Applies to both**

* **Every operation is recorded in the audit log**, with the actor, timestamp, and outcome. This includes tag changes and any feedback sent to the monitoring provider.
* **An optional `comment`** can be attached to either operation and is stored as part of the audit trail.
* **Access is validated against your account.** If a tag or record ID does not exist, or belongs to another account, the API returns `404`. The response does not indicate whether the record exists. This prevents information disclosure.
* **Provider feedback never blocks the operation.** Where feedback is sent to the monitoring provider, a delivery failure does not roll back the tag or status change.

**Alert resolution only**

* **Tags applied to an alert cascade to its associated activity.** The activity inherits the alert's tags.
* `manualStatus `**is required.** **Tags are optional**. Tags are supplementary and record why a decision was made.
* The `FALSE_POSITIVE` and `IN_REVIEW` outcomes apply to alerts only. They are review states for the alert, not the underlying activity, and do not cascade to the activity.
* **Removing a tag from an alert does not remove it from the activity.** Activity tags must be removed separately.
* **Tag intent cannot be mixed.** A request must not combine `FALSE_POSITIVE`- or `IN_REVIEW`-category tags with tags of any other category; the request is rejected with `400`. Duplicate tag IDs are removed automatically.
* **Feedback is sent automatically** to the monitoring provider as part of resolving the alert.

**Activity classification only**

* **Tags are required.** An activity has no status field: applying a tag is itself the classification, so a request must include at least one.
* **Activities carry** `TRUE_POSITIVE `**classifications only.** `FALSE_POSITIVE` and `IN_REVIEW` are alert concepts and cannot be applied directly to an activity. To undo a `TRUE_POSITIVE` classification, remove the tag — no "false positive" tag is stored in its place.
* **Tags applied directly to an activity do not cascade to any alert.** (This is the reverse of alert resolution, where tags cascade down to the activity.)
* **The request is atomic and idempotent.** If any activity or tag ID is invalid, the entire request fails and no tags are applied. Re-applying a tag an activity already has updates the existing classification rather than creating a duplicate. However, feedback is re-sent to your monitoring provider on every request, even if the tags have not changed.
* **Feedback reflects the tags on the activity.** A `TRUE_POSITIVE` classification signals the activity as fraudulent to the monitoring provider; removing all `TRUE_POSITIVE` classifications signals it as not fraudulent. Feedback is triggered only when the activity's tags are updated.
* **FrankieOne always saves the classification to its data stores**, even if feedback delivery to the provider fails. On the FrankieOne side, tags can be applied and removed. Feedback delivered to the provider is immutable at the provider end.
* A request must not combine a `FALSE_POSITIVE` category tag with any other category. Violations are rejected with `422`.

## Classify an activity

Applying tags labels the activity itself — for example, marking it as a known fraud typology. The tags in `tagIds` are applied to every activity listed in `activityIds`.

### Before you begin

* **The entity exists:** Activities are tied to an entity that already exists in the FrankieOne platform.
* **The activities exist:** You classify activities that were previously submitted through [Evaluate an activity](/v2/docs/tm/implementation-evaluate-activity). You need their activity IDs.
* **The tags exist and are in the** `ACTIVITY `**domain:** Each tag must exist, be accessible to your account, and have the domain `ACTIVITY`. See [Tags and Reasons reference](/v2/docs/tm/tags-and-reasons-reference) for the full list of available tags.
* `X-Frankie-Username `**is optional:** If provided, it identifies the actor in the audit log.

### Endpoint

`POST /v2/activities/classify`

### Request body

<ParamField type="string">
  The entity that owns the activities being classified, as a UUID.
</ParamField>

<ParamField type="string[]">
  The activities to classify, as ULIDs. Minimum one. Every ID must exist and belong to `entityId`.
</ParamField>

<ParamField type="string[]">
  The tags to apply, as UUIDs. Minimum one. Every tag must exist, be accessible to your account, and have the domain `ACTIVITY`. The first tag is treated as the primary.

  <Note>
    **Tag ordering matters:** The first tag in `tagIds` is treated as the primary classification by the monitoring provider. Order your tags accordingly.
  </Note>
</ParamField>

<ParamField type="object">
  An optional comment recorded in the audit log for this classification.

  <Expandable title="comment properties">
    <ParamField type="string">
      The comment text.
    </ParamField>

    <ParamField type="string">
      The entity the comment relates to, as a UUID.

      <Note>
        The `entityId` inside the comment does not need to match the top-level `entityId`. The system uses the top-level `entityId` for the classification. Set the comment's `entityId` to the same value unless you have a specific reason not to.
      </Note>
    </ParamField>

    <ParamField type="string">
      The entity type — for example, `INDIVIDUAL` or `ORGANIZATION`.
    </ParamField>
  </Expandable>
</ParamField>

### Example request

```bash theme={null}
curl -X POST \
  'https://api.uat.frankie.one/v2/activities/classify' \
  -H 'accept: application/json' \
  -H 'api_key: YOUR_API_KEY' \
  -H 'X-Frankie-CustomerID: YOUR_CUSTOMER_ID' \
  -H 'X-Frankie-Username: example@frankieone.com' \
  -H 'Content-Type: application/json' \
  -d '{
    "entityId": "{{entityId}}",
    "activityIds": [
      "{{activityId}}",
      "{{activityId}}"
    ],
    "tagIds": [
      "{{tagId}}"
    ],
    "comment": {
      "text": "Confirmed romance scam pattern after manual review.",
      "entityId": "{{entityId}}",
      "entityType": "INDIVIDUAL"
    }
  }'
```

### Example response

A `201 Created` response confirms that every activity was tagged and, where configured, feedback was sent to the monitoring provider. The `mappings` array groups the applied tags by activity.

```json theme={null}
{
  "requestId": "01HN9XHZN6MGXM9JXG50K59Q85",
  "mappings": [
    {
      "objectId": "01JN2YRZK8ABCD1234EXAMPLE",
      "objectType": "ACTIVITY",
      "tags": [
        {
          "mappingId": "12345678-1234-1234-1234-123456789012",
          "tagId": "12345678-1234-1234-1234-123456789012",
          "label": "ROMANCE_SCAM",
          "category": "FRAUD",
          "type": "SYSTEM",
          "domain": "ACTIVITY"
        }
      ]
    }
  ]
}
```

Within each activity, tags are returned newest first (by the time the mapping was created).

For error response structures and common status codes, see [Error handling](/v2/docs/tm/implementation-error-handling).

## Related pages

* [Resolve alerts and re-evaluate](/v2/docs/tm/implementation-resolve-reevaluate) — set the manual outcome of a flagged result and re-run the workflow.
* [Evaluate an activity](/v2/docs/tm/implementation-evaluate-activity) — submit an activity for monitoring before you classify it.
* [Reviewing activities](/v2/docs/tm/features-reviewing-activities) — review activity history and classify activities in the FrankieOne Portal.


# Key Terms and Definitions
Source: https://docs.frankieone.com/v2/docs/tm/concepts-and-definitions

This page defines the key terms used across FrankieOne Fraud and Transaction Monitoring. Use it as a reference when reading the Implementation Guide, Features Guide, or API documentation.

## Common terms

| Term                                         | Definition                                                                                                                                                                                                                                                        | Notes / Relationships                                                                                                        |
| :------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
| **Entity**                                   | A customer represented in FrankieOne. Can be an Individual or Organization. Identified by a unique **Entity ID**.                                                                                                                                                 | Anchor for risk, activities, accounts, and alerts.                                                                           |
| **Individual (entity)**                      | A person represented in FrankieOne, usually created via onboarding or import.                                                                                                                                                                                     | Most current flows focus on Individuals.                                                                                     |
| **Entity ID**                                | Unique FrankieOne identifier for an entity (Individual or Organization).                                                                                                                                                                                          | Used to join activities, accounts, alerts and workflows.                                                                     |
| **Workflow (general)**                       | Configured sequence of steps FrankieOne runs for an entity (onboarding or monitoring).                                                                                                                                                                            | Workflows drive when and how risk checks run.                                                                                |
| **Onboarding workflow**                      | Workflow type used for KYC/KYB and onboarding fraud checks.                                                                                                                                                                                                       | Shares core concepts (steps, PROs, feedback) with monitoring workflows.                                                      |
| **Onboarding Fraud**                         | Fraud prevention at onboarding, screening phone, email, device, and behavioral signals.                                                                                                                                                                           | One of two products under Fraud and Transaction Monitoring, alongside Transaction and Activity Monitoring.                   |
| **Transaction and Activity Monitoring (TM)** | TM refers to the Transaction and Activity Monitoring product, also referred to as Transaction Monitoring in navigation and headings. The full name — Transaction and Activity Monitoring — is used in API and technical contexts.                                 | TM is the standard abbreviation for the product. TxAM appears only in the technical bundle identifier Basic-Monitoring-TxAM. |
| **Monitoring workflow**                      | Workflow type used for ongoing transaction and activity monitoring (AML, Fraud, Events).                                                                                                                                                                          | Reuses same workflow engine as onboarding with monitoring-specific steps.                                                    |
| **Workflow step**                            | Single executable unit inside a workflow (for example, device check, fraud TM step, AML TM step, event monitoring).                                                                                                                                               | Each step can produce one or more PROs and activity results.                                                                 |
| **workflowExecutionId**                      | Unique identifier for a single run of a workflow for an entity.                                                                                                                                                                                                   | Used to trace the full run, including all steps and PROs.                                                                    |
| **workflowName**                             | Logical name for a workflow (for example, “Onboarding – Retail”, “TM – AML-Fraud”).                                                                                                                                                                               | Used in config, analytics, and reporting.                                                                                    |
| **Process Result (PRO) / Alert**             | Core result object from running a workflow step. PRO stands for Process Result and represents an alert in FrankieOne.                                                                                                                                             | PRO ID = alert ID; holds risk details, status, related activities.                                                           |
| **Transaction ID / transactionIdentifier**   | External or provider transaction identifier                                                                                                                                                                                                                       | Used for debugging, grouping, and feedback.                                                                                  |
| **Session key (sessionKey)**                 | Identifier for a device / session context for an activity.                                                                                                                                                                                                        | Critical for device and behavioral risk signals and linking related events.                                                  |
| **Account**                                  | Logical representation of a customer account (for example, bank account, card, wallet) associated with an entity.                                                                                                                                                 | Account properties can be used as risk factors.                                                                              |
| **Account external reference**               | Client’s identifier for an account in their own system.                                                                                                                                                                                                           | Used for reconciliation and mapping to FrankieOne accounts.                                                                  |
| **Account metadata**                         | Additional attributes on the account (for example, account type, VIP flag, product tier).                                                                                                                                                                         | Treated as risk factors and can influence monitoring decisions.                                                              |
| **Custom attributes (general)**              | Client-defined key–value pairs added to entities, activities, accounts or alerts.                                                                                                                                                                                 | Used to enrich data and as optional risk factors.                                                                            |
| **Entity custom attributes**                 | Custom attributes attached to an entity (for example, risk segment, customer tier, KYC channel, referral source).                                                                                                                                                 | Can affect risk assessments and segmentation.                                                                                |
| **Activity custom attributes**               | Custom attributes attached to an activity (for example, merchant category, campaign ID, promo code, channel).                                                                                                                                                     | Used heavily in TM to contextualize transactions and events.                                                                 |
| **Risk assessment**                          | The process where FrankieOne evaluates the risk of an entity, activity, or account using provider signals and risk handlers.                                                                                                                                      | Outputs a normalized FrankieOne risk level used by both products.                                                            |
| **Risk handler**                             | Backend logic that ingests provider signals and maps them into FrankieOne risk factors and outcomes.                                                                                                                                                              | Same framework used; triggered at different stages (onboarding vs monitoring).                                               |
| **Risk factor**                              | Input used during risk assessment, such as device signals, rule hits, behavior patterns, custom attributes, or account metadata.                                                                                                                                  | Shared conceptual list, different subsets may be relevant per product.                                                       |
| **Risk level / risk outcome**                | Normalized risk evaluation (for example, LOW, MEDIUM, HIGH, VERY\_HIGH or internal mappings like UNACCEPTABLE).                                                                                                                                                   | Derived from provider scores.                                                                                                |
| **Alert**                                    | A Process Result (PRO) that has met the risk threshold to require attention. It is generated from an activity evaluation or workflow step. It is distinct from an Issue. An alert is an evaluation output; an issue is a workflow problem requiring intervention. | Central unit of work for analysts/ops teams.                                                                                 |
| **Alert ID**                                 | Identifier for an alert in FrankieOne, typically the **Process Result (PRO) ID**.                                                                                                                                                                                 | Used in UI and APIs for alert management.                                                                                    |
| **Alert class / subclass**                   | Type of alert, such as `ACTIVITY_AML`, `ACTIVITY_FRAUD`, `ACTIVITY_EVENT`.                                                                                                                                                                                        | Enables filtering, routing, and reporting.                                                                                   |
| **Alert status / manualStatus**              | Operational status of an alert (for example, Needs Attention, In Review, True Positive, False Positive).                                                                                                                                                          | Drives analyst workflows and SLAs.                                                                                           |
| **Issue**                                    | A problem raised during a workflow that requires manual review or intervention (for example, an AML alert generates an AML issue). It is distinct from an alert. Issues are workflow-level flags; alerts are risk evaluation outputs.                             |                                                                                                                              |

## Transaction and Activity Monitoring Terms

| Term                           | Definition                                                                                                                                                                                                 | Notes / Relationships                                                                                           |
| :----------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Activity**                   | An event or operation associated with an entity (transactional or non-transactional) that FrankieOne and your provider evaluates.                                                                          | Core object monitored for risk; can generate alerts (PROs).                                                     |
| **Transaction activity**       | Activities representing financial movements (for example, fiat transfer, fiat deposit, fiat withdrawal, card payment, crypto transfer).                                                                    | Primary focus for Transaction and Activity Monitoring v2 workflows.                                             |
| **Event-based activity**       | Non-financial events (for example, account create, login fail, insufficient funds, KYC fail or pass, challenge fail or pass).                                                                              | Important for device/behavior signals and non-transactional fraud.                                              |
| **Activity ID**                | Unique identifier for an activity in FrankieOne                                                                                                                                                            | Used to link activities to PROs (alerts), feedback, and workflows.                                              |
| **Activity request ID**        | Client-supplied identifier for an activity request, used for idempotency and tracking.                                                                                                                     | Helps reconcile client systems with FrankieOne activities.                                                      |
| **Activity custom attributes** | See also: Activity custom attributes in Common terms above.                                                                                                                                                | Used heavily in TM to contextualize transactions and events.                                                    |
| **Alert origination webhook**  | Webhook notifying clients when a new alert is created.                                                                                                                                                     | Includes entity, activity/activities, alert metadata, custom attributes.                                        |
| **Alert resolution webhook**   | Webhook notifying clients when an alert is resolved.                                                                                                                                                       | Includes final status, decision, classifications/reasons when present.                                          |
| **Tag**                        | A label that classifies an activity or alert. Tags are identified by ID and belong to the `ACTIVITY` domain. Each tag has a label, category (for example, `FRAUD`, `FALSE_POSITIVE`, `IN_REVIEW`).         | API-level concept. In the Portal, tags are presented as Reasons.                                                |
| **Reason**                     | The Portal-facing term for a Tag. When you resolve an alert or classify an activity in the Portal, you select one or more Reasons.                                                                         | Reasons and Tags refer to the same underlying object. "Reason" is used in the Portal; "Tag" is used in the API. |
| **Classification**             | The act of applying one or more Tags (or Reasons) to an activity or alert. Classifying an activity records a typology or outcome against it.                                                               | Applied via the classify endpoint (activities) or the resolve endpoint (alerts).                                |
| **Cascade**                    | The automatic inheritance of Tags from an alert to its associated activities when the alert is resolved. Only `TRUE_POSITIVE` Tags cascade. `FALSE_POSITIVE` and `IN_REVIEW` Tags apply to the alert only. | One-directional: alert to activity. Tags applied directly to an activity do not cascade up to alerts.           |
| **Feedback**                   | A notification sent to the monitoring provider when a classification is applied. Feedback communicates the outcome (for example, true positive or not suspicious) so the provider can update its models.   | Sent automatically. A delivery failure does not roll back the classification in FrankieOne.                     |
| **Re-evaluation**              | A workflow re-run triggered after all alerts for an entity have been resolved. Re-evaluation updates the entity's risk score and workflow status to reflect the resolved alerts.                           | Triggered automatically in the Portal. Via API, you must call the execute workflow endpoint.                    |

## How key objects relate

When FrankieOne evaluates an activity, it produces one or more **Process Results (PROs)** — each representing the outcome of a single check (for example, an AML check or a fraud check). PROs that meet the risk threshold to require attention are surfaced as **alerts** in the FrankieOne Portal.

An **issue** is a separate, distinct object — a problem raised during a workflow that requires manual review or intervention. Issues are created for significant events, such as a high-risk AML transaction  alert or a fraudulent activity, and provide clear guidance on the next steps.

In summary:

| Object                       | What it is                                                                   |
| ---------------------------- | ---------------------------------------------------------------------------- |
| Activity                     | An event or transaction submitted for evaluation                             |
| Process Result (PRO) = Alert | The outcome of evaluating an activity; surfaced when risk thresholds are met |
| Issue                        | A workflow-level problem requiring manual review or intervention             |


# Available products: Fraud and Transaction Monitoring
Source: https://docs.frankieone.com/v2/docs/tm/core-fraud-transaction-monitoring

This page lists the products available in the FrankieOne Fraud and Transaction Monitoring suite. It is intended for developers and product teams evaluating which capabilities apply to their use case. Applies to: FrankieOne Fraud and Transaction Monitoring — v2.

## Available features

The Fraud and Transaction Monitoring solution combines fraud prevention at onboarding with continuous monitoring of ongoing activity. These features are available in v2 of the FrankieOne Fraud and Transaction Monitoring product suite.

<AccordionGroup>
  <Accordion title="Phone and email screening">
    Screens phone numbers and email addresses at onboarding and during activity evaluation to detect suspicious or high-risk contact details before they enter your system.

    **Key benefits**:

    * **Deter fraudulent onboarding**: Prevent bad actors from entering your ecosystem by flagging suspicious contact details early.
    * **Enhance data accuracy**: Ensure the legitimacy of customer contact information.
  </Accordion>

  <Accordion title="Device and behavioral biometrics">
    Analyses device characteristics and user behaviour patterns — including device fingerprinting, IP intelligence, and mouse/typing biometrics — to detect account takeover and bot activity.

    **Key benefits**:

    * **Detect account takeover**: Identify unusual login behavior or session anomalies.
    * **Prevent bot attacks**: Differentiate between human users and automated scripts.
    * **Deepen risk insights**: Gain a comprehensive understanding of the digital footprint associated with an activity.
  </Accordion>

  <Accordion title="Transaction monitoring">
    Evaluates financial transactions (for example, deposits, withdrawals, and transfers) against configurable AML and fraud rulesets to assign a real-time risk score and generate alerts when thresholds are met.

    **Key benefits**:

    * **Real-time risk scoring**: Assigns a dynamic risk score to each transaction, enabling automated decision-making.
    * **Prevent financial loss**: Intercept high-risk transactions before they can cause damage.
    * **Meet AML obligations**: Identify suspicious financial patterns that could indicate money laundering.
  </Accordion>

  <Accordion title="Activity monitoring">
    Continuously monitors non-financial activities (for example, logins, password changes, and account updates) for behavioural anomalies and fraud patterns beyond the initial onboarding process.

    **Key benefits**:

    * **Proactive fraud detection**: Identify evolving fraud patterns and emerging threats.
    * **Build user behavior profiles**: Understand normal user activity to better spot anomalies.
    * **Support ongoing due diligence**: Provide continuous oversight beyond initial onboarding.
  </Accordion>
</AccordionGroup>


# Understanding activity results
Source: https://docs.frankieone.com/v2/docs/tm/features-activity-results



FrankieOne's Transaction and Activity Monitoring (TM) solution actively monitors both financial and non-financial activities against predefined rulesets to identify potential fraud and money laundering risks. This guide will walk you through how to review and manage these results within the FrankieOne Portal.

## Reviewing Transaction and Activity Monitoring check results

<Frame>
  <img alt="Image" />
</Frame>

In the entities table, those with active Transaction and Activity monitoring issues will have an issue marked as **Activity**. To view all of these entities, find the **Issues** filter and select Activity.

<img alt="Issues" />

Select an entity from the filtered results to go to the entity view. This view will display the workflow events tab with the transaction and activity monitoring check results.

## Entity view

### Activity and Alerts

An **activity** is an event or transaction submitted to FrankieOne for evaluation — for example, a bank deposit, a login, or a profile change.

An **alert** is the Portal representation of a Process Result (PRO) generated when an activity meets the risk threshold configured in your monitoring workflow. Alerts indicate a potential fraud or AML concern and require review by a Fraud or Compliance Officer.

Here is how they relate:

* **Activity initiates a check:** An activity (for example, a transaction) triggers a check.
* **Check results in an Alert:** If the check identifies something suspicious based on configured rules, an alert is generated.
* **Alerts are managed:** Fraud and AML officers then manage these alerts, which might involve resolving them, creating a case for further investigation, or assigning them to a colleague.

Essentially, an "activity" is the transaction or event itself, while an "alert" is a notification or flag raised due to the risk assessment of that activity. For full definitions, see [Key Terms and Definitions](/v2/docs/tm/concepts-and-definitions).

### Alerts (Check results)

When the [Evaluate API](/api-reference/activities/evaluate-an-activity) is called and the system detects potential transaction and activity monitoring issues, alerts are generated. These alerts indicate potential fraud or AML concerns that require investigation and resolution. These alerts are categorized into two primary sections:

* **AML transactions and activities** - includes alerts related to suspicious financial transactions (for example, transfers, deposits, withdrawals) and activity patterns that may indicate money laundering or other financial crimes.
* **Fraud transactions and activities** - includes alerts related to fraudulent transactions (for example, unauthorized payments) and high-risk behavioral activities (for example, unusual login attempts and account changes) often associated with account takeover or identity fraud.

#### Collapsed view

The collapsed view provides a high-level summary of the check results. This allows for a quick assessment of outstanding alerts or those currently flagged as 'In Review'. It prominently highlights the specific rules that were triggered during the check, offering immediate insight into the potential risk areas.

<img alt="Collapsed view showing triggered rules summary" />

#### Expanded view

Expanding either the AML Transactions and Activities or Fraud Transactions and Activities section will reveal all individual alerts related to that issue type, along with their detailed information.

<img alt="Expanded view of AML and Fraud transaction alerts" />

#### Show current alerts

**Current alerts** are the alerts in the entity's current monitoring workflow execution: the result of the most recent workflow run. This includes alerts you have already resolved in this run.

* A **resolved alert** stays in the table, sorted to the bottom, until you resolve every current alert and the workflow re-evaluates. See [Resolve alerts and re-evaluate](/v2/docs/tm/implementation-resolve-reevaluate#re-evaluate-the-results) for what changes on re-evaluation.
* **Alerts are sorted** so the ones needing the most attention appear first: **Needs Attention**, then **In Review**, then **True Positive: Reject**, **True Positive: Accept**, and **False Positive**. Within each group, the highest-risk alert is shown at the top. As a result, alerts that still need action appear above alerts already resolved in this run.
* If a section has no current alerts, it shows the message **No new alerts have been raised.**
* An outstanding-alerts counter shows how many alerts still need action. It counts **Needs Attention** and **In Review** alerts.

From here, you can select an alert from the table. This will open up a drawer on the right side showing the details of the alert such as:

<img alt="Alert details drawer showing activity and transaction information" />

* **Activity Details and Triggered Rules**: Specific information about the activity that generated the alert and the rules that were triggered.
* **Transaction Details**: Comprehensive information about the financial transaction, if applicable.
* **Device Signals**: Data related to the device used, such as VPN detection, remote monitoring, and other device intelligence.
* **IP Signals**: Information regarding the IP address, including location and associated risk.
* **Other information** – These are [custom attributes](/v2/docs/tm/implementation-evaluate-activity) (`details.customAttributes` )  that have been set as part of the details object during the evaluation of an activity. This makes additional activity-level information easy to review alongside standard KYC details.

**Transaction display name**

When a transaction has been submitted with a custom `transactionLabel`, the Portal displays that label as the activity type in the following views:

* The **Alerts** table
* The **Alert details** drawer
* The **Activities** table
* The **Associated activities** table
* The **Activity details** drawer

If no custom label was set, the activity type is derived from the transaction's `currencyType` and `transactionType` (for example, `FIAT WITHDRAWAL`).

#### View previously resolved alerts

By default, each monitoring section shows the entity's current alerts, with the ones that still need action sorted to the top. When you need the full picture, the **Include previously resolved** toggle brings in alerts resolved in earlier workflow runs. This helps with audits and with understanding how an entity's risk profile has changed over time.

* Each section (AML and Fraud) has an **Include previously resolved** toggle. It is **off** by default.
* **Previously resolved alerts** are alerts actioned as **True Positive** (Accept or Reject) or **False Positive** in earlier workflow executions
* If a section has no previously resolved alerts, hovering over the toggle shows a tooltip letting you know there are none to display.

<Note>
  **The toggle resets when you leave the page**

  The **Include previously resolved** setting is not saved. If you refresh the page, or navigate away and come back, each section returns to its default view: current alerts only, with the toggle off.
</Note>

### When every alert is resolved

Once all current alerts in a check are resolved, the Portal [re-evaluates the monitoring workflow](/v2/docs/tm/implementation-resolve-reevaluate#re-evaluate-the-results). Those alerts then belong to a completed execution, and the new current execution has no alerts left to action. The alerts table is hidden and the outstanding counter shows zero. You can still review the entity's history at any time by turning on **Include previously resolved**.

For further investigation, select *More details* to open an external link to the provider's system in a new tab. This allows you to delve directly into the raw data or extended context provided by the underlying service.

To learn more on activities and alerts, visit our [Implementation Guide - Transaction and Activity Monitoring](/v2/docs/tm/implementation).


# Analytics dashboard
Source: https://docs.frankieone.com/v2/docs/tm/features-analytics

This guide explains the analytics dashboard available to Fraud and Compliance Officers in the FrankieOne Portal. The dashboard provides operational metrics and reporting insights for Transaction and Activity Monitoring (TM).

# Accessing the dashboard

The [analytics dashboard](/docs/dashboard) is accessible from the main navigation in the FrankieOne Portal. TM metrics are displayed in the Activity tab.

**Applies to:** FrankieOne Fraud and Transaction Monitoring — v2

**Required permission:** Access analytics dashboard

# Activity tab

The **Activity** tab provides operational metrics for Transaction and Activity Monitoring (TM). Use this tab to monitor alert volumes, review resolution performance, and assess the effectiveness of your monitoring rules over time.

## Available metrics

| Metric                                    | Description                                                                                                                                |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Average time to review and resolve alerts | The average time taken to resolve a closed alert, calculated from when the alert was created to when it was resolved.                      |
| Daily alerts created                      | The number of new alerts generated per day.                                                                                                |
| Daily alerts closed                       | The number of alerts resolved or closed per day. Closed statuses include True positive: Accept, True positive: Reject, and False positive. |
| Alert Creation and Closure Trends         | Tracks daily alert creation against closure rates to monitor workload balance and identify potential backlogs                              |
| True positive rate                        | The proportion of reviewed alerts that were marked as True positive (Accept or Reject).                                                    |
| False positive rate                       | The proportion of reviewed alerts that were marked as False positive.                                                                      |
| Confirmed fraud rate                      | The proportion of monitored activities that included at least one confirmed fraud alert.                                                   |
| Alerts by status                          | The count of alerts per resolution status per day.                                                                                         |
| Alert Distribution                        | Shows how alerts are distributed by time-to-review bands helping teams quickly spot backlogs and unusually long review times.              |

### Filters

You can filter the Activity tab by date range to focus on a specific time period.


# Resolving alerts
Source: https://docs.frankieone.com/v2/docs/tm/features-resolving-alerts

This guide explains how to resolve alerts in the FrankieOne Portal for Transaction and Activity Monitoring. It covers the resolution workflow, re-evaluation of results, and how to add comments for audit purposes.

## Video Guide

<iframe />

## Resolve alerts

If you have the "Modify transaction and activity alert statuses" permission, you can resolve alerts directly from the alert details drawer. The **Resolve alert** button is located at the bottom-left corner.

<Frame>
  <img alt="Alert details drawer with Resolve alert button at the bottom-left corner" />
</Frame>

<Frame>
  <img alt="Alert marked as resolved with updated status indicator and reasons" title="Resolve activity alert" />
</Frame>

A modal appears, prompting you to select a status, select one or more Reasons, and leave a comment for auditability.

When you select **Resolve alert**, the portal updates the status of the selected alert accordingly.

<Frame>
  <img alt="Alert marked as resolved with updated status indicator" />
</Frame>

<Note>
  **Re-evaluation of results**

  Once all alerts within a specific check have been resolved, the portal will automatically [re-evaluate the monitoring workflow](/v2/docs/tm/implementation-resolve-reevaluate). This updates the entity's risk score and workflow status to reflect the resolved alerts.
</Note>

### Reasons

When you resolve an alert, you record one or more Reasons that explain the decision made.

* **The available Reasons depend on the status you select.** Selecting a status filters the list to the Reasons that apply to that outcome. For the full list of available Reasons, see [Tags and Reasons reference](/v2/docs/tm/tags-and-reasons-reference).
* **You can apply more than one Reason** to a single alert. If you apply more than one Reason to an alert, you will need to select a Focus reason. The Focus reason will be sent to the monitoring provider.
* **True Positive reasons you apply to an alert automatically cascade to the associated activity.** False Positive and In Review reasons apply to the alert only and do not cascade.
* **Reason changes are captured in the audit trail** alongside the status change, so the resolution and the reasons behind it are recorded together for compliance purposes.

### Comments

Comments are recorded each time the status of a specific alert is changed. The comment history displayed in the alert details drawer shows only the comments for the **currently selected alert**. When you select a different alert, the comment history updates to reflect that alert's history only.

To view comments for an alert, select the comment icon in the alert details drawer. All comments and status changes for that alert are listed in chronological order.

<img alt="Alert comment history showing all recorded comments" />

All actions are recorded as part of the audit trail for compliance purposes. This includes resolving an alert, changing its status, and adding a comment. You can view these in the audit report.


# Reviewing activities
Source: https://docs.frankieone.com/v2/docs/tm/features-reviewing-activities

This guide explains how to review activity history for an entity in the FrankieOne Portal, find the activity that triggered a specific alert, and investigate associated activities from routine-based alerts.

## Video Guide

<iframe />

The video above demonstrates how to navigate to the Activities tab for an entity, filter by date range, and open the activity detail drawer to review transaction details and triggered rules.

## Viewing all activities

To view all recorded activities and transactions for a given entity or alert, select **View all activities** from the **Workflow events** tab. This will show you a history of all activities recorded for the entity.

<Frame>
  <img alt="Link to All activities page" />
</Frame>

<Frame>
  <img alt="Screenshot showing all activities view" />
</Frame>

## Viewing the activity that caused an alert

<Frame>
  <img alt="View the primary activity" />
</Frame>

From any alert that includes an **Activity ID**, you can:

* Select the **Activity ID** to open the **Activities** page for the relevant entity.
* See the **selected activity** in the Activities table.
* View the **activity details drawer** automatically expanded for that activity.
* Review **all activities that occurred in the 30 days before** the selected activity.
* If needed, you can adjust the date range filters on the Activities page to look further back in time, or narrow down to a shorter investigation window.

<Note>
  **Activity data and entity data**

  The party details shown in the activity details drawer reflect the data that was present at the time the activity was evaluated. If the entity's profile has been updated since the activity was submitted, the activity record retains the original snapshot.

  The most relevant contact data point is selected from the entity's profile using the following logic.

  **For individuals:**

  * **Address:** Residential addresses are preferred, then postal, then any other type. Within each type, the most recently updated address is selected.
  * **Email address and phone number:** The entry marked as preferred (`isPreferred: true`) is selected. If no preferred entry exists, the most recently updated entry is selected.

  **For organizations:**

  * **Address:** Place of Business is preferred, then Registered Office, then any other type. Within each type, the most recently updated address is selected.
  * **Email address and phone number:** Only registry-provided contact data is used. The most recently updated entry is selected.

  This selection determines what is used for the analysis at the time of evaluation.
</Note>

## Associated activities

### What is an associated activity?

You may receive **routine-based or batch alerts** from your provider, where a single routine run often flags a *set* of activities (for example, a velocity pattern, a cluster of withdrawals) rather than a single transaction.

In this case, the latest activity in that set will be flagged as a “Routine” alert, and all activities in that set will be considered “associated activities” to such an alert.

### Reviewing associated activities

<Frame>
  <img alt="Alert details drawer with associated activities" />
</Frame>

In the workflow tab, you may see an alert that might be a routine-based alert. When you select that alert, you will see a link under the **Rules triggered** section showing the number of activities associated with that alert.

Select this link, and you will be redirected to the list of activities associated with this routine alert.

<Frame>
  <img alt="Expanded activity details in side drawer" />
</Frame>

To find the original alert, open any associated activity and you will see a link to the original alert in the activity detail drawer. This will appear in the **All activities** table as well if an activity has been associated with another.

### Viewing alerts linked to an activity

When you open an activity in the activity details drawer, you can see any alerts that are directly associated with that activity. This is available on both the **All activities** page and the **Associated activities** page.

#### Rules triggered by this activity

<Frame>
  <img alt="Image" title="Image" />

  <img alt="Image" title="Image" />
</Frame>

This section shows you all the rules triggered by this specific activity, grouped by alert type. These may show up as separate alerts or a single alert in the workflow tab view. This area will be empty if this activity did not trigger any alerts.

#### Associated alerts involving other activities

<Frame>
  <img alt="Image" title="Image" />
</Frame>

This section shows you alerts this activity is associated with because of a routine alert. This means that this activity is part of a group of activities found from a routine check. Select the alert to view more details and the full list of activities from that routine. This section will be empty if the activity is not associated with other activities from routine alerts.

## Classifying an activity

<iframe />

Reviewing an activity may lead you to classify it. In the Portal, you classify an activity by applying one or more Reasons to it from the activity details drawer.

<Frame>
  <img alt="Activity details drawer showing Reasons applied to the activity" title="Activity details drawer showing Reasons applied to the activity" />

  <img alt="Activity details drawer showing Reasons applied to the activity" title="Activity details drawer showing Reasons applied to the activity" />
</Frame>

<br />

<Frame>
  <img alt="Selecting Reasons to classify an activity" title="Selecting Reasons to classify an activity" />

  <img alt="Selecting Reasons to classify an activity" title="Selecting Reasons to classify an activity" />
</Frame>

* **Activities take true-positive Reasons only.** False positive and In review are alert outcomes and are not applied directly to an activity.
* **An activity can receive Reasons two ways:** applied directly here, or cascaded automatically when you resolve an alert that the activity raised. See [Resolving alerts](/v2/docs/tm/features-resolving-alerts).
* **To remove a classification, remove the Reason from the activity.** When an activity has all of its true-positive reasons removed, the Portal shows it as **Not suspicious**.
* **Reasons applied directly to an activity stay on the activity.** They do not cascade up to any alert — this is the reverse of resolving an alert, where the alert's Reasons cascade down to the activity. Reason changes on an activity are captured in the audit trail with the actor, timestamp, and outcome.


# Introduction to Fraud and Transaction Monitoring
Source: https://docs.frankieone.com/v2/docs/tm/fraud-and-transaction-monitoring-introduction

This page introduces our Fraud and Transaction Monitoring solution — what it does, why you need it, and how it works at a high level. It is the starting point for developers, compliance officers, and product teams looking to understand the solution before moving to implementation or feature guides.

## What is Fraud and Transaction Monitoring?

Protect your business with a comprehensive Fraud and Transaction Monitoring solution that combines fraud prevention at onboarding with continuous monitoring of ongoing activity.

The solution evaluates both non-financial activities (like login and registration) and financial transactions against a default set of dynamic rules to determine fraud and/or money laundering risks. It involves continuously assessing an entity's behavior, device characteristics, and transaction patterns to detect suspicious activity and ensure ongoing protection beyond the initial onboarding process.

### Why you need Fraud and Transaction Monitoring

The solution gives you a competitive advantage by protecting your business, your customers, and your reputation, and its importance extends far beyond simple compliance.

* **Mitigate financial crime**: Uncover and prevent fraudulent transactions and money laundering schemes to protect your organization from financial and reputational harm.
* **Navigate global regulations**: Confidently meet requirements from various financial crime regulations by continuously monitoring suspicious activities, so you can ensure compliance and avoid penalties.
* **Protect customer assets**: Ensure customer accounts and transactions are secure, demonstrating a strong commitment to security and building customer trust with your customers.
* **Improve operational efficiency**: Automate detection and streamline investigation workflows, allowing your team to focus on high-risk cases more effectively.

### How Fraud and Transaction Monitoring works

1. Onboarding fraud checks - You can leverage advanced screening for phone numbers, email addresses, device characteristics, and behavioral biometrics to prevent fraudsters from being onboarded.
2. Continuous activity monitoring - You can continuously evaluate non-financial activities such as logins, password changes and financial transactions such as deposits, withdrawals against dynamic rulesets to detect suspicious behavior.
3. Risk assessment and case resolution - Generate real-time risk scores for entities and activities. In the FrankieOne Portal, you can investigate pending cases, review a complete risk profile for each individual and organization, and resolve them based on your investigation.

## Fraud and Transaction Monitoring Product Suite

The solution offers a comprehensive suite of products designed to work together, providing complete coverage across the entire fraud prevention and monitoring lifecycle.

For a detailed breakdown of each product and how they work together, see [Core Products: Fraud and Transaction Monitoring](/v2/docs/tm/core-fraud-transaction-monitoring), which covers FrankieOne Fraud, FrankieOne Transaction Monitoring, and their integration points.

<Note>
  Our team of compliance and integration experts is ready to help you design and deploy a world-class Fraud and Transaction Monitoring solution. [Contact us today](https://www.frankieone.com/contactus).

  If you are an existing FrankieOne customer, contact your Customer Success Manager or Account Executive to find out more.
</Note>


# Transaction and Activity Monitoring — Implementation Guide
Source: https://docs.frankieone.com/v2/docs/tm/implementation

This guide covers the prerequisites and workflow setup required before integrating FrankieOne Transaction and Activity Monitoring.

# Prerequisites

<Steps>
  <Step title="Integration overview">
    Check out the [integration](/v2/docs/tm/integration) page for an overview of the implementation process.
  </Step>

  <Step title="Workflow configured for transaction and activity monitoring">
    <Accordion title="Confirm your workflow setup">
      Before you can start verifying customers, your account needs to be configured with at least one workflow and one service profile. Your Customer Success Manager typically sets these up for you.

      You can confirm your setup by calling the GET /v2/workflows endpoint. This will list all the executable monitoring workflows available to you. For Transaction and Activity Monitoring, it is critical to have only one workflow with a lifecyclePhase: MONITORING and monitoringTypes: \["ACTIVITY"]

      ### Request - Get workflows

      ```bash theme={null}
      curl --location 'https://api.uat.frankie.one/v2/workflows' \
      --header 'api_key: {{your_api_key}}' \
      --header 'X-Frankie-CustomerId: {{your_customer_id}}'
      ```

      You should receive a 200 OK response with a workflows array. If the array is empty, please contact your Customer Success Manager to get your workflows published.

      ### Response - Get workflows

      ```json theme={null}
      {
        "requestId": "req_01J...",
        "workflows": [
          {
            "serviceName"   : "DEFAULT",
            "workflowId"    : "wf_01J...",
            "workflowName"  : "Monitoring",
            "type"          : "SYSTEM",
            "lifecyclePhase": "MONITORING",
            "monitoringTypes": ["ACTIVITY"]
          }
        ]
      }
      ```
    </Accordion>
  </Step>
</Steps>

## Implementation steps

Once your prerequisites are complete, follow these steps in order.

<Steps>
  <Step title="Evaluate an activity">
    Send a transaction or event to FrankieOne for evaluation using the Evaluate an activity endpoint. This is where you structure your request payload and submit it to the API. [Go to Evaluate an activity](/v2/docs/tm/implementation-evaluate-activity)
  </Step>

  <Step title="Interpret activity results">
    Read the `workflowResult` response to understand the outcome, identify any alerts that were generated, and determine whether manual review is required. [Go to Interpret activity results](/v2/docs/tm/implementation-interpret-results)
  </Step>

  <Step title="Resolve alerts and re-evaluate">
    Update the status of any alerts via the API and trigger a workflow re-evaluation to close out the activity. [Go to Resolve alerts and re-evaluate](/v2/docs/tm/implementation-resolve-reevaluate)
  </Step>
</Steps>

## Error handling

For a full list of error codes and response structures returned at any step, see [Error handling](/v2/docs/tm/implementation-error-handling).

***

## Related pages

* [Key terms and definitions](/v2/docs/tm/concepts-and-definitions) — reference for all TM terminology
* [Workflows and standard bundle](/v2/docs/tm/workflows) — understand the Basic-Monitoring-TxAM bundle
* [Understanding activity results](/v2/docs/tm/features-activity-results) — how to review results in the Portal


# Error handling
Source: https://docs.frankieone.com/v2/docs/tm/implementation-error-handling

This page lists the error codes and response structures returned by the Transaction and Activity Monitoring API, with example payloads for each scenario. 

## Error handling

The FrankieOne API uses a standardized error format to ensure that you can reliably handle issues that arise from bad requests, server problems, or invalid data. All non-2xx responses will return a consistent JSON error object.

For a full list of error types and their meanings, see the [API Error Codes](/docs/reference/error-codes) documentation. This document replaces any specific error handling guides for individual products unless explicitly stated otherwise.

### Scenarios

The error response format is the same across all Transaction and Activity Monitoring API endpoints, including [Evaluate an activity](/v2/docs/tm/implementation-evaluate-activity), [Resolve alerts](/v2/docs/tm/implementation-resolve-reevaluate), and [Classify activities](/v2/docs/tm/classifying-activities-and-alerts). The examples below use the evaluate endpoint, but the response structure applies to all.

### Generic Bad request

**HTTP Status Code : FrankieOne Error Code**

`400 : VAL-0400`

```json theme={null}
{
  "details": [
    {
      "issue": "request body has an error: doesn't match schema #/components/schemas/...",
      "issueLocation": "Request",
      "issueType": "Bad Request"
    }
  ],
  "errorCode": "400",
  "errorMsg": "Bad Request",
  "requestId": "01K8SQNX22ZC66XKHMQ1324RJC"
}
```

### Bad request - Validation issues (Any business or process validation)

**HTTP Status Code : FrankieOne Error Code**

`400 : VAL-0400`

```json theme={null}
{
    "errorCode": "VAL-0400",
    "errorMsg": "Validation failed",
    "details": [
        {
            "issue": "{message}",
            "issueLocation": "{location}"
        }
    ],
    "requestId": "01GVEDZ0C1Q9NWQ699DBBKPE4Y"
}
```

### Bad request - Schema issues

* Invalid limit or page parameter
* `beforeActivityAt` is earlier than `afterActivityAt`
* Invalid sortField other than `activityAt`
* `afterActivityAt` is in the future

**HTTP Status Code : FrankieOne Error Code**

`400 : VAL-0400`

```json theme={null}
{
  "details": [
    {
      "issue": "request body has an error: doesn't match schema #/components/schemas/Evaluate-Activity-Req: Error at \"/activity/detail\": ...",
      "issueLocation": "Request",
      "issueType": "Bad Request"
    }
  ],
  "errorCode": "400",
  "errorMsg": "Bad Request",
  "requestId": "01K8SQNX22ZC66XKHMQ1324RJC"
}
```

<Note>
  Schema validation errors include the full OpenAPI path in the `issue` field, which can be long. Parse `issueLocation` for the affected property.
</Note>

### Bad request - Entity not found

**HTTP Status Code : FrankieOne Error Code**

`400 : VAL-0404`

```json theme={null}
{
    "errorCode": "VAL-0404",
    "errorMsg": "Entity not found",
    "details": [
        {
            "issue": "The specified entity does not exist",
            "issueLocation": "body.party.entityId"
        }
    ],
    "requestId": "01GVEDZ0C1Q9NWQ699DBBKPE4Y"
}
```

### Duplicated transactions

**HTTP Status Code : FrankieOne Error Code**

`409 : VAL-0409`

```json theme={null}
{
  "errorCode": "VAL-0409",
  "errorMsg": "Validation failed",
  "details": [
    {
      "issue": "The transaction with the provided identifier already exists.",
      "issueLocation": "activity.detail.transaction.transactionIdentifier" 
    }
  ],
  "requestId": "01HN9XHZN6MGXM9JXG50K59Q88"
}
```

### System errors

**HTTP Status Code : FrankieOne Error Code**

`500 : SYS-0500`

```json theme={null}
{
    "errorCode": "SYS-0500",
    "errorMsg": "Provider service error",
    "details": [
        {
            "issue": "Failed to evaluate activity",
            "issueLocation": "connector"
        }
    ],
    "requestId": "01GVEDZ0C1Q9NWQ699DBBKPE4Y"
}
```

## More resources

* [Implementation Overview](/v2/docs/tm/implementation) — return to the full implementation map
* [Evaluate an activity](/v2/docs/tm/implementation-evaluate-activity) — check your request payload structure
* [Key terms and definitions](/v2/docs/tm/concepts-and-definitions) — reference for all TM terminology


# Evaluate an activity
Source: https://docs.frankieone.com/v2/docs/tm/implementation-evaluate-activity

This guide explains how to structure and submit an activity evaluation request to the FrankieOne Transaction and Activity Monitoring API.

## Use the Transaction and Activity Monitoring API

Start sending transaction and activity details to FrankieOne by calling the Evaluate an activity endpoint.

<Accordion title="Evaluate activity request">
  ```bash theme={null}
  curl --location 'https://api.uat.frankie.one:443/v2/activities' \
  --header 'X-Frankie-CustomerID: {{your_customer_id}}' \
  --header 'api_key: {{your_api_key}}' \
  --header 'Content-Type: application/json' \
  --data '{
      "activity": {
          "session": {
              "token": "{{session_token}}"
          },
          "party": {
              "entityId": "'"{{entityId}}"'",
              "entityType": "{{entityType}}"
          },
          "detail": {
              "customAttributes": {
                  "transactionRiskScore": {
                    "type": "NUMBER",
                    "value": "750" 
                  },
                  "purposeOfTransaction": {
                    "type": "STRING",
                    "value": "International property purchase"
                  },
                  "sourceOfFunds": {
                    "type": "STRING",
                    "value": "Savings from employment"
                  }
              },
              "activityType": "TRANSACTION",
              "activityAt": "2025-09-02T05:38:02.000360071+00:00",
              "transaction": {
                  "amount": 200000.00,
                  "currency": "AUD",
                  "currencyType": "FIAT",
                  "transferMethod": "BANK_TRANSFER",
                  "counterpartyAmount": 200000.00,
                  "counterpartyCurrency": "AUD",
                  "counterpartyCurrencyType": "FIAT",
                  "counterpartyTransferMethod": "BANK_TRANSFER",
                  "transactionType": "WITHDRAWAL",
                  "description": "Payment for real estate in New York",
                  "account": {
                      "type": "SAVINGS",
                      "pan": "331387321",
                      "hashedPan": "{{hashedPan}}",
                      "maskedPan": "******321",
                      "name": "super saver",
                      "class": "PERSONAL",
                      "externalIdentifier": "{{externalIdentifier}}",
                      "externalIdentifierType": "EXTERNAL_ID_NUMBER"
                  },
                  "merchant": {
                      "merchantIdentifier": "REALESTATEINC001",
                      "industryCodes": [
                          {
                              "code": "6513",
                              "description": "Real Estate Agents and Managers",
                              "type": "MCC"
                          }
                      ]
                  },
                  "transactionIdentifier": "{{transaction_id}}"
              },
              "counterparty": {
                  "entityName": "Global Property Investments LLC",
                  "account": {
                      "type": "SAVINGS",
                      "pan": "123783133",
                      "hashedPan": "{{hashedPan}}",
                      "maskedPan": "******133",
                      "name": "Property Sales Account",
                      "class": "BUSINESS"
                  }
              }
          }
      }
  }'
  ```
</Accordion>

### High-level process flow

<img alt="Activity Evaluation Flow Diagram" />

1. Customer sends transaction / activity data to FrankieOne.
2. FrankieOne will pass the activity data to the service provider
   * FrankieOne checks the entity data store and enrich the customer request with additional data
   * FrankieOne enriches the activity data to the service provider, handling mapping between models
3. Vendor assesses the data provided against Customer rules to make a point-in-time evaluation of the activity risk.
   * All risks, rules checked and additional evaluation data are returned to FrankieOne
   * FrankieOne maps vendor data back to common model
4. FrankieOne will persist the resulting evaluation information
   * Create the activity record
     1. Create the device data retrieved from the provider and store the evaluation data (risk, signals, etc.)
     2. Return the evaluation data to the customer for a final risk-based decisioning
   * **Asynchronous Enhanced Processing** – Push an activity event to the internal message queue for enhanced processing.
     1. The event message is consumed by the internal activity assessment service.
     2. If the activity does not meet the risk criteria to trigger an alert or further assessment, then no further action is taken.
     3. If the activity does meet the risk criteria for an alert, it will retrieve the activity data, and create an assessment result which represents the alert details.
     4. Once done, it will push a message into the workflow engine message queue to trigger relevant monitoring workflows.
     5. Inside the monitoring workflow, the Activity Monitor Step will consume relevant results to build up a view of alerts that should be actioned.
     6. This workflow will also generate risk assessments that combine risk factors across the onboarding and monitoring life cycle phases of the relevant entity.

### The `session` object

Provides a `token` to link together activities within the same end-user session. This is important for identifying grouped activities and contributes to risk calculations by allowing FrankieOne to analyze a sequence of user actions as a single and coherent session. For example, all actions from a user login to a significant transaction can be linked together.

Passing an existing session token from your system ensures that activity linking aligns with your own session model, including longer-running sessions.

### The `party` object

Identifies the individual or organization performing the activity. It's essential for linking the activity to an existing entity in FrankieOne. Key details include:

* `entityId`: The unique identifier for the individual or organization in FrankieOne.
* `entityType`: Specifies whether the party is an INDIVIDUAL or ORGANIZATION.

#### **Overriding party details for an activity**

When you evaluate an activity, you can pass party details — such as address, phone number, or email address — directly in the request payload. These values override the data stored on the entity for the purposes of that evaluation only. The entity's stored data is not modified.

This is useful when the activity involves data that is not yet recorded on the entity, or when the data at the time of the activity differs from the entity's current state.

Additional details like `addresses`, `emailAddresses` and `phoneNumbers` provide additional context for the party's profile for more accurate risk assessment.

Below are the supported override fields in the `party` object:

| Field            | Description                                                                                                        |
| :--------------- | :----------------------------------------------------------------------------------------------------------------- |
| `addresses`      | One or more address objects. Reference an existing address by `addressId`, or provide a new address without an ID. |
| `phoneNumbers`   | One or more phone number objects.                                                                                  |
| `emailAddresses` | One or more email address objects.                                                                                 |
| `name`           | The individual's name. Overrides the entity's stored primary name for this evaluation.                             |
| `dateOfBirth`    | The individual's date of birth.                                                                                    |
| `registeredName` | The organization's registered name (organization entities only).                                                   |

Override data is stored as a snapshot of the party details provided at evaluation time, alongside the activity record. This means:

* The party details returned by Get Activity and Get Activities reflect the data that was present at the time of evaluation, not the current state of the entity.
* If the entity's data changes after an activity is evaluated, the activity record retains the snapshot as it was at evaluation time.
* Party details are stored as encrypted data within the activity record.

### The `detail` object

Contains specific information about the activity being evaluated.

* `activityType` : Categorizes the activity broadly (for example, `TRANSACTION` or `EVENT`).
* `transactionIdentifier` - This field in the payload is only present on `TRANSACTION` activityTypes. Each evaluation requires this to be unique.
* `eventType` : Provides a more granular classification of the activity (such as `LOGIN`, `WITHDRAWAL`, `DEPOSIT`, or `PASSWORD_CHANGE`). This is critical for triggering specific rules relevant to the event.
* `activityAt`: Timestamp of the activity.
* `customAttributes`: Allows you to pass any additional context-specific data that might be relevant for your custom rules.
  * `customAttributes.partyAccount` is an optional string that identifies which **account** the activity relates to.
    * Look for a matching `externalReference` entry where `type = "ACCOUNT"` and the `value` equals `partyAccount`.
    * If exactly one match is found, FrankieOne enriches the evaluation with that account’s metadata, using keys prefixed with `partyAccount` (for example, `partyAccountStatus`, `partyAccountProductType`).
    * If no matching `externalReference` entry is found, no enrichment is applied and the evaluation continues normally.
    * If more than one `ACCOUNT` match is found, the evaluation returns an error.
    * **Note:** Existing custom attributes are never overwritten by enrichment.
* `externalReference`: Allows you to add any other identifiers for the individual or organization from your own system or a third-party system. Some external references are forwarded to the provider for enrichment. These are:
  * `"type": "CUSTOMER"`,`"name": "CUSTOMER-REFERENCE"` - This is an optional external reference. This is treated as an identifier from your own system.
    * When `type: CUSTOMER` and `name: CUSTOMER-REFERENCE` are included in the `externalReference` array of the activity payload, FrankieOne uses that value during evaluation.
    * If not included in the activity payload, FrankieOne falls back to the matching external reference stored on the individual or organization entity (where `type = CUSTOMER` and `name = CUSTOMER-REFERENCE`).

#### **Setting a custom transaction display name**

You can set an optional `transactionLabel` on a transaction to give it a meaningful display name. By default, the display name is inferred from `currencyType` and `transactionType` (for example, `FIAT WITHDRAWAL`). When a label is provided, it replaces this default in the FrankieOne Portal and in downstream fraud analysis.

| Field              | Type   | Required | Max length     |
| :----------------- | :----- | :------- | :------------- |
| `transactionLabel` | string | No       | 128 characters |

Note: This does not affect which fraud checks are run. Check selection continues to be determined by `currencyType` and `transactionType`.

These objects are further detailed in the [API documentation](/api-reference/activities/evaluate-an-activity).

## Next step

Once you have submitted your activity evaluation request, read the response to understand what FrankieOne found: [Interpret activity results](/v2/docs/tm/implementation-interpret-results)


# Interpret activity results
Source: https://docs.frankieone.com/v2/docs/tm/implementation-interpret-results

This guide explains how to read the workflowResult response, understand step outcomes, and identify alerts generated by an activity evaluation.

## Review alerts

Once an activity has been deemed to be alerting, relevant workflows will be triggered and the alerts will be consumed and presented in the workflowResult object. This object is the key to understanding the outcome, the reason for any alerts, and the granular details of the checks performed. Operators will typically review these alerts via the Portal, where issues are flagged for manual review.

### via API

Get the result of the evaluation by calling the [Get Workflow Execution Results](/api-reference/individual-workflows/get-the-result-of-a-specific-execution-by-its-executionid) endpoint. The `workflowResult` object in the response will contain the comprehensive details needed to interpret the outcome.

<Accordion title="Get workflow execution result request">
  ```bash theme={null}
  curl https://api.uat.frankie.one/v2/individuals/{{your_entity_id}}/serviceprofiles/serviceName/workflows/workflowName/executions/workflowExecutionId \
       -H "api_key: X" \
       -H "X-Frankie-CustomerID: {{your_customer_id}}"
  ```
</Accordion>

### via Portal

To learn how Fraud and Compliance Officers can review alerts generated via Portal here, review [Entity View](/v2/docs/tm/features-activity-results).

### Interpreting the results

The `workflowResult` object provides a structured, top-down view of the evaluation. Here's how to interpret the key sections, focusing on Transaction and Activity Monitoring:

**Overall outcome (`workflowResult` top-level fields)**

| API                                                                                                                                                                                                                                                                                                                                                                | Portal                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| `workflowExecutionState`: This confirms the workflow’s technical status. <br /> It must be `COMPLETED` for the status to be considered final and for you to reliably review the activity's details. <br />Other states like `IN_PROGRESS`, `ERROR`, `TIMEOUT`, `CANCELED`, or `TERMINATED` indicate the workflow did not finish successfully.                      | Not displayed in Portal                                                         |
| `status` : This represents a conclusive recommendation (configured status in your selected workflow) for the activity after evaluation and accounts for any manual overrides. <br />For monitoring workflows, common/preferred statuses include <br />- `CLEAR` (no negative information found) <br />- `REVIEW` (requires manual review due to identified issues) | <img /><br />No issues (CLEAR)<br /><br /><img /><br />Needs attention (REVIEW) |
| `result`: This field holds the original, automated outcome of the workflow *before* any manual changes. <br />It is useful for auditing and understanding the system's initial verdict versus any human intervention.                                                                                                                                              | Not displayed in Portal                                                         |

### Issues

This array will contain a list of problems that may require manual review. If the status is REVIEW, this array will provide the specific reasons why the activity needs further investigation.

For Transaction and Activity Monitoring, this might include flags of different types for unusual transaction patterns, device anomalies, or AML concerns with issueCategory: ACTIVITY. The Portal will display these as “Activity” as seen in the image below.

<img /> Entities flagged with issue Activity

| Issue Type      | Description                                                                                                                                                                                                                                           |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ACTIVITY\_AML   | An issue identified during an Anti-Money Laundering (AML) check within the activity monitoring workflow. This could be due to potentially high-risk financial behavior patterns detected during transaction or activity monitoring.                   |
| ACTIVITY\_FRAUD | An issue identified as potential fraud during the transaction and activity monitoring workflow. This can stem from indicators of fraudulent intent related to financial activities.                                                                   |
| ACTIVITY\_EVENT | An issue identified as potential fraud during the activity monitoring workflow. This can stem from indicators that are non-transactional or behavioral by nature such as device anomalies, or unusual login patterns or interactions with the device. |

Each issue corresponds to an alert (a [process result](/v2/docs/tm/concepts-and-definitions)) raised against the activity. Once you have reviewed these, set a manual outcome or apply tags — see [Classifying activities and alerts](/v2/docs/tm/classifying-activities-and-alerts).

### Workflow step results

The `workflowStepResults` array is a log of each step in the workflow, explaining how the overall `status` was reached. Each object in this array corresponds to a step configured in your monitoring workflow (for example, AML check, device check, transaction velocity check).

<AccordionGroup>
  <Accordion title="stepName">
    **API** **`stepName`**: The name of the specific step that was executed

    * `ACTIVITY_AML` - a step dedicated to performing AML checks on the activity.
    * `ACTIVITY_FRAUD` - a step dedicated to performing fraud checks on the activity.

    **Portal** <img /> stepName: `ACTIVITY_AML` is available

    <img /> stepName: `ACTIVITY_FRAUD` is available
  </Accordion>

  <Accordion title="result">
    **API** `result`: The outcome of this specific step. For monitoring, this can be:

    * `CLEAR` (step passed): The step completed successfully without identifying any issues.
    * `HIT` (step identified an issue): The step identified a potential issue or match according to its configured rules.
    * `ERROR` (technical issue with the step): The step encountered an unrecoverable technical error during its execution. **Portal** <img /> `HIT`, Expanded view

    <img /> `CLEAR`, Expanded view

    <img /> `HIT` Expanded view
  </Accordion>

  <Accordion title="summary">
    **API** **`summary`**: A concise, human-readable summary of the step’s outcome.

    ```json theme={null}
    {
        "amlActivityCount": 3,
        "amlActivityTruePositiveCount": 0,
        "eventActivityCount": 0,
        "eventActivityTruePositiveCount": 0,
        "fraudActivityCount": 0,
        "fraudActivityTruePositiveCount": 0,
        "stepName": "ACTIVITY_MONITOR"
    }
    ```

    **Portal**

    Not displayed in Portal
  </Accordion>

  <Accordion title="risk">
    **API** **`risk`**: The risk assessment specific to this step, including the score it contributed to the overall `workflowRiskScore` and `workflowRiskLevel`.

    ### Portal

    <img alt="" />
  </Accordion>
</AccordionGroup>

### Activity alerts

<Note>
  On evaluations each activity will have activity results, but only activity results that meet the risk threshold to trigger an alert are represented as a [Process Result (PRO)](/v2/docs/tm/concepts-and-definitions). These are the alerts that require action.
</Note>

For granular detail, look inside a `workflowStepResult` at its `processResults` array. A [**Process Result** (PRO)](/v2/docs/tm/concepts-and-definitions) is the raw evidence from a single check against a single data source (for example, a specific device fingerprint provider, an AML watchlist provider).

* **`processResultId`**: A unique identifier for this specific piece of evidence.
* `systemStatus`: The lifecycle status of this PRO (for example, VALID, STALE, MARKED\_INVALID). A STALE status means the underlying entity data has changed since this check was performed and it might need re-evaluation. Only the alerts with a systemStatus: VALID will be displayed in Portal.
* **`class`**: The high-level category of the check performed, for Transaction and Activity Monitoring, it’s `ACTIVITY`.
* **`objectType`**: The specific data element that was checked (for example, INDIVIDUAL, TRANSACTION, DEVICE).
* **`result`**: The outcome of this specific PRO (for example, MATCH for a hit, CLEAR for no hit, CREATED for data fetched).
* **`manualStatus`**: If an operator has manually reviewed this specific PRO, their conclusion (for example, `TRUE_POSITIVE`, `FALSE_POSITIVE`, `IN_REVIEW`) is recorded here. This is directly linked to the statuses described in [Resolve alerts and re-evaluate](/v2/docs/tm/implementation-resolve-reevaluate).
* **`providerResult`**: An object containing details from the downstream data provider, including the source of the data.
* **`supplementaryData`**: A rich, context-specific object containing detailed metrics or extracted data, like AML hits details or specific device intelligence data. This is where most of the alerts or rows in the table gets its details as seen in the Portal.

## Next step

You have interpreted the workflow result and identified the alerts raised by the activity. Next, record an outcome for each alert.

* [Classifying activities and alerts](/v2/docs/tm/classifying-activities-and-alerts) — set an alert's manual status (for example, `FALSE_POSITIVE`) or apply tags to an activity, via API.
* [Resolve alerts and re-evaluate](/v2/docs/tm/implementation-resolve-reevaluate) — after resolving every alert, re-run the workflow so the entity's status is updated.


# Resolve alerts and re-evaluate
Source: https://docs.frankieone.com/v2/docs/tm/implementation-resolve-reevaluate

This guide explains how to update alert statuses via API, trigger a workflow re-evaluation, and retrieve an entity's activity history.

## Resolve alerts

| Portal display               | API manualStatus       | Description                                                                                                                                                               |
| ---------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img /> Needs attention      | `null`                 | Indicates that the alert requires review and resolution.                                                                                                                  |
| <img />In review             | IN\_REVIEW             | Indicates that the alert is being actively investigated or reviewed.                                                                                                      |
| <img />True positive: Reject | TRUE\_POSITIVE\_REJECT | Indicates that the activity was confirmed or suspected to be fraudulent or high-risk, and the associated activity was rejected (e.g. transaction blocked).                |
| <img />True positive: Accept | TRUE\_POSITIVE\_ACCEPT | Indicates that the activity was confirmed or suspected to be fraudulent or high-risk, and the associated activity was accepted (e.g. transaction approved with override). |
| <img />False positive        | FALSE\_POSITIVE        | Indicates the alert was reviewed, and confirmed or assumed to be genuine or low-risk.                                                                                     |

### via API

To resolve an alert, update the activity result's status by calling the Update Activity Results endpoint. For more details around classification (applying `tagIds`), see [Classifying activities and alerts](/v2/docs/tm/implementation-classification).

`X-Frankie-Username` is optional. If provided, it identifies the actor in the audit log.

```shellscript theme={null}
curl -X 'PATCH' \
  'https://api.uat.frankie.one:443/v2/individuals/{{your_entity_id}}/results/activity' \
  -H 'accept: application/json' \
  -H 'api_key: X' \
  -H 'X-Frankie-CustomerID: {{your_customer_id}}' \
  -H 'X-Frankie-Username: example@frankieone.com' \
  -H 'Content-Type: application/json' \
  -d '{
  "processResults": [
    "{{processResultId}}"
  ],
   "tagIds": [
        "{{tagId}}",
        "{{tagId}}"
  ],
  "manualStatus": "TRUE_POSITIVE_ACCEPT",
  "comment": {
    "text": "Update after speaking to customer over the phone directly.",
    "entityId": "{{your_entity_id}}",
    "entityType": "{{entityType}}"
  }
}'
```

<Accordion title="Request body">
  <ParamField type="string[]">
    The IDs of the process results (alerts) to update. A process result is created when an activity is flagged for review. Supply one or more UUIDs; the `manualStatus` is applied to each.
  </ParamField>

  <ParamField type="string">
    The manual outcome to record for the alert. Must be one of:

    * `FALSE_POSITIVE` — the result was reviewed and determined to be genuine or low-risk; the activity is within the risk profile to continue.
    * `TRUE_POSITIVE_ACCEPT` — the result was determined to be a true positive, and the activity is within the risk profile to continue (for example, the transaction is approved with an override).
    * `TRUE_POSITIVE_REJECT` — the result was determined to be a true positive, and the activity is not within the risk profile to continue (for example, the transaction is blocked).
    * `IN_REVIEW` — the alert has been picked up and is being actively investigated. "Needs attention" is the unresolved default state of an alert. It corresponds to no manual status being set and is not a value you send through this field.
  </ParamField>

  <ParamField type="string[]">
    Optional tags to apply to the alert and its associated activity. Each tag must exist and be accessible to your account (a FrankieOne `SYSTEM` tag or a `CUSTOMER` tag your account owns). Duplicate IDs are removed automatically. A request must not mix `FALSE_POSITIVE`- or `IN_REVIEW`-category tags with tags of any other category — the intent cannot be reconciled and the request is rejected with `400`

    See [Tags and Reasons reference](/v2/docs/tm/tags-and-reasons-reference) for the full list of available tags.
  </ParamField>

  <ParamField type="object">
    An optional comment recorded in the audit log alongside the status change. Because comments are tied to the manual status action, they form part of the compliance audit trail.

    <Expandable title="comment properties">
      <ParamField type="string">
        The comment text.
      </ParamField>

      <ParamField type="string">
        The entity the comment relates to, as a UUID.
      </ParamField>

      <ParamField type="string">
        The entity type — for example, `INDIVIDUAL` or `ORGANIZATION`.
      </ParamField>
    </Expandable>
  </ParamField>
</Accordion>

### via Portal

See [Features](/v2/docs/tm/features-resolving-alerts) for more details

## Re-evaluate the results

<Warning>
  This is crucial for the entity's overall risk score, which are calculated based on historical activity, and device or customer characteristics.
</Warning>

Once all alerts have been resolved, you must re-run the workflow for the entity.

1. **To update the** `status`: The overall `workflowResult.status` will only be changed by the system from `REVIEW` to `PASS` or `CLEAR` after the workflow is executed again and the steps included in the monitoring workflow confirms that no unresolved hits remain.
2. **To clear** `issues`: The re-execution will cause the steps to re-evaluate the issues. If all PROs that previously caused an `ACTIVITY` issue are now classified as `FALSE_POSITIVE`, the issue will be cleared from the workflow result.

This re-evaluation ensures that your entity’s compliance status is officially updated, reflects the latest risk assessment, and maintains an accurate audit trail.

### via API

To trigger a re-evaluation via API, you will execute the workflow again. Refer to the [Execute a workflow for the given service profile](/api-reference/individual-workflows/execute-a-workflow-for-the-given-service-profile) documentation.

### via Portal

The Portal will automatically re-run the workflow for you once all alerts associated with an activity have been resolved (i.e. no alerts with “Needs attention” and “In review” status remain).

### Detecting manual overrides

It’s crucial to know if a workflow’s result was changed by a person. When an operator manually changes the status (for example, from `FAIL` to `PASS`), the following fields are populated:

* `statusOverrideRequestId`: The unique ID of the override request.
* `statusOverrideBy`: The user who performed the override.
* `statusOverrideAt`: The timestamp of the override.

To detect an override, check if `statusOverrideRequestId` exists and is not empty.

## (Optional) Retrieve all activities

Fetch historical information about the transactions to help get context of the user behavior and investigate.

<Accordion title="Get Activities request">
  ```shellscript theme={null}
  curl -X 'GET' \  
    'https://api.uat.frankie.one:443/v2/individuals/d2859e0c-1f63-4208-947a-038bcb7b1e5e/activities?sortField=ACTIVITY_AT&sort=ASC&limit=20&page=1' \                           
    -H 'accept: application/json' \
    -H 'api_key: X ' \ 
    -H 'X-Frankie-CustomerID: {{your_customer_id}}' \
    -H 'X-Frankie-Username: {{example@frankieone.com}}'
  ```
</Accordion>

## Related pages

* [Classifying activities and alerts](/v2/docs/tm/classifying-activities-and-alerts) — set alert statuses and classify activities via API.
* [Interpret activity results](/v2/docs/tm/implementation-interpret-results) — read the workflow result and identify the alerts to resolve.

## Next step

Your implementation is complete. If you encounter errors at any step, see the full list of error codes and response structures: [Error handling](/v2/docs/tm/implementation-error-handling)


# Integration overview — Transaction and Activity Monitoring
Source: https://docs.frankieone.com/v2/docs/tm/integration



## Prerequisites

<Steps>
  <Step title="Get access to the APIs and authenticate">
    Your Customer Success Manager will provide you with a starter pack containing everything you need for each environment. You should have the following:

    | Resource                                                                   | UAT / Sandbox                                                    | Production                                               |
    | -------------------------------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------- |
    | Portal URL                                                                 | [https://portal.uat.frankie.one](https://portal.uat.frankie.one) | [https://portal.frankie.one](https://portal.frankie.one) |
    | API Base URL for Onboarding Fraud, and Transaction and Activity monitoring | [https://api.uat.frankie.one/v2](https://api.uat.frankie.one/v2) | [https://api.frankie.one/v2](https://api.frankie.one/v2) |
    | Customer ID                                                                | Your unique UAT Customer ID                                      | Your unique Production Customer ID                       |
    | API Key                                                                    | Your secret UAT API Key                                          | Your secret Production API Key                           |

    <Accordion title="Test your connection">
      The easiest way to verify that your credentials and connection are working is to call our simple health check endpoint: /ruok. This endpoint doesn’t require a request body and is used purely to confirm successful authentication.

      ### Request - Health check

      ```bash theme={null}
      curl --location '[https://api.uat.frankie.one/v2/kyc/ruok](https://api.uat.frankie.one/v2/kyc/ruok)' \--header 'api_key: {{your_uat_api_key}}' \--header 'X-Frankie-CustomerId: {{your_uat_customer_id}}'
      ```

      ### Response

      If you receive an error, double-check that your API key and Customer ID are correct and that you are using the correct base URL for the environment.
    </Accordion>

    Refer to the [authentication](/docs/reference/authentication) page for more details.
  </Step>

  <Step title="Set up risk rules in the rule engine">
    <Warning>
      FrankieOne must configure device and behavioral intelligence for your account. This includes advanced features such as:

      * Detecting multiple users linked to one device
      * IP address analysis
      * Phone and mouse movement patterns
      * High-risk information entry (for example, excessive copying and pasting)
      * Remote software detection

      Contact your Customer Success Manager to enable or adjust this feature.
    </Warning>
  </Step>

  <Step title="Setup queues for routine-based (batch) alerts">
    <Warning>
      FrankieOne will help configure queue names and rules that should be detected in those queues. Contact your Customer Success Manager to enable or adjust this feature.
    </Warning>
  </Step>
</Steps>

## Integration overview

* OneSDK: Capture device and location details to have them evaluated by the system.
* KYC API: Capture phone and email details for the entity so they can be checked or evaluated by the system.
* Transaction and Activity Monitoring API: Send financial transactions and non-financial activities (for example, registration, login, account changes) for evaluation against configured fraud and AML rulesets.

| Product function                   | OneSDK                                | KYC API              | **Transaction and Activity Monitoring API** |
| :--------------------------------- | :------------------------------------ | :------------------- | ------------------------------------------- |
| Onboarding fraud (data collection) | Phone, email, device, location checks | Phone and email only | Not applicable                              |
| AML transaction and activity       | Phone, email, device, location checks | Phone and email only | AML transaction alerts                      |
| Fraud transaction and activity     | Phone, email, device, location checks | Phone and email only | Fraud and behavior alerts                   |
| Review and manage                  | FrankieOne Portal                     | FrankieOne Portal    | FrankieOne Portal                           |

View the data in FrankieOne Portal for a cohesive and unified view of phone, email, device, location, and fraud checks. Data and check results are available on the entity view's workflow events page.


# Overview of Transaction and Activity Monitoring
Source: https://docs.frankieone.com/v2/docs/tm/overview



## Introduction

**Monitor and safeguard your customers beyond onboarding**. Fraud and financial crime don't stop at account creation — and neither do we. FrankieOne continuously monitors entity behavior across logins, sessions, and transactions, triggering real-time checks to detect both fraud and AML risks.

### Video Guide

<iframe />

## Key terminology

<AccordionGroup>
  <Accordion title="Relevant terms">
    * **Activity**: any action performed by an entity on a client's platform that FrankieOne monitors for suspicious behavior and risk assessment
      * **Transaction**: A financial event performed by an entity on the client's platform such as a deposit or withdrawal.
      * **Event**:  A behavioral or non-financial event performed by an entity  on the client's platform such as logins, password changes or account changes. These are presented as “Behaviour” in Portal.
    * **Alerts**: A Process Result (PRO) that has met the risk threshold to require attention generated from a transaction or event. Alerts are visible in the FrankieOne Portal and managed by Fraud and Compliance Officers.
    * **Issue**: An alert created due to a triggered rule will create issues for analysts to easily identify the result of the workflow execution.
      * **Fraud Issue**: Detect instances where a client or customer may be at risk of financial loss due to deliberate deception or misrepresentation.
      * **AML Issue**: Detect potential instances of money laundering, terrorism financing, proliferation financing, or other financial crime.
      * **Device/Customer Characteristics Issue**: Detect unauthorized, or unusual behavior or activity related to identity attributes (e.g. phone number or email address) or device activity (using device intelligence, IP intelligence and behavioral biometrics).
    * **Entity**: Representation of what is being checked for fraudulent activity. It collects all relevant data for an individual from multiple sources for a comprehensive view.

    For full definitions, see [Key Terms and Definitions](/v2/docs/tm/concepts-and-definitions).
  </Accordion>
</AccordionGroup>

## Key features and signals

### Payment screening

Assess fraud signals like device signals, transaction amount, transaction velocity on network, Payment method risk at the point of transaction to enable the client to allow, flag or block based on company policy/business logic.

### Transaction and activity monitoring

Analyze ongoing transaction patterns to identify potential money laundering such as recipient risk, transaction pattern anomalies, volume over time, and customer profile changes. Monitor device intelligence and behavioral signals across customer interactions such as device fingerprinting, biometrics, login/session anomalies, geolocation analysis.

* **Device intelligence**: Identifies devices via cookies and device fingerprinting. Based on the data gathered, we can effectively flag suspicious devices (emulators / scripts) and sessions (proxies / VPNs / remote desktop) typically used to create synthetic accounts.
* **Behavioral biometrics**: Detects fraudsters via their intrinsic behaviors. For example, fraudsters are 30x more likely to copy and paste bank details, less likely to hesitate when pasting values, and more likely to use advanced shortcuts and straight line mouse movements.

## Use cases

The following use cases are examples of where FrankieOne can help you with transaction and activity monitoring.

<AccordionGroup>
  <Accordion title="Identity fraud">
    Fraudsters use entirely fabricated (synthetic) identities or stolen personal information to open new accounts, obtain credit, or conduct fraudulent transactions.

    **Signals detected**

    * New device usage
    * Unusual login activity (new locations, devices, times), IP address irregularities (known proxies/VPNs, geographically inconsistent)
    * Remote desktop or emulator usage
    * Copy/paste behavior during sensitive interactions
    * Hesitation/typing speed anomalies
    * Changes to sensitive account details (password, address, phone, email, 2FA, payment method update) followed by high-risk actions
    * Multiple accounts from same device/IP
    * Device fingerprint changes
    * Temporary emails
    * Multiple emails associated with a device
    * Unusual email or phone characteristics (disposable, VoIP, newly registered domain)

    **Relevant industries**

    * Financial institutions (banks, superannuation, credit unions, insurance)
    * Payment companies (fintech, payment service providers, remittance services)
    * Cryptocurrency exchanges
    * E-commerce
    * Digital wallets
    * Online gaming or gambling
    * Lending platforms
  </Accordion>

  <Accordion title="Financial transaction fraud">
    These are fraud activities involving financial transactions:

    * Payment fraud / card-not-present (CNP) fraud - Unauthorized transactions made using stolen credit card details or payment credentials
    * Electronic funds transfers - Fraudulent transactions completed using unauthorized or through social engineering (e.g. for scams)
    * Crypto purchase and transfers
    * Direct debit
    * International payments and transfers

    **Signals detected**

    * Transaction amount (e.g. high transaction amount or frequency for a new user)
    * Transaction velocity on network (e.g. multiple transactions to different recipients shortly after account creation)
    * Payment method risk
    * Device signals during transaction
    * Inconsistent application data
    * Multiple applications from the same device or IP address
    * Unusual device interactions during application
    * Rapid withdrawal of loan funds post-approval
    * Non-repayment of first loan

    **Relevant industries**

    * Financial institutions (banks, superannuation, credit unions, insurance)
    * Payment companies (fintech, payment service providers, remittance services)
    * Cryptocurrency exchanges
    * E-commerce
    * Digital wallets
    * Online gaming or gambling
    * Lending platforms
    * Travel and hospitality
  </Accordion>

  <Accordion title="Application fraud">
    These are fraud activities involving applications:

    * Loan and Credit Application Fraud - Fraudulent applications for loans or credit, often involving false information or synthetic identities, manipulating financial statements, income, and employment details.

    **Signals detected**

    * Inconsistent application data
    * Multiple applications from the same device or IP address
    * Unusual device interactions during application
    * Use of synthetic identities
    * Disposable/temporary emails or VoIP phone numbers
    * New device usage / unusual login activity
    * Rapid withdrawal of loan funds post-approval / Non-repayment of first loan
    * Account age and activity history
    * Mismatch between IP location and declared address
    * Brute force attempts or rapid account creation followed by immediate bonus withdrawal

    **Relevant industries**

    * Financial institutions (banks, credit unions, lending platforms)
    * Payment companies (fintech, payment service providers, digital wallets)
    * Cryptocurrency exchanges
    * E-commerce and online retail (for credit-based purchases)
    * Online gaming or gambling (for credit lines or promotional offers)
    * Any industry offering sign-up bonuses, credit, or requiring identity verification for account creation.
  </Accordion>

  <Accordion title="Anti-Money Laundering (AML) compliance">
    Detecting patterns indicative of money laundering, including structuring, transactions with high-risk entities or jurisdictions, and evasion of sanctions.

    * Structuring (smurfing) - money launderers split large transactions into multiple smaller ones to evade reporting thresholds
    * High-risk jurisdictions / geolocation risk - transactions involving countries or regions known for high money laundering or terrorism financing risks, or inconsistencies in user location.
    * Sanctions evasion - attempting to conduct transactions with individuals, entities, or countries subject to sanctions

    **Signals detected**

    * Suspicious frequency of low-value transactions (multiple deposits or withdrawals below reporting thresholds)
    * Transaction volume velocity (exceeding limits over daily/weekly/monthly periods)
    * Transactions to or from high-risk jurisdictions
    * Transactions originating from unusual IP addresses, known proxy/VPN services, or geographically inconsistent locations for the user

    **Relevant industries**

    * Financial institutions (banks, superannuation, credit unions, insurance)
    * Payment companies (fintech, payment service providers, remittance services)
    * Cryptocurrency exchanges
    * E-commerce
    * Digital wallets
    * Online gaming or gambling
    * Lending platforms
  </Accordion>

  <Accordion title="Organized crime and abuse">
    Encompasses activities by organized groups, such as fraud farms, money mule networks, and attempts to abuse promotions or manipulate systems

    * Fraud farms / organized fraud rings - coordinated efforts by criminal groups to create numerous fraudulent accounts or execute multiple fraudulent transactions
    * Money mule activity - individuals (often unknowingly recruited) transfer illicit funds on behalf of criminal organizations
    * Bonus or promotion abuse - users exploit promotional offers, welcome bonuses, or referral programs by creating multiple accounts or manipulating systems

    **Signals detected**

    * Multiple accounts created from the same device, IP address or network
    * Emulator or virtual machine (VM) usage
    * Bot activity
    * Rapid multiple login attempts (brute force simulation)
    * Profile changes before large transaction (indicating account takeover to facilitate mule activity)
    * Transactions from a new or untrusted device
    * Unusual login activity
    * Unusual transaction patterns (e.g. receiving funds from multiple unknown sources and immediately forwarding them)
    * Device used for login linked to multiple other suspicious accounts
    * Rapid succession of deposits and withdrawals with minimal retained account balance
    * Multiple accounts linked to the same device or IP address
    * Similar user details across different accounts
    * Rapid account creation followed by immediate withdrawal of bonus funds

    **Relevant industries**

    * Any industry with digital accounts and promotional offers: financial institutions, e-commerce, online gaming and gambling, fintechs, and software-as-a-service (SaaS) providers.
  </Accordion>

  <Accordion title="Internal fraud and insider threats">
    Malicious acts committed by employees, such as embezzlement, creating ghost accounts, or manipulating records.

    **Signals detected**

    * Unauthorized transfers from digital wallets
    * Unusual login activity to wallet
    * Linking of new, suspicious payment methods
    * Large or frequent transactions inconsistent with user history
    * Device intelligence indicating compromised device

    **Relevant industries**

    Any industry with internal financial processes or access to sensitive data (e.g., financial institutions, retail, e-commerce and software-as-a-service (SaaS) providers).
  </Accordion>
</AccordionGroup>

## How it works

<Steps>
  <Step title="Initial transaction and activity assessment">
    When a customer performs a transaction or activity on your platform (e.g., a login, deposit, or withdrawal), your system sends this activity data, along with relevant signals (like device information collected via FrankieOne's SDK), to FrankieOne.

    Our solution immediately processes this data, applying configured rules and leveraging real-time intelligence from various sources (e.g., device intelligence, behavioral biometrics, network analysis).
  </Step>

  <Step title="Perform risk assessment">
    The solution passes risk signals into the configurable risk rating engine, which determines the overall risk for the entity based on a consistent set of risk factors and policies specific to your business.

    This high-risk activity triggers the creation of alerts within the FrankieOne Portal for review by your AML/Fraud officers.
  </Step>

  <Step title="Determine the entity’s monitoring status">
    Based on your policy, dynamically define the entity’s monitoring status from various data points available such as risk level and alerts.
  </Step>

  <Step title="Resolve alerts">
    Review each alert detected during a customer’s transaction or activity accordingly by tagging them as false positive, true positive or in review.
  </Step>
</Steps>

To learn more, see the [Implementation Guide](/v2/docs/tm/implementation) or [Features Guide](/v2/docs/tm/features-activity-results).


# Risks
Source: https://docs.frankieone.com/v2/docs/tm/risks

Applies to: FrankieOne Fraud and Transaction Monitoring — v2

OInboarding fraud and Transaction and Activity Monitoring risk factors measure how an entity's data, activities, and alerts contribute to their overall risk profile. These factors are generated from activity results (AML, Fraud, and Behavior) and can be used alongside existing [KYC and onboarding fraud risk factors](/docs/assessing-risk). For a full reference, see [Risk factors](/docs/risk-factors).

## Onboarding Fraud Risk Factors

Onboarding fraud risk factors — including phone, email, device, and behavioral signals — are documented in the [KYC risk factors reference](/docs/assessing-risk). They can be combined with the TM risk factors on this page for a unified risk view.

## Transaction and Activity Risk Factors

These factors are calculated from activity monitoring results (AML, Fraud, and Behavior), and are designed for **ongoing monitoring and transaction monitoring**, not onboarding.

| **Portal display name**       | **Factor (API)**                  | **What it measures**                                                                             | **Typical usage**                                                                             |
| :---------------------------- | :-------------------------------- | :----------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------- |
| AML alerts                    | `activity_aml_ct`                 | Total number of **all transactional AML alerts generated across all activities** for the entity. | Escalate entities with many unresolved AML alerts; drive EDD or periodic review triggers.     |
| Fraud alerts                  | `activity_fraud_ct`               | Total number of **all transactional fraud alerts generated across all activities**.              | Identify entities with repeated fraud alerts; drive additional controls or limits.            |
| Behavior alerts               | `activity_event_ct`               | Total number of **all behavioral or non-transactional alerts generated across all activities**.  | Track unusual behavioral activity, e.g. risky logins or profile changes.                      |
| True positive AML alerts      | `activity_aml_true_positive_ct`   | Total number of **true positive AML alerts** (manually confirmed issues).                        | Capture confirmed historical AML behavioral patterns; feed into long-term AML risk posture.   |
| True positive Fraud alerts    | `activity_fraud_true_positive_ct` | Total number of **true positive Fraud alerts**.                                                  | Identify entities with a known history of confirmed fraud; inform block/de-risking decisions. |
| True positive Behavior alerts | `activity_event_true_positive_ct` | Total number of **true positive Behavior alerts**.                                               | Capture confirmed risky behavioral patterns for ongoing monitoring.                           |


# Tags and Reasons reference
Source: https://docs.frankieone.com/v2/docs/tm/tags-and-reasons-reference

Reference list of all standard Tags (Reasons) available for classifying activities and resolving alerts in Transaction and Activity Monitoring.

This page lists all standard Tags available in FrankieOne Transaction and Activity Monitoring. Tags are the API-level concept. In the FrankieOne Portal, they are presented as **Reasons**.

When you [resolve an alert](/v2/docs/tm/implementation-resolve-reevaluate) or [classify an activity](/v2/docs/tm/classifying-activities-and-alerts), you select one or more Tags (Reasons) to record the outcome. The available Reasons in the Portal are filtered by the status you select:

* **True Positive** statuses (True Positive: Accept, True Positive: Reject) show the true positive Reasons listed below.
* **False Positive** shows the false positive Reasons.
* **In Review** shows the in review Reasons.

All Reasons are available regardless of alert category. For example, a fraud alert can be resolved with a money laundering Reason if the investigation supports it.

Tags are managed by FrankieOne. You cannot create, rename, or delete Tags through the API. Only active Tags can be applied.

## True Positive

True Positive Tags classify an activity or alert as confirmed or suspected fraudulent, suspicious, or high-risk. They are grouped by category.

### Money laundering

| Tag                         | Reason                               | When to use                                                                                                                                                                                                                                                                                                                                                           |
| :-------------------------- | :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ML_CASH_STRUCTURING`       | Cash structuring or opacity          | The customer is splitting cash deposits or withdrawals to stay below thresholds, or cash is being handled to hide ownership or origin through mules, third-party deposits, or mixing of funds.                                                                                                                                                                        |
| `ML_LAYERING`               | Layering                             | An account is being used as a pass-through or mule to move funds and hide their origin. This includes rapid in-out movement, circular flows, fan-in/fan-out patterns with unrelated counterparties, crypto on/off-ramp or stablecoin layering, cash-to-crypto conversion via ATMs or digital currency exchanges, and placement or layering through gambling channels. |
| `ML_IDENTITY_CRIME`         | Identity crime                       | A stolen or fake identity has been used to open accounts, access funds, or bypass controls.                                                                                                                                                                                                                                                                           |
| `ML_DECEPTION`              | Deception or misrepresentation       | Fabricated or inconsistent documents have been used to make transactions look legitimate, the customer's stated source of funds conflicts with the actual transactions, or trade payments don't match business reality such as over/under invoicing or phantom shipments.                                                                                             |
| `ML_FACILITATION`           | Insider or professional facilitation | A staff member, trusted insider, or external professional is helping bypass controls, open accounts, or move funds.                                                                                                                                                                                                                                                   |
| `ML_STRUCTURAL_CONCEALMENT` | Structural concealment               | Shells, trusts, nominees, or unjustified complexity are being used to hide beneficial owners or control. This includes entities with no real operations used as pass-throughs, trust accounts used to mix funds, and proceeds integrated through luxury goods, vehicles, real estate, or bullion inconsistent with the customer's profile.                            |
| `ML_DETECTION_AVOIDANCE`    | Detection or sanctions avoidance     | Unregulated channels, remitters, informal value transfer services, high-risk jurisdictions, or transaction patterns have been chosen to reduce visibility or circumvent sanctions outside the weapons of mass destruction or proliferation context.                                                                                                                   |
| `ML_DRUG_PROCEEDS`          | Drug trafficking proceeds            | Funds are linked to narcotics trafficking or drug-related criminal activity.                                                                                                                                                                                                                                                                                          |
| `ML_CORRUPTION`             | Corruption or bribery proceeds       | Funds are linked to corruption, bribery, or politically exposed person abuse of public office.                                                                                                                                                                                                                                                                        |
| `ML_TAX_CRIME`              | Tax crime proceeds                   | Funds are linked to tax evasion or tax fraud.                                                                                                                                                                                                                                                                                                                         |
| `ML_CYBER_CRIME`            | Cyber-enabled crime proceeds         | Proceeds of ransomware, business email compromise, or other cyber crime are being laundered. This covers the offender or proceeds side and is distinct from victim-facing scam or fraud codes.                                                                                                                                                                        |
| `ML_OTHER_PREDICATE`        | Other predicate offense              | Funds are linked to a designated predicate offense not covered by a specific code, including human trafficking, arms trafficking, environmental crime, kidnapping, or counterfeiting. Specify the predicate in case notes.                                                                                                                                            |

### Fraud

| Tag                    | Reason                           | When to use                                                                                                                                                                                                   |
| :--------------------- | :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `FR_UNAUTHORIZED_CARD` | Unauthorized card fraud          | There is a confirmed unauthorized card transaction, whether online (card-not-present) or physical (skimming, counterfeit, lost/stolen, or intercepted in mail).                                               |
| `FR_IDENTITY_TAKEOVER` | Identity takeover                | Someone's identity has been captured and used to open accounts, credit lines, or products without their knowledge, or an account or product was opened through deception or misrepresentation at application. |
| `FR_ACCOUNT_TAKEOVER`  | Account takeover                 | A legitimate account has been taken over using stolen or compromised credentials.                                                                                                                             |
| `FR_MALWARE`           | Malware                          | Malware has been used to access accounts or redirect transactions without the victim knowing.                                                                                                                 |
| `FR_PORTING`           | Porting or SIM swap              | Fraud resulted from phone number porting or a SIM swap.                                                                                                                                                       |
| `FR_FIRST_PARTY`       | First-party fraud                | The customer intentionally disputes a legitimate transaction or claims it was unauthorized while they participated or benefited.                                                                              |
| `FR_PHISHING`          | Phishing-led fraud               | The victim was tricked into revealing credentials, sharing information, or authorizing a payment through phishing.                                                                                            |
| `FR_ELDER_ABUSE`       | Elder or vulnerable person abuse | There is evidence of financial exploitation of an elderly or vulnerable person by someone in a position of trust.                                                                                             |

### Scam

| Tag                    | Reason                       | When to use                                                                                                                                       |
| :--------------------- | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SC_RELATIONSHIP`      | Relationship scam            | The victim authorized payments because of relationship manipulation.                                                                              |
| `SC_INVESTMENT`        | Investment scam              | The victim authorized payments into a fake investment opportunity, including crypto schemes such as pig butchering, fake exchanges, or rug pulls. |
| `SC_BUYING_SELLING`    | Buying or selling scam       | The victim paid for goods or services that were never delivered or don't exist.                                                                   |
| `SC_THREATS_EXTORTION` | Threat or extortion scam     | The victim authorized payment because of threats, coercion, extortion, or a ransomware demand.                                                    |
| `SC_JOB_EMPLOYMENT`    | Job or employment scam       | The victim authorized payments for a fake job or guaranteed income. This may also involve mule recruitment.                                       |
| `SC_UNEXPECTED_MONEY`  | Unexpected money or winnings | The victim paid an upfront fee or shared information to claim a fake prize or windfall.                                                           |
| `SC_IMPERSONATION`     | Impersonation scam           | The victim authorized payment or shared information because someone impersonated a trusted person or organization.                                |
| `SC_PAYMENT_REDIRECT`  | Payment redirection          | A business was tricked into sending an invoice payment or urgent transfer to a fraudulent account.                                                |
| `SC_REMOTE_ACCESS`     | Remote access scam           | The victim installed remote-access software and was coached into transferring funds.                                                              |

### Terrorism financing

| Tag                       | Reason                               | When to use                                                                                                                                                                                                                                                                 |
| :------------------------ | :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TF_SELF_FUNDED`          | Self-funding or supporter funds      | A lone actor is self-funding, personal savings or small contributions from associates are being used to support terrorism, or outgoing transfers appear intended to support offshore terrorist organizations or affiliates.                                                 |
| `TF_CHARITABLE_NPO`       | Charitable or linked to NPO          | Donations are presented as charity or mixed with legitimate displaced-person support but indicators suggest diversion to a terrorist nexus, or a non-profit organization appears set up, controlled, or exploited to support terrorist-linked individuals or organizations. |
| `TF_ONLINE_ECOSYSTEM`     | Online funding ecosystem             | Payments are linked to social media fundraising, crowdfunding, communications platforms, or recruitment networks.                                                                                                                                                           |
| `TF_INFORMAL_CHANNELS`    | Informal or non-traditional channels | A de-risked actor or non-profit organization has shifted to cash couriering, hawala-like channels, unregistered remitters, or digital currency for raising, moving, or storing funds.                                                                                       |
| `TF_CONDUIT_JURISDICTION` | Conduit jurisdiction                 | Funds are sent to a neighboring or conduit country and then likely moved physically into a conflict zone.                                                                                                                                                                   |

### Proliferation financing

| Tag              | Reason                    | When to use                                                                                                                                                                                                                                                                                                                 |
| :--------------- | :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PF_PROCUREMENT` | Proliferation procurement | Payments or trade finance are linked to procurement of dual-use or proliferation-sensitive goods, use of unwitting suppliers where payments look normal but end-use or end-user is illicit, or a state-linked procurement network targeting suppliers or financial services.                                                |
| `PF_EVASION`     | Proliferation evasion     | Funds are routed through third countries, trans-shipment hubs, front or shell entities, intermediaries, or professionals to hide the real parties or evade DPRK or Iran-related targeted financial sanctions. Also covers goods mislabeled or exported just under control or reporting thresholds to avoid export controls. |

## False Positive

False Positive Tags record that an alert was reviewed and determined to be genuine or low-risk.

| Tag                       | Reason                              | When to use                                                                                                                                                                               |
| :------------------------ | :---------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FP_NOT_SUSPICIOUS`       | Not suspicious                      | The activity is not suspicious for a reason not covered by the other false positive Reasons. This is also the default Reason when all true positive Reasons are removed from an activity. |
| `FP_CONFIRMED_AUTHORIZED` | Customer confirmed authorized       | The customer explicitly confirms they authorized the transaction and the purpose is legitimate.                                                                                           |
| `FP_PLAUSIBLE_SOF`        | Plausible source of funds or wealth | The customer provides a credible source of funds or wealth that explains the activity.                                                                                                    |
| `FP_ACTIVITY_EXPLAINED`   | Activity explained by profile       | The activity fits the known customer profile, risk appetite, established payee history, or declared business model.                                                                       |
| `FP_KNOWN_COUNTERPARTY`   | Known counterparty                  | The counterparty identity is verified and the relationship or purpose is confirmed (for example, supplier, family, landlord).                                                             |
| `FP_DOCUMENTARY_EVIDENCE` | Documentary evidence matches        | Supporting documents (invoice, contract, purchase order, settlement statement) match the payee, amount, goods or services, and timeline.                                                  |
| `FP_CRYPTO_SUPPORTED`     | Declared crypto activity supported  | The customer has declared crypto trading or investing and exchange records and source of funds support the activity.                                                                      |
| `FP_OWN_ACCOUNTS`         | Own-account transfer                | Transfers are between the same beneficial owner's accounts.                                                                                                                               |
| `FP_REVERSED_VOIDED`      | Payment reversed or voided          | The alerted transaction was reversed or voided in the normal course of business.                                                                                                          |

## In Review

In Review Tags record that an alert is under active investigation and a final decision has not been reached.

| Tag                        | Reason                            | When to use                                                                                                                                                                                                                                                                                                                                                                               |
| :------------------------- | :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `IR_PENDING_CUSTOMER_INFO` | Pending customer information      | You need to contact the customer, are waiting for documents, or incomplete or outdated KYC data prevents a clear decision.                                                                                                                                                                                                                                                                |
| `IR_LAW_ENFORCEMENT`       | Law enforcement                   | The decision depends on law enforcement feedback, negative news, open-source intelligence, or external intelligence.                                                                                                                                                                                                                                                                      |
| `IR_REPORTING_DECISION`    | Reporting decision                | Pending a decision on whether to file a suspicious activity report (SAR), suspicious matter report (SMR), or equivalent.                                                                                                                                                                                                                                                                  |
| `IR_LINKED_CASE`           | Linked alert or case pending      | The outcome depends on another active fraud, AML, or scam alert or case that hasn't been finalized.                                                                                                                                                                                                                                                                                       |
| `IR_SPECIALIST_ANALYSIS`   | Specialist analysis in progress   | Complex funds-flow analysis, network or graph mapping, multi-entity payment chain analysis, mule pattern monitoring, or cross-channel activity review is being performed by a technical specialist before determining an outcome.                                                                                                                                                         |
| `IR_INTERNAL_ESCALATION`   | Internal escalation               | The alert has been escalated to a team leader, risk, or compliance team for review. This includes higher-risk countries, sanctions screening dependencies, complex customer structures, terrorism or proliferation financing red flags, internal misconduct indicators, scam coaching concerns, enhanced due diligence requirements, or borderline behavior needing policy clarification. |
| `IR_AWAITING_EXTERNAL`     | Awaiting external outcome         | You are waiting on a response from another organization, payment provider, or card scheme, or waiting on the outcome of a funds recall, reversal, or recovery before deciding.                                                                                                                                                                                                            |
| `IR_VULNERABILITY`         | Customer vulnerability assessment | Indicators of vulnerability (age, disability, language, bereavement) require specialist review before the case can be resolved.                                                                                                                                                                                                                                                           |


# Workflows and Standard Bundle
Source: https://docs.frankieone.com/v2/docs/tm/workflows

This page explains how FrankieOne uses workflows and standard bundles to configure monitoring for Transaction and Activity Monitoring (v2). It covers the available out-of-the-box workflow — Basic-Monitoring-TxAM — and how to extend it for your use case.

## Overview

FrankieOne uses **workflows** and **standard bundles** to provide fast, opinionated configurations for common KYC, AML, and monitoring use cases.

* A **workflow** is a named, versioned configuration that defines:
  * Which checks run (for example, AML, transaction and activity monitoring, and fraud signals).
  * How results are evaluated and mapped to a final `workflowResult`.
  * How issues or alerts are created in the FrankieOne Portal.
* A **standard bundle** is an **out-of-the-box workflow** that FrankieOne maintains and recommends for a given use case (for example, AU Essential KYC, Risk-Based Onboarding, or Basic Monitoring for Transaction and Activity Monitoring). These bundles are:
  * **Pre-configured** based on best-practice compliance.
  * **API-addressable** via a stable `workflowName`.
  * **Extensible** – customers can start with the default and move to custom workflows as needed.

## Onboarding Fraud Standard Bundle

For onboarding fraud, see [Risk-based onboarding standard bundles](/docs/standard-kyc-bundles), which covers the AU Essential KYC and Risk-Based Onboarding workflows.

## Transaction and Activity Monitoring Standard Bundle

All workflows under Transaction and Activity Monitoring will have lifecyclePhase: MONITORING

### Basic-Monitoring-TxAM

The standard bundle for Transaction and Activity Monitoring is **Basic-Monitoring-TxAM** (where TxAM is a technical identifier for Transaction and Activity Monitoring used in bundle names).

| Field                      | Value                                                                                                                                                                                                                                                   |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Monitoring types**       | `["ACTIVITY"]`                                                                                                                                                                                                                                          |
| **Checks/Steps available** | `ACTIVITY_FRAUD` – fraud and behavioral rules<br />`ACTIVITY_AML` – AML transaction monitoring rules                                                                                                                                                    |
| **Risk profile**           | Essential and baseline monitoring                                                                                                                                                                                                                       |
| **Typical users**          | Digital financial services, fintechs, wallets and brokers who want **fraud, behavioral, and AML activity monitoring** (logins, account and device changes, deposits, withdrawals, high-risk transfers) and are happy to start from FrankieOne defaults. |
| **Result Types Mapping**   | 1. Any step `HIT` → `workflowResult.status = REVIEW` and creation of an **ACTIVITY** issue.<br />2. All steps `CLEAR` → `workflowResult.status = PASS or CLEAR`.<br />3. Any step `ERROR` → `workflowResult.status = FAIL`                              |
| **Issue Types Mapping**    | 1.`ACTIVITY_AML` (AML-related alerts on transactions)<br />2.`ACTIVITY_FRAUD` (fraud and behavioral alerts) <br />3.`ACTIVITY_EVENT` (non-transactional behavioral events)                                                                              |

This standard bundle can be further configured to take into consideration risk assessment, AML monitoring, and other processes as part of your company's policies.


# Common use cases
Source: https://docs.frankieone.com/v2/introduction/common-use-cases

Explore common ways teams use FrankieOne to solve real-world identity, compliance, and fraud challenges.

Each guide shows how to combine products and integrations for a specific industry or use case.

## By industry

Use cases tailored to specific industries and regulatory environments.

<Columns>
  <Card title="Banking - Risk-Based Customer Onboarding (Australia)" icon="building-columns" href="/v2/kyc/kyc/use-cases/kyc-banking">
    Implement risk-based KYC for banking customers, aligned with Australian regulatory requirements.
  </Card>

  <Card title="Gaming - Risk-Based Customer Onboarding (Australia)" icon="gamepad" href="/v2/kyc/kyc/use-cases/kyc-gaming">
    Apply KYC controls tailored for gaming and betting platforms operating in Australia.
  </Card>

  <Card title="Crypto — Risk-Based Customer Onboarding (Global, US, UK, Europe)" icon="bitcoin" href="/v2/kyc/kyc/use-cases/kyc-crypto">
    Build compliant, risk-based onboarding for crypto platforms across global jurisdictions.
  </Card>

  <Card title="Real Estate — Risk-Based Customer Onboarding (Australia)" icon="house" href="/v2/kyc/kyc/use-cases/real-estate-risk-based-customer-onboarding">
    Support Tranche 2 real estate obligations with risk-based KYC for buyers, sellers, and agents in Australia.
  </Card>
</Columns>

## By scenario

Common workflows that combine multiple FrankieOne products.

### Onboarding with fraud prevention

<Columns>
  <Card title="End-to-End Individual Onboarding with Fraud Signals" icon="shield-halved" href="/docs/fraud-v2-getting-started">
    Combine KYC verification with email, phone, device, and behavioural biometric checks to block high-risk users during onboarding.
  </Card>

  <Card title="Remote Onboarding with Document Capture" icon="fingerprint" href="/docs/quickstart-guide/use-case-1-hosted-onesdk">
    Use Hosted OneSDK to deliver a fully managed onboarding flow with document verification and facial matching.
  </Card>
</Columns>

### Business verification

<Columns>
  <Card title="Business Customer Onboarding" icon="building" href="/docs/kyb/business-onboarding">
    Verify business entities, identify UBOs, and screen against watchlists in a single onboarding flow.
  </Card>

  <Card title="Ongoing AML Screening for Business Clients" icon="money-check-dollar" href="/docs/kyb/anti-money-laundering">
    Continuously screen businesses and associated individuals against global sanctions and watchlists.
  </Card>
</Columns>

### Ongoing monitoring

<Columns>
  <Card title="Real-Time Transaction and Activity Monitoring" icon="chart-line" href="/docs/implementation-guide-transaction-monitoring">
    Monitor transactions and user activity in real time to detect money laundering patterns and high-risk behaviour.
  </Card>

  <Card title="Continuous AML Monitoring for Individuals" icon="bell" href="/docs/anti-money-laundering">
    Set up ongoing watchlist screening to detect changes in customer risk profiles after onboarding.
  </Card>
</Columns>

## Combined product workflows

See how FrankieOne's products work together across the customer lifecycle.

**Example: Full-lifecycle compliance for a fintech**

1. **Onboarding** — Use **KYC** + **OneSDK** to verify individual customers with document capture and facial matching.
2. **Fraud prevention** — Layer on **Fraud signals** during onboarding to block high-risk sign-ups based on device, email, and phone intelligence.
3. **AML screening** — Screen customers against global watchlists at onboarding and on an ongoing basis.
4. **Transaction monitoring** — Monitor customer transactions in real time to detect suspicious activity post-onboarding.
5. **Operations** — Use the **Portal** to review flagged cases, manage verifications, and maintain a complete audit trail.

For help designing a workflow like this, [contact the FrankieOne team](https://www.frankieone.com/contact).


# Integrating with FrankieOne
Source: https://docs.frankieone.com/v2/introduction/integrating-with-frankie-one

FrankieOne offers multiple ways to integrate, depending on your technical requirements and desired level of control. This page outlines the core integration options and resources available.

## Choose your integration approach

FrankieOne offers multiple integration paths depending on your technical requirements and how much control you need over the user experience.

| Approach            | Best for                 | Effort | Control        |
| ------------------- | ------------------------ | ------ | -------------- |
| **Hosted OneSDK**   | Fast launch, minimal dev | Low    | Low            |
| **Embedded OneSDK** | Custom web UX            | Medium | High           |
| **Native OneSDK**   | iOS / Android apps       | Medium | High           |
| **API**             | Full backend control     | High   | Full           |
| **Portal**          | Ops teams, no-code       | None   | Dashboard only |

> **Not sure?** Most teams start with the **API and Portal** for the fastest path to production.

## Integration resources

<Columns>
  <Card title="Portal" icon="credit-card" href="/docs/getting-started-with-the-frankieone-portal">
    Manage daily onboarding and compliance tasks through the FrankieOne Portal.
  </Card>

  <Card title="API" icon="terminal" href="/v2/api/introduction/introduction-to-frankie-one-api">
    FrankieOne’s API provides maximum flexibility for a custom onboarding experience.
  </Card>

  <Card title="Hosted OneSDK Solution" icon="laptop-code" href="/docs/quickstart-guide/use-case-1-hosted-onesdk">
    Use hosted OneSDK for a fully managed, low-code onboarding experience.
  </Card>

  <Card title="Embedded OneSDK Solution" icon="laptop-code" href="/docs/embedded-flows/quick-start">
    Embed OneSDK directly into your application to enable a custom verification experience.
  </Card>

  <Card title="Native App OneSDK Solution" icon="laptop-code" href="/docs/native-integration">
    Embed OneSDK directly into your application to enable a custom verification experience.
  </Card>

  <Card title="Webhook Notifications" icon="code-branch" href="/docs/notifications-and-webhooks">
    Set up real-time notifications for key verification and entity events via webhooks.
  </Card>

  <Card title="Test Data" icon="database" href="/docs/test-data">
    Use test data and sandbox environments to develop and validate your integration safely.
  </Card>
</Columns>

## Next steps

Once you've chosen your integration approach and set up your environment:

1. [Authenticate your API credentials](/docs/reference/authentication) to connect to FrankieOne.
2. Follow the [Quick Start Guide](/docs/getting-started) to make your first verification call.
3. Use [test data](/docs/test-data) in the sandbox environment to develop and validate your integration.


# Overview
Source: https://docs.frankieone.com/v2/introduction/overview

Learn how FrankieOne's platform connects your application to hundreds of global data sources for identity verification, compliance screening, and fraud prevention through a single API.

## Welcome to FrankieOne

FrankieOne is an identity verification, compliance, and fraud prevention platform. It connects your application to hundreds of global data sources through a single API, so you can verify individuals and businesses, screen against watchlists, and monitor for fraud without managing multiple vendor integrations.

Whether you're in financial services, fintech, crypto, or any regulated industry, FrankieOne provides the tools to onboard customers, stay compliant, and prevent fraud at scale.

## Products

Modular products that work together or independently, depending on your use case.

<Columns>
  <Card title="KYC" icon="user-group" href="/docs/frankieone-introduction-to-kyc">
    Know Your Customer (KYC) creates a seamless onboarding experience for individual customers.
  </Card>

  <Card title="KYB" icon="business-time" href="/docs/introduction-to-kyb">
    Know Your Business (KYB) helps you onboard business customers quickly and securely.
  </Card>

  <Card title="Portal" icon="credit-card" href="/docs/getting-started-with-the-frankieone-portal">
    The FrankieOne Portal is your single point of truth for managing identity verification, AML, and Fraud.
  </Card>

  <Card title="Fraud and Transaction Monitoring" icon="shield-halved" href="/v2/docs/tm/fraud-and-transaction-monitoring-introduction">
    Prevent financial crime with risk signals, secure onboarding, and continuous monitoring.
  </Card>

  <Card title="OneSDK" icon="display-code" href="/docs/about-onesdk">
    OneSDK lets you deliver fast, secure identity verification without building the UI from scratch.
  </Card>
</Columns>

> **How these fit together:** Most teams start with **KYC** (for individuals) to handle onboarding. **OneSDK** provides the customer-facing UI, while the **Portal** gives your ops team a dashboard to manage verifications. **Fraud and Transaction Monitoring** layers on risk signals across the lifecycle. You can adopt products individually or combine them.

## Quick start guides

Get up and running quickly with our step-by-step quick start guides:

<Columns>
  <Card title="KYC" icon="user-group" href="/docs/getting-started">
    Set up your environment and make your first API call to the FrankieOne platform in minutes. This guide covers everything you need to get up and running.
  </Card>

  <Card title="OneSDK" icon="display-code" href="/docs/quickstart-guide">
    Use our Hosted OneSDK to deliver a fully managed, compliant, and customisable onboarding experience without building integrations or UI from scratch.
  </Card>

  <Card title="Fraud and Risk-Based Onboarding" icon="shield-halved" href="/docs/fraud-v2-getting-started">
    Integrate FrankieOne’s fraud signals and risk-based decisioning into your onboarding flow with our Fraud API.
  </Card>
</Columns>

## Not sure where to start?

<Columns>
  <Card title="Common use cases" icon="lightbulb" href="/v2/introduction/common-use-cases">
    Explore real-world scenarios to find the right products and integration approach for your needs.
  </Card>

  <Card title="Integrating with FrankieOne" icon="plug" href="/v2/introduction/integrating-with-frankie-one">
    Understand the key concepts and integration options before you start building.
  </Card>
</Columns>


# Products
Source: https://docs.frankieone.com/v2/introduction/products

Explore FrankieOne's products and capabilities across identity verification, business verification, fraud prevention, and compliance management.

## KYC

Verify individual customers during onboarding and ongoing compliance checks.

<Columns>
  <Card title="Electronic KYC" icon="address-card" href="/docs/electronic-kyc-checks">
    Verify a customer electronically using trusted data sources
  </Card>

  <Card title="Manual KYC Verification" icon="clipboard" href="/docs/manual-kyc-checks">
    Verify a customer in person or through offline checks
  </Card>

  <Card title="Manage Duplicate Entities" icon="clone" href="/docs/duplicate-checks">
    Detect, review, and resolve duplicate customer records.
  </Card>

  <Card title="Visa Checks" icon="passport" href="/docs/performing-visa-checks">
    Verify an individual’s visa status during onboarding.
  </Card>

  <Card title="Supporting Documents" icon="file-lines" href="/docs/supporting-documents-review">
    Review and assess documents provided during verification.
  </Card>

  <Card title="Webhooks and Event Notifications" icon="copy" href="/docs/notifications-and-webhooks">
    Receive real-time notifications when entity events occur.
  </Card>

  <Card title="Anti-money laundering" icon="money-check-dollar" href="/docs/anti-money-laundering">
    Screen customers against global watchlists to detect financial crime risks.
  </Card>

  <Card title="Fraud check" icon="masks-theater" href="/docs/fraud-checks-guide">
    Optimise onboarding using risk-based signals to detect and prevent fraud.
  </Card>

  <Card title="IDV and Biometrics" icon="fingerprint" href="/docs/idv-biometrics-guide">
    Verify genuine identities and block stolen IDs during onboarding.
  </Card>

  <Card title="Comments" icon="message" href="/docs/comments">
    Add programmatic notes to entity profiles for a complete audit trail.
  </Card>
</Columns>

***

## KYB

Verify businesses, ownership structures, and regulatory obligations.

<Columns>
  <Card title="Business Registration Verification" icon="building-circle-check" href="/docs/kyb/lookup-a-business">
    Validates a company’s details  against authoritative registries
  </Card>

  <Card title="UBO Discovery & Ownership Mapping" icon="user-group" href="/docs/kyb/organization-ownership">
    Identify directors, shareholders, and Ultimate Beneficial Owners (UBOs)
  </Card>

  <Card title="Watchlist & Sanctions Screening" icon="list" href="/docs/kyb/anti-money-laundering">
    Screen businesses and associated individuals against watchlists
  </Card>
</Columns>

***

## OneSDK

Choose how you integrate FrankieOne into your applications.

<Columns>
  <Card title="Hosted OneSDK" icon="layer-group" href="/docs/quickstart-guide/use-case-1-hosted-onesdk">
    Hosted OneSDK is a low-code identity verification solution that lets teams integrate KYC and IDV, without front-end development.
  </Card>

  <Card title="Embedded OneSDK" icon="rocket" href="/docs/embedded-flows/quick-start">
    Embedded OneSDK offers complete control over flexible identity verification and user experience.
  </Card>

  <Card title="Native Integration" icon="arrows-spin" href="/docs/native-integration">
    Integrate OneSDK into native mobile apps via WebView to combine web and native functionality seamlessly.
  </Card>
</Columns>

***

## Fraud and Transaction Monitoring

Detect and prevent fraud across onboarding, transactions, and ongoing customer activity.

<Columns>
  <Card title="Phone and email screening" icon="envelope-open-text" href="/docs/fraud-prevention-risk-based-onboarding-1">
    Verify customer contact details to block bad actors from entering.
  </Card>

  <Card title="Device and behavioral biometrics" icon="mobile" href="/docs/fraud-prevention-risk-based-onboarding-1">
    Use device signals and behaviour to stop fraud and bots.
  </Card>

  <Card title="Transaction monitoring" icon="credit-card-blank" href="/docs/overview-transaction-monitoring">
    Stop high-risk transactions and identify money laundering patterns.
  </Card>
</Columns>

***

## Portal

Manage verifications, review cases, and configure compliance workflows.

<Columns>
  <Card title="Getting Started with the Portal" icon="grid-2" href="/docs/getting-started-with-the-frankieone-portal">
    Navigate the FrankieOne Portal and manage your day-to-day operations.
  </Card>

  <Card title="Managing Entities" icon="users" href="/docs/entities-v2">
    Search, review, and manage individual and business entity profiles and their verification history.
  </Card>

  <Card title="Analytics and Reporting" icon="chart-line" href="/docs/dashboard">
    Track verification volumes, pass rates, and compliance metrics with built-in dashboards.
  </Card>
</Columns>


# Quick start guides
Source: https://docs.frankieone.com/v2/introduction/quickstart-guides

Get up and running quickly with FrankieOne using our step-by-step quick start guides.

Each guide walks you through setup, authentication, and your first successful implementation.

<Columns>
  <Card title="Getting Started with KYC: Your first API call" icon="user-group" href="/docs/getting-started">
    Set up, authenticate, and make your first FrankieOne API call for KYC.
  </Card>

  <Card title="Getting Started with KYB: Your first API call" icon="terminal" href="/docs/kyb/getting-started">
    Set up, authenticate, and make your first FrankieOne API call for KYB.
  </Card>

  <Card title="Fraud and Risk-based Onboarding" icon="shield-halved" href="/docs/fraud-v2-getting-started">
    Integrate FrankieOne’s fraud signals and risk-based decisioning into your onboarding flow with OneSDK and our Onboarding API.
  </Card>

  <Card title="Transaction and Activity Monitoring" icon="shield-halved" href="/docs/implementation-guide-transaction-monitoring">
    Integrate FrankieOne Transaction Monitoring via the Transaction Monitoring API.
  </Card>

  <Card title="Getting Started with Hosted OneSDK" icon="laptop-code" href="/docs/quickstart-guide/use-case-1-hosted-onesdk">
    Get up and running with OneSDK in minutes. This guide walks you through implementing two common onboarding flows: eKYC and IDV verification.
  </Card>

  <Card title="Getting Started with the FrankieOne Portal" icon="credit-card" href="/docs/getting-started-with-the-frankieone-portal">
    Learn how to navigate the FrankieOne Portal.
  </Card>
</Columns>

<Tip>
  **Not sure where to start?**

  * **Developers:** Begin with [KYC Quick Start](/docs/getting-started) to make your first API call
  * **Product/Ops teams:** Start with the [Portal Guide](/docs/getting-started-with-the-frankieone-portal)
  * **Front-end teams:** Try [Hosted OneSDK](/docs/quickstart-guide/use-case-1-hosted-onesdk) for the fastest integration
</Tip>


# FrankieOne KYC v2 - LLM Reference Guide
Source: https://docs.frankieone.com/v2/kyc/kyc/concepts-and-definitions/kyc-llm-reference

KYC LLM reference guide

## Quick Reference Card

```yaml theme={null}
api_version: v2                                                                                        
base_urls:                                                                                             
  uat: https://api.uat.frankie.one                                                                     
  production: https://api.frankie.one                                                                  
                                                                                                       
auth_headers:                                                                                          
  api_key: required                                                                                    
  X-Frankie-CustomerID: required (UUID)                                                                
  X-Frankie-CustomerChildID: optional (UUID)                                                           
  X-Frankie-Channel: optional (api|portal|smartui|custom)                                              
  X-Frankie-Username: optional (email for audit)                                                       
                                                                                                       
rate_limits:                                                                                           
  execute_workflow: 20 TPS                                                                             
  tracked_by: CustomerID + CustomerChildID combination                                                 
                                                                                                       
session_urls:                                                                                          
  uat: https://backend.kycaml.uat.frankiefinancial.io/auth/v1/machine-session                          
  production: https://backend.kycaml.frankiefinancial.io/auth/v1/machine-session                       
```

***

## 1. Complete Endpoint Reference

### Individual Management

| Method   | Endpoint                     | Purpose                          |
| -------- | ---------------------------- | -------------------------------- |
| `POST`   | `/v2/individuals`            | Create individual entity         |
| `GET`    | `/v2/individuals/{entityId}` | Get individual with all profiles |
| `PATCH`  | `/v2/individuals/{entityId}` | Update individual data           |
| `DELETE` | `/v2/individuals/{entityId}` | Delete individual                |

### Workflow Operations

| Method | Endpoint                                                                                    | Purpose                  |
| ------ | ------------------------------------------------------------------------------------------- | ------------------------ |
| `GET`  | `/v2/workflows`                                                                             | List available workflows |
| `POST` | `/v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/execute` | Execute workflow         |
| `GET`  | `/v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/results` | Get workflow results     |

### System

| Method | Endpoint | Purpose      |
| ------ | -------- | ------------ |
| `GET`  | `/ruok`  | Health check |

***

## 2. Field Enumerations (Complete)

### Document Types

````
### Valid Identity & Supporting Document Types

These document types **can be submitted** as part of identity or supporting evidence.

| Document Type | Description |
|--------------|------------|
| `OTHER` | Generic document type. Unspecified. |
| `DRIVERS_LICENSE` | Driver's license. |
| `PASSPORT` | Passport. |
| `VISA` | Visa document (not Visa payment card). |
| `IMMIGRATION` | Immigration card. |
| `NATIONAL_ID` | Any national ID card. |
| `TAX_ID` | Any national tax identifier. |
| `NATIONAL_HEALTH_ID` | National health program ID (e.g. Medicare, NHS). |
| `CONCESSION` | State-issued concession card. |
| `HEALTH_CONCESSION` | State-issued health-specific concession card. |
| `PENSION` | State-issued pension ID. |
| `MILITARY_ID` | Military identification card. |
| `BIRTH_CERT` | Birth certificate. |
| `CITIZENSHIP` | Citizenship certificate. |
| `MARRIAGE_CERT` | Marriage certificate. |
| `DEATH_CERT` | Death certificate. |
| `NAME_CHANGE` | Name change confirmation document. |
| `UTILITY_BILL` | Regulated utility bill (electricity, gas, etc.). |
| `BANK_STATEMENT` | Bank or card statement. |
| `BANK_ACCOUNT` | Bank account document. |
| `INTENT_PROOF` | Proof of intent (photo, video, or scanned letter). |
| `ATTESTATION` | Document of attestation (e.g. Statutory Declaration). |

---

### ❌ Internal or Manual Supporting Documents

The following document types are internal or manual review supporting documents.

| Document Type | Reason |
|--------------|-------|
| `SELF_IMAGE` | Used only for biometric comparison. |
| `DEVICE` | Device identifier, not an identity document. |
| `VEHICLE_REGISTRATION` | Not a valid identity document. |
| `PROOF_OF_ADDRESS` | Address evidence must use specific document types. |
| `HOUSE_REGISTRATION` | Not supported. |
| `YELLOW_HOUSE_REGISTRATION` | Not supported (Thor Ror 13). |
| `WORK_PERMIT` | Not accepted as a supporting identity document. |
| `EMPLOYMENT_CERTIFICATE` | Not accepted. |
| `NOTARY_PUBLIC_ID` | Not accepted. |

---

### Business & Corporate Document Types (KYB)

These document types are used **only for business verification (KYB)**.

| Document Type | Description |
|--------------|------------|
| `EXTERNAL_ADMIN` | Appointed administrator details. |
| `CHARGES` | Charges laid against a company or director. |
| `PRE_ASIC` | Pre-ASIC documentation. |
| `ANNUAL_RETURN` | Company annual return. |
| `REPORT` | Frankie-generated report. |
| `TRUST_DEED` | Corporate trust deed. |
| `DEED_OF_VARIATION` | Deed of variation document. |
| `REGISTER_OF_UNIT_HOLDERS` | Register of unit holders. |
| `PARTNERSHIP_AGREEMENT` | Partnership agreement documents. |
| `ADMIN_CHANGE` | Change of administrator. |
| `COMPANY_REPORT` | Registry-filed company report. |
| `ORGANIZATION_PROFILE` | Organization profile document. |
| `ORGANIZATION_OWNERSHIP` | Organization ownership structure. |

---

### Special Document Types

These document types have **special system-level purposes**.

| Document Type | Description |
|--------------|------------|
| `CHECK_RESULTS` | Results of checks completed outside Frankie workflows. |
| `AVIATION_SECURITY_ID` | Aviation Security Identification Card. |
| `MARITIME_SECURITY_ID` | Maritime Security Identification Card. |

---

### Available Enum Values (LLM Reference)

```text
OTHER, DRIVERS_LICENSE, PASSPORT, VISA, IMMIGRATION, NATIONAL_ID,
TAX_ID, NATIONAL_HEALTH_ID, CONCESSION, HEALTH_CONCESSION, PENSION,
MILITARY_ID, BIRTH_CERT, CITIZENSHIP, MARRIAGE_CERT, DEATH_CERT,
NAME_CHANGE, UTILITY_BILL, BANK_STATEMENT, BANK_ACCOUNT, INTENT_PROOF,
ATTESTATION, SELF_IMAGE, DEVICE, VEHICLE_REGISTRATION, PROOF_OF_ADDRESS,
HOUSE_REGISTRATION, YELLOW_HOUSE_REGISTRATION, WORK_PERMIT,
EMPLOYMENT_CERTIFICATE, NOTARY_PUBLIC_ID, EXTERNAL_ADMIN, CHARGES,
PRE_ASIC, ANNUAL_RETURN, REPORT, TRUST_DEED, DEED_OF_VARIATION,
REGISTER_OF_UNIT_HOLDERS, PARTNERSHIP_AGREEMENT, ADMIN_CHANGE,
COMPANY_REPORT, CHECK_RESULTS, AVIATION_SECURITY_ID,
MARITIME_SECURITY_ID, ORGANIZATION_PROFILE, ORGANIZATION_OWNERSHIP
                                                 
````

### Document Classes

```
IDENTITY              - Primary identity documents                                                     
SUPPORTING            - Supporting documents (utility bills, etc.)                                     
REPORT                - Generated reports                                                              
OTHER                 - Other document types                                                           
```

### Address Types

```
RESIDENTIAL           - Home address                                                                   
BUSINESS              - Business/work address                                                          
POSTAL                - Mailing address                                                                
PREVIOUS              - Former address                                                                 
OTHER                 - Other address type                                                             
```

Full address type options, note some are for KYB such as OFFICE\_LOCALITY

Available options:

`OTHER`,

`RESIDENTIAL`,

`BUSINESS`,

`POSTAL`,

`REGISTERED_OFFICE`,

`PLACE_OF_BUSINESS`,

`OFFICIAL_CORRESPONDANCE`,

`PLACE_OF_BIRTH`,

`OFFICE_LOCALITY`,

`AUTHORITATIVE_RESIDENTIAL`

### Address Status

```
CURRENT               - Current active address                                                         
PREVIOUS              - Previous address                                                               
UNVERIFIED            - Not yet verified                                                               
```

### Phone Types

```
MOBILE                - Mobile phone                                                                   
HOME                  - Home landline                                                                  
WORK                  - Work phone                                                                     
OTHER                 - Other phone type                                                               
```

### Email Types

```
PERSONAL              - Personal email                                                                 
WORK                  - Work email                                                                     
BUSINESS              - Business email                                                                 
OTHER                 - Other email type                                                               
```

### Gender Values

```
MALE                                                                                                   
FEMALE                                                                                                 
NON_BINARY                                                                                             
OTHER                                                                                                  
UNSPECIFIED                                                                                            
```

### Name Types (for alternateNames)

```
ALIAS                 - Also known as                                                                  
PREVIOUS              - Former name (maiden name, etc.)                                                
OTHER                 - Other name type                                                                
```

***

## 3. Workflow Response Enumerations

### Workflow Execution State

```
IN_PROGRESS           - Workflow is executing                                                          
COMPLETED             - Workflow finished successfully                                                 
CANCELED              - Workflow was canceled                                                          
TERMINATED            - Workflow was terminated early                                                  
ERROR                 - Workflow encountered error                                                     
TIMEOUT               - Workflow timed out                                                             
```

### Workflow Status (Overall Result)

```
PASS                  - Verification successful                                                        
FAIL                  - Verification failed                                                            
REVIEW                - Manual review required                                                         
UNCHECKED             - Not yet determined                                                             
IN_PROGRESS           - Still processing                                                               
BLOCKED               - Processing blocked                                                             
INCOMPLETE            - Missing required data                                                          
```

### Service Profile State

```
INIT                  - Just created                                                                   
AUTO                  - Automatically assigned                                                         
ACTIVE                - Profile is active                                                              
ARCHIVED              - No longer active                                                               
BLOCKLISTED           - Blocked from actions                                                           
INACTIVE              - Not currently in use                                                           
DELETED               - Soft deleted                                                                   
DUPLICATE             - Duplicate of another                                                           
```

### Risk Levels

```
LOW                   - Minimal risk (score 1-10)                                                      
MEDIUM                - Moderate risk (score 11-25)                                                    
HIGH                  - Significant risk (score 26-50)                                                 
UNACCEPTABLE          - Unacceptable risk (score 51+)                                                  
UNKNOWN               - Cannot determine                                                               
```

***

## 4. Issue Categories & Severities

### Issue Categories

```
KYC                   - Identity verification issues                                                   
AML                   - Anti-money laundering flags                                                    
BAD_DATA              - Invalid or malformed data                                                      
DOCUMENT              - Document-related issues                                                        
DUPLICATE             - Duplicate entity detected                                                      
FRAUD                 - Fraud indicators                                                               
IDV                   - Identity document verification                                                 
WATCHLIST             - Watchlist/sanctions match                                                      
DECEASED              - Deceased person match                                                          
ACTIVITY              - Suspicious activity                                                            
SYSTEM                - System/technical errors                                                        
```

### Issue Severities

```
INFO                  - Informational only                                                             
WARNING               - Non-blocking warning                                                           
REVIEW                - Requires manual review                                                         
BLOCK                 - Blocks further processing                                                      
CRITICAL              - Critical issue found                                                           
ERROR                 - Error encountered                                                              
```

### Common Issue Codes

```
NOT_FOUND             - Person not found in data sources                                               
BAD_DATA_ID           - Invalid document identifier                                                    
SERVICE_ERROR         - External service error                                                         
SERVICE_TIMEOUT       - Timeout with the request                                                      
PEP	/ SANCTION        - Sanctions/PEP match found                                                      
LIVENESS_DETECTION    - Biometric liveness failed                                                           
DATA_VALIDATION       - Document data validation failure                                                    
DATA_COMPARISON       - Document mismatch with other sources
DENY_LIST             - Visa deny list                                                              
...                                                    
```

Full category and issue code mapping with severity and meaning

| Category    | Issue Type                    | Severity     | Meaning                               |
| ----------- | ----------------------------- | ------------ | ------------------------------------- |
| AML         | PEP                           | REVIEW       | Politically Exposed Person detected   |
| AML         | SANCTION                      | BLOCK        | Sanctions list match                  |
| AML         | MEDIA                         | REVIEW       | Adverse media detected                |
| AML         | WATCHLIST                     | REVIEW       | Watchlist match                       |
| ACTIVITY    | ACTIVITY\_AML                 | REVIEW       | AML-related suspicious activity       |
| ACTIVITY    | ACTIVITY\_FRAUD               | REVIEW       | Fraud-related suspicious activity     |
| ACTIVITY    | ACTIVITY\_DEVICE              | REVIEW       | Device-related suspicious activity    |
| BAD\_DATA   | BAD\_DATA\_NAME               | WARNING      | Name missing or unusable              |
| BAD\_DATA   | BAD\_DATA\_DOB                | WARNING      | Date of birth missing or unusable     |
| BAD\_DATA   | BAD\_DATA\_DEVICE             | WARNING      | Device data missing or unusable       |
| BAD\_DATA   | BAD\_DATA\_ADDRESS            | WARNING      | Address missing or unusable           |
| BAD\_DATA   | BAD\_DATA\_ID                 | WARNING      | Identity document missing or unusable |
| BAD\_DATA   | BAD\_DATA\_EMAIL              | WARNING      | Email missing or unusable             |
| BAD\_DATA   | BAD\_DATA\_MOBILE             | WARNING      | Mobile number missing or unusable     |
| BLOCKLISTED | MATCHED\_INTERNAL             | BLOCK        | Internal blocklist match              |
| BLOCKLISTED | MATCHED\_SHARED               | BLOCK        | Shared blocklist match                |
| BLOCKLISTED | MATCHED\_EXTERNAL             | BLOCK        | External blocklist match              |
| DECEASED    | DECEASED                      | BLOCK        | Person is deceased                    |
| DEVICE      | DEVICE\_FRAUD\_MATCH          | REVIEW       | Device fraud detected                 |
| DEVICE      | DEVICE\_INVALID               | WARNING      | Device invalid or unverifiable        |
| DOCUMENT    | DATA\_VALIDATION              | REVIEW       | Document data validation failure      |
| DOCUMENT    | DATA\_CONSISTENCY             | REVIEW       | Document data inconsistent            |
| DOCUMENT    | DATA\_COMPARISON              | REVIEW       | Document mismatch with other sources  |
| DOCUMENT    | VISUAL\_AUTHENTICITY          | REVIEW       | Document failed visual authenticity   |
| DOCUMENT    | IMAGE\_INTEGRITY              | REVIEW       | Document image integrity issue        |
| DOCUMENT    | OCR                           | REVIEW       | OCR mismatch with user data           |
| DOCUMENT    | COMPROMISED\_DOCUMENT         | BLOCK        | Document is compromised               |
| DOCUMENT    | LIVENESS\_DETECTION           | REVIEW       | Liveness detection failed             |
| DOCUMENT    | DOCUMENT\_COMPARISON          | REVIEW       | Multiple documents mismatch           |
| DOCUMENT    | DOCUMENT\_CHECK\_INCOMPLETE   | INFO         | Document check incomplete             |
| DUPLICATE   | DUPLICATE                     | REVIEW       | Duplicate entity detected             |
| EXPIRY      | REQUIRES\_KYC                 | WARNING      | KYC expired                           |
| EXPIRY      | REQUIRES\_IDV                 | WARNING      | IDV expired                           |
| EXPIRY      | REQUIRES\_AML                 | WARNING      | AML expired                           |
| EXPIRY      | REQUIRES\_VISA                | WARNING      | Visa verification expired             |
| FRAUD       | FRAUD\_LIST                   | BLOCK        | Known fraud list match                |
| FRAUD       | FRAUD\_CHECK                  | REVIEW       | Generic fraud detected                |
| FRAUD       | FRAUD\_DEVICE                 | REVIEW       | Device-based fraud detected           |
| FRAUD       | FRAUD\_IP\_ADDRESS            | REVIEW       | IP-based fraud detected               |
| FRAUD       | FRAUD\_EMAIL\_ADDRESS         | REVIEW       | Email-based fraud detected            |
| FRAUD       | FRAUD\_PHONE\_NUMBER          | REVIEW       | Phone-based fraud detected            |
| FRAUD       | FRAUD\_INCOMPLETE             | INFO         | Fraud check incomplete                |
| KYC         | PARTIAL                       | REVIEW       | Partial KYC success                   |
| KYC         | NOT\_FOUND                    | REVIEW       | No identity match found               |
| KYC         | KYC\_INCOMPLETE               | INFO         | KYC incomplete                        |
| SYSTEM      | SERVICE\_TIMEOUT              | ERROR        | All providers timed out               |
| SYSTEM      | SERVICE\_ERROR                | ERROR        | Provider or internal system error     |
| VISA        | DENY\_LIST                    | BLOCK        | Visa deny list match                  |
| VISA        | VISA\_FAILED                  | REVIEW       | Visa verification failed              |
| BIOMETRICS  | LIVENESS\_DETECTION           | REVIEW       | Biometric liveness failed             |
| BIOMETRICS  | DOCUMENT\_COMPARISON          | REVIEW       | Selfie vs document mismatch           |
| BIOMETRICS  | BIOMETRICS\_INCOMPLETE        | INFO         | Biometrics incomplete                 |
| WATCHLIST   | INTERNAL\_MATCH               | REVIEW       | Internal watchlist match              |
| RISK        | RISK\_THRESHOLD\_HIGH         | REVIEW/BLOCK | High risk                             |
| RISK        | RISK\_THRESHOLD\_UNACCEPTABLE | REVIEW/BLOCK | Unacceptable risk                     |

***

## Risk Factors

FrankieOne calculates an overall risk assessment by evaluating multiple risk factors across identity, AML, fraud, behavior, and workflow integrity.

Each factor contributes to the final **risk level** (`LOW`, `MEDIUM`, `HIGH`, `UNACCEPTABLE`) returned in workflow results.

<Info>
  All risk factors, weightings, thresholds, and scoring are configurable per customer. The examples below illustrate typical categories and signals, not fixed scoring rules.
</Info>

***

## Core Risk Factors (Overview)

| Factor               | Description                                                                         |
| -------------------- | ----------------------------------------------------------------------------------- |
| `entity_type`        | Individual or organisation being verified                                           |
| `entity_age`         | Age group derived from date of birth                                                |
| `document_type`      | Type of identity document provided                                                  |
| `jurisdiction_risk`  | Risk associated with country of nationality, residence, birth, or document issuance |
| `pep_level`          | Politically Exposed Person classification                                           |
| `sanctions_hits`     | Sanctions list match severity                                                       |
| `adverse_media`      | Presence of negative media                                                          |
| `idv_results`        | Document, facial, and OCR verification outcomes                                     |
| `fraud_signals`      | Device, IP, email, phone, and session behavior                                      |
| `behavioral_signals` | Relationship length and workflow attempt patterns                                   |
| `workflow_integrity` | Duplicate entities or internal blocklists                                           |

For full risk view, see:\
[Assessing Risk](https://docs.frankieone.com/docs/assessing-risk)

***

## Risk Categories & Signals

### Entity Profile Risk

| Risk Factor                   | Handler                | Values                                                                       |
| ----------------------------- | ---------------------- | ---------------------------------------------------------------------------- |
| Entity Type                   | `entity_age`           | Under 18, Under 25, Adult 25+, Senior 65+                                    |
| Entity Type                   | `entity_type`          | Individual, Organisation                                                     |
| Document Type                 | `document_type_lookup` | Passport, Driver License, National ID, Visa, Birth Certificate, Tax ID, etc. |
| Nationality Risk              | `jurisdiction_lookup`  | Country-based                                                                |
| Residential Country Risk      | `jurisdiction_lookup`  | Country-based                                                                |
| Birth Country Risk            | `jurisdiction_lookup`  | Country-based                                                                |
| Document Issuing Country Risk | `jurisdiction_lookup`  | Country-based                                                                |

***

### AML & Screening Risk

| Risk Factor     | Handler             | Values            |
| --------------- | ------------------- | ----------------- |
| Sanctions Hits  | `num_sanctions`     | Low, Medium, High |
| PEP Level       | `pep_level_lookup`  | Level 1–4         |
| PEP Origin      | `pep_origin_lookup` | Local, Foreign    |
| Adverse Media   | `has_adverse_media` | TRUE / FALSE      |
| Watchlist Match | `on_watchlist`      | TRUE / FALSE      |

***

### Identity Verification (IDV) Risk

| Risk Factor                  | Handler                        |
| ---------------------------- | ------------------------------ |
| Document Verification Result | `idv_document_result`          |
| Facial Comparison Result     | `idv_facial_comparison_result` |
| OCR Consistency Result       | `idv_ocr_comparison_result`    |

These factors influence confidence in document authenticity and biometric matching.

***

### Onboarding Fraud Risk

| Risk Factor     | Handler               | Values                                   |
| --------------- | --------------------- | ---------------------------------------- |
| Device Risk     | `fraud_device`        | LOW, MEDIUM, HIGH, UNACCEPTABLE, UNKNOWN |
| IP Address Risk | `fraud_ip_address`    | LOW, MEDIUM, HIGH, UNACCEPTABLE, UNKNOWN |
| Email Risk      | `fraud_email`         | LOW, MEDIUM, HIGH, UNACCEPTABLE, UNKNOWN |
| Phone Risk      | `fraud_phone_number`  | LOW, MEDIUM, HIGH, UNACCEPTABLE, UNKNOWN |
| Session Count   | `fraud_count_session` | ≤2, 3–5, >5                              |

***

### Behavioral & Integrity Risk

| Risk Factor         | Handler                     | Values                            |
| ------------------- | --------------------------- | --------------------------------- |
| Relationship Length | `relationship_length`       | New, Short, Established, Credible |
| Workflow Attempts   | `workflow_attempts_counter` | Low, Multiple, High               |

***

### Workflow Logic Risk

| Risk Factor         | Handler                    | Impact          |
| ------------------- | -------------------------- | --------------- |
| Potential Duplicate | `unresolved_duplicates`    | Review or block |
| Confirmed Duplicate | `true_positive_duplicates` | Block           |
| Internal Matchlist  | `on_matchlist_internal`    | Block           |

***

### Custom Risk Factors

| Risk Factor                 | Handler                   |
| --------------------------- | ------------------------- |
| Customer-defined attributes | `custom_attribute_lookup` |

Custom attributes allow customers to inject domain-specific risk signals into workflows.

***

## How Risk Is Used

* Risk factors are evaluated during workflow execution
* Results contribute to:
  * `riskLevel`
  * `riskScore`
  * Issue categories and severities
* Outcomes may trigger:
  * Step-up verification
  * Manual review
  * Workflow termination

<Note>
  Risk scoring models vary by jurisdiction, industry, and customer configuration. Always validate behavior in UAT before production rollout.
</Note>

***

## 6. OneSDK Events (Complete)

### Lifecycle Events

```javascript theme={null}
oneSdk.on('ready', () => {})                    // SDK initialized                                     
oneSdk.on('loading', () => {})                  // Component loading                                   
oneSdk.on('mounted', () => {})                  // Component mounted to DOM                            
oneSdk.on('unmounted', () => {})                // Component removed from DOM                          
```

### Result Events

```javascript theme={null}
oneSdk.on('results:success', (data) => {})      // Verification passed                                 
oneSdk.on('results:partial', (data) => {})      // Partial success, review needed                      
oneSdk.on('results:pending', (data) => {})      // Still processing                                    
oneSdk.on('results:fail', (data) => {})         // Verification failed                                 
                                                                                                       
// Legacy format (also supported)                                                                      
oneSdk.on('form:result:success', (data) => {})                                                         
oneSdk.on('form:result:failed', (data) => {})                                                          
oneSdk.on('form:result:pending', (data) => {})                                                         
oneSdk.on('form:result:partial', (data) => {})                                                         
```

### Form Events

```javascript theme={null}
oneSdk.on('form:input:changed', (field, value) => {})                                                  
oneSdk.on('form:input:valid', (field) => {})                                                           
oneSdk.on('form:input:invalid', (field, errors) => {})                                                 
oneSdk.on('form:submitted', (data) => {})                                                              
oneSdk.on('form:step:changed', (step) => {})                                                           
```

### Document Events

```javascript theme={null}
oneSdk.on('document:uploaded', (docInfo) => {})                                                        
oneSdk.on('document:captured', (docInfo) => {})                                                        
oneSdk.on('document:error', (error) => {})                                                             
```

### Biometric Events

```javascript theme={null}
oneSdk.on('biometric:started', () => {})                                                               
oneSdk.on('biometric:captured', (data) => {})                                                          
oneSdk.on('biometric:error', (error) => {})                                                            
```

### Error Events

```javascript theme={null}
oneSdk.on('error', (error) => {                                                                        
  // error.code, error.message, error.details                                                          
})                                                                                                     
```

### Catch-All

```javascript theme={null}
oneSdk.on('*', (eventName, eventData) => {                                                             
  console.log(eventName, eventData);                                                                   
})                                                                                                     
```

***

## 7. Error Codes

### Authentication Errors (AUTH-\*)

| Code        | Message             | Resolution                                    |
| ----------- | ------------------- | --------------------------------------------- |
| `AUTH-0001` | Missing credentials | Add api\_key and X-Frankie-CustomerID headers |
| `AUTH-0002` | Unauthorized        | Check API key is valid                        |
| `AUTH-0003` | Forbidden           | Check CustomerID has access                   |
| `AUTH-0004` | Token expired       | Generate new session token                    |

### Validation Errors (API-\*)

| Code       | Message              | Resolution                      |
| ---------- | -------------------- | ------------------------------- |
| `API-0400` | Bad request          | Check request body format       |
| `API-0404` | Not found            | Check endpoint URL and entityId |
| `API-0409` | Conflict             | Entity already exists           |
| `API-0422` | Unprocessable entity | Validate field values           |
| `API-0429` | Rate limited         | Reduce request frequency        |

### System Errors (SYS-\*)

| Code       | Message                  | Resolution        |
| ---------- | ------------------------ | ----------------- |
| `SYS-1000` | Internal error           | Retry request     |
| `SYS-1063` | Report generation failed | Contact support   |
| `SYS-1100` | Service unavailable      | Check status page |

### Workflow Errors (WF-\*)

| Code      | Message                | Resolution                       |
| --------- | ---------------------- | -------------------------------- |
| `WF-0001` | Workflow not found     | Check workflowName spelling      |
| `WF-0002` | Workflow not available | Workflow not enabled for account |
| `WF-0003` | Missing required data  | Add required fields for workflow |

***

## 8. Workflow Requirements Matrix

| Workflow          | Document Required | Address Required | DOB Required | Name Required |
| ----------------- | ----------------- | ---------------- | ------------ | ------------- |
| `*-IDOnly`        | ✅ Yes             | ❌ No             | ✅ Yes        | ✅ Yes         |
| `*-TwoPlus`       | ❌ No              | ✅ Yes            | ✅ Yes        | ✅ Yes         |
| `*-TwoPlusID`     | ✅ Yes             | ✅ Yes            | ✅ Yes        | ✅ Yes         |
| `*-OnePlusOne`    | ✅ Yes             | ❌ No             | ✅ Yes        | ✅ Yes         |
| `*-AgeVerify`     | ❌ No              | ❌ No             | ✅ Yes        | ✅ Yes         |
| `*-AddressVerify` | ❌ No              | ✅ Yes            | ❌ No         | ✅ Yes         |

### Document Requirements by Workflow Type

**IDOnly Workflows:**

```json theme={null}
{                                                                                                      
  "documents": {                                                                                       
    "IDENTITY": [{                                                                                     
      "type": "PASSPORT|DRIVERS_LICENSE|NATIONAL_ID",                                                  
      "country": "AUS",                                                                                
      "primaryIdentifier": "required"                                                                  
    }]                                                                                                 
  }                                                                                                    
}                                                                                                      
```

**TwoPlus Workflows:**

**Address line 1 can be provided in street name**

```json theme={null}
{                                                                                                      
  "addresses": [{                                                                                      
    "type": "RESIDENTIAL",                                                                             
    "country": "AUS",                                                                                  
    "streetNumber": "required", //unless in streetName address line 1                                                                       
    "streetName": "required",  //can have address line 1                                                                        
    "locality": "required",   //generally required city/town/locality                                                                         
    "subdivision": "required",    //generally required state/region/subdivision                                                                     
    "postalCode": "required"                                                                           
  }]                                                                                                   
}                                                                                                      
```

***

## 9. Complete Request/Response Examples

### Create Individual + Execute Workflow

**Request:**

```http theme={null}
POST /v2/individuals HTTP/1.1                                                                          
Host: api.uat.frankie.one                                                                              
api_key: your-api-key                                                                                  
X-Frankie-CustomerID: your-customer-id                                                                 
Content-Type: application/json                                                                         
                                                                                                       
{                                                                                                      
  "individual": {                                                                                      
    "name": {                                                                                          
      "givenName": "Jane",  
      "middleName": "",                                                                           
      "familyName": "Smith"                                                                            
    },                                                                                                 
    "dateOfBirth": {                                                                                   
      "year": "1990",                                                                                  
      "month": "05",                                                                                   
      "day": "15"                                                                                      
    },                                                                                                 
    "addresses": [{                                                                                    
      "type": "RESIDENTIAL",                                                                           
      "country": "AUS",                                                                                
      "streetNumber": "123",                                                                           
      "streetName": "Main",                                                                            
      "streetType": "Street",                                                                          
      "locality": "Sydney",                                                                            
      "subdivision": "NSW",                                                                            
      "postalCode": "2000"                                                                             
    }],                                                                                                
    "documents": {                                                                                     
      "IDENTITY": [{                                                                                   
        "type": "PASSPORT",                                                                            
        "country": "AUS",                                                                              
        "primaryIdentifier": "PA1234567"                                                               
      }]                                                                                               
    }                                                                                                  
  },                                                                                                   
  "serviceName": "DEFAULT",                                                                                
  "workflowName": "AUS-Basic1V-IDOnly"                                                                 
}                                                                                                      
```

**Response (201 Created):**

```json theme={null}
{                                                                                                      
  "individual": {                                                                                      
    "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",                                                
    "entityType": "INDIVIDUAL",                                                                        
    "name": {                                                                                          
      "nameId": "uuid",                                                                                
      "givenName": "Jane",                                                                             
      "familyName": "Smith",                                                                           
      "displayName": "Jane Smith"                                                                      
    },                                                                                                 
    "dateOfBirth": {                                                                                   
      "dateOfBirthId": "uuid",                                                                         
      "year": "1990",                                                                                  
      "month": "05",                                                                                   
      "day": "15",                                                                                     
      "normalized": "1990-05-15"                                                                       
    },                                                                                                 
    "createdAt": "2026-01-27T00:00:00.000Z"                                                            
  },                                                                                                   
  "serviceProfiles": [{                                                                                
    "serviceProfileId": "uuid",                                                                        
    "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",                                                
    "serviceName": "DEFAULT",                                                                              
    "state": "INIT"                                                                                    
  }],                                                                                                  
  "requestId": "01HN9XHZN6MGXM9JXG50K59Q85"                                                            
}                                                                                                      
```

### Execute Workflow

**Request:**

```http theme={null}
POST /v2/individuals/3fa85f64-5717-4562-b3fc-2c963f66afa6/serviceprofiles/DEFAULT/workflows/AUS-Basic1     
V-IDOnly/execute HTTP/1.1                                                                              
Host: api.uat.frankie.one                                                                              
api_key: your-api-key                                                                                  
X-Frankie-CustomerID: your-customer-id                                                                 
Content-Type: application/json                                                                         
                                                                                                       
{}                                                                                                     
```

**Response:**

```json theme={null}
{                                                                                                      
  "requestId": "01HN9XHZN6MGXM9JXG50K59Q86",                                                           
  "workflowExecutionId": "01HN9XHZN6MGXM9JXG50K59Q87"                                                  
}                                                                                                      
```

### Get Results

**Request:**

```http theme={null}
GET /v2/individuals/3fa85f64-5717-4562-b3fc-2c963f66afa6 HTTP/1.1                                      
Host: api.uat.frankie.one                                                                              
api_key: your-api-key                                                                                  
X-Frankie-CustomerID: your-customer-id                                                                 
```

**Response (workflow completed):**

```json theme={null}
{                                                                                                      
  "individual": { ... },                                                                               
  "serviceProfiles": [{                                                                                
    "serviceName": "DEFAULT",                                                                              
    "state": "ACTIVE",                                                                                 
    "workflowSummaries": [{                                                                            
      "workflowName": "AUS-Basic1V-IDOnly",                                                            
      "workflowExecutionId": "01HN9...",                                                               
      "workflowExecutionState": "COMPLETED",                                                           
      "status": "PASS",                                                                                
      "steps": {                                                                                       
        "order": ["START", "MATCHLIST", "KYC"],                                                        
        "passed": ["START", "MATCHLIST", "KYC"],                                                       
        "failed": [],                                                                                  
        "incomplete": []                                                                               
      },                                                                                               
      "issues": [],                                                                                    
      "riskAssessment": {                                                                              
        "riskLevel": "LOW",                                                                            
        "riskScore": 7                                                                                 
      }                                                                                                
    }]                                                                                                 
  }]                                                                                                   
}                                                                                                      
```

***

## 10. Webhook Payload Schemas

### WorkflowComplete Event

```json theme={null}
{                                                                                                      
  "version": "2.0",                                                                                    
  "notificationType": "EVENT",                                                                         
  "function": "WorkflowComplete",                                                                      
  "functionResult": "SUCCESS",                                                                         
  "requestId": "01HN9...",                                                                             
  "entityId": "3fa85f64-...",                                                                          
  "entityType": "INDIVIDUAL",                                                                          
  "entityCustomerReference": "your-ref-123",                                                           
  "serviceName": "DEFAULT",                                                                                
  "workflowExecutionId": "01HN9...",                                                                   
  "workflowName": "AUS-Basic1V-IDOnly",                                                                
  "overallStatus": "PASS",                                                                             
  "message": "Workflow completed successfully",                                                        
  "channel": "api"                                                                                     
}                                                                                                      
```

### EntityRiskChanged Event

```json theme={null}
{                                                                                                      
  "version": "2.0",                                                                                    
  "notificationType": "EVENT",                                                                         
  "function": "EntityRiskChanged",                                                                     
  "functionResult": "SUCCESS",                                                                         
  "entityId": "3fa85f64-...",                                                                          
  "serviceName": "DEFAULT",                                                                                
  "previousRiskLevel": "LOW",                                                                          
  "newRiskLevel": "MEDIUM",                                                                            
  "riskScore": 18                                                                                      
}                                                                                                      
```

***

## 11. Australian Document Identifiers

### Driver's License Format by State

**Licence Number Formats**

| **State** | **Format**   | **Length** | **Example** |
| :-------- | :----------- | :--------- | :---------- |
| ACT       | Numeric      | Up to 10   | `123456789` |
| NT        | Numeric      | Up to 10   | `123456789` |
| QLD       | Numeric      | 8-9        | `12345678`  |
| NSW       | Alphanumeric | 6-8        | `N49187`    |
| SA        | Alphanumeric | 6          | `ABC123`    |
| TAS       | Alphanumeric | 6-8        | `A12345`    |
| VIC       | Numeric      | Up to 10   | `123456789` |
| WA        | Numeric      | 7          | `1234567`   |

**Card Number Formats**

| **State** | **Format**   | **Length** | **Example**  |
| :-------- | :----------- | :--------- | :----------- |
| ACT       | Alphanumeric | 10         | `ABC1234567` |
| NT        | Numeric      | 6-8        | `123456`     |
| QLD       | Alphanumeric | 10         | `ABC1234567` |
| NSW       | Numeric      | 10         | `1234567890` |
| SA        | Alphanumeric | 9          | `ABC123456`  |
| TAS       | Alphanumeric | 9          | `ABC123456`  |
| VIC       | Alphanumeric | 8          | `ABC12345`   |
| WA        | Alphanumeric | 8-10       | `ABC123456`  |

### Passport Format

* Australian: 2 letters + 7 digits (e.g., PA1234567)
* International: Varies by country

### Medicare Card

* 10 digits + IRN (1 digit)
* Format: XXXX XXXXX X/X

***

## 12. Testing in UAT

### Test Data Behavior

* UAT environment connects to test data sources
* Fake document numbers will return `NOT_FOUND` or `BAD_DATA_ID`
* Use FrankieOne-provided test credentials for realistic responses

### Expected Test Results

| Scenario              | Expected Status | Issues            |
| --------------------- | --------------- | ----------------- |
| Valid real ID         | PASS            | None              |
| Fake ID number        | FAIL            | BAD\_DATA\_ID     |
| Missing ID for IDOnly | 400 Error       | Validation error  |
| Expired document      | FAIL            | DOCUMENT\_EXPIRED |

***

## 13. Rate Limiting

### Headers (when rate limited)

```http theme={null}
HTTP/1.1 429 Too Many Requests                                                                         
X-RateLimit-Limit: 20                                                                                  
X-RateLimit-Remaining: 0                                                                               
X-RateLimit-Reset: 1706316000                                                                          
Retry-After: 60                                                                                        
```

### Best Practices

1. Implement exponential backoff
2. Cache workflow list (changes infrequently)
3. Batch operations where possible
4. Use webhooks instead of polling

***

## 14. SDK Installation

### NPM

```bash theme={null}
npm install @frankieone/one-sdk                                                                        
```

### CDN

```html theme={null}
<script src="https://assets.frankiefinancial.io/one-sdk/v1/oneSdk.umd.js"></script>                    
```

### Initialization

```javascript theme={null}
const oneSdk = await OneSDK({                                                                          
  session: sessionTokenFromBackend,                                                                    
  mode: "development",  // or "production"                                                             
  recipe: {                                                                                            
    form: {                                                                                            
      provider: { name: 'react' }  // or 'vanilla'                                                     
    }                                                                                                  
  }                                                                                                    
});                                                                                                    
```

## OpenAPI & Swagger Specification

| Item                   | Status    | How to Resolve                                                                                                                |
| ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
| OpenAPI / Swagger spec | Available | Access via [https://docs.frankieone.com/docs/introduction/resources](https://docs.frankieone.com/docs/introduction/resources) |

<Note>
  The OpenAPI specifications are published as separate resources.\
  Use the **KYC v2 spec** for individual, workflow, document, and results APIs.\
  Use the **Core v2 spec** for shared operations such as workflow discovery and audit access.
</Note>

***

## Remaining Gaps (Contact Support)

| Item                   | Status                 | How to Resolve                                          |
| ---------------------- | ---------------------- | ------------------------------------------------------- |
| Webhook setup          | Requires manual config | Email [help@frankieone.com](mailto:help@frankieone.com) |
| Custom workflows       | Account-specific       | Contact Customer Success                                |
| Production credentials | Requires contract      | Contact Sales                                           |


# Workflows
Source: https://docs.frankieone.com/v2/kyc/kyc/concepts-and-definitions/kyc-workflows

Available verification workflows and their requirements

## Understanding Workflows

Workflows define the verification checks performed on an individual. Different workflows have different data requirements and query different data sources depending on regulatory and risk needs.

<Info>
  Use <code>
  GET /v2/workflows</code>

  to see which workflows are enabled for your account.
</Info>

***

## Workflow Requirements Matrix

| Workflow Pattern  | Document | Address | DOB | Name |
| ----------------- | :------: | :-----: | :-: | :--: |
| `*-IDOnly`        |     ✅    |    ❌    |  ✅  |   ✅  |
| `*-TwoPlus`       |     ❌    |    ✅    |  ✅  |   ✅  |
| `*-TwoPlusID`     |     ✅    |    ✅    |  ✅  |   ✅  |
| `*-OnePlusOne`    |     ✅    |    ❌    |  ✅  |   ✅  |
| `*-AddressVerify` |     ❌    |    ✅    |  ❌  |   ✅  |
| `*-AgeVerify`     |     ❌    |    ❌    |  ✅  |   ✅  |

<Warning>
  Submitting insufficient data for a workflow will result in a 400 Bad Request error or BAD\_DATA issues in the verification result.

  For example if you use an \*-IDOnly workflow such as AUS-Basic1V-IDOnly and do not provide a government ID you will get a 400 Bad Request error.
</Warning>

***

## Australia Workflows

### Essential Tier

<AccordionGroup>
  <Accordion title="AUS-Basic1V-IDOnly">
    **Description:** Single government ID verification via DVS

    **Requirements:**

    * Name (given + family)
    * Date of birth
    * Identity document (passport, driver’s license, or national ID)

    **Data Sources:**

    * Australian Document Verification Service (DVS)

    ```json theme={null}
    {
      "documents": {
        "IDENTITY": [{
          "type": "PASSPORT",
          "country": "AUS",
          "primaryIdentifier": "PA1234567"
        }]
      }
    }
    ```
  </Accordion>

  <Accordion title="AUS-Basic2V-TwoPlus">
    **Description:** Two or more data source verification (no ID required)

    **Requirements:**

    * Name (given + family)
    * Date of birth
    * Residential address

    **Data Sources:**

    * Credit bureaus
    * Electoral rolls
    * Public records
  </Accordion>

  <Accordion title="AUS-Basic2V-TwoPlusID">
    **Description:** Two+ data sources plus ID verification

    **Requirements:**

    * Name (given + family)
    * Date of birth
    * Residential address
    * Identity document

    **Data Sources:**

    * DVS
    * Credit bureaus
    * Electoral rolls
  </Accordion>

  <Accordion title="AUS-Basic3V-TwoPlus">
    **Description:** Three data source verification

    **Requirements:**

    * Name (given + family)
    * Date of birth
    * Residential address
  </Accordion>

  <Accordion title="AUS-Basic3V-TwoPlusAge">
    **Description:** Three data sources with explicit age verification

    **Requirements:**

    * Name (given + family)
    * Date of birth (age verified)
    * Residential address
  </Accordion>
</AccordionGroup>

***

### Enhanced Tier

<AccordionGroup>
  <Accordion title="AUS-Advanced1V-IDOnly">
    **Description:** Enhanced ID verification with additional compliance checks

    **Requirements:**

    * Name (given + family)
    * Date of birth
    * Identity document

    **Additional Checks:**

    * AML screening
    * PEP screening
    * Sanctions lists
  </Accordion>

  <Accordion title="AUS-Advanced3V-TwoPlusID">
    **Description:** Comprehensive verification with three sources plus ID

    **Requirements:**

    * Name (given + family)
    * Date of birth
    * Residential address
    * Identity document
  </Accordion>
</AccordionGroup>

***

### Risk-Based Tier

<AccordionGroup>
  <Accordion title="AUS-Risk-CDD-Email-Phone">
    **Description:** Customer Due Diligence with contact risk assessment

    **Requirements:**

    * Name (given + family)
    * Date of birth
    * Email address
    * Phone number

    **Fraud Signals:**

    * Email risk scoring
    * Phone risk indicators
  </Accordion>

  <Accordion title="AUS-Risk-CDD-Email-Phone-Device-IP">
    **Description:** Full risk assessment including device and network intelligence

    **Requirements:**

    * All CDD requirements
    * Device fingerprint (via OneSDK)
    * IP address

    **Fraud Signals:**

    * Email risk
    * Phone risk
    * Device risk
    * IP geolocation
  </Accordion>
</AccordionGroup>

***

## New Zealand Workflows

<Accordion title="NZL-Basic1V-OnePlusOne">
  **Description:** One primary plus one secondary source verification

  **Requirements:**

  * Name (given + family)
  * Date of birth
  * Identity document (NZ passport or driver’s license)
</Accordion>

***

## United States Workflows

<AccordionGroup>
  <Accordion title="USA-Basic1V-OnePlus">
    **Description:** Basic US identity verification

    **Requirements:**

    * Name (given + family)
    * Date of birth
    * US address
    * SSN (optional, improves match rate)
  </Accordion>

  <Accordion title="USA-eIDExpress">
    **Description:** Express electronic identity verification

    **Requirements:**

    * Name (given + family)
    * Date of birth
  </Accordion>
</AccordionGroup>

***

## Global Workflows

<AccordionGroup>
  <Accordion title="GLB-IntlOnePlus">
    **Description:** International verification using country-specific data sources

    **Requirements:**

    * Name (given + family)
    * Date of birth
    * Country of residence

    **Coverage:** Contact FrankieOne for supported countries and data sources.
  </Accordion>

  <Accordion title="GLB-AMLBasic">
    **Description:** AML screening only (no identity verification)

    **Requirements:**

    * Name (given + family)
    * Date of birth

    **Checks:**

    * PEP screening
    * Sanctions lists
    * Watchlists
  </Accordion>

  <Accordion title="GLB-AMLMedia">
    **Description:** AML screening with adverse media monitoring

    **Requirements:**

    * Name (given + family)
    * Date of birth

    **Checks:**

    * PEP screening
    * Sanctions lists
    * Adverse media
  </Accordion>
</AccordionGroup>

## Global Address Verification (Ruleset-Based)

<AccordionGroup>
  <Accordion title="Global Address Verification (KYC Ruleset)">
    **Description:**\
    Verifies a residential address using country-specific data sources and fuzzy matching rules, without requiring full identity verification.

    **Typical Crypto Use Cases:**

    * Wallet creation
    * Tiered onboarding (Tier 0 / Tier 1)
    * Jurisdiction eligibility checks
    * Proof-of-address prior to higher transaction limits

    **Requirements:**

    * Residential address
    * Country of residence

    **Supported Address Fields:**

    * Street number
    * Street name
    * Locality / city
    * Subdivision / state (where applicable)
    * Postal code
    * Country

    **Verification Capabilities:**

    * Address normalization
    * Partial and fuzzy matching across providers
    * Country-specific address formats
    * Multiple provider corroboration

    **Does NOT require:**

    * Government ID
    * Name matching
    * Date of birth verification

    **Optional Add-ons:**

    * AML screening via `GLB-AMLBasic` or `GLB-AMLMedia`
    * Risk-based escalation to identity verification if required

    ```json theme={null}
    {
      "addresses": [
        {
          "type": "RESIDENTIAL",
          "typeDescription": "Home Address",
          "format": "standard",
          "streetNumber": "1200",
          "streetName": "SW Orleans",
          "locality": "Topeka",
          "district": "",
          "subdivision": "KS",
          "country": "USA",
          "postalCode": "66604",
          "status": "CURRENT"
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

## Global Age Verification (DOB Only)

<AccordionGroup>
  <Accordion title="GLB-DOBVerify (two_plus_age)">
    **Description:**\
    Standalone date-of-birth verification against trusted data sources.\
    This workflow verifies **age only** and does **not** perform full identity verification.

    **Use cases:**

    * Age-gated products (gaming, content platforms)
    * Lightweight eligibility checks
    * Pre-KYC or step-up verification flows
    * Jurisdictional age compliance without ID collection

    **Requirements:**

    * Given name
    * Family name
    * Date of birth
    * Country of residence

    **Verification Behavior:**

    * DOB is checked against two or more independent data sources
    * No document upload required
    * No biometric or identity matching performed
    * Returns age confidence only (not identity confidence)

    **Typical Outcomes:**

    * `PASS` — Date of birth confidently verified
    * `REVIEW` — Partial match or insufficient confidence
    * `FAIL` — Date of birth could not be verified

    **Risk Factors Evaluated:**

    * Entity Age
    * Jurisdiction Risk
    * Data Consistency Across Sources

    **Limitations:**

    * Does not verify identity
    * Does not satisfy KYC or AML requirements on its own
    * Should be paired with a KYC workflow if identity assurance is required

    **Recommended Pairings:**

    * Identity verification: `GLB-IntlOnePlus`
    * Fraud signals (optional): Device and IP risk checks

    ```json theme={null}
    {
      "individual": {
        "name": {
            "familyName": "YOUNGTEN",
            "middleName": "J",
            "givenName": "Oliver"
        },
        "dateOfBirth": {
            "day": "15",
            "month": "06",
            "year": "2015"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "country": "AUS"
          }
        ]
      },
      "serviceName": "DEFAULT",
      "workflowName": "GLB-DOBVerify"
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Choosing the Right Workflow

<Steps>
  <Step title="Determine regulatory requirements">
    Understand the verification level required in your jurisdiction.
  </Step>

  <Step title="Assess available user data">
    Choose workflows that match the data you can reliably collect.
  </Step>

  <Step title="Balance UX and security">
    More checks increase assurance but add user friction.
  </Step>

  <Step title="Apply risk-based escalation">
    Use enhanced workflows for higher-risk users.
  </Step>
</Steps>

| Use Case                     | Recommended Workflow                 |
| ---------------------------- | ------------------------------------ |
| Low-risk onboarding          | `AUS-Basic1V-IDOnly`                 |
| Regulated financial services | `AUS-Basic2V-TwoPlusID`              |
| High-value accounts          | `AUS-Advanced3V-TwoPlusID`           |
| Fraud-prone industries       | `AUS-Risk-CDD-Email-Phone-Device-IP` |
| AML screening only           | `GLB-AMLBasic`                       |


# BNPL - Customer Onboarding
Source: https://docs.frankieone.com/v2/kyc/kyc/use-cases/bnpl-risk-based-customer-onboarding

KYC BNPL Use Case: Risk-Based Customer Onboarding

## Overview

This guide covers FrankieOne's KYC solution for Buy Now Pay Later (BNPL) providers, designed to support identity verification, fraud prevention, and responsible lending obligations while maintaining the low-friction experience BNPL customers expect.

***

## Summary

### Available Workflows

| Workflow                          | Purpose                   | When to Use                                                        |
| --------------------------------- | ------------------------- | ------------------------------------------------------------------ |
| `AUS-Basic3V-twoplus`             | Low-friction verification | **Primary** - Low-value first purchases                            |
| `AUS-Basic3V-twoplusid`           | Standard verification     | Step-up for higher-value or elevated risk requires a government ID |
| `AUS-Risk-CDD-Email-Phone-Device` | Fraud detection           | Fraud signal assessment                                            |

### Tiered Verification Approach

```mermaid theme={null}
flowchart TD
    A["New Customer Application"] --> B{Transaction Value}
    B -->|under $150| C["Tier 1: Basic Verification"]
    B -->|$150 - $500| D["Tier 2: Standard Verification"]
    B -->|over $500| E["Tier 3: Enhanced Verification"]
    C --> F{Fraud Risk}
    D --> F
    E --> F
    F -->|Low| G["Approve"]
    F -->|Medium| H["Step-Up or Limit"]
    F -->|High| I["Decline or Review"]
```

### Tier Definitions

| Tier       | Transaction Value | Verification Level  | Target Time      |
| ---------- | ----------------- | ------------------- | ---------------- |
| **Tier 1** | Under \$150       | Basic (2-source)    | Under 5 seconds  |
| **Tier 2** | $150 - $500       | Standard (3-source) | Under 10 seconds |
| **Tier 3** | Over \$500        | Enhanced + Document | Under 60 seconds |

### Quick Implementation Flow

```mermaid theme={null}
flowchart LR
    A["Customer Details"] --> B["Identity Verification"]
    B --> C["Fraud Assessment"]
    C --> D["Risk Decision"]
    D --> E["Transaction Approved"]
```

### Decision Outcomes

| Outcome     | Action                                         |
| ----------- | ---------------------------------------------- |
| **APPROVE** | Proceed with transaction, set credit limit     |
| **STEP-UP** | Request additional verification (time-limited) |
| **DECLINE** | Display compliant message, log for review      |

### Key Fraud Signals

| Signal                            | Risk Level | Description             |
| --------------------------------- | ---------- | ----------------------- |
| Device on fraud blocklist         | Critical   | Known fraudulent device |
| Email domain disposable           | Critical   | Temporary email service |
| Email age under 7 days            | High       | Recently created email  |
| Multiple applications from device | High       | Velocity indicator      |

### Support

* **Documentation**: [docs.frankieone.com](https://docs.frankieone.com)
* **Support**: Contact your FrankieOne representative

***

## Expanded Details

### Regulatory Context

> **Disclaimer:** The information in this section is provided for general guidance only and does not constitute legal or compliance advice. Customers must seek independent legal and regulatory advice to ensure their implementation meets their specific regulatory obligations. FrankieOne is not responsible for customers' compliance decisions or outcomes.

> **Regulatory Updates:** BNPL regulation in Australia is evolving. The Australian Government has announced reforms to bring BNPL under the National Consumer Credit Protection Act. Customers should monitor updates from ASIC and Treasury to ensure ongoing compliance.

#### Australian BNPL Regulatory Framework

BNPL providers operate under an evolving regulatory framework. FrankieOne's BNPL workflows can support these obligations:

| Obligation                  | Requirement                                     | How FrankieOne Can Support                                |
| --------------------------- | ----------------------------------------------- | --------------------------------------------------------- |
| **Customer Identification** | Verify customer identity                        | Automated identity verification with low-friction options |
| **Age Verification**        | Ensure customers are 18+                        | Age verification against authoritative sources            |
| **Fraud Prevention**        | Prevent identity fraud and synthetic identities | Device, email, and phone risk assessment                  |
| **Responsible Lending**     | Assess customer suitability (under reforms)     | Identity data to support affordability assessments        |
| **AML/CTF Compliance**      | Where applicable as reporting entity            | Risk-based verification aligned to AML/CTF programs       |

#### Upcoming BNPL Reforms

The Australian Government has announced BNPL will be regulated as a credit product. Key changes may include:

| Reform Area       | Expected Requirement               | Preparation                                   |
| ----------------- | ---------------------------------- | --------------------------------------------- |
| **Licensing**     | Australian Credit Licence required | Enhanced compliance program                   |
| **Affordability** | Unsuitability assessments          | Income/expense verification capability        |
| **Hardship**      | Hardship provisions                | Customer identification for hardship requests |
| **Disclosure**    | Enhanced disclosure requirements   | Clear verification messaging                  |

***

### Workflow Configuration Details

#### Design Principles for BNPL

BNPL verification must balance:

* **Low friction**: Customers expect instant approval
* **Fraud prevention**: BNPL is a target for fraud due to instant credit
* **Regulatory compliance**: Meeting current and upcoming obligations
* **Scalability**: High volume, variable transaction values

#### Primary Workflow: `AUS-Basic2V-LowFriction`

Optimised for BNPL's low-friction requirements while maintaining verification integrity.

**Core Checks:**

| Check Type                | Purpose                | Typical Response Time |
| ------------------------- | ---------------------- | --------------------- |
| Name and DOB verification | Identity confirmation  | under 3 seconds       |
| Age verification (18+)    | Regulatory requirement | under 3 seconds       |
| Address verification      | Identity confirmation  | under 3 seconds       |
| Device risk assessment    | Fraud prevention       | Real-time             |

#### Step-Up Workflow: `AUS-Basic3V-Standard`

Triggered for higher-risk scenarios or higher credit limits.

**Step-Up Triggers:**

| Trigger             | Threshold                 | Action                |
| ------------------- | ------------------------- | --------------------- |
| Transaction value   | over \$500 (configurable) | Enhanced verification |
| Account age         | under 30 days             | Additional checks     |
| Device risk         | Medium or higher          | Step-up required      |
| Cumulative exposure | over \$2,000              | Enhanced verification |

#### Fraud Detection: `AUS-Risk-CDD-Email-Phone-Device`

BNPL is particularly vulnerable to fraud. This workflow assesses fraud signals.

**Risk Signals Evaluated:**

| Signal                            | Risk Level | Description                  |
| --------------------------------- | ---------- | ---------------------------- |
| Device on fraud blocklist         | Critical   | Known fraudulent device      |
| Multiple applications from device | High       | Velocity indicator           |
| Email age under 7 days            | High       | Recently created email       |
| Email domain disposable           | Critical   | Temporary email service      |
| Phone number invalid              | High       | Non-working number           |
| Synthetic identity indicators     | Critical   | Fabricated identity patterns |
| IP geolocation mismatch           | Medium     | Location inconsistency       |

***

### Step-by-Step Implementation

> **Note:** This section describes the conceptual implementation flow. For actual API endpoints and schemas, refer to the [FrankieOne API Documentation](https://docs.frankieone.com).

#### Step 1: Collect Customer Details

Collect minimal required information for frictionless experience:

* Full name
* Date of birth
* Residential address
* Email address
* Mobile phone number

> **UX Consideration:** Pre-fill where possible, minimise form fields, support autofill.

#### Step 2: Identity Verification

Verify customer identity against authoritative sources. For BNPL, speed is critical.

**Verification Approach by Scenario:**

| Scenario                   | Approach              | Target Time      |
| -------------------------- | --------------------- | ---------------- |
| New customer, low value    | Basic 2-source        | under 5 seconds  |
| New customer, higher value | Standard 3-source     | under 10 seconds |
| Returning customer         | Cached verification   | Instant          |
| Step-up required           | Document verification | under 60 seconds |

#### Step 3: Fraud Assessment

Evaluate fraud risk signals to protect against BNPL-specific fraud patterns.

**Common BNPL Fraud Patterns:**

| Pattern            | Detection Method                        |
| ------------------ | --------------------------------------- |
| Synthetic identity | Cross-source consistency checks         |
| Account takeover   | Device fingerprint, behavioural signals |
| Friendly fraud     | Purchase history, dispute patterns      |
| Bust-out fraud     | Velocity checks, exposure monitoring    |

#### Step 4: Risk Decision

Combine identity and fraud signals into a risk decision.

#### Step 5: Handle Outcomes

**APPROVE:**

* Proceed with transaction
* Set appropriate credit limit
* Enable repeat purchase capability

**STEP-UP:**

* Request additional verification
* May include document upload
* Time-limited to maintain conversion

**DECLINE:**

* Display compliant decline message
* Do not disclose specific reasons
* Log for review if borderline

***

### Risk Tier Examples

#### Tier 1: Low Risk - Instant Approve

**Customer Profile:**

* Australian resident, 28 years old
* Name and DOB verified
* Email aged 3+ years
* Device not flagged
* First purchase \$80

```mermaid theme={null}
flowchart LR
    A["Application"] --> B["ID Verified ✓"]
    B --> C["Fraud: Low Risk"]
    C --> D["Result: APPROVE"]
```

**Example Scenario:**

> Sarah Testone, 28, makes her first BNPL purchase for \$80 at an online retailer. Identity verified instantly against electoral roll and credit bureau. Email is 5 years old, device shows no risk signals. Approved in 3 seconds.

#### Tier 2: Medium Risk - Step-Up Required

**Customer Profile:**

* Identity verified but address mismatch
* New email address (14 days)
* Higher value purchase (\$450)

```mermaid theme={null}
flowchart TD
    A["Application"] --> B["ID: Partial Match"]
    B --> C["Fraud: Medium Risk"]
    C --> D["Step-Up Required"]
    D --> E["Document Upload"]
    E --> F["Document Verified ✓"]
    F --> G["Result: APPROVE"]
```

**Example Scenario:**

> Michael Testtwo, 24, attempts a $450 purchase. Name and DOB verified but address doesn't match (recently moved). Email created 14 days ago. System triggers step-up verification. Customer uploads driver licence, document verified. Approved with $500 initial limit.

#### Tier 3: High Risk - Decline

**Customer Profile:**

* Multiple identity inconsistencies
* Disposable email domain
* Device associated with previous fraud
* Synthetic identity indicators

```mermaid theme={null}
flowchart TD
    A["Application"] --> B["ID: Inconsistencies"]
    B --> C["Fraud: High Risk"]
    C --> D["Synthetic ID Indicators"]
    D --> E["Result: DECLINE"]
```

**Example Scenario:**

> Application received with name "David Testthree". Identity check shows inconsistencies across sources. Email is from disposable domain. Device fingerprint matches 3 previously declined applications. Synthetic identity patterns detected. Application declined.

***

### Edge Cases and Special Handling

#### Young Adults (18-21)

Young adults may have limited credit history, making verification challenging.

| Challenge               | Handling                                         |
| ----------------------- | ------------------------------------------------ |
| No credit bureau record | Accept alternative sources (electoral roll, DVS) |
| Recently turned 18      | Accept but may require document verification     |
| Student address         | Accept temporary addresses with verification     |

#### Address Verification Challenges

| Scenario            | Handling                           |
| ------------------- | ---------------------------------- |
| Recent move         | Accept document proof of address   |
| Living with parents | Verify name at address, may accept |
| No fixed address    | Higher risk, may require step-up   |

#### Returning Customers

| Scenario                  | Approach                            |
| ------------------------- | ----------------------------------- |
| Verified within 12 months | Use cached verification             |
| Details changed           | Re-verify changed elements          |
| Previously declined       | Apply cooling-off period, re-assess |

#### Merchant Risk Considerations

Some merchants/categories carry higher fraud risk:

| Category    | Risk Level  | Consideration                       |
| ----------- | ----------- | ----------------------------------- |
| Electronics | High        | Lower limits, enhanced verification |
| Gift cards  | High        | May restrict or decline             |
| Fashion     | Medium      | Standard verification               |
| Travel      | Medium-High | Enhanced for high values            |

***

### Fraud Prevention

#### BNPL-Specific Fraud Vectors

| Fraud Type             | Description                              | Mitigation                               |
| ---------------------- | ---------------------------------------- | ---------------------------------------- |
| **Synthetic Identity** | Fabricated identity using real/fake data | Cross-source consistency, device signals |
| **Account Takeover**   | Legitimate account compromised           | Device fingerprint, behavioural analysis |
| **First-Party Fraud**  | Customer disputes legitimate purchase    | Purchase history, pattern analysis       |
| **Bust-Out**           | Build credit then max out                | Velocity limits, exposure monitoring     |
| **Refund Abuse**       | Exploit refund policies                  | Transaction pattern monitoring           |

#### Device Intelligence

Device signals are critical for BNPL fraud prevention:

| Signal             | Risk Indication                   |
| ------------------ | --------------------------------- |
| Device age         | New devices higher risk           |
| Device velocity    | Multiple applications = high risk |
| Device reputation  | Known fraud = block               |
| Emulator detection | Automated fraud attempts          |
| Jailbreak/root     | Potential manipulation            |

#### Velocity Controls

| Control                          | Typical Threshold | Action                |
| -------------------------------- | ----------------- | --------------------- |
| Applications per device per day  | 3                 | Block additional      |
| Applications per email per week  | 2                 | Review/block          |
| Applications per phone per week  | 2                 | Review/block          |
| Cumulative exposure per customer | \$2,000           | Enhanced verification |

***

### Compliance Reporting

#### Audit Trail Requirements

| Data Category                 | Retention Period           | Purpose              |
| ----------------------------- | -------------------------- | -------------------- |
| Verification requests         | Per regulatory requirement | Compliance evidence  |
| Identity verification results | Per regulatory requirement | Audit trail          |
| Fraud assessment results      | Per regulatory requirement | Fraud investigation  |
| Decision outcomes             | Per regulatory requirement | Compliance reporting |

#### Responsible Lending Support

For upcoming responsible lending obligations, FrankieOne verification data can support:

* Customer identification for affordability assessments
* Consistent identity across credit applications
* Fraud indicators that may affect creditworthiness assessment

***

### Conversion Optimisation Tips

| Factor         | Recommendation                    |
| -------------- | --------------------------------- |
| Form fields    | Minimise to essential only        |
| Autofill       | Support browser autofill          |
| Error messages | Clear, actionable guidance        |
| Step-up UX     | Mobile-optimised document capture |
| Timeout        | Allow reasonable time for step-up |

***

### Troubleshooting

| Issue                           | Likely Cause               | Resolution                      |
| ------------------------------- | -------------------------- | ------------------------------- |
| High decline rate               | Thresholds too strict      | Review and tune risk thresholds |
| Slow verification               | Too many sequential checks | Enable parallel processing      |
| Step-up abandonment             | Poor UX                    | Optimise document capture flow  |
| False positives on young adults | Limited credit history     | Add alternative data sources    |


# Banking — Risk-Based Customer Onboarding
Source: https://docs.frankieone.com/v2/kyc/kyc/use-cases/kyc-banking

KYC Banking Use Case: Australian Risk-Based Onboarding

## Overview

This guide covers FrankieOne's KYC solution for Australian banking, designed to support AUSTRAC risk-based customer due diligence requirements (current framework aligned with '2+2' expectations, designed to evolve with upcoming AML/CTF reforms in Australia).

This use case illustrates how a configurable risk-based onboarding flow can support both current AUSTRAC expectations and the direction of upcoming AML/CTF reforms in Australia.

***

## Summary

### Available Workflows

| Workflow                   | CDD Tier       | Purpose                    | When to Use                                                  |
| -------------------------- | -------------- | -------------------------- | ------------------------------------------------------------ |
| `AUS-Risk-CDD-Email-Phone` | All            | Risk-based orchestration   | **Recommended** - Automatically routes based on risk signals |
| `AUS-Basic3V-TwoPlusID`    | Simplified     | Streamlined verification   | Low-risk customers, established relationships                |
| `AUS-Advanced1V-IDOnly`    | Standard       | Government ID verification | Medium-risk customers, most new accounts                     |
| `AUS-Advanced3V-TwoPlusID` | Enhanced (EDD) | Full enhanced verification | High-risk customers, PEPs, high-value products               |

### Risk-Based Orchestration: `AUS-Risk-CDD-Email-Phone`

<video />

```mermaid theme={null}
flowchart TD
    A["Customer Onboarding"] --> B["AUS-Risk-CDD-Email-Phone<br/>Risk Signal Evaluation"]
    B --> C{Risk Assessment}
    C -->|Low Risk| D["AUS-Basic3V-TwoPlusID<br/>Simplified CDD"]
    C -->|Medium Risk| E["AUS-Advanced1V-IDOnly<br/>Standard CDD"]
    C -->|High Risk| F["AUS-Advanced3V-TwoPlusID<br/>Enhanced CDD"]
    D --> G["Decision"]
    E --> G
    F --> G
```

| Risk Level | CDD Tier       | Routed To                  | Checks Included                                                 |
| ---------- | -------------- | -------------------------- | --------------------------------------------------------------- |
| **Low**    | Simplified     | `AUS-Basic3V-TwoPlusID`    | DVS, dual credit bureau, electoral roll, PEP/sanctions          |
| **Medium** | Standard       | `AUS-Advanced1V-IDOnly`    | Government ID verification, PEP/sanctions , biometrics          |
| **High**   | Enhanced (EDD) | `AUS-Advanced3V-TwoPlusID` | All Standard + biometrics, document authenticity, adverse media |

### Quick Implementation Flow

```mermaid theme={null}
flowchart LR
    A["Create Individual"] --> B["Collect Documents"] --> C["Run Workflow"]
    C --> D["Receive Webhook"]
    D --> E["Handle Decision"]
    E --> F["Activate Account"]
```

### Decision Outcomes

| Outcome    | Action                                       |
| ---------- | -------------------------------------------- |
| **PASS**   | Activate account, send welcome notification  |
| **REVIEW** | Route to compliance queue, inform customer   |
| **FAIL**   | Record rejection, send customer-safe message |

PASS/REVIEW/FAIL outcomes can be combined with periodic reviews and ongoing monitoring rules to help customers keep pace with evolving AUSTRAC expectations around ongoing CDD.

**Next steps:**

* Configure triggers for refresh (e.g., profile changes, new PEP/adverse media hits)
* Use AML screening and fraud signals to inform ongoing risk rating over the customer lifecycle

### Risk-Based CDD Tiers

Under Australia's AML/CTF reforms, customer due diligence follows a three-tiered model aligned with FATF recommendations. FrankieOne workflows map to each tier:

| CDD Tier               | When to Apply                                                      | FrankieOne Workflow        | Verification Intensity                                                                 |
| ---------------------- | ------------------------------------------------------------------ | -------------------------- | -------------------------------------------------------------------------------------- |
| **Simplified CDD**     | Low-risk customers, standard products, established relationships   | `AUS-Basic3V-TwoPlusID`    | Government ID + credit bureau + electoral roll + screening                             |
| **Standard CDD**       | Medium-risk customers, most new account openings                   | `AUS-Advanced1V-IDOnly`    | Government ID verification + screening                                                 |
| **Enhanced CDD (EDD)** | High-risk customers, PEPs, high-value products, complex structures | `AUS-Advanced3V-TwoPlusID` | Full verification + biometrics + document authenticity + adverse media + manual review |

**Applying the tiers:**

* **Simplified CDD** — Appropriate where ML/TF risk is demonstrably low. Reduced verification intensity, but identification still required. Your AML/CTF program defines eligible scenarios.
* **Standard CDD** — The baseline for most customer onboarding. Meets current AUSTRAC expectations for identity verification.
* **Enhanced CDD** — Required when risk factors are elevated. Includes additional verification steps, deeper screening, and ongoing enhanced monitoring.

> **Note:** The reforms allow reporting entities flexibility in how they apply these tiers based on their risk assessment. FrankieOne's configurable workflows support all three tiers and can be adjusted as your AML/CTF program evolves.

### Workflow Selection Guide

| Customer Type                          | Product Risk | CDD Tier          | Recommended Workflow                                  |
| -------------------------------------- | ------------ | ----------------- | ----------------------------------------------------- |
| Australian citizen, standard account   | Low          | Simplified        | `AUS-Risk-CDD-Email-Phone` → Basic3V                  |
| Australian citizen, new relationship   | Medium       | Standard          | `AUS-Risk-CDD-Email-Phone` → Advanced1V               |
| Australian citizen, high-value product | Medium-High  | Enhanced          | `AUS-Risk-CDD-Email-Phone` → Advanced3V               |
| Temporary resident                     | Medium       | Standard/Enhanced | `AUS-Risk-CDD-Email-Phone` → Advanced1V or Advanced3V |
| Foreign national, non-resident         | High         | Enhanced          | `AUS-Advanced3V-TwoPlusID` + manual review            |
| PEP or PEP associate                   | High         | Enhanced          | `AUS-Advanced3V-TwoPlusID` + manual review            |
| Business/Trust                         | High         | Enhanced          | Business verification (KYB)                           |

### Support

* **Documentation**: [docs.frankieone.com](https://docs.frankieone.com)
* **Support**: Contact your FrankieOne representative

***

## Expanded Details

### Regulatory Context

> **Disclaimer:** The information in this section is provided for general guidance only and does not constitute legal or compliance advice. Customers must seek independent AML/CTF compliance advice to ensure their implementation meets their specific regulatory obligations. FrankieOne is not responsible for customers' compliance decisions or outcomes.

> **AML/CTF Reforms:** The Australian Government is implementing significant reforms to the AML/CTF regime. Customers should review the latest guidance and legislative changes to ensure ongoing compliance:
>
> * [Anti-Money Laundering and Counter-Terrorism Financing Amendment Bill](https://www.aph.gov.au/Parliamentary_Business/Bills_Legislation/Bills_Search_Results/Result?bId=r7243)
> * [AUSTRAC AML/CTF Program Reform Guidance](https://www.austrac.gov.au/amlctf-reform/reforms-guidance/amlctf-program-reform)

#### AUSTRAC AML/CTF Act Obligations

Australian banks must comply with the Anti-Money Laundering and Counter-Terrorism Financing Act 2006 (AML/CTF Act). FrankieOne's banking workflows can support these core obligations:

| Obligation                         | Requirement                                                               | How FrankieOne Can Support                                        |
| ---------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Customer Identification**        | Collect and verify customer identity before providing designated services | Automated identity verification against government data sources   |
| **Ongoing Customer Due Diligence** | Monitor customers and transactions on an ongoing basis                    | Re-verification triggers and screening refresh (where configured) |
| **AML/CTF Program**                | Establish and maintain a compliant program                                | Configurable risk rules aligned to your program                   |
| **Reporting**                      | Submit SMRs, TTRs, and IFTIs as required                                  | Audit trails and exportable verification and audit data           |

#### Customer Identification Requirements

AUSTRAC's customer identification procedure for individuals involves collecting and verifying specific information before providing a designated service. FrankieOne's `AUS-Basic3V-TwoPlusID` workflow is designed to support these requirements.

**Common Collection Requirements:**

Common practice is to collect all three of the following. Your AML/CTF program defines specific requirements for your customer type and channel.

| Information             | Description                                         | FrankieOne Collection                                |
| ----------------------- | --------------------------------------------------- | ---------------------------------------------------- |
| **Full Name**           | Customer's complete legal name                      | Captured via form input and document OCR             |
| **Date of Birth**       | Customer's DOB                                      | Captured via form input and document OCR             |
| **Residential Address** | Customer's current residential address (not PO Box) | Captured via form input with address standardisation |

**Verification Requirements:**

Common verification requirements include:

* **Full name** - verified against a reliable and independent source
* **Either date of birth OR residential address** - verified against a reliable and independent source

Your AML/CTF program defines specific verification requirements based on your risk assessment.

| Requirement                          | FrankieOne Verification                                                                                                                                                                            |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Full Name Verification**           | Verified against DVS (passport, driver licence, Medicare, visa) and cross-referenced with credit bureau records                                                                                    |
| **Date of Birth Verification**       | Validated via eligible document verification responses (where available) with consistency checks across data sources                                                                               |
| **Residential Address Verification** | Verified against electoral roll, credit bureau, and utility records; GNAF standardisation applied                                                                                                  |
| **Government ID Verification**       | DVS verification for eligible documents (passport, driver licence, Medicare card, visa); birth certificates and citizenship certificates supported as identity evidence depending on configuration |

**Note:** FrankieOne's default workflows verify all three data points (name, DOB, and address) to provide enhanced assurance, though AUSTRAC's minimum requirement is name plus either DOB or address. Your AML/CTF program should define which verification approach applies based on your risk assessment.

#### Electronic Verification for Risk-Based Onboarding

FrankieOne supports electronic verification procedures that meet current AUSTRAC customer identification expectations (2+2 style) and can be configured to support the upcoming single, risk-based CDD model. Requirements are defined by your AML/CTF program; customers should validate specific requirements with their compliance advisers.

This configuration is designed to adapt as Australian AML/CTF reforms consolidate customer identification into a single, risk-based CDD obligation and refine ongoing monitoring expectations.

| Requirement                  | FrankieOne Support                                                                        |
| ---------------------------- | ----------------------------------------------------------------------------------------- |
| Multiple independent sources | Supports verification across multiple electronic data sources, depending on configuration |
| Government source            | Supports Australian government document verification via DVS                              |
| Name + additional attribute  | Supports verification of name, DOB, and address                                           |
| Reliable and up-to-date data | Uses real-time electronic data sources where available                                    |

**Note:** Risk-based onboarding requirements depend on your specific AML/CTF program configuration and compliance practices. Customers should seek independent advice to confirm their implementation meets their program requirements.

#### APRA Prudential Standards

For ADIs (Authorised Deposit-taking Institutions), additional APRA requirements apply:

* **CPS 234 (Information Security)**: FrankieOne is ISO 27001 certified and data is encrypted at rest and in transit
* **CPS 220 (Risk Management)**: Configurable risk thresholds align verification intensity to your risk appetite
* **CPS 231 (Outsourcing)**: FrankieOne provides security, risk, and operational documentation (e.g., ISO 27001, SOC 2 Type II, data residency, and subcontractor disclosures) to support customer outsourcing assessments

***

### Workflow Configuration Details

#### Primary Workflow: `AUS-Basic3V-TwoPlusID`

This workflow provides baseline verification suitable for low-to-medium risk customers.

**Data Sources (example configuration):**

| Source Type                            | Purpose                    |
| -------------------------------------- | -------------------------- |
| Government document verification (DVS) | Government ID verification |
| Credit bureau (primary)                | Identity match             |
| Credit bureau (secondary)              | Fallback identity match    |
| Electoral roll                         | Address verification       |
| Sanctions/PEP lists                    | AML screening              |

> **Note:** Specific data sources and providers depend on your configuration and region. Contact your FrankieOne representative for available options.

**Verification Logic (illustrative):**

```
IF government_id_match = TRUE AND credit_bureau_match = TRUE
  AND sanctions_clear = TRUE
  AND pep_level <= configured_threshold
THEN → PASS

IF government_id_match = FALSE OR credit_bureau_match = FALSE
THEN → Step-up to advanced workflow

IF sanctions_hit = TRUE OR pep_level >= configured_threshold
THEN → REVIEW (manual queue)
```

#### Step-Up Workflow: `AUS-Advanced3V-TwoPlusID`

Triggered when primary verification is inconclusive or risk indicators are elevated.

**Additional Checks:**

| Check                         | Description                                      | Trigger Condition                      |
| ----------------------------- | ------------------------------------------------ | -------------------------------------- |
| Biometric facial match        | Liveness detection and face-to-document matching | Primary verification inconclusive      |
| Document authenticity         | Tampering and fraud detection                    | Document quality or consistency issues |
| Adverse media screening       | News and media source checks                     | PEP match or sanctions near-match      |
| Enhanced address verification | Additional address data sources                  | No electoral roll match                |

> **Note:** Specific biometric and screening providers depend on your configuration. Contact your FrankieOne representative for available options.

#### Risk-Based Orchestration: `AUS-Risk-CDD-Email-Phone`

This risk model implements a risk-based approach to customer due diligence and ongoing monitoring, consistent with AUSTRAC's expectations and the direction of current AML/CTF reforms in Australia.

This orchestration workflow evaluates risk signals at verification start and automatically routes customers to the appropriate verification path. A single-call approach that eliminates manual step-up decision logic.

**Risk Signals Evaluated:**

| Signal                      | Risk Level | Description                                                           |
| --------------------------- | ---------- | --------------------------------------------------------------------- |
| Email age under 30 days     | High       | Recently created email address                                        |
| Email domain disposable     | Critical   | Temporary email service detected                                      |
| Phone type = VoIP           | Medium     | Non-mobile number provided                                            |
| Phone carrier mismatch      | Medium     | Carrier doesn't match country                                         |
| IP geolocation mismatch     | High       | IP country differs from claimed residence                             |
| Device fingerprint velocity | High       | Same device used for multiple applications                            |
| Session anomalies           | Medium     | Unusual browser/device patterns                                       |
| Customer risk rating        | Variable   | Higher ratings drive enhanced due diligence and more frequent reviews |

These risk factors can be tuned as regulatory guidance evolves (for example, where reforms call out higher-risk customer types or jurisdictions).

**Low Risk Indicators:**

* Email aged 6 months or more
* Valid mobile phone number matching country
* IP geolocation matches claimed residence
* No device velocity concerns
* Standard product application

**High Risk Indicators:**

* Recently created email (under 30 days)
* Disposable email domain
* VoIP or invalid phone number
* IP/residence mismatch
* Device linked to multiple applications
* High-value product application

**Benefits of Single-Call Orchestration:**

* Simplified integration (one API call)
* Automatic risk-based routing
* Consistent risk assessment
* Reduced development overhead
* Real-time fraud signal evaluation

***

### Step-Up Workflow Approaches

FrankieOne offers two approaches for implementing risk-based step-up verification. Choose the approach that best fits your integration requirements and desired level of control.

> **Note:** The examples in this section are illustrative and show conceptual patterns. Actual API endpoints, request/response formats, and workflow names may vary. Refer to the [FrankieOne API documentation](https://docs.frankieone.com) for current implementation details. Workflow availability depends on your plan and configuration.

#### Option A: Risk-Based Orchestration Workflow (Example: `AUS-CDD-Risk`)

For streamlined integration, use a risk-based orchestration workflow that automatically adjusts verification intensity based on real-time risk assessment. Availability and configuration of risk-based orchestration workflows depends on your plan and implementation.

**How it works:**

A risk-based orchestration workflow evaluates risk signals at the start of verification and automatically selects the appropriate verification path:

```mermaid theme={null}
flowchart TD
    A["AUS-CDD-Risk Workflow<br/>(Single API Call)"] --> B["Risk Assessment"]
    B --> C{Risk Level}
    C -->|LOW RISK| D["Basic3V TwoPlusID<br/>(Auto)"]
    C -->|HIGH RISK| E["Advanced3V TwoPlusID<br/>+ Biometrics<br/>+ Adverse Media"]
    D --> F["Final Decision"]
    E --> F
```

**Risk Factors Evaluated:**

| Factor               | Low Risk                                | High Risk                                      |
| -------------------- | --------------------------------------- | ---------------------------------------------- |
| Product type         | Everyday account, basic savings         | Home loan, business account, high-limit credit |
| Customer nationality | Australian citizen/PR                   | Foreign national, high-risk jurisdiction       |
| PEP indicators       | None                                    | Any PEP level detected                         |
| Age of customer data | Existing customer, data under 12 months | New customer, no prior relationship            |
| Channel              | Branch, established digital             | New device, VPN detected                       |
| Transaction profile  | Standard patterns                       | Unusual for demographic                        |

**When to use this approach:**

* You want simplified integration with a single API call
* You prefer FrankieOne to manage risk-based orchestration
* Your risk appetite aligns with standard banking risk tiers
* You want consistent risk assessment across all customers

#### Option B: Explicit Multi-Workflow Chaining

For maximum control, you can explicitly call two or more workflows in sequence, implementing your own step-up logic based on the results of each workflow.

**How it works:**

```mermaid theme={null}
flowchart TD
    A["Run Basic Workflow"] --> B["Evaluate Outcome"]
    B --> C{Result}
    C -->|PASS| D["Activate Account"]
    C -->|INCONCLUSIVE/HIGH RISK| E["Run Advanced Workflow"]
    E --> F["Final Decision"]
```

**When to use this approach:**

* You need custom step-up logic based on your specific risk appetite
* You want to integrate additional business rules between workflow calls
* You need to call different step-up workflows based on the failure reason
* You require detailed control over the customer experience at each stage

#### Comparison: CDD Risk vs Explicit Multi-Workflow

| Aspect                 | CDD Risk Workflow       | Explicit Multi-Workflow |
| ---------------------- | ----------------------- | ----------------------- |
| API calls              | 1 (single call)         | 2+ (one per workflow)   |
| Step-up logic          | FrankieOne managed      | Your implementation     |
| Customisation          | Configurable thresholds | Full control            |
| Integration complexity | Lower                   | Higher                  |
| Risk assessment        | Built-in risk engine    | Your rules              |
| Best for               | Standard banking flows  | Complex custom logic    |

***

### Step-by-Step Implementation

> **Note:** This section describes the conceptual implementation flow. For actual API endpoints, request/response schemas, and code examples, refer to the [FrankieOne API Documentation](https://docs.frankieone.com).

#### Prerequisites

Before implementing, ensure you have:

* FrankieOne API credentials
* Webhook endpoint configured and accessible
* OneSDK embedded in your application (recommended) OR direct API integration
* Test environment access for sandbox verification

#### Step 1: Create Individual

Create a customer record with collected personal information:

* Full name (given, middle, family)
* Date of birth
* Residential address
* Contact details (phone, email)
* Your internal customer reference

**API Reference:** See [Managing Individuals](https://docs.frankieone.com) in the FrankieOne documentation.

#### Step 2: Upload Identity Documents

Submit government-issued ID for verification.

**Supported Document Types:**

| Document Type           | Description                   |
| ----------------------- | ----------------------------- |
| Australian Passport     | International travel document |
| Driver Licence          | State-issued driver licence   |
| Medicare Card           | Healthcare entitlement card   |
| Visa                    | Immigration document          |
| Birth Certificate       | Birth registration document   |
| Citizenship Certificate | Citizenship evidence          |

**API Reference:** See [Document Upload](https://docs.frankieone.com) in the FrankieOne documentation.

#### Step 3: Execute Verification Workflow

Trigger the KYC workflow for the individual. The workflow will:

* Verify identity against government and commercial data sources
* Perform PEP and sanctions screening
* Assess fraud risk signals
* Return an outcome (PASS, REVIEW, or FAIL)

**API Reference:** See [Executing Workflows](https://docs.frankieone.com) in the FrankieOne documentation.

#### Step 4: Handle Webhook Events

Configure your webhook endpoint to receive verification results asynchronously.

**Typical Webhook Events:**

| Event Type         | Description                | Recommended Action                 |
| ------------------ | -------------------------- | ---------------------------------- |
| Workflow completed | Verification finished      | Process outcome (PASS/REVIEW/FAIL) |
| Workflow failed    | System error occurred      | Retry or escalate to support       |
| Review required    | Manual review needed       | Route to compliance queue          |
| Screening alert    | New screening match found  | Investigate alert                  |
| Document rejected  | Document validation failed | Request new document from customer |

**API Reference:** See [Webhooks & Notifications](https://docs.frankieone.com) in the FrankieOne documentation.

#### Step 5: Process Decision Outcomes

Handle verification outcomes in your application:

**PASS Outcome:**

* Update customer KYC status to verified
* Activate account and enable features
* Send welcome notification

**REVIEW Outcome:**

* Create internal review case with priority and SLA
* Notify compliance team
* Update customer status to pending review
* Inform customer their application is being reviewed

**FAIL Outcome:**

* Record rejection with internal reason codes
* Update application status
* Send customer-safe rejection notification (without sensitive details)
* Log for audit purposes

***

### Risk Tier Examples

#### Tier 1: Low Risk - Auto-Approve

**Customer Profile:**

* Australian citizen
* Valid Australian passport or driver licence
* Residential address matches electoral roll
* No PEP or sanctions matches
* Email and phone pass fraud checks

```mermaid theme={null}
flowchart LR
    A["Customer Input"] --> B["Government ID ✓"]
    B --> C["Credit Bureau ✓"]
    C --> D["Electoral Roll ✓"]
    D --> E["Screening: Clear"]
    E --> F["Result: PASS"]
```

**Example Scenario:**

> Mary Testone, 32, applies for an everyday transaction account via mobile app. She provides her Victorian driver licence and current address. Government ID verification confirms the licence is valid, credit bureau matches her name and DOB, electoral roll confirms her address. No screening matches. Account activated.

#### Tier 2: Medium Risk - Enhanced Due Diligence

**Customer Profile:**

* Foreign national with Australian visa
* PEP Level 2 or 3 (family member or close associate)
* Minor discrepancies in data matching
* Higher-value product (e.g., home loan, business account)

```mermaid theme={null}
flowchart TD
    A["Customer Input"] --> B["Government ID ✓"]
    B --> C["Credit Bureau ~"]
    C --> D["Electoral Roll ✗"]
    D --> E["Screening: PEP L2"]
    E -->|Step-up triggered| F["Biometric ✓"]
    F --> G["Adverse Media: Clear"]
    G --> H["Enhanced Address ✓"]
    H --> I["Manual Review Queue"]
    I --> J["Result: REVIEW"]
```

**Example Scenario:**

> James Testtwo, 45, applies for a business transaction account. He's a permanent resident originally from Singapore. His father is a former Singaporean government minister (PEP Level 2). Government ID validates his passport, but no electoral roll match (recent address change). System triggers step-up: biometric check passes, no adverse media found, address verified via alternative source. Case routed to compliance for PEP assessment. Compliance approves with enhanced monitoring flag.

#### Tier 3: High Risk - Manual Review Required

**Customer Profile:**

* Sanctions list near-match (similar name, different DOB)
* Adverse media findings
* Multiple identity documents with discrepancies
* High-risk jurisdiction connections
* Fraud signals detected

```mermaid theme={null}
flowchart TD
    A["Customer Input"] --> B["Government ID ✓"]
    B --> C["Credit Bureau ✓"]
    C --> D["Screening: Sanctions near-match"]
    D -->|Immediate escalation| E["Biometric ✓"]
    E --> F["Adverse Media: 2 hits"]
    F --> G["Enhanced Screening: Reviewed"]
    G --> H["Manual Review Queue"]
    H --> I["Result: REVIEW"]
```

**Example Scenario:**

> Robert Testthree, 38, applies for a savings account. Name returns a near-match on sanctions list (different middle name and DOB). Adverse media search finds articles about a fraud investigation involving someone with a similar name. Biometric passes. Case escalated to senior compliance officer. After investigation: sanctions match confirmed as false positive (different person), adverse media relates to different individual. Approved with standard monitoring.

#### Tier 4: Auto-Reject

**Triggers for Automatic Rejection:**

| Trigger                               | Rationale           | Customer Communication               |
| ------------------------------------- | ------------------- | ------------------------------------ |
| Confirmed sanctions match             | Legal prohibition   | "Unable to proceed with application" |
| Document confirmed fraudulent         | Fraud prevention    | "Unable to verify identity"          |
| Age verification failed (under 18)    | Product eligibility | "Age requirement not met"            |
| Duplicate application (fraud pattern) | Fraud prevention    | "Application already exists"         |
| Deceased indicator                    | Data integrity      | "Unable to verify identity"          |
| Device/IP on fraud blocklist          | Fraud prevention    | "Unable to proceed at this time"     |

***

### Edge Cases and Special Handling

#### Name Mismatches

| Scenario                 | Example                                          | Handling                                                  |
| ------------------------ | ------------------------------------------------ | --------------------------------------------------------- |
| Married name change      | Licence: Sarah Testfive, Passport: Sarah Testsix | Accept with statutory declaration or marriage certificate |
| Transliteration variance | Mikel vs Mikael vs Michael                       | Fuzzy matching; manual review if below threshold          |
| Hyphenated names         | Emma-Test vs Emma Test vs EmmaTest               | Normalise hyphens and spaces before matching              |
| Name order differences   | Wei Testseven vs Testseven Wei                   | Support both Western and Eastern name order conventions   |
| Titles and suffixes      | Dr. Tom Testeight Jr. vs Tom Testeight           | Strip titles/suffixes before matching                     |
| Accent marks             | José Testnine vs Jose Testnine                   | Normalise diacritics for matching                         |

#### Document Expiry Handling

| Document Type           | Expired Acceptance | Grace Period | Conditions                         |
| ----------------------- | ------------------ | ------------ | ---------------------------------- |
| Passport                | No                 | 0 days       | Must be current                    |
| Driver Licence          | Conditional        | 90 days      | If renewal in progress             |
| Medicare                | Yes                | 2 years      | For identity only, not entitlement |
| Visa                    | No                 | 0 days       | Must be current and valid          |
| Birth Certificate       | Yes                | N/A          | No expiry                          |
| Citizenship Certificate | Yes                | N/A          | No expiry                          |

#### Re-verification Triggers

| Trigger                                       | Re-verification Level               | Timeframe                |
| --------------------------------------------- | ----------------------------------- | ------------------------ |
| Product upgrade (e.g., basic → premium)       | Document refresh                    | Before activation        |
| Dormant account reactivation (over 12 months) | Full re-verification                | Before reactivation      |
| Significant transaction pattern change        | Risk reassessment                   | Within 7 days            |
| Customer-initiated detail change              | Verify changed elements             | Immediate                |
| Screening alert on existing customer          | Enhanced due diligence              | Within 24 hours          |
| Regulatory requirement (periodic review)      | Full re-verification                | Per risk rating schedule |
| Fraud indicator detected                      | Full re-verification + fraud checks | Immediate                |

Fraud and cyber signals are increasingly relevant to both financial crime risk and broader AML/CTF expectations and can be integrated into your overall ML/TF risk assessment.

#### Periodic Review Schedule

| Customer Risk Rating | Review Frequency | Scope                                     |
| -------------------- | ---------------- | ----------------------------------------- |
| Low                  | Every 3 years    | Screening refresh, address confirmation   |
| Medium               | Annually         | Full identity re-verification             |
| High                 | Every 6 months   | Full re-verification + enhanced screening |
| PEP                  | Every 6 months   | Full re-verification + adverse media      |

#### Joint Account Handling

All account holders must be independently verified before account activation.

```mermaid theme={null}
flowchart TD
    A["Joint Account Application"] --> B["Primary Holder"]
    A --> C["Joint Holder 1"]
    A --> D["Joint Holder 2"]
    B --> E["Full KYC Workflow"]
    C --> F["Full KYC Workflow"]
    D --> G["Full KYC Workflow"]
    E --> H{All PASS?}
    F --> H
    G --> H
    H -->|Yes| I["Account Activated"]
    H -->|Any REVIEW/FAIL| J["Hold until all resolved"]
```

#### Minor Accounts (Under 18)

| Account Type  | Age Range | Requirements                             |
| ------------- | --------- | ---------------------------------------- |
| Youth saver   | 14-17     | Minor KYC + parent/guardian verification |
| Child trust   | 0-17      | Parent/guardian KYC only; minor recorded |
| Teen everyday | 16-17     | Minor KYC + parent/guardian consent      |

#### Non-Resident Accounts

| Customer Type      | ID Requirements         | Additional Checks             |
| ------------------ | ----------------------- | ----------------------------- |
| Tourist/Visitor    | Foreign passport + visa | Visa validity, travel history |
| Temporary resident | Passport + valid visa   | VEVO check, visa conditions   |
| Foreign student    | Passport + student visa | CoE verification              |
| Working holiday    | Passport + WHV          | VEVO check                    |

***

### Compliance Reporting

#### Audit Trail Requirements

FrankieOne maintains comprehensive audit trails for all verification activities.

| Data Category             | Retention Period | Purpose            |
| ------------------------- | ---------------- | ------------------ |
| Verification requests     | 7 years          | AML/CTF compliance |
| Document images           | 7 years          | Evidence retention |
| Decision outcomes         | 7 years          | Audit trail        |
| Screening results         | 7 years          | AML/CTF compliance |
| API request/response logs | 2 years          | Technical audit    |
| Webhook delivery logs     | 90 days          | Troubleshooting    |

#### AUSTRAC Reporting Support

FrankieOne provides data exports to support AUSTRAC reporting requirements:

* Subject details and identification documents
* Verification history
* Screening alerts and suspicious indicators

> **Note:** Transaction monitoring and patterns are typically managed by your core banking system, not FrankieOne.

#### Regulatory Examination Support

FrankieOne can assist with generating examination packages for AUSTRAC or APRA examinations.

| Section              | Description                                        |
| -------------------- | -------------------------------------------------- |
| Executive Summary    | Verification volumes, pass rates, key metrics      |
| Policy Documentation | Current workflow configurations and thresholds     |
| Screening Summary    | PEP/sanctions alerts and resolution outcomes       |
| Manual Review Log    | All manual decisions with rationale                |
| Exception Report     | Cases outside normal parameters                    |
| System Change Log    | Configuration changes with approvals               |
| Sample Cases         | Representative examples from each outcome category |

***

### Troubleshooting

| Issue                                            | Likely Cause             | Resolution                                              |
| ------------------------------------------------ | ------------------------ | ------------------------------------------------------- |
| Government ID verification returning "NO\_MATCH" | Name/DOB format mismatch | Check date format (YYYY-MM-DD), remove titles from name |
| Biometric check failing repeatedly               | Poor image quality       | Guide user on lighting, positioning; allow retry        |
| Webhook not received                             | Firewall blocking        | Whitelist FrankieOne IPs; check endpoint accessibility  |
| High false positive rate on screening            | Thresholds too sensitive | Tune matching thresholds; implement exclusion lists     |
| Slow response times                              | Configuration issue      | Contact FrankieOne support for optimisation             |

***

### Regulatory Context (Australia)

This example is designed for reporting entities operating under Australia's AML/CTF framework and is aligned to current AUSTRAC guidance.

Australian AML/CTF laws are undergoing reform, including a move to a single, risk-based customer due diligence obligation and expanded coverage of additional sectors (tranche 2).

FrankieOne does not provide legal or regulatory advice. Reporting entities should obtain their own advice and configure workflows in line with their AML/CTF programs.


# Crypto — Customer Onboarding
Source: https://docs.frankieone.com/v2/kyc/kyc/use-cases/kyc-crypto

KYC use case for crypto companies using global risk based onboarding, specifically US, UK and EU

## Overview

This guide covers FrankieOne's KYC solution for cryptocurrency and digital asset businesses, designed to support multi-jurisdictional compliance requirements including AUSTRAC (Australia), FinCEN (USA), MiCA (EU), and global AML standards.

***

## Summary

### Available Workflows

| Workflow                   | Purpose                      | When to Use                                                   |
| -------------------------- | ---------------------------- | ------------------------------------------------------------- |
| `GLB-IntlOnePlus`          | Global identity verification | Multi-jurisdictional customer base                            |
| `USA-Basic1V-OnePlus`      | USA identity verification    | US-based customers (combine with biometrics)                  |
| `AUS-Risk-CDD-Email-Phone` | AU risk-based orchestration  | **Recommended for AU** - Auto-routes to Basic3V or Advanced3V |
| `AUS-Basic3V-TwoPlusID`    | AU standard verification     | Australian customers, low-medium risk                         |
| `AUS-Advanced3V-TwoPlusID` | AU enhanced verification     | High-risk, step-up scenarios                                  |
| `GLB-AMLMedia`             | AML screening                | PEP, sanctions, adverse media checks                          |

### Multi-Jurisdictional Coverage

| Jurisdiction       | Regulatory Framework       | Recommended Workflow                     |
| ------------------ | -------------------------- | ---------------------------------------- |
| **Australia**      | AUSTRAC DCE Registration   | `AUS-Risk-CDD-Email-Phone`               |
| **USA**            | FinCEN MSB, State Licenses | `USA-Basic1V-OnePlus` + biometrics       |
| **European Union** | MiCA                       | `GLB-IntlOnePlus` + address verification |
| **Global**         | FATF Recommendations       | `GLB-IntlOnePlus`                        |

### Quick Implementation Flow

```mermaid theme={null}
flowchart LR
    A["Collect Details"] --> B["Identity Verification"]
    B --> C["Address Verification"]
    C --> D["AML Screening"]
    D --> E["Risk Assessment"]
    E --> F["Decision"]
```

### Decision Outcomes

| Outcome    | Action                                                    |
| ---------- | --------------------------------------------------------- |
| **PASS**   | Create account, set transaction limits, enable trading    |
| **REVIEW** | Queue for enhanced due diligence, request additional docs |
| **FAIL**   | Block registration, log reason, display compliant message |

### MiCA Compliance Checklist

| Requirement                 | FrankieOne Support |
| --------------------------- | ------------------ |
| Name verification           | ✓ Supported        |
| Address verification (full) | ✓ Supported        |
| Document verification       | ✓ Supported        |
| Sanctions screening         | ✓ Supported        |
| PEP screening               | ✓ Supported        |
| Audit trail                 | ✓ Supported        |

### Support

* **Documentation**: [docs.frankieone.com](https://docs.frankieone.com)
* **Support**: Contact your FrankieOne representative

***

## Expanded Details

### Regulatory Context

> **Disclaimer:** The information in this section is provided for general guidance only and does not constitute legal or compliance advice. Customers must seek independent legal and regulatory advice to ensure their implementation meets their specific regulatory obligations across all operating jurisdictions. FrankieOne is not responsible for customers' compliance decisions or outcomes.

> **Regulatory Updates:** Cryptocurrency regulations are rapidly evolving globally. Customers should monitor updates from relevant regulators (AUSTRAC, FinCEN, EU supervisory authorities, FATF) and ensure ongoing compliance.

#### AUSTRAC Digital Currency Exchange (DCE) Requirements

Australian Digital Currency Exchanges must register with AUSTRAC and comply with AML/CTF obligations.

| Obligation                  | Requirement                                        | How FrankieOne Can Support                                                                 |
| --------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Customer Identification** | Verify customer identity before providing services | Automated identity verification with risk-based approach                                   |
| **Ongoing CDD**             | Monitor customers on risk-based schedule           | Re-verification triggers and screening refresh (where configured)                          |
| **AML/CTF Program**         | Maintain compliant program                         | Configurable risk rules aligned to your program                                            |
| **Transaction Monitoring**  | Monitor transactions for suspicious activity       | Verified identity data and risk signals to support customer transaction monitoring systems |
| **Reporting**               | Submit SMRs and threshold reports                  | Audit trails and exportable verification and audit data                                    |

#### MiCA (Markets in Crypto-Assets) Regulation - EU

MiCA introduces harmonised requirements for crypto-asset service providers (CASPs) operating in the European Union.

| MiCA Requirement           | Description                                          | How FrankieOne Can Support                               |
| -------------------------- | ---------------------------------------------------- | -------------------------------------------------------- |
| **Customer Due Diligence** | Verify identity of customers before onboarding       | Identity verification workflows with EU document support |
| **Name Verification**      | Verify customer's full legal name                    | Name verification against authoritative sources          |
| **Address Verification**   | Verify customer's residential address                | Full address verification                                |
| **Travel Rule**            | Originator and beneficiary information for transfers | Verification data to support Travel Rule compliance      |
| **Sanctions Screening**    | Screen against EU and international sanctions lists  | PEP and sanctions screening included in workflows        |

#### Travel Rule Considerations

The FATF Travel Rule requires virtual asset service providers (VASPs) to collect and transmit originator and beneficiary information for transfers above thresholds.

| Party           | Required Information                                                      |
| --------------- | ------------------------------------------------------------------------- |
| **Originator**  | Name, account number, address (or national ID, or DOB and place of birth) |
| **Beneficiary** | Name, account number                                                      |

FrankieOne's verification workflows collect identity data that can support Travel Rule compliance. FrankieOne does not transmit Travel Rule messages; these are handled by dedicated Travel Rule solutions.

***

### Name and Address Verification

#### Full Address Verification Setup

MiCA and other regulations require verification of customer residential address.

**Required Address Components:**

| Component          | Description                     | Example                   |
| ------------------ | ------------------------------- | ------------------------- |
| **Address Line 1** | Street address including number | 123 Main Street, Unit 4B  |
| **City**           | City or locality                | Sydney, Berlin, Singapore |
| **Postal Code**    | Postal/ZIP code                 | 2000, 10115, 048624       |
| **State/Province** | State, province, or region      | NSW, Bavaria, N/A         |
| **Country**        | ISO country code                | AUS, DEU, SGP             |

**Address Verification Methods:**

| Method                      | Description                               | Coverage                       |
| --------------------------- | ----------------------------------------- | ------------------------------ |
| **Electronic Verification** | Verify against authoritative data sources | Australia, EU, selected global |
| **Document Verification**   | Extract and verify address from documents | Global                         |
| **Utility/Bank Statement**  | Verify via uploaded proof of address      | Global                         |

#### Name Matching Considerations

| Scenario                                 | Handling                                   |
| ---------------------------------------- | ------------------------------------------ |
| Transliteration variants                 | Fuzzy matching with configurable threshold |
| Name order differences (Eastern/Western) | Support both conventions                   |
| Hyphenated names                         | Normalisation before matching              |
| Titles and suffixes                      | Strip before matching                      |
| Diacritics/accents                       | Normalise for matching                     |

***

### Workflow Configuration Details

#### Global Identity Workflow: `GLB-IntlOnePlus`

This workflow provides unified global coverage for crypto customer onboarding.

| Region         | Document Types                          | Verification Sources                 |
| -------------- | --------------------------------------- | ------------------------------------ |
| Australia      | Passport, Driver Licence, Medicare      | Government (DVS), credit bureaus     |
| European Union | Passport, National ID, Residence Permit | Government databases, credit bureaus |
| United Kingdom | Passport, Driver Licence                | Government databases                 |
| United States  | Passport, Driver Licence, State ID      | DMV, credit bureaus                  |
| Asia Pacific   | Passport, National ID                   | Varies by country                    |

#### USA Identity Workflow: `USA-Basic1V-OnePlus`

**Important: US Document Verification Limitations**

Unlike some jurisdictions, the USA does not have centralised government data sources for verifying Driver Licences or Passports via KYC checks. FrankieOne recommends:

| Document Type      | Recommended Verification Approach                        |
| ------------------ | -------------------------------------------------------- |
| **Driver Licence** | Biometric verification (document + face match)           |
| **State ID**       | Biometric verification (document + face match)           |
| **Passport**       | Biometric verification (document + face match)           |
| **Digital mDL**    | Coming soon - digital mobile Driver Licence verification |

**KYC Data Source Verification:**

| Check Type                  | Purpose                          | Source                         |
| --------------------------- | -------------------------------- | ------------------------------ |
| Name and DOB verification   | Identity confirmation            | Credit bureaus, public records |
| SSN verification            | Identity cross-reference         | Credit bureaus                 |
| Address verification        | Residential address confirmation | Credit bureaus, utility data   |
| PEP and sanctions screening | OFAC and AML risk assessment     | Sanctions lists, PEP databases |

#### AU Risk Based Onboarding: `AUS-Risk-CDD-Email-Phone`

This orchestration workflow evaluates risk signals at verification start and automatically routes Australian customers to the appropriate verification path.

```mermaid theme={null}
flowchart TD
    A["Customer Onboarding"] --> B["AUS-Risk-CDD-Email-Phone<br/>Risk Signal Evaluation"]
    B --> C{Risk Assessment}
    C -->|Low Risk| D["AUS-Basic3V-TwoPlusID<br/>Standard Verification"]
    C -->|High Risk| E["AUS-Advanced3V-TwoPlusID<br/>Enhanced Verification"]
    D --> F["Decision"]
    E --> F
```

**Risk Signal Evaluation:**

| Signal             | Risk Indicator                        |
| ------------------ | ------------------------------------- |
| Email age          | Recently created (under 30 days)      |
| Email domain       | Disposable email services             |
| Phone type         | VoIP phone numbers                    |
| Phone carrier      | Country mismatch                      |
| IP geolocation     | Misalignment with claimed residence   |
| Device fingerprint | Velocity across multiple applications |

**`Low Risk Path: AUS-Basic3V-TwoPlusID`**

| Check Type                       | Purpose                       |
| -------------------------------- | ----------------------------- |
| Government ID verification (DVS) | Primary identity confirmation |
| Dual credit bureau checks        | Identity cross-reference      |
| Electoral roll                   | Address verification          |
| PEP and sanctions screening      | AML risk assessment           |

**`High Risk Path: AUS-Advanced3V-TwoPlusID`**

| Check Type                    | Purpose                                        |
| ----------------------------- | ---------------------------------------------- |
| All Basic3V checks            | Baseline verification                          |
| Biometric facial matching     | Face-to-document match with liveness detection |
| Document authenticity         | Fraud and tampering detection                  |
| Adverse media screening       | Additional risk assessment                     |
| Enhanced address verification | Multiple source address confirmation           |

#### AML Screening Workflow: `GLB-AMLMedia`

| Check                   | Description                              | Risk Levels                |
| ----------------------- | ---------------------------------------- | -------------------------- |
| **Sanctions Screening** | OFAC, UN, EU, DFAT, and other lists      | Match / Near-match / Clear |
| **PEP Screening**       | Politically Exposed Persons (Levels 1-4) | Level indicated            |
| **Adverse Media**       | Negative news screening                  | Hits found / Clear         |
| **Watchlists**          | Law enforcement and regulatory lists     | Match / Clear              |

**PEP Levels:**

| Level | Description                      | Typical Action                  |
| ----- | -------------------------------- | ------------------------------- |
| PEP 1 | Head of state, senior government | Enhanced due diligence required |
| PEP 2 | Senior political figure          | Enhanced due diligence required |
| PEP 3 | Mid-level political figure       | Review recommended              |
| PEP 4 | Associate or family member       | Flag for awareness              |

***

### Risk Tier Examples

#### Tier 1: Low Risk - Auto-Approve

**Customer Profile:**

* Australian citizen
* Valid passport
* Address verified electronically
* No PEP or sanctions matches
* Low-risk jurisdiction

```mermaid theme={null}
flowchart LR
    A["Customer Input"] --> B["ID Verified ✓"]
    B --> C["Address Verified ✓"]
    C --> D["Screening: Clear"]
    D --> E["Risk: Low"]
    E --> F["Result: PASS"]
```

**Example Scenario:**

> Emma Testone, 28, registers from Sydney, Australia. She provides her Australian passport and residential address. Identity verified against government records, address confirmed via electronic sources, no PEP or sanctions matches. Account activated with standard limits.

#### Tier 2: Medium Risk - Enhanced CDD

**Customer Profile:**

* EU citizen (Germany)
* Valid passport and national ID
* Address requires document verification
* No sanctions, PEP Level 4 (family member)

```mermaid theme={null}
flowchart TD
    A["Customer Input"] --> B["ID Verified ✓"]
    B --> C["Address: Partial Match"]
    C --> D["Screening: PEP L4"]
    D -->|Enhanced CDD| E["Request Proof of Address"]
    E --> F["Document Verified ✓"]
    F --> G["Result: PASS + Enhanced Monitoring"]
```

**Example Scenario:**

> Hans Testtwo, 35, registers from Berlin, Germany. Identity verified via German national ID. Address electronic verification returns partial match. PEP screening identifies him as family member of a mid-level political figure (PEP Level 4). Proof of address document requested and verified. Account activated with enhanced monitoring flag.

#### Tier 3: High Risk - Manual Review

**Customer Profile:**

* High-risk jurisdiction
* PEP Level 2
* Adverse media findings
* High intended transaction volume

```mermaid theme={null}
flowchart TD
    A["Customer Input"] --> B["ID Verified ✓"]
    B --> C["Address Verified ✓"]
    C --> D["Screening: PEP L2 + Adverse Media"]
    D --> E["Risk: High"]
    E --> F["Manual Review Queue"]
    F --> G["Compliance Review"]
    G --> H["Result: REVIEW"]
```

**Example Scenario:**

> Alex Testthree, 42, registers with high intended trading volume. Jurisdiction is on FATF grey list. PEP screening identifies Level 2 status (senior political figure). Adverse media search returns articles about regulatory investigation (subsequently cleared). Case escalated to compliance team for enhanced due diligence review.

#### Tier 4: Auto-Reject

| Trigger                   | Rationale              | Action                          |
| ------------------------- | ---------------------- | ------------------------------- |
| Confirmed sanctions match | Legal prohibition      | Block, file report if required  |
| Prohibited jurisdiction   | Regulatory restriction | Block with jurisdiction message |
| Document fraud detected   | Fraud prevention       | Block, flag for investigation   |
| Age under 18              | Regulatory requirement | Block                           |
| Duplicate account         | Terms violation        | Block                           |

***

### Jurisdiction Handling

#### Supported vs Restricted Jurisdictions

| Category               | Example Countries                   | Typical Handling                |
| ---------------------- | ----------------------------------- | ------------------------------- |
| **Fully Supported**    | Australia, Germany, UK, Singapore   | Standard onboarding             |
| **Supported with EDD** | High-risk FATF countries            | Enhanced due diligence required |
| **Restricted**         | Sanctioned countries                | Block registration              |
| **Not Supported**      | Countries outside operating licence | Block with appropriate message  |

#### FATF Grey List Considerations

Customers from FATF grey list countries may require enhanced due diligence:

* Additional identity documentation
* Source of funds verification
* Ongoing customer due diligence with screening refresh
* Senior management approval

***

### Edge Cases and Special Handling

#### Name Verification Edge Cases

| Scenario        | Example                    | Handling                                        |
| --------------- | -------------------------- | ----------------------------------------------- |
| Transliteration | Михаил → Mikhail / Michael | Fuzzy matching with transliteration support     |
| Name order      | Wei Zhang vs Zhang Wei     | Support both conventions                        |
| Compound names  | María José García López    | Match full compound name                        |
| Single name     | Sukarno (Indonesian)       | Accept single name where culturally appropriate |

#### Address Verification Edge Cases

| Scenario                           | Handling                                         |
| ---------------------------------- | ------------------------------------------------ |
| No postal code (some countries)    | Mark as N/A, verify other components             |
| PO Box address                     | Reject for residential, request physical address |
| New development (not in databases) | Document verification required                   |
| Rural address (no street number)   | Accept descriptive address with document         |

#### Document Verification Edge Cases

| Scenario                             | Handling                                   |
| ------------------------------------ | ------------------------------------------ |
| Passport in non-Latin script         | MRZ verification + transliteration         |
| Recently issued ID (not in database) | Document verification, flag for monitoring |
| Dual nationality                     | Accept either valid passport               |
| Refugee travel document              | Accept with enhanced verification          |

***

### Compliance Reporting

#### Audit Trail Requirements

| Data Category         | Retention Period           | Purpose            |
| --------------------- | -------------------------- | ------------------ |
| Verification requests | Per regulatory requirement | AML/CTF compliance |
| Document images       | Per regulatory requirement | Evidence retention |
| Screening results     | Per regulatory requirement | AML/CTF compliance |
| Decision outcomes     | Per regulatory requirement | Audit trail        |

> **Note:** Retention periods vary by jurisdiction (e.g., 7 years Australia, 5 years EU). Configure based on your regulatory requirements.

#### Travel Rule Data Support

FrankieOne verification data can support Travel Rule compliance by providing verified:

* Full legal name
* Account identifier
* Address OR national ID OR DOB and place of birth

***

### Troubleshooting

| Issue                              | Likely Cause                  | Resolution                           |
| ---------------------------------- | ----------------------------- | ------------------------------------ |
| Address verification failing       | Incomplete address components | Ensure all required fields collected |
| Name mismatch on foreign documents | Transliteration differences   | Enable fuzzy matching                |
| High false positive on sanctions   | Common name                   | Tune matching thresholds             |
| Jurisdiction incorrectly blocked   | Configuration issue           | Review jurisdiction settings         |


# Gaming — Risk-Based Customer Onboarding
Source: https://docs.frankieone.com/v2/kyc/kyc/use-cases/kyc-gaming

KYC Gaming Use Case: Australian Risk-Based Onboarding

## Overview

This guide covers FrankieOne's KYC solution for Australian gaming operators, designed to support state and territory regulatory requirements for age verification, identity verification, and responsible gambling compliance.

***

## Summary

### Available Workflows

| Workflow                             | Purpose                     | When to Use                              |
| ------------------------------------ | --------------------------- | ---------------------------------------- |
| `AUS-Basic3V-AgeVerify`              | Age + identity verification | **Primary** - Standard registration      |
| `AUS-Risk-CDD-Email-Phone-Device-IP` | Fraud detection             | Multi-accounting, bonus abuse prevention |
| Biometric step-up                    | Enhanced verification       | Elevated risk scenarios                  |

### Quick Implementation Flow

```mermaid theme={null}
flowchart LR
    A["Collect Details"] --> B["Age Check"]
    B --> C["Identity Verification"]
    C --> D["Fraud Assessment"]
    D --> E["Decision"]
    E --> F["Account Created"]
```

### Age Verification (Mandatory)

| Outcome              | Action                                   |
| -------------------- | ---------------------------------------- |
| **Verified 18+**     | Proceed to identity verification         |
| **Under 18**         | Permanent block (regulatory requirement) |
| **Unable to verify** | Request alternative documentation        |

### Step-Up Verification Flow

```mermaid theme={null}
flowchart TD
    A["Initial Verification"] --> B{Risk Assessment}
    B -->|Low Risk| C["PASS - Account Activated"]
    B -->|Medium Risk| D["Step-Up Required"]
    B -->|High Risk| E["FAIL - Manual Review"]
    D --> F["Biometric Verification"]
    F -->|Pass| C
    F -->|Fail| E
```

### Key Fraud Signals

| Signal                              | Risk Level | Description                |
| ----------------------------------- | ---------- | -------------------------- |
| Device on blocklist                 | Critical   | Known fraudulent device    |
| Multiple accounts from device       | High       | Multi-accounting indicator |
| Session velocity over 5 in 24 hours | High       | Abuse pattern              |
| Email age under 7 days              | High       | Recently created email     |
| Email domain disposable             | Critical   | Temporary email service    |

### Decision Outcomes

| Outcome    | Action                                      |
| ---------- | ------------------------------------------- |
| **PASS**   | Create account, enable gambling features    |
| **REVIEW** | Queue for manual verification               |
| **FAIL**   | Block registration, display generic message |

### Support

* **Documentation**: [docs.frankieone.com](https://docs.frankieone.com)
* **Support**: Contact your FrankieOne representative

***

## Expanded Details

### Regulatory Context

> **Disclaimer:** The information in this section is provided for general guidance only and does not constitute legal or compliance advice. Customers must seek independent legal and regulatory advice to ensure their implementation meets their specific licensing obligations. FrankieOne is not responsible for customers' compliance decisions or outcomes.

> **Regulatory Updates:** Gaming regulations vary by state and territory and are subject to change. Customers should monitor updates from their relevant regulator (e.g., Liquor & Gaming NSW, VGCCC, OLGR Queensland) and ensure ongoing compliance.

#### Australian Gaming Regulatory Framework

Australian gaming operators must comply with state and territory licensing requirements. FrankieOne's gaming workflows can support these common obligations:

| Obligation                | Requirement                                                    | How FrankieOne Can Support                                                |
| ------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
| **Age Verification**      | Verify customers are 18+ before allowing gambling              | Automated age verification against government and commercial data sources |
| **Identity Verification** | Verify customer identity to prevent fraud and multi-accounting | Identity verification workflows with document and biometric options       |
| **Self-Exclusion**        | Check against national and state self-exclusion registers      | Self-exclusion checks are managed separately by the operator              |
| **Responsible Gambling**  | Support responsible gambling obligations                       | Configurable risk triggers and monitoring capabilities                    |
| **Record Keeping**        | Maintain verification records                                  | Audit trails and verification history                                     |

#### State and Territory Considerations

Gaming regulations differ across Australian jurisdictions. Your compliance program should address requirements specific to your operating jurisdictions.

| Jurisdiction | Primary Regulator              | Key Considerations                                 |
| ------------ | ------------------------------ | -------------------------------------------------- |
| NSW          | Liquor & Gaming NSW            | Point of consumption, online wagering requirements |
| VIC          | VGCCC                          | Wagering and betting licence requirements          |
| QLD          | OLGR                           | Interactive gambling requirements                  |
| SA           | CBS                            | Gambling codes of practice                         |
| WA           | Department of Local Government | Betting and gaming requirements                    |
| National     | ACMA                           | Interactive Gambling Act compliance                |

***

### Workflow Configuration Details

#### Primary Workflow: `AUS-Basic3V-AgeVerify`

This workflow provides age verification with identity checks suitable for gaming onboarding.

**Core Checks:**

| Check Type                 | Purpose                            | Outcome                |
| -------------------------- | ---------------------------------- | ---------------------- |
| Age verification           | Confirm applicant is 18+           | Pass/Fail              |
| Government ID verification | Validate identity document via DVS | Match/No Match         |
| Credit bureau check        | Cross-reference identity data      | Match/Partial/No Match |
| Electoral roll             | Address verification               | Match/No Match         |

#### Fraud Detection: `AUS-Risk-CDD-Email-Phone-Device-IP`

Gaming has elevated fraud exposure due to bonus abuse, multi-accounting, and payment fraud. This workflow assesses fraud risk signals.

**Risk Signals Evaluated:**

| Signal                              | Risk Level | Description                |
| ----------------------------------- | ---------- | -------------------------- |
| Device fingerprint on blocklist     | Critical   | Known fraudulent device    |
| Multiple accounts from same device  | High       | Multi-accounting indicator |
| Session velocity over 5 in 24 hours | High       | Abuse pattern detected     |
| Email age under 7 days              | High       | Recently created email     |
| Email domain disposable             | Critical   | Temporary email service    |
| IP geolocation mismatch             | Medium     | Location inconsistency     |
| VPN/proxy detected                  | Medium     | Connection anonymisation   |
| Phone type = VoIP                   | Medium     | Non-mobile number          |

#### Step-Up Verification

For elevated risk scenarios, additional verification can be triggered:

**Step-Up Triggers:**

| Trigger                       | Action                         |
| ----------------------------- | ------------------------------ |
| Device risk score > threshold | Require biometric verification |
| Partial identity match        | Request additional document    |
| Address verification failed   | Request proof of address       |
| High fraud risk signals       | Manual review required         |

#### Self-Exclusion Checks

Self-exclusion register checks (including BetStop National Self-Exclusion Register) are managed separately by the operator outside of FrankieOne workflows. Operators should implement self-exclusion checks as part of their overall onboarding process in accordance with their licensing requirements.

***

### Step-by-Step Implementation

> **Note:** This section describes the conceptual implementation flow. For actual API endpoints, request/response schemas, and code examples, refer to the [FrankieOne API Documentation](https://docs.frankieone.com).

#### Prerequisites

Before implementing, ensure you have:

* FrankieOne API credentials
* Webhook endpoint configured
* OneSDK embedded in your application (recommended for mobile)
* Test environment access

#### Step 1: Collect Customer Details

Collect required information from the applicant:

* Full name
* Date of birth
* Residential address
* Email address
* Mobile phone number
* Government ID details

#### Step 2: Age Verification

Verify the applicant is 18 or older. Age verification is mandatory for gaming.

**Outcomes:**

* **Verified 18+**: Proceed to identity verification
* **Under 18**: Permanent block (regulatory requirement)
* **Unable to verify**: Request alternative documentation

#### Step 3: Identity Verification

Verify customer identity against government and commercial data sources.

#### Step 4: Fraud Assessment

Evaluate fraud risk signals to detect multi-accounting and bonus abuse.

#### Step 5: Handle Decision Outcomes

**PASS:**

* Create customer account
* Enable gambling features
* Set initial deposit limits (if applicable)

**REVIEW:**

* Queue for manual verification
* Notify compliance team
* Do not activate account until resolved

**FAIL:**

* Block registration
* Log rejection reason (internal only)
* Display generic message to user

***

### Risk Tier Examples

#### Tier 1: Low Risk - Auto-Approve

**Customer Profile:**

* Australian citizen, 25 years old
* Valid driver licence
* Address matches electoral roll
* No fraud signals

```mermaid theme={null}
flowchart LR
    A["Customer Input"] --> B["Age: 25 ✓"]
    B --> C["ID Verified ✓"]
    C --> D["Fraud Check: Clear"]
    D --> E["Result: PASS"]
```

**Example Scenario:**

> James Testone, 25, registers for an online wagering account via mobile app. He provides his NSW driver licence. Age verified as 25, identity confirmed against government records, no fraud signals detected. Account activated immediately.

#### Tier 2: Medium Risk - Step-Up Required

**Customer Profile:**

* Valid ID but address mismatch
* New email address
* Multiple registration attempts from device

```mermaid theme={null}
flowchart TD
    A["Customer Input"] --> B["Age: 22 ✓"]
    B --> C["ID Verified ✓"]
    C --> D["Address: Mismatch"]
    D --> E["Fraud Check: Medium Risk"]
    E -->|Step-up triggered| F["Biometric Verification"]
    F --> G["Biometric: Pass"]
    G --> H["Result: PASS"]
```

**Example Scenario:**

> Sarah Testtwo, 22, registers for a betting account. Her identity is verified but address doesn't match electoral roll (recently moved). Device shows 3 previous registration attempts (abandoned). System triggers biometric step-up. Facial match confirms identity. Account activated with enhanced monitoring flag.

#### Tier 3: High Risk - Manual Review

**Customer Profile:**

* Identity verification inconclusive
* High fraud risk score
* Device associated with blocked accounts

```mermaid theme={null}
flowchart TD
    A["Customer Input"] --> B["Age: 19 ✓"]
    B --> C["ID: Partial Match"]
    C --> D["Fraud Check: High Risk"]
    D --> E["Manual Review Queue"]
    E --> F["Result: REVIEW"]
```

**Example Scenario:**

> Michael Testthree, 19, attempts to register. Name partially matches ID records (middle name discrepancy). Device fingerprint associated with 2 previously blocked accounts. Case escalated to compliance team for manual review.

#### Tier 4: Auto-Reject

**Triggers for Automatic Rejection:**

| Trigger                               | Rationale              | User Message                         |
| ------------------------------------- | ---------------------- | ------------------------------------ |
| Age under 18                          | Regulatory requirement | "You must be 18 or over to register" |
| Confirmed fraudulent device           | Fraud prevention       | "Unable to complete registration"    |
| Document tampering detected           | Fraud prevention       | "Unable to verify identity"          |
| Multiple blocked accounts from device | Abuse prevention       | "Unable to complete registration"    |

> **Note:** Self-exclusion checks should be implemented separately by the operator. Never disclose self-exclusion status to the user.

***

### Edge Cases and Special Handling

#### Age Verification Edge Cases

| Scenario                             | Handling                                                  |
| ------------------------------------ | --------------------------------------------------------- |
| DOB makes applicant exactly 18 today | Accept (18+ satisfied)                                    |
| DOB on ID differs from entered DOB   | Reject with mismatch error                                |
| Expired ID document                  | Reject, request current document                          |
| Foreign passport (tourist)           | Accept if gambling permitted for tourists in jurisdiction |

#### Multi-Accounting Detection

Gaming operators need to prevent customers from creating multiple accounts for bonus abuse.

**Detection Signals:**

| Signal                    | Weight | Action                              |
| ------------------------- | ------ | ----------------------------------- |
| Same device fingerprint   | High   | Block or review                     |
| Same email domain pattern | Medium | Flag for review                     |
| Same residential address  | Medium | Flag for review                     |
| Similar name variations   | Low    | Flag if combined with other signals |
| Same payment method       | High   | Block or review                     |

#### Self-Exclusion Handling

Self-exclusion register checks are managed separately by the operator outside of FrankieOne. When implementing self-exclusion checks:

| Scenario                               | Recommended Action                   |
| -------------------------------------- | ------------------------------------ |
| Exact match on exclusion register      | Block registration silently          |
| Near match (similar name/DOB)          | Manual review required               |
| Previously excluded, exclusion expired | Allow if exclusion genuinely expired |
| Requests to check own exclusion status | Direct to BetStop website            |

> **Note:** Never disclose self-exclusion status to the user.

***

### Compliance Reporting

#### Audit Trail Requirements

FrankieOne maintains audit trails for gaming verification activities.

**Data Retained:**

| Data Category            | Retention Period          | Purpose                   |
| ------------------------ | ------------------------- | ------------------------- |
| Verification requests    | Per licensing requirement | Regulatory compliance     |
| Age verification results | Per licensing requirement | Age verification evidence |
| Decision outcomes        | Per licensing requirement | Audit trail               |
| Fraud assessment results | Per licensing requirement | Fraud prevention          |

> **Note:** Retention periods vary by jurisdiction. Ensure your configuration aligns with your licensing requirements.

#### Reporting Capabilities

FrankieOne can support gaming compliance reporting including:

* Verification volumes and outcomes
* Age verification statistics
* Fraud detection metrics
* Device risk assessments

***

### Troubleshooting

| Issue                                        | Likely Cause             | Resolution                          |
| -------------------------------------------- | ------------------------ | ----------------------------------- |
| Age verification failing for valid customers | DOB format mismatch      | Check date format (YYYY-MM-DD)      |
| High false positive rate on multi-accounting | Shared household devices | Tune device fingerprint sensitivity |
| Fraud check timeout                          | Integration issue        | Contact FrankieOne support          |


# Lending - Customer Onboarding
Source: https://docs.frankieone.com/v2/kyc/kyc/use-cases/lending-risk-based-customer-onboarding

KYC Lending Use Case: Risk-Based Customer Onboarding

## Overview

This guide covers FrankieOne's KYC solution for lenders and credit providers, designed to support identity verification, fraud prevention, and responsible lending obligations under the National Consumer Credit Protection Act.

***

## Summary

### Available Workflows

| Workflow                   | Purpose               | When to Use                                 |
| -------------------------- | --------------------- | ------------------------------------------- |
| `AUS-Basic3V-TwoPlusID`    | Standard verification | Personal loans, standard consumer credit    |
| `AUS-Advanced3V-TwoPlusID` | Enhanced verification | Home loans, high-value loans, elevated risk |
| `AUS-Risk-CDD-Lending`     | Fraud detection       | Lending-specific fraud signals              |
| `AUS-Business-KYB`         | Business verification | Small business loans, director verification |

### Verification by Loan Type

| Loan Type     | Value Range  | Recommended Workflow                   |
| ------------- | ------------ | -------------------------------------- |
| Personal loan | Under \$10K  | `AUS-Basic2V` + fraud scoring          |
| Personal loan | \$10K+       | `AUS-Basic3V-TwoPlusID`                |
| Vehicle loan  | $10K - $100K | `AUS-Basic3V-TwoPlusID` + document     |
| Home loan     | \$200K+      | `AUS-Advanced3V-TwoPlusID` + biometric |
| Business loan | Variable     | Individual + `AUS-Business-KYB`        |

### Risk-Based Verification Flow

```mermaid theme={null}
flowchart TD
    A["Loan Application"] --> B{Loan Value & Type}
    B -->|Personal under $20K| C["Standard Verification"]
    B -->|Personal $20K-$50K| D["Standard + Enhanced Screening"]
    B -->|Vehicle/Asset| E["Standard + Asset Verification"]
    B -->|Home Loan| F["Enhanced Verification"]
    C --> G{Fraud Risk Assessment}
    D --> G
    E --> G
    F --> G
    G -->|Low| H["Proceed to Credit Assessment"]
    G -->|Medium| I["Step-Up Verification"]
    G -->|High| J["Manual Review / Decline"]
```

### Decision Outcomes

| Outcome                    | Action                          |
| -------------------------- | ------------------------------- |
| **Verified - Low Risk**    | Proceed to credit assessment    |
| **Verified - Medium Risk** | Proceed with caution flags      |
| **Step-Up Required**       | Request additional verification |
| **High Risk**              | Manual review or decline        |

### Key Fraud Signals

| Signal                        | Risk Level | Description                          |
| ----------------------------- | ---------- | ------------------------------------ |
| Synthetic identity indicators | Critical   | Fabricated identity patterns         |
| Application velocity          | High       | Multiple applications across lenders |
| Credit file inconsistencies   | High       | Mismatch with credit bureau data     |
| Device on fraud network       | Critical   | Known fraudulent device              |

### Support

* **Documentation**: [docs.frankieone.com](https://docs.frankieone.com)
* **Support**: Contact your FrankieOne representative

***

## Expanded Details

### Regulatory Context

> **Disclaimer:** The information in this section is provided for general guidance only and does not constitute legal or compliance advice. Customers must seek independent legal and regulatory advice to ensure their implementation meets their specific regulatory obligations. FrankieOne is not responsible for customers' compliance decisions or outcomes.

> **Regulatory Updates:** Lending regulations continue to evolve. Customers should monitor updates from ASIC regarding responsible lending, hardship obligations, and consumer protection requirements.

#### Australian Lending Regulatory Framework

Lenders providing consumer credit must comply with multiple regulatory requirements. FrankieOne's lending workflows can support these obligations:

| Obligation                    | Regulatory Source                | How FrankieOne Can Support                         |
| ----------------------------- | -------------------------------- | -------------------------------------------------- |
| **Customer Identification**   | AML/CTF Act (where applicable)   | Automated identity verification workflows          |
| **Identity Fraud Prevention** | General law, responsible lending | Fraud detection and synthetic identity prevention  |
| **Responsible Lending**       | NCCP Act                         | Identity verification to support credit assessment |
| **Hardship Identification**   | NCCP Act                         | Customer verification for hardship applications    |
| **Privacy**                   | Privacy Act                      | Secure handling of personal information            |
| **Record Keeping**            | Various                          | Audit trails and verification records              |

#### National Consumer Credit Protection Act (NCCP)

The NCCP Act establishes responsible lending obligations. While FrankieOne provides identity verification (not credit assessment), verification supports:

| NCCP Requirement              | How Identity Verification Supports                                       |
| ----------------------------- | ------------------------------------------------------------------------ |
| **Make reasonable inquiries** | Verified identity ensures inquiries relate to correct person             |
| **Verify information**        | Identity verification as foundation for information verification         |
| **Assess suitability**        | Confirmed identity enables accurate credit assessment                    |
| **Not unsuitable credit**     | Fraud detection helps prevent unsuitable lending to synthetic identities |

> **Note:** Credit assessment, income verification, and suitability determination are separate from identity verification.

#### AML/CTF Obligations

Some lenders are AUSTRAC reporting entities with AML/CTF obligations:

| Entity Type              | AML/CTF Status                 |
| ------------------------ | ------------------------------ |
| ADI lenders (banks)      | Reporting entity               |
| Finance companies (some) | May be reporting entity        |
| Mortgage brokers         | Not typically reporting entity |
| Peer-to-peer lenders     | Depends on structure           |

***

### Workflow Configuration Details

#### Standard Verification: `AUS-Basic3V-TwoPlusID`

Suitable for personal loans and standard consumer credit.

**Core Checks:**

| Check Type                       | Purpose                                |
| -------------------------------- | -------------------------------------- |
| Government ID verification (DVS) | Primary identity confirmation          |
| Credit bureau identity check     | Cross-reference and credit file link   |
| Electoral roll                   | Address verification                   |
| PEP and sanctions screening      | AML risk assessment (where applicable) |

#### Enhanced Verification: `AUS-Advanced3V-TwoPlusID`

For higher-value loans, home loans, and elevated risk scenarios.

**Additional Checks:**

| Check Type                    | Purpose                              |
| ----------------------------- | ------------------------------------ |
| Biometric verification        | Face-to-document matching            |
| Document authenticity         | Fraud and tampering detection        |
| Enhanced address verification | Multiple source address confirmation |
| Adverse media screening       | Additional risk assessment           |

#### Fraud Detection: `AUS-Risk-CDD-Lending`

Lending-specific fraud detection workflow.

**Risk Signals:**

| Signal                        | Risk Level  | Description                          |
| ----------------------------- | ----------- | ------------------------------------ |
| Synthetic identity indicators | Critical    | Fabricated identity patterns         |
| Application velocity          | High        | Multiple applications across lenders |
| Credit file inconsistencies   | High        | Mismatch with credit bureau data     |
| Device on fraud network       | Critical    | Known fraudulent device              |
| Email/phone risk              | Medium-High | Recently created or disposable       |
| Address risk                  | Medium      | Non-residential or high-risk address |

***

### Step-by-Step Implementation

> **Note:** This section describes the conceptual implementation flow. For actual API endpoints and schemas, refer to the [FrankieOne API Documentation](https://docs.frankieone.com).

#### Implementation Flow

```mermaid theme={null}
flowchart LR
    A["Application"] --> B["Identity Verification"]
    B --> C["Fraud Assessment"]
    C --> D["Risk Decision"]
    D --> E["Credit Assessment"]
    E --> F["Loan Decision"]
```

#### Step 1: Collect Applicant Details

Collect required information for identity verification:

* Full legal name
* Date of birth
* Residential address (current and previous if under 3 years)
* Email address
* Mobile phone number
* Government ID details
* Employment details (for credit assessment)

#### Step 2: Identity Verification

Verify applicant identity against authoritative sources.

**Verification by Loan Type:**

| Loan Type                 | Minimum Verification            |
| ------------------------- | ------------------------------- |
| Personal loan under \$10K | 2-source electronic             |
| Personal loan \$10K+      | 3-source electronic             |
| Vehicle loan              | 3-source + document recommended |
| Home loan                 | Enhanced + document + biometric |

#### Step 3: Fraud Assessment

Evaluate fraud signals specific to lending.

**Lending Fraud Patterns:**

| Pattern            | Detection Approach                             |
| ------------------ | ---------------------------------------------- |
| Synthetic identity | Cross-source consistency, credit file age      |
| Identity takeover  | Device signals, application behaviour          |
| First-party fraud  | Historical data, bureau alerts                 |
| Application fraud  | Velocity checks, data consistency              |
| Income fraud       | Outside FrankieOne scope (income verification) |

#### Step 4: Risk Decision

Combine identity and fraud signals for risk decision.

#### Step 5: Support Credit Assessment

Verified identity enables accurate credit assessment by ensuring:

* Credit file belongs to applicant
* Previous applications linked correctly
* Fraud indicators flagged before credit decision

> **Note:** Credit assessment, income verification, and affordability checks are outside FrankieOne's identity verification scope.

***

### Risk Tier Examples

#### Tier 1: Low Risk - Standard Verification

**Application Profile:**

* Personal loan \$8,000
* Australian citizen, employed
* Strong credit bureau match
* No fraud signals

```mermaid theme={null}
flowchart LR
    A["Application"] --> B["ID Verified ✓"]
    B --> C["Credit Bureau Match ✓"]
    C --> D["Fraud: Low Risk"]
    D --> E["Proceed to Credit Assessment"]
```

**Example Scenario:**

> Sarah Testone, 34, applies for an \$8,000 personal loan for home renovations. Identity verified against DVS (driver licence) and credit bureau. Name, DOB, and address all match. No fraud signals detected. Identity verification complete, proceeds to credit assessment.

#### Tier 2: Medium Risk - Enhanced Verification

**Application Profile:**

* Vehicle loan \$45,000
* Recent address change
* New to credit bureau
* Moderate fraud signals

```mermaid theme={null}
flowchart TD
    A["Application"] --> B["ID Verified ✓"]
    B --> C["Credit Bureau: Thin File"]
    C --> D["Address: Recent Change"]
    D --> E["Fraud: Medium Risk"]
    E --> F["Step-Up: Document Verification"]
    F --> G["Document Verified ✓"]
    G --> H["Proceed to Credit Assessment"]
```

**Example Scenario:**

> Michael Testtwo, 23, applies for a \$45,000 car loan. Identity verified but credit bureau shows thin file (recently turned 18 when file created). Address changed 2 months ago. Device shows no prior applications. Step-up triggered: driver licence document uploaded and verified. Proceeds to credit assessment with flags for thin file.

#### Tier 3: High Risk - Manual Review

**Application Profile:**

* Home loan \$650,000
* Identity inconsistencies
* Application velocity detected
* High-risk fraud indicators

```mermaid theme={null}
flowchart TD
    A["Application"] --> B["ID: Partial Match"]
    B --> C["Credit Bureau: Inconsistencies"]
    C --> D["Velocity: 4 Applications/30 Days"]
    D --> E["Fraud: High Risk"]
    E --> F["Manual Review Required"]
    F --> G["Fraud Investigation"]
```

**Example Scenario:**

> Application received for \$650,000 home loan. Name matches but DOB discrepancy between application and credit file. Credit bureau shows 4 recent inquiries from other lenders in 30 days. Device fingerprint associated with previous declined application at another lender. Escalated to fraud team for investigation before proceeding.

***

### Edge Cases and Special Handling

#### Joint Applications

Many loans involve joint applicants (e.g., home loans with partners).

| Scenario          | Verification Requirement                     |
| ----------------- | -------------------------------------------- |
| Married couple    | Both applicants verified independently       |
| De facto partners | Both applicants verified independently       |
| Parent guarantor  | Guarantor verified + legal capacity          |
| Business partners | All parties verified + business verification |

#### Guarantor Verification

| Requirement              | Verification                               |
| ------------------------ | ------------------------------------------ |
| Identity verification    | Standard verification process              |
| Legal capacity           | Age 18+, not under administration          |
| Independent legal advice | Document confirmation (outside FrankieOne) |
| Relationship to borrower | Disclosed and documented                   |

#### Refinance Applications

| Consideration         | Approach                                 |
| --------------------- | ---------------------------------------- |
| Existing customer     | Leverage existing verification if recent |
| Verification currency | Re-verify if over 12 months              |
| Address changes       | Verify current address                   |
| Name changes          | Verify with supporting documents         |

#### Small Business Lending

| Component           | Verification                       |
| ------------------- | ---------------------------------- |
| Individual borrower | Standard individual verification   |
| Business entity     | Business verification (ABN, ASIC)  |
| Directors/partners  | Individual verification of all     |
| Guarantors          | Individual verification + capacity |

***

### Fraud Prevention

#### Lending-Specific Fraud Vectors

| Fraud Type             | Description                                    | Mitigation                                     |
| ---------------------- | ---------------------------------------------- | ---------------------------------------------- |
| **Synthetic Identity** | Fabricated identity using mixed real/fake data | Cross-source consistency, credit file analysis |
| **Identity Takeover**  | Using stolen identity to obtain credit         | Device intelligence, behavioural signals       |
| **First-Party Fraud**  | Borrower provides false information            | Data verification, velocity checks             |
| **Application Fraud**  | False application details                      | Automated verification, document checks        |
| **Broker Fraud**       | Falsified applications via broker channel      | Broker verification, application analysis      |

#### Synthetic Identity Detection

| Indicator                        | Detection                                        |
| -------------------------------- | ------------------------------------------------ |
| Credit file age vs applicant age | File created recently for older applicant        |
| Authorised user patterns         | Only authorised user accounts, no primary        |
| Address inconsistencies          | Multiple identities at same address              |
| SSN/TFN anomalies                | Number patterns inconsistent with issue date     |
| Data element mismatches          | DOB/name combinations don't match across sources |

#### Velocity Controls

| Control                             | Typical Threshold   | Action            |
| ----------------------------------- | ------------------- | ----------------- |
| Applications per identity per month | 3                   | Flag / review     |
| Applications per device per week    | 2                   | Flag / review     |
| Applications per address per month  | 3                   | Flag / review     |
| Cross-lender velocity (via bureau)  | 5 inquiries/90 days | Enhanced scrutiny |

***

### Integration with Credit Assessment

#### Identity Verification vs Credit Assessment

| Component                  | FrankieOne Scope | Credit Assessment (Separate) |
| -------------------------- | ---------------- | ---------------------------- |
| Identity confirmation      | ✓                |                              |
| Fraud detection            | ✓                |                              |
| PEP/sanctions screening    | ✓                |                              |
| Credit score               |                  | ✓                            |
| Income verification        |                  | ✓                            |
| Expense analysis           |                  | ✓                            |
| Serviceability calculation |                  | ✓                            |
| Loan suitability           |                  | ✓                            |

#### Data Handoff

FrankieOne provides verified identity data to support credit assessment:

* Verified full legal name
* Verified date of birth
* Verified address
* Credit bureau file reference
* Identity verification confidence score
* Fraud risk indicators

***

### Compliance Reporting

#### Audit Trail Requirements

| Data Category                 | Retention Period           | Purpose             |
| ----------------------------- | -------------------------- | ------------------- |
| Identity verification results | Per regulatory requirement | Compliance evidence |
| Document images               | Per regulatory requirement | Evidence retention  |
| Fraud assessment results      | Per regulatory requirement | Fraud investigation |
| Decision outcomes             | Per regulatory requirement | Audit trail         |

#### Hardship Verification Support

For customers requesting hardship variations:

* Verify identity of person making request
* Confirm they are the account holder
* Support secure communication

***

### Troubleshooting

| Issue                  | Likely Cause                     | Resolution                              |
| ---------------------- | -------------------------------- | --------------------------------------- |
| Credit bureau no-match | Name/DOB format                  | Verify data entry, check variations     |
| Thin credit file flags | Young or new-to-credit applicant | Document verification, alternative data |
| High fraud score       | Legitimate signals               | Manual review, step-up verification     |
| Address mismatch       | Recent move                      | Document proof of address               |


# Real Estate - Customer Onboarding
Source: https://docs.frankieone.com/v2/kyc/kyc/use-cases/real-estate-risk-based-customer-onboarding

KYC Real Estate Use Case: Risk-Based Customer Verification

## Overview

This guide covers FrankieOne's KYC solution for real estate professionals, designed to support identity verification obligations for real estate agents, conveyancers, and property transaction participants under current and upcoming AML/CTF requirements.

***

## Summary

### Available Workflows

| Workflow                  | Purpose                 | When to Use                          |
| ------------------------- | ----------------------- | ------------------------------------ |
| `AUS-Basic3V-TwoPlusID`   | Individual verification | Buyers, sellers (individuals)        |
| `AUS-Business-KYB`        | Entity verification     | Companies, trusts, partnerships      |
| `AUS-PEP-Sanctions-Media` | Enhanced screening      | High-value, higher-risk transactions |

### Verification by Party Type

| Party                | Workflow                                     | Timing            |
| -------------------- | -------------------------------------------- | ----------------- |
| Individual Seller    | `AUS-Basic3V-TwoPlusID`                      | Listing agreement |
| Individual Buyer     | `AUS-Basic3V-TwoPlusID`                      | Offer/contract    |
| Company/Trust Seller | `AUS-Business-KYB` + individual verification | Listing agreement |
| Company/Trust Buyer  | `AUS-Business-KYB` + UBO verification        | Offer/contract    |
| Foreign Purchaser    | Enhanced verification + FIRB check           | Offer/contract    |

### Risk-Based Approach

```mermaid theme={null}
flowchart TD
    A["Property Transaction"] --> B{Transaction Risk Assessment}
    B -->|Low Risk| C["Standard CDD"]
    B -->|Medium Risk| D["Enhanced CDD + Screening"]
    B -->|High Risk| E["Enhanced CDD + Source of Funds + Senior Approval"]
    C --> F["Proceed"]
    D --> F
    E --> G["Manual Review"]
    G --> F
```

### Risk Factors

| Factor            | Lower Risk               | Higher Risk                       |
| ----------------- | ------------------------ | --------------------------------- |
| Transaction value | Under \$1M               | Over \$5M                         |
| Property type     | Residential              | Commercial, development           |
| Buyer type        | Australian individual    | Foreign entity, complex structure |
| Payment method    | Bank transfer (domestic) | Cash, offshore funds, crypto      |
| PEP/sanctions     | Clear                    | Matches or near-matches           |

### Verification Checklists

**Individual:**

* Full legal name ✓
* Date of birth ✓
* Residential address ✓
* Government ID ✓
* PEP/sanctions screening ✓

**Entity:**

* Entity name and registration ✓
* Directors/trustees ✓
* Beneficial owners over 25% ✓
* Each UBO verified ✓
* PEP/sanctions screening (all) ✓

### Support

* **Documentation**: [docs.frankieone.com](https://docs.frankieone.com)
* **Support**: Contact your FrankieOne representative

***

## Expanded Details

### Regulatory Context

> **Disclaimer:** The information in this section is provided for general guidance only and does not constitute legal or compliance advice. Customers must seek independent legal and regulatory advice to ensure their implementation meets their specific regulatory obligations. FrankieOne is not responsible for customers' compliance decisions or outcomes.

> **Regulatory Updates:** The Australian Government is implementing AML/CTF Tranche 2 reforms that will bring real estate professionals under AUSTRAC reporting obligations. Customers should monitor updates from AUSTRAC and prepare for compliance requirements.

#### AML/CTF Tranche 2 - Real Estate

Real estate has been identified as a high-risk sector for money laundering. Tranche 2 reforms will extend AML/CTF obligations to:

| Covered Entity          | Expected Obligations                                                  |
| ----------------------- | --------------------------------------------------------------------- |
| **Real Estate Agents**  | Customer identification, suspicious matter reporting, AML/CTF program |
| **Conveyancers**        | Customer identification, transaction monitoring, reporting            |
| **Property Developers** | Customer due diligence for off-plan sales                             |
| **Settlement Agents**   | Customer identification, fund source verification                     |

#### Expected Obligations Under Tranche 2

| Obligation                      | Requirement                                               | How FrankieOne Can Support                               |
| ------------------------------- | --------------------------------------------------------- | -------------------------------------------------------- |
| **Customer Identification**     | Verify identity of buyers, sellers, and beneficial owners | Automated identity verification workflows                |
| **Beneficial Ownership**        | Identify and verify beneficial owners of entities         | Business verification and UBO identification             |
| **Ongoing CDD**                 | Risk-based ongoing customer due diligence                 | Screening refresh and re-verification (where configured) |
| **AML/CTF Program**             | Establish and maintain compliant program                  | Configurable risk rules aligned to your program          |
| **Suspicious Matter Reporting** | Report suspicious matters to AUSTRAC                      | Audit trails and exportable verification data            |
| **Record Keeping**              | Maintain verification records for 7 years                 | Secure record retention                                  |

#### Current Industry Obligations

Even before Tranche 2, real estate professionals have verification obligations:

| Source                             | Requirement                                  |
| ---------------------------------- | -------------------------------------------- |
| **Real Estate Institute Codes**    | Client identification best practices         |
| **State Licensing Requirements**   | Varies by jurisdiction                       |
| **Anti-Money Laundering Guidance** | Industry guidance on suspicious transactions |
| **Foreign Investment (FIRB)**      | Foreign purchaser identification             |

***

### Workflow Configuration Details

#### Individual Verification: `AUS-Basic3V-TwoPlusID`

Standard identity verification for individual buyers and sellers.

**Core Checks:**

| Check Type                       | Purpose                       |
| -------------------------------- | ----------------------------- |
| Government ID verification (DVS) | Primary identity confirmation |
| Credit bureau check              | Identity cross-reference      |
| Electoral roll                   | Address verification          |
| PEP and sanctions screening      | AML risk assessment           |

#### Business Verification: `AUS-Business-KYB`

Verification for companies, trusts, and other entities involved in property transactions.

**Entity Verification Components:**

| Component               | Description                                 |
| ----------------------- | ------------------------------------------- |
| Entity existence        | ASIC/ABR verification                       |
| Entity details          | Name, registration, status                  |
| Directors/officeholders | Identification of key persons               |
| Beneficial owners       | Individuals with over 25% ownership/control |
| Trust structures        | Trustee and beneficiary identification      |

#### Enhanced Screening: `AUS-PEP-Sanctions-Media`

Enhanced screening for higher-risk transactions.

**Screening Components:**

| Check               | Description                              |
| ------------------- | ---------------------------------------- |
| PEP screening       | Politically Exposed Persons (Levels 1-4) |
| Sanctions screening | DFAT, UN, OFAC, EU lists                 |
| Adverse media       | Negative news screening                  |
| Watchlists          | Law enforcement lists                    |

***

### Step-by-Step Implementation

> **Note:** This section describes the conceptual implementation flow. For actual API endpoints and schemas, refer to the [FrankieOne API Documentation](https://docs.frankieone.com).

#### Seller Verification Flow

```mermaid theme={null}
flowchart LR
    A["Listing Enquiry"] --> B["Verify Seller Identity"]
    B --> C["Verify Authority to Sell"]
    C --> D["Screening Check"]
    D --> E["Risk Assessment"]
    E --> F["Proceed with Listing"]
```

**Step 1: Verify Seller Identity**

For individual sellers:

* Full legal name
* Date of birth
* Residential address
* Government ID verification

For entity sellers:

* Entity verification (company/trust)
* Director/trustee identification
* Beneficial owner verification
* Authority to sell

**Step 2: Verify Authority to Sell**

| Scenario          | Verification Required                    |
| ----------------- | ---------------------------------------- |
| Sole owner        | Title search confirmation                |
| Joint owners      | All owners verified                      |
| Company owner     | Director authority, company verification |
| Trust owner       | Trustee authority, trust verification    |
| Deceased estate   | Executor verification, probate           |
| Power of Attorney | POA document, attorney verification      |

#### Buyer Verification Flow

```mermaid theme={null}
flowchart LR
    A["Offer Received"] --> B["Verify Buyer Identity"]
    B --> C["Entity/UBO Check"]
    C --> D["Screening Check"]
    D --> E["Source of Funds"]
    E --> F["Risk Assessment"]
    F --> G["Proceed to Contract"]
```

**Step 1: Verify Buyer Identity**

For individual buyers:

* Full legal name
* Date of birth
* Residential address
* Government ID verification

For entity buyers:

* Entity verification
* Beneficial owner identification
* All UBOs with over 25% ownership verified

**Step 2: Beneficial Ownership Verification**

```mermaid theme={null}
flowchart TD
    A["Entity Buyer"] --> B["Identify Entity Type"]
    B --> C{Entity Type}
    C -->|Company| D["ASIC Extract<br/>Directors + Shareholders"]
    C -->|Trust| E["Trust Deed<br/>Trustee + Beneficiaries"]
    C -->|Partnership| F["Partnership Agreement<br/>Partners"]
    D --> G["Identify UBOs over 25%"]
    E --> G
    F --> G
    G --> H["Verify Each UBO"]
    H --> I["Complete"]
```

**Step 3: Foreign Purchaser Verification**

| Requirement           | Verification                          |
| --------------------- | ------------------------------------- |
| FIRB approval         | Confirm approval obtained             |
| Passport verification | Foreign passport + visa if applicable |
| Overseas address      | Address verification or document      |
| Source of funds       | May require enhanced due diligence    |

***

### Risk Tier Examples

#### Tier 1: Low Risk - Standard CDD

**Transaction Profile:**

* Australian individual seller
* Australian individual buyer
* Residential property \$650,000
* Bank transfer from domestic account

```mermaid theme={null}
flowchart LR
    A["Transaction"] --> B["Seller ID ✓"]
    B --> C["Buyer ID ✓"]
    C --> D["Screening: Clear"]
    D --> E["Risk: Low"]
    E --> F["Standard CDD Complete"]
```

**Example Scenario:**

> James Testone sells his Sydney apartment to Mary Testtwo for \$650,000. Both are Australian citizens with verified identities. Standard CDD completed. Funds transferred from Mary's domestic bank account. Transaction proceeds.

#### Tier 2: Medium Risk - Enhanced CDD

**Transaction Profile:**

* Company seller (investment property)
* Foreign individual buyer
* Property value \$1.8M
* FIRB approval required

```mermaid theme={null}
flowchart TD
    A["Transaction"] --> B["Company Verification"]
    B --> C["Director ID ✓"]
    C --> D["Foreign Buyer ID"]
    D --> E["FIRB Check"]
    E --> F["Enhanced Screening"]
    F --> G["Risk: Medium"]
    G --> H["Enhanced CDD Complete"]
```

**Example Scenario:**

> TestCorp Pty Ltd (verified company, directors identified) sells Melbourne property to Hans Testthree, a German national with FIRB approval. Enhanced due diligence performed: foreign passport verified, FIRB approval confirmed, PEP/sanctions screening clear. Transaction proceeds with enhanced documentation.

#### Tier 3: High Risk - Senior Approval Required

**Transaction Profile:**

* Complex trust structure seller
* Offshore company buyer
* High-value commercial property \$12M
* PEP Level 3 identified in ownership structure

```mermaid theme={null}
flowchart TD
    A["Transaction"] --> B["Trust Verification"]
    B --> C["Multiple Beneficiaries"]
    C --> D["Offshore Company Buyer"]
    D --> E["UBO Verification"]
    E --> F["PEP L3 Identified"]
    F --> G["Enhanced Screening"]
    G --> H["Source of Funds Review"]
    H --> I["Senior Approval Required"]
    I --> J["Risk: High - Manual Review"]
```

**Example Scenario:**

> A family trust sells commercial property to an offshore company. Trust has 5 beneficiaries requiring verification. Buyer's UBO structure reveals a PEP Level 3 (family member of political figure). Enhanced due diligence required: all beneficiaries verified, offshore company structure documented, source of funds investigated. Senior management approval required before proceeding.

***

### Edge Cases and Special Handling

#### Complex Ownership Structures

| Structure                    | Verification Approach                           |
| ---------------------------- | ----------------------------------------------- |
| **Discretionary Trust**      | Trustee + appointor + beneficiary classes       |
| **Unit Trust**               | Trustee + unit holders over 25%                 |
| **SMSF**                     | Corporate trustee/individual trustees + members |
| **Foreign Trust**            | Equivalent to Australian requirements           |
| **Multi-layered Structures** | Verify through to ultimate beneficial owners    |

#### Authorised Representatives

| Scenario               | Verification Required                     |
| ---------------------- | ----------------------------------------- |
| Power of Attorney      | POA document verification, attorney ID    |
| Company representative | Authority confirmation, representative ID |
| Solicitor acting       | Law society verification, solicitor ID    |
| Buyer's agent          | Authority letter, agent ID                |

#### Deceased Estates

| Document                          | Purpose                       |
| --------------------------------- | ----------------------------- |
| Death certificate                 | Confirm death                 |
| Probate/Letters of Administration | Authority to sell             |
| Executor ID verification          | Identity of authorised person |

#### Property-Specific Considerations

| Property Type      | Additional Considerations                    |
| ------------------ | -------------------------------------------- |
| Off-the-plan       | Developer verification, sunset clauses       |
| Auction            | Time-sensitive verification                  |
| Commercial         | Higher value thresholds, tenant verification |
| Rural/agricultural | Water rights, foreign ownership restrictions |

***

### Beneficial Ownership

#### Identifying Beneficial Owners

Under expected Tranche 2 requirements, beneficial owners are individuals who:

* Own over 25% of the entity (directly or indirectly)
* Control over 25% of voting rights
* Exercise significant control over the entity

**Verification Requirements:**

| UBO Category                 | Verification                        |
| ---------------------------- | ----------------------------------- |
| Direct shareholders over 25% | Standard individual verification    |
| Indirect owners over 25%     | Trace through to individual, verify |
| Controlling persons          | Verify identity, document control   |
| Trust beneficiaries          | Named beneficiaries or classes      |

#### Common Entity Structures

```mermaid theme={null}
flowchart TD
    A["Property Purchase by Entity"] --> B{Entity Type}
    B --> C["Pty Ltd Company"]
    B --> D["Family Trust"]
    B --> E["SMSF"]
    B --> F["Partnership"]

    C --> G["Verify: Directors, Shareholders over 25%"]
    D --> H["Verify: Trustee, Appointor, Beneficiaries"]
    E --> I["Verify: Trustees, Members"]
    F --> J["Verify: All Partners"]

    G --> K["Identify & Verify UBOs"]
    H --> K
    I --> K
    J --> K
```

***

### Compliance Reporting

#### Record Keeping Requirements

Under expected Tranche 2 requirements, records must be kept for 7 years.

**Records to Maintain:**

| Record Type               | Details                                       |
| ------------------------- | --------------------------------------------- |
| Customer identification   | Verification records, documents collected     |
| Transaction records       | Property details, values, parties             |
| Risk assessments          | Risk rating, rationale                        |
| Screening results         | PEP/sanctions checks                          |
| Suspicious matter reports | Internal records (reports filed with AUSTRAC) |

#### Suspicious Matter Indicators

Real estate professionals should be alert to:

| Indicator                         | Example                                   |
| --------------------------------- | ----------------------------------------- |
| Unusual payment arrangements      | Cash deposits, third-party payments       |
| Price anomalies                   | Significantly above/below market value    |
| Rapid transactions                | Quick buy/sell sequences                  |
| Reluctance to provide information | Avoiding verification                     |
| Complex structures                | Unnecessarily complex ownership           |
| High-risk jurisdictions           | Funds or parties from high-risk countries |

***

### Troubleshooting

| Issue                         | Likely Cause            | Resolution                                      |
| ----------------------------- | ----------------------- | ----------------------------------------------- |
| Entity verification failing   | Incorrect ABN/ACN       | Verify registration details                     |
| UBO identification incomplete | Complex trust structure | Request trust deed, trace ownership             |
| Foreign passport verification | Document not supported  | Request alternative ID or document verification |
| FIRB approval not confirmed   | Timing issue            | Confirm with buyer's solicitor                  |


# Create an individual entity
Source: https://docs.frankieone.com/api-reference/individual-entities/create-an-individual-entity

/specs/fc-kyc-bundled_generated.yaml post /v2/individuals
Creates an Individual entity object which can be used to store data about an individual. You can optionally include documents, attachments, references etc. to the entity.
Information stored in an entity object can be used to verify the individual against external data sources for the purposes of eKYC, or in other verifications supported by FrankieOne.



# Delete an individual entity
Source: https://docs.frankieone.com/api-reference/individual-entities/delete-an-individual-entity

/specs/fc-kyc-bundled_generated.yaml delete /v2/individuals/{entityId}
Delete Individual Entity with the matching entity ID.



# Get an individual entity
Source: https://docs.frankieone.com/api-reference/individual-entities/get-an-individual-entity

/specs/fc-kyc-bundled_generated.yaml get /v2/individuals/{entityId}
Retrieve all the information of the Individual Entity with the matching entity ID.



# Update an individual entity
Source: https://docs.frankieone.com/api-reference/individual-entities/update-an-individual-entity

/specs/fc-kyc-bundled_generated.yaml patch /v2/individuals/{entityId}
Update any of the information of the Individual Entity with the matching entity ID.



# Create an individual and execute a workflow for the given service profile
Source: https://docs.frankieone.com/api-reference/individual-workflows/create-an-individual-and-execute-a-workflow-for-the-given-service-profile

/specs/fc-kyc-bundled_generated.yaml post /v2/individuals/new/serviceprofiles/{serviceName}/workflows/{workflowName}/execute
Create an individual and execute a workflow for the given service profile



# Evaluate a workflow for the given service profile using existing results
Source: https://docs.frankieone.com/api-reference/individual-workflows/evaluate-a-workflow-for-the-given-service-profile-using-existing-results

/specs/fc-kyc-bundled_generated.yaml post /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/evaluate
Re-evaluate a workflow for the given service profile using only the current set of results, without gathering any new data.



# Execute a workflow for the given service profile
Source: https://docs.frankieone.com/api-reference/individual-workflows/execute-a-workflow-for-the-given-service-profile

/specs/fc-kyc-bundled_generated.yaml post /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/execute
Execute a workflow for the given service profile.



# Get a list of executable workflows
Source: https://docs.frankieone.com/api-reference/individual-workflows/get-a-list-of-executable-workflows

/specs/fc-kyc-bundled_generated.yaml get /v2/workflows
Get a list of workflows that can be executed



# Get a list of executions and their results
Source: https://docs.frankieone.com/api-reference/individual-workflows/get-a-list-of-executions-and-their-results

/specs/fc-kyc-bundled_generated.yaml get /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions
Get a list of entity results. Always sorted in reverse chrono order



# Get the result of a specific execution by its executionId.
Source: https://docs.frankieone.com/api-reference/individual-workflows/get-the-result-of-a-specific-execution-by-its-executionid

/specs/fc-kyc-bundled_generated.yaml get /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions/{workflowExecutionId}
Get the result of a specific execution by its executionId.



# A note on middle names
Source: https://docs.frankieone.com/docs/a-note-on-middle-names



<Info>
  ##### Middle names importance

  Middle names do impact KYC results particularly when it comes to government IDs.
</Info>

Below is a general rule on how the middle name being present and its format impacts the result of a check.

|                           |                                                                                                                                                                                                                                                                 |                       |
| :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------- |
| **Check Type / Document** | **Summary**                                                                                                                                                                                                                                                     | **Related documents** |
| AU Driver’s License       | Driver's licenses are more lenient when it comes to middle name matching. DVS doesn't check the middle name on driver's licenses                                                                                                                                |                       |
| Passports in AU           | Passport matching is pretty strict when it comes to name matching.<br /><br />It requires the name exactly as it's on the passport, so if there’s a middle name collect it from the applicant                                                                   |                       |
| AU Medicare card          | Middle names on medicare cards are tricky, to say the least.<br /><br />The details need to be provided as exactly as it's on the medicare card taking into account whether the middle name on it's an initial, the full middle name, or no middle name at all. |                       |


# Handling Single Name Applicants
Source: https://docs.frankieone.com/docs/a-note-on-single-names



There are cultures and regions that use single names for individuals, also known as mononyms. When handling data entry and verification for applicants with single names, it's crucial to follow a consistent and culturally sensitive approach. Below are the guidelines you should follow as part of your integration with FrankieOne.

## Name Storage for Single Names

Store a single name in the `FamilyName` field. `FamilyName` is the only name field FrankieOne requires — `GivenName` is optional — and most downstream data sources also mandate a family name or "Last Name", so this approach keeps the profile valid and gives the widest verification coverage.

1. `FamilyName `**Field (Preferred)**
   * Store the single name in the `FamilyName` field, and use a hyphen (`-`) as the `GivenName` placeholder.
   * Ensure that any system rules that differentiate between given and family names are appropriately configured to accept a single name in this context.
2. `GivenName `**Field**
   * Only use the `GivenName` field where a specific data source requires it, and keep `FamilyName` populated — a single name stored in `GivenName` with an empty `FamilyName` will be rejected.
3. **`DisplayName` for Renderings**
   * Utilize the `DisplayName` field to reflect culturally appropriate renderings of the name. This is particularly important for systems that output names for display where a single name might be used differently than conventional given-family name structures.

<Info>
  ##### Special Cases: Australian Document Verification Service (DVS)

  * Use a hyphen (`-`) as the first name placeholder.
  * Enter the single name into the `FamilyName` field.
  * A full stop (`.`) can be used as an alternative to a hyphen if preferred by the service providers during verification processes.
</Info>

## Tips for Implementation

* **Consistent Application**: Ensure your application's data entry and storage processes consistently apply these rules to prevent errors or discrepancies in user data.
* **Default to `FamilyName`**: Store the single name in `FamilyName` unless a specific data source requires otherwise, and never leave `FamilyName` empty.
* **Configured Displays**: Adjust how names are displayed in your application. Use `DisplayName` for areas where users or clients view a person's name, ensuring natural or preferred readings.

If you require further assistance or need specific guidance on handling single names, do not hesitate to reach out to our developer support team.

***

For detailed technical specifications, please refer to our [API Reference](/api-reference/individual-entities/create-an-individual-entity) which includes full descriptions and examples for the individual `name` object.

For the API-side implementation, including the Australian DVS formatting rules and which check types support single names, see [Single Name Handling](/docs/kyc-v2/implementation-guide/single-name-verification).


# Angular
Source: https://docs.frankieone.com/docs/angular-onesdk-implementation

This guide walks you through integrating OneSDK with a new Angular project, providing a robust foundation for building KYC/AML features in your Angular application.

## Quick Setup

<Steps>
  <Step title="Install Angular CLI">
    ```shell theme={null}
    npm install -g @angular/cli
    ```
  </Step>

  <Step title="Create New Angular Project">
    ```shell theme={null}
    ng new <project-name>
    ```
  </Step>

  <Step title="Install OneSDK Package">
    ```shell theme={null}
    npm install @frankieone/one-sdk
    ```
  </Step>
</Steps>

## Webpack Configuration

<Accordion title="Setting up Webpack (Optional)">
  <Steps>
    <Step title="Install Dependencies">
      ```shell theme={null}
      npm install -D @angular-builders/custom-webpack file-loader style-loader css-loader @types/react
      ```
    </Step>

    <Step title="Update angular.json">
      Add custom Webpack configuration:

      ```json theme={null}
      {
        "projects": {
          "<project-name>": {
            "architect": {
              "build": {
                "builder": "@angular-builders/custom-webpack:browser",
                "options": {
                  "customWebpackConfig": {
                    "path": "./webpack.config.js"
                  }
                }
              },
              "serve": {
                "builder": "@angular-builders/custom-webpack:dev-server"
              }
            }
          }
        }
      }
      ```
    </Step>

    <Step title="Create webpack.config.js">
      ```javascript theme={null}
      module.exports = {
        module: {
          rules: [
            {
              test: /\.svg$/,
              use: [
                {
                  loader: "file-loader",
                  options: {
                    name: "assets/[name].[hash:8].[ext]",
                  },
                },
              ],
            },
            {
              test: /\.css$/,
              use: [{ loader: "style-loader" }, { loader: "css-loader" }],
              exclude: /src/,
            },
          ],
        },
      };
      ```
    </Step>
  </Steps>
</Accordion>

## TypeScript Configuration

<Accordion title="Configure TypeScript">
  Update your `tsconfig.json` or `tsconfig.app.json`:

  ```json theme={null}
  {
    "compilerOptions": {
      "allowSyntheticDefaultImports": true,
      "skipLibCheck": true
    }
  }
  ```
</Accordion>

## Implementation

<Tabs>
  <Tab title="Component Setup">
    ```typescript app.component.ts theme={null}
    @Component({
      selector: 'app-root',
      templateUrl: './app.component.html'
    })
    export class AppComponent implements OnInit {
      async ngOnInit() {
        await this.initializeOneSDK();
      }

      private async initializeOneSDK() {
        const session = await this.getSessionToken();
        const oneSdk = await this.setupSDK(session);
        await this.configureSDK(oneSdk);
      }

      private async getSessionToken() {
        const config = {
          CUSTOMER_ID: '',
          CUSTOMER_CHILD_ID: '',
          API_KEY: ''
        };

        const response = await fetch(
          "https://backend.latest.frankiefinancial.io/auth/v2/machine-session",
          {
            method: "POST",
            headers: {
              authorization: "machine " + btoa([
                config.CUSTOMER_ID,
                config.CUSTOMER_CHILD_ID,
                config.API_KEY
              ].filter(Boolean).join(":")),
              "Content-Type": "application/json"
            },
            body: JSON.stringify({
              permissions: {
                preset: "one-sdk",
                reference: `demo-${new Date().toISOString()}`
              }
            })
          }
        );

        return response.json();
      }

      private async setupSDK(session: any) {
        return await OneSDK({
          session,
          recipe: {
            form: {
              provider: {
                name: 'react',
                googleApiKey: "YOUR_GOOGLE_API_KEY"
              },
            }
          }
        });
      }

      private async configureSDK(oneSdk: any) {
        // Setup event logging
        oneSdk.on('*', console.log);

        // Initialize individual flow
        const individual = oneSdk.individual();
        await this.setupConsent(individual);

        // Configure IDV flow
        await this.setupIDVFlow(oneSdk);
      }

      private async setupConsent(individual: any) {
        individual.addConsent("general");
        individual.addConsent("docs");
        individual.addConsent("creditheader");
        await individual.submit();
      }

      private async setupIDVFlow(oneSdk: any) {
        const component = oneSdk.component as unknown as (arg0: any, arg1?: any) => any;
        const flow = oneSdk.flow as unknown as (arg0: any) => any;

        const idv = flow("idv");
        const loading1 = component("form", {
          name: "LOADING",
          title: { label: "Loading..." },
          descriptions: [{ label: "" }]
        });

        const loading2 = component("form", {
          name: "LOADING",
          title: { label: "Processing results..." },
          descriptions: [{
            label: "Hold tight, this can take up to 30 seconds. Please don't refresh this page."
          }]
        });

        const review = component("form", {
          name: "REVIEW",
          type: "ocr"
        });

        this.setupIDVEventHandlers(idv, loading1, loading2, review);
        idv.mount("#e2e-idv-container");
      }

      private setupIDVEventHandlers(idv: any, loading1: any, loading2: any, review: any) {
        let before = true;

        idv.on("loading", (display: boolean) => {
          if (display && before) {
            loading1.mount("#e2e-idv-loading1");
          } else if (before) {
            loading1.unmount();
            before = false;
          }
        });

        idv.on("results", async ({ checkStatus }: { checkStatus: boolean }) => {
          if (checkStatus) {
            loading2.unmount();
            review.mount("#e2e-idv-container");
          }
        });

        idv.on("detection_complete", () => {
          loading2.mount("#e2e-idv-loading2");
        });

        // Error handling
        idv.on("error", ({ message, payload }: { message: string, payload: any }) => {
          console.error("IDV Error:", message, payload);
        });
      }
    }
    ```
  </Tab>

  <Tab title="Template Setup">
    ```html app.component.html theme={null}
    <div class="idv-container">
      <div id="e2e-idv-container" class="main-container"></div>
      <div id="e2e-idv-loading1" class="loading-container"></div>
      <div id="e2e-idv-loading2" class="loading-container"></div>
    </div>
    ```

    ```css app.component.css theme={null}
    .idv-container {
      display: flex;
      flex-direction: column;
    }

    .main-container {
      min-width: 100vh;
      height: 85vh;
    }

    .loading-container {
      width: 100%;
      min-height: 200px;
    }
    ```
  </Tab>
</Tabs>

## Running the Application

<Steps>
  <Step title="Start Development Server">
    ```shell theme={null}
    npm run start
    ```
  </Step>

  <Step title="Access Application">
    Open your browser and navigate to `http://localhost:4200`
  </Step>
</Steps>

<Callout icon="bell">
  ##### Security Note

  Never store API keys or credentials in your frontend code. Use environment
  variables and a secure backend service to handle authentication.
</Callout>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Common Issues">
    * **Webpack Configuration Errors**: Ensure all loaders are properly configured in webpack.config.js
    * **TypeScript Errors**: Verify tsconfig.json settings, especially `allowSyntheticDefaultImports`
    * **Component Mounting Issues**: Check if container IDs match in both component and template files
  </Accordion>

  <Accordion title="Best Practices">
    * Use environment variables for API keys and endpoints
    * Implement proper error handling for API calls
    * Follow Angular's lifecycle hooks for initialization
    * Implement proper cleanup in ngOnDestroy
  </Accordion>
</AccordionGroup>

<Card title="Need Help?" icon="circle-question">
  If you encounter issues, check our [sample code
  repository <Icon icon="arrow-up-right-from-square" />](https://github.com/frankieone/frontend-onesdk-public-sample-codes)
  or reach out to our support team.
</Card>


# Audit Report tab
Source: https://docs.frankieone.com/docs/audit-report



It provides a convenient way to review steps and event details and copy request IDs for further evaluation. The steps are shown chronologically, with the latest event on top and the earliest at the bottom. From this tab, you can generate and download the audit report.

<Frame>
  <img alt="" />
</Frame>

## Audit logs

### Entity events

| Audit events              | Description                                                                                                                       | Sample                           |
| :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------- | :------------------------------- |
| Entity creation           | Logs the creation of a new entity within the system                                                                               | **John Doe created this entity** |
| Entity updates            | Logs when changes are made to an existing entity                                                                                  | **John Doe updated this entity** |
| Assign users to an entity | Logs the event when a user is assigned to an entity.                                                                              | **Service profile was updated**  |
| Archive an entity         | Logs the archiving of an entity, which marks an entity as archived. Removing it from active usage but retaining it in the system. | **Service profile was updated**  |

### Workflow events

| Audit events                                    | Description                                                                                                                     | Sample                                                        |
| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------ |
| Workflow initiation                             | Logs the initiation or start of a new workflow. This event captures the workflow details when it's first launched or triggered. | **John Doe initiated Safe Harbour**                           |
| Workflow status has been updated to a new value | Logs any automatic or system-driven changes in the workflow's status                                                            | **The status of Safe Harbour changed from UNCHECKED to PASS** |
| Workflow completion                             | Logs the end of the workflow process and show the final status of the workflow event                                            | **Safe Harbour completed**                                    |
| The user manually changed the workflow status   | Logs changes made directly by a user, as opposed to automatic or system-driven updates                                          | **John Doe changed the status of Safe Harbour**               |

#### Workflow events: KYC database check

| Audit events                                   | Description                                                                                                                                                                    | Sample                                                                                                                    |
| :--------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |
| The KYC process has started                    | Logs the start of the KYC process.                                                                                                                                             | **KYC was initiated**<br />Workflow: Safe Harbour <br />Data connector: dvs                                               |
| KYC database check resulted in matched results | Logs when the system finds results that match the customer’s details. This indicates that the customer's details have been verified against the connector.                     | **KYC database check was successful, resulting in 3 matches found**<br />Workflow: Safe Harbour <br />Data connector: dvs |
| KYC database check resulted in partial matches | Logs when the system finds results have partially matched the customer’s details. This indicates that some of the customer's details have been verified against the connector. | **KYC database check failed because partial matches were found**<br />Workflow: Safe Harbour <br />Data connector: dvs    |
| KYC database check resulted in no matches      | Logs when the system finds no results that match the customer’s details. This indicates that none of the customer's details have been verified against the connector.          | **KYC database check failed because no matches were found**<br />Workflow: Safe Harbour <br />Data connector: dvs         |

#### Risk events

| Audit events     | Description                                                | Sample                                                                         |
| :--------------- | :--------------------------------------------------------- | :----------------------------------------------------------------------------- |
| Risk has changed | Logs adjustments to the risk score during risk assessment. | **Risk status changed to low**<br />Workflow: Safe Harbour <br />Risk score: 6 |

### Connector events

| Audit events                                     | Description                                                                                                                                                                                                      | Sample                                                                                 |
| :----------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |
| The connector returned with a "success" response | Logs the successful transmission of data from the system to a connector and receipt of a response. This indicates that the data was sent correctly and a reply was received from the external system or service. | **Connector request successfully sent to the service provider. Response received.**    |
| Unable to send the request to a connector        | Logs a failure to send data to a connector due to a connection error. This indicates that the data transmission attempt encountered issues such as network problems or unreachable endpoints.                    | **The connector failed to send the request to the service provider. Connector errors** |

## Generate an audit report

To generate and download an audit report, select the **Generate report** button to generate and download a PDF version of the audit report.

<Frame>
  <img alt="" />
</Frame>

<Frame>
  <img alt="" />
</Frame>

<Frame>
  <img alt="" />
</Frame>


# Biometrics
Source: https://docs.frankieone.com/docs/biometrics



Biometric verification uniquely identifies individuals by evaluating one or more distinguishing biological traits.

You can have biometrics checked as part of your workflow and trigger biometrics via three channels:

1. **API Biometrics**: In your onboarding flow you can trigger Biometrics
2. **OneSDK Biometrics**: Using our OneSDK you can enable Biometrics checks
3. **Portal Biometrics**: In our Portal you can manually trigger Biometrics

## Portal Biometrics

<Callout icon="thumbtack">
  ##### Note on Biometrics

  Send Link is valid for a configurable time, generally set to 24 hrs.

  There is a limited amount of text possible in the text message, up to 24 characters.
</Callout>

At the top right of the workflow events tab, select the **Send link** icon located between the **Assignee** and three-dot "**...**" icon to send a workflow link to an entity.

<Frame>
  <img alt="" />
</Frame>

This will open the **Send link via SMS** modal where you can set the workflow to send, the mobile number of the applicant, and any comment you want to add to the audit event associated with sending the link (this comment isn't sent to the customers).

The mobile number will be auto-populated if the entity has a mobile number.

<Frame>
  <img alt="" />
</Frame>

From this modal, select either **Biometrics/OCR** or **OCR only** from the **Workflow to send** drop-down menu.

<Frame>
  <img alt="" />
</Frame>

### Retries

<Frame>
  <img alt="" />
</Frame>

When an entity has either failed a document or biometrics check, the system recommends you send a link again.

Optionally, you can opt to [manually override the check results](/docs/manually-overriding-biometricsocr-results).


# Blocklist Overview
Source: https://docs.frankieone.com/docs/blocklists-overview

Blocklists are lists of customer profiles or individual attributes such as mailing address, email or phone number that have been identified by you or your organisation as being fraudulent.

### Video Guide

<iframe />

## What’s an internal blocklist?

This is a list of customer profiles or individual attributes such as mailing address, email or phone number that have been identified by you or your organisation as being fraudulent. Once a profile is added to your internal blocklist, new potential customers with matching information will be blocked from future attempts to onboard and open an account.

### How’s this different to a Sanctions List?

Sanctions lists are external lists created by governments and international authorities of known sanctioned individuals or businesses around the world. Sanctions checks are performed as part of the PEP/Sanctions check and the results of this check are found in the PEP/Sanctions tab. New potential customer’s details are checked against pre-defined lists as set up in your initial configuration

### How’s this different to a watchlist?

The internal watchlist allows you to ‘flag’ or mark a customer/profile in your system as Watchlisted.

This adds an extra risk factor to the customer’s risk score. The result of this will move the customer into a higher risk bracket, and therefore further checks may need to be run when changes are made to the customer’s profile.

### What types of profiles and attributes can be added to the blocklist?

An entire profile or individual attributes such as an address, ID document, email address, or phone number can be added to the internal blocklist.  With the Internal Blocklist check configured as part of an entity profile, Frankie will check each incoming applicant’s details to see if they’re a potential match with any of the blocklisted profiles or attributes.

Once a profile or individual attribute has been added to your internal blocklist, it will be visible on the manage blocklist page.

* **Entire Profile** - This is a full customer profile which has been entered into the system either manually or via API. This profile will most likely already have checks run against it, either passed or failed.

* **Individual Blocklisted Attribute** - An individual blocklisted attribute may be added to the blocklist. These attributes are visible on the manage blocklist page only. The only check that will ever be shown against a blocklisted individual attribute is the Blocklist Search which is run each time an individual attribute is saved to the blocklist to check if any profiles already in the system match the newly saved blocklisted attribute.

## What are blocklisted entities?

### Video Guide

<iframe />

These are entities that matched against an internal blocklist. The system can automatically reject the application, thereby preventing potential fraud.

<img alt="" />

Blocklisted entities will have badge indicator.

### Restrictions

No actions are allowed to be performed against any Blocklisted entities e.g.

* Not allowed to be edited (Edit profile)

* Not allowed to be run against a workflow

## Who can manage Blocklist (Permissions)

<img alt="" />

By default, Admins and Operators are able to manage the Blocklist. Being able to manage blocklist means.

* Create blocklist entries

* Add an existing to a blocklist

* Remove an existing from a blocklist

* Resolving any blocklist issue


# Bulk actions
Source: https://docs.frankieone.com/docs/bulk-actions



### Video Guide

<iframe />

Selecting entities allows you to perform bulk actions. Select "..." to see the actions allowed.

<img alt="" />

## Bulk actions

Bulk actions are limited to 100 entities at a time.

### Assignment

Easily identify and manage unallocated resources or tasks by bulk assigning entities. Select **Assign selected** from the actions dropdown to open the **Assign selected entities** menu. From this menu, select the user you want to assign your selected entities.

<img alt="" />

Optionally, add a comment for other portal users regarding this action.

Afterwards, select **Assign entities**. The new assignments will appear under the **Assignee** column on the **Entities** page.


# Change a Entity's workflow
Source: https://docs.frankieone.com/docs/change-entity-workflow

A workflow allows you to change the combination of checks that are performed on a entity.

A workflow allows you to change the combination of checks that are performed on a customer at any given time in the customer's lifecycle.

**To change the ‘workflow’ via the Portal.**

1. Open the entity profile.
2. Select **Edit profile** from the profile menu.

<Frame>
  <img />
</Frame>

3. In the **Edit entity details** page, select the preferred workflow from the **Workflow** dropdown menu.

<Frame>
  <img />
</Frame>

4. Select **Save & Verify** to run the new workflow.

<Frame>
  <img />
</Frame>


# Changing and Re-running a Workflow
Source: https://docs.frankieone.com/docs/changing-and-re-running-workflow



### Video Guide

<iframe />

## Change an entity's workflow

You might need a different set of checks after new information arrives—for example, moving from a **Safe Harbour** workflow to an **Enhanced Due Diligence** workflow.

1. Open the entity.
2. Click the **⋯** menu and choose **Edit profile**.
3. In **Edit entity details**, pick a new **Workflow** from the drop-down.
4. Click **Save & Verify**.
   The Portal saves the change and immediately runs the new workflow on the existing data.

## Run a workflow manually

Sometimes you only need to re-run the current workflow (for example, after correcting a name or adding a document).

1. Open the entity.
2. Press **Save & Verify** (top-right).
   *If Save & Verify is greyed out, make a small edit — such as adding a comment — to enable it.*
3. A fresh **event** appears in the Workflow events tab with status **Unchecked**, then updates to Pass/Fail as checks finish.

You can repeat these manual runs as often as needed; each run is listed as Attempt #2, Attempt #3, and so on in the event history.


# Configuring SSO with the FrankieOne Portal
Source: https://docs.frankieone.com/docs/configuring-sso-with-the-frankieone-portal



Single sign-on is an authentication scheme that allows a user to log in with a single ID and password to any of several related, yet independent, software systems. True single sign-on allows the user to log in once and access services without re-entering authentication factors. Currently Frankie One’s portal only supports the SAML standard of integration.

<Callout icon="thumbtack">
  ##### Note on SAML

  SAML (Security Assertion Mark-up Language) is an umbrella standard that covers federation, identity management and single sign-on (SSO).
</Callout>

## Getting Started with SAML

The portal admin pages for configuring SSO are currently under development and for that reason email communication is required to finish the setup. This guide will use OKTA, a popular IdP service, as part of the guide for each step, but any other service compliant with the SAML standard will integrate successfully.

**Concepts**

* SP - Service Provider; in our context, this is always Frankie One’s portal
* IdP - Identity Provider; Okta, Azure AD, Google, OneLogin and any other identity service
* Metadata - XML files containing details on how to integrate to both SP and IdP

The configuration needs to be done both on the SP side and on the IdP side. We will take care of configuring the SP and will generate the SP XML metadata, which is sent over to you by email or any other preferred means of communication.

<Note>
  Although the Portal has moved to `https://portal.frankie.one`, the SSO endpoints (ACS and logout URLs) in the SP metadata intentionally remain on the legacy `*.frankiefinancial.io` domain. Use the URLs exactly as provided in the metadata, and do not update an existing IdP configuration unless FrankieOne asks you to.
</Note>

<Info>
  ##### IDP Initiated Authentication Only

  The FrankieOne Portal only supports IDP initiated SSO authentication at the moment. Please have that in mind while following this Guide and setting up your SAML based SSO setup.
</Info>

With the SP XML metadata file in hands, you’ll need to configure the IdP service. Depending on your IdP, there are two ways to do that, by file upload (1) and by manually entering details (2). Okta uses the latter.

1. Upload the SP metadata file, from where all required information will be automatically extracted
2. Manually insert the following details, which can be found in the SP XML metadata file (see image below)

* **Assertion Consumer Service (ACS)**, sometimes also called Login URL
* **SingleLogoutService** sometimes also called Logout URL
* Entity ID/Audience URL
* Name ID format, always use “Email Address” for Frankie One
* x.509 Certificate.

<img alt="" />

For both methods above, you will also be required to add extra attributes when configuring your IdP. The following extra attributes are stricly required on your IdP configuration:

1. **email**: User’s unique email (must not be repeated for different users of the portal in the same environment: uat, demo, production and others)
2. **fullName**: User’s complete name as to be displayed in portal
3. **roles**: List of role names, exactly as displayed on Portal’s User configuration page (case sensitive). Depending on your IdP, it might be a list of string values or a single comma separated string value (no spaces). Okta accept both formats. These roles are case sensitive, so make sure they're spelt perfectly. As of 27 Oct 2021 system Roles defined are:\
   a. Administrator\
   b. Operator\
   c. Compliance officer

Missing the required attributes unique email, fullName and a list of existing roles will result in a failed integration, so make sure they're valid and correct

<Check>
  ##### Note on IdP

  After configuring your IdP, you’ll be provided by IdP with the IdP XML Metadata. **Please download it and email it to [help@frankieone.com <Icon icon="arrow-up-right-from-square" />](mailto:help@frankieone.com)**.
  Please ensure you mention what Domain the SAML is being configured for and which environment you'd like this provisioned in.
</Check>

## Frequently Asked Questions / Errors Shown for SSO;

1. Error shown is "duplicate key error constraint". - This email is in use elsewhere (could be in use on the child account or in a different entity entirely.
2. Error shown is "you don't have permission" – The user is being sent without roles correctly passed through (typo/not at all). This could be a mistake, or intentional for unauthorized users (in which case a user is still created in Frankie).
3. Error shown is "Excessive users in the portal" – Unintended SSO users are being shown the link to Frankie, attempting the creation will still make the account just without roles (See #2)
4. Error shown is “certificate error” - If you have updated your meta data, you need to provide the same to Frankie so that they can update it at their end which should solve the issue.
5. How do I delete a user? - Deletion of users must be done in the portal for now.
6. Can I have multiple SSO providers? - You can have multiple SSO products/providers pointed to the same account (for example, Parent).
7. Can I have separate SSO? - We can have also have separate SSO for parent/child accounts
8. How can I initialise an authentication? - The SSO product must initialise the authentication. (for example, someone can't go to Frankie, try to sign in and be redirected to an external SSO service).
9. How do I setup an SSO? - Setup is currently a manual process, for example, raise a ticket in Jira.
10. How to setup roles with SSO? - You can set up a new role in FrankieOne portal and give permissions as per the requirement. Once done, kindly give the user same role in your IdP (make sure it's spelled correctly). Now when the user logs in, they will have the permissions as per the new assigned role.
11. Can one email address be used for multiple/different accounts to login using SSO? - No, the email address must be unique for each account.
12. What do I do if a user’s email address changes? - You can update the email address in the IdP for that user. No changes will be required on Frankie side.


# Create new entity
Source: https://docs.frankieone.com/docs/create-a-new-profile-via-the-portal



## Video Guide

<iframe />

The **Create new entity** screen allows you to input a customer’s personal information and run checks.

## To create a New entity via the Portal

Navigate to the Create new entity form by clicking the **+ New Entity** button.

<Frame>
  <img />
</Frame>

### Create manually

Select **Create manually** to enter the entity profile details yourself.

### Send a link

Select **Send a link** to send a link to the customer to complete their own profile.

## Creating manually

### Select a Workflow

Select the **Workflow** you would like to apply to the new entity profile. This will determine the sequence of checks to accomplish a business process (or a part of it) that's run on this customer.

<Frame>
  <img />
</Frame>

### Personal Info

Use the form fields to enter the customer’s personal information. Fields will be optional or required based on the workflow and your FrankieOne configuration.

<Frame>
  <img alt="" />
</Frame>

### Personal Information Fields

|                   |                                                                                                                                                                |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Customer ID**   | *Made up of numbers and or letters and no spacing.*<br /> <br /> Search by Customer ID using the search bar.                                                   |
| **Given Name**    | *The customer’s Given Name as shown on their ID document.*<br /> <br /> Required field for all customer profiles.<br /> <br />\* Also known as **First Name**. |
| **Middle Name**   | *Middle name is an optional field*<br /> <br /> Enter a middle name if it's shown on the customer’s ID document.                                               |
| **Family Name**   | *The customer’s Family Name as shown on their ID document.*<br /> <br /> Also known as **Surname** or **Last Name**                                            |
| **Date of Birth** | - The customer’s Date of Birth                                                                                                                                 |
| **Phone Number**  | - Optional field                                                                                                                                               |
| **Email Address** | *Optional field*<br /> <br /> Must be a valid email address format                                                                                             |

### Residential address

Use the address search field to quickly find an address and populate it into the correct fields.

<Frame>
  <img alt="" />
</Frame>

Or select **Enter address manually** to display the individual address fields.

<Frame>
  <img alt="" />
</Frame>

<Frame>
  <img alt="" />
</Frame>

### Add an ID Document

Click **Add New Document** to add an ID document to a customer profile.

Different **workflows** will have different requirements for the number and type of ID documents required and this will be set up in your FrankieOne configuration.

Drag and drop to **upload a document scan** or browse and select a file from your computer.

<Frame>
  <img alt="" />
</Frame>

<Callout icon="bell">
  ##### Important

  FrankieOne keeps every version of an uploaded document, but only the latest version is available in the Portal and API. This design ensures operators make decisions using the most current evidence and avoids confusion that could occur if outdated files were shown, without their related verification results.

  Building a full historical view that links each document version to its outcome is not supported today.

  If you need to override a decision, always use the latest document, not an older version.
</Callout>

#### Consent

You must obtain **Consent** from your customer as per the **AML/CTF** act to run certain checks. You won't be able to save and verify where consent is required as part of the selected **Workflow.**

<Frame>
  <img alt="" />
</Frame>

### Save & verify

Selecting **Save & verify** will save the changes to the profile and run all of the checks required as per the selected workflow. If checks have been run previously, FrankieOne will decide which, if any, further checks need to be run and which don't need to be run again.

#### Save Changes

Selecting **Save changes** will save changes to the profile and any new information or information that has been changed after checks have already been run will show as **Unchecked**.

If changes were made that don't impact the result of previous checks, these results will remain.

If a new ID document has been added and saved, and a different ID document has previously passed, the original document will remain as passed.

## Send link to create

If you selected **Send a link** when creating a new entity, you will be prompted to enter the customer’s details.

Instead of typing every detail yourself, you can text an onboarding link to the customer.
The customer opens the link, uploads their ID and selfie, and the Portal updates the profile automatically.

<Frame>
  <img alt="" />
</Frame>

### 1. Enter phone number and name

In the **Send link** modal, type the customer’s

* **Phone number** (include country code).
* **Given name** and **Family name** (optional but helps match results).

<Callout icon="thumbtack">
  The phone number becomes the **Customer reference (Cust ref)** for easy searching later.
</Callout>

### 2. Choose the onboarding workflow

Select the **Workflow to send** from the drop-down.
Common options include **Biometrics/OCR** or **OCR only**.

### 3. Click **Next** – Choose Send Link or Copy Link

<Frame>
  <img alt="" />
</Frame>

| Option        | What happens                                           |
| :------------ | :----------------------------------------------------- |
| **Send link** | Sends an SMS immediately.                              |
| **Copy link** | Copies the URL so you can paste it into email or chat. |

If  you select **Copy link**, a notification will appear to confirm the link is copied.

<Frame>
  <img alt="" />
</Frame>

### 4. After you send the link

* The entity is **automatically assigned to you** for easy follow-up.
* The **phone number appears as the Cust ref** in the entity record.
* The profile status shows **Unchecked** until the customer finishes.

A notification will appear to confirm the link is sent.

<Frame>
  <img alt="" />
</Frame>

### Finding an incomplete entity

1. Use the **Search bar** at the top of the Portal page.
2. Select **Customer Ref** from the drop-down.
3. Paste or type the **Cust ref** (customer’s phone number).
4. Press **Enter** to open the profile.

### Resending a link

If the customer’s link expired or they had trouble:

1. Open the entity and go to **Workflow events**.
2. Click the **Send link** icon again.
3. Confirm the phone number (edit if needed) and press **Send**.


# Custom views
Source: https://docs.frankieone.com/docs/custom-views



The FrankieOne Portal provides you with an option to create custom views based on Entities table filters to tailor the data display to specific criteria that are relevant to your tasks or analysis.

### Video Guide

<iframe />

## Features

The FrankieOne Portal custom views let you:

* Create up to five (5) custom views using the Entities table filters to tailor data display to the criteria relevant to your tasks or analysis.
* View all custom views in the menu sidebar.
* Edit custom views to refine results and ensure relevance.
* Delete unused custom views to keep your navigation organized.

<img />

## Create a new custom view

You can see the list of custom views and create new ones from the menu sidebar.

To create a new view, select the plus \[+] icon beside the Custom Views list on the sidebar.

<img />

The **Select filters to create a new custom view** appears. From here you can select the filters to apply to the custom view.

<img />

Select the filters you prefer and click **Apply filters**. This will apply the selected filters and display the results. This won't save the custom view.

To save this set of filters and display the results after, select **Apply filters and save view**.

If you selected to apply the filters without saving it first, the results will be displayed in the Entities table.

You can further refine your view by choosing the appropriate filters from the **Filters** menu.

## Save a custom view

Once you're satisfied with the filter combinations, select the **Save view** button on the right-side of the Entities page. The **Save view** modal will open.

Enter the name of the custom view. Please note that there is a 24-character limit to the names.

<img />

The new custom view will be added to the sidebar.

<img />

## Edit a custom view

You can still refine a custom view.

Select it from the sidebar and edit the filters. Once you're satisfied, select the **Save view** menu. From there, select to either **save the changes**, or **save the refine filter selection as a new view**.

<img />

## Delete a custom view

To delete a custom view, select it from the sidebar. Then, select **Delete view** from the 3-dot menu on the right-side of the view.

<img />

Select the **Yes, I'm sure** button if you're certain about deleting the view. Otherwise, select **No, cancel**.

<img />


# Entity - Individuals (KYC)
Source: https://docs.frankieone.com/docs/customer-profiles-individuals-kyc

KYC means Know Your Customer and sometimes Know Your Client.

Know Your Customer (KYC) is the practice of confirming a customer’s identity when an account is created and at scheduled review points.

An entity profile stores the person’s details and every verification check completed for that customer.


# Analytics
Source: https://docs.frankieone.com/docs/dashboard

The FrankieOne Analytics page allows you to quickly see an overview of your Pass/Fail rates and where issues might be occurring.

The dashboard is organized into tabs. The tabs available to you depend on your FrankieOne product configuration.

| Tab                                     | What it shows                                                                                                 |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| [Individual](#individual-tab)           | Pass rates and primary fail reasons for individual KYC checks                                                 |
| [Organisation](#organisation-tab)       | Focus organizations, discovered organizations, and discovered individuals                                     |
| [OneSDK](#onesdk-tab)                   | Customer drop-out rates, time to complete, and primary fail reasons for OneSDK flows                          |
| [AML](#aml-tab)                         | AML screening outcomes, match dispositions, and changes over time                                             |
| [Activity](#activity-tab)               | Alert volumes, resolution times, and monitoring effectiveness metrics for Transaction and Activity Monitoring |
| [Risk](#risk-tab)                       | Entity risk levels, contributing factors, and assessment history                                              |
| [Data Dictionary](#data-dictionary-tab) | Definitions of the metrics and terms used across all analytics tabs                                           |

The following section covers essential information for navigating the Analytics tab and examining data at both individual and organizational levels. You will learn how to leverage OneSDK, interpret the data dictionary, and apply filters for a customized data view.

## Log into your portal and navigate to the analytics tab

<Frame>
  <img alt="" />
</Frame>

Log in to the FrankieOne Portal and select **Analytics** from the main navigation.

## Set the view options

At the top of the Analytics page, you can set the following view options:

| Option                         | Description                                                                          |
| ------------------------------ | ------------------------------------------------------------------------------------ |
| Final Transaction Timestamp TZ | Sets the period or date range to display.                                            |
| Recipe                         | Lists all recipe types for the selected period. Select the ones you want to display. |
| Account                        | Lists the accounts and sub-accounts you have access to. Select the ones to view.     |
| Timezone                       | Lists the available time zones to display data in.                                   |

To save your filter settings, select **Save view**, enter a name for the view, and optionally select **Make view available to everyone with access to this Liveboard**.

<Frame>
  <img alt="" />
</Frame>

<Frame>
  <img alt="" />
</Frame>

Your saved views are accessible from the **Save view** menu on your next visit. From the same menu you can manage saved views — rename or delete them, or reset the Liveboard to the default view.

## Individual tab

<Frame>
  <img alt="" />
</Frame>

The **Individual** tab shows pass rates and primary fail reasons for your customers.

Visuals on this tab are filtered on individuals only, using the Latest Entity Data Asset. Government ID checks also use the ID Checks Data Asset as a secondary data asset.

<Callout icon="thumbtack">
  All data set timestamps are in UTC. The Portal's Entities tab displays time in your local browser time zone.
</Callout>

## Organisation tab

<Callout icon="thumbtack">
  If you are a KYB primary customer you can request a KYB Standard Dashboard via the [jira support system](https://frankieone.atlassian.net/servicedesk/customer/portal/3) or send an email through [help@frankieone.com ](mailto:help@frankieone.com)<Icon icon="arrow-up-right-from-square" />
</Callout>

Navigate to the **Organisation** tab in the standard dashboard.

<Frame>
  <img alt="" />
</Frame>

The **Organisation** tab displays information on your focus organizations, discovered organizations, and discovered individuals.

Visuals are filtered using the Latest Entity Data Asset and the KYB transactional billing data as a secondary data asset.

## OneSDK tab

If you use our OneSDK, review this tab for information on customer drop-out rates, time to complete, and primary fail reasons.

## AML tab

The **AML** tab shows the results of AML screening for your customers — including PEP, sanctions, adverse media, and watchlist checks. Use this tab to monitor screening performance, manage your open hit queue, and track how your high-risk population changes over time.

The tab includes four KPI tiles showing your current AML pass rate, entities needing attention, weekly hit rate, and screening volume — alongside charts covering STP pass rate over time, disposition summary, high-risk population trend, weekly hit counts by type, and false and true positive rates.

## Activity tab

The **Activity** tab provides operational metrics for Transaction and Activity Monitoring (TM). Use this tab to monitor alert volumes, review resolution performance, and assess the effectiveness of your monitoring rules over time.

For a full description of the available metrics and filters, see [Analytics dashboard — Transaction and Activity Monitoring](/v2/docs/tm/features-analytics).

## Risk tab

The **Risk** tab provides a view of the current risk state of your customer population. It includes four charts:

* **Risk level distribution** — a breakdown of your entities by current risk level (Low, Medium, High, and Unacceptable), with KPI tiles showing counts and week-on-week comparisons.
* **Top contributing risk factors** — the factors driving the most risk across your entities, ranked by total effective factor score and segmented by risk level.
* **Assessment history timeline** — average risk scores per month across your entity population, segmented by risk level, showing how your overall risk profile has changed over time.
* **Risk level changes over time** — a monthly view of how many entities moved between risk levels between assessments, broken down by transition direction.

## Data dictionary tab

The **Data Dictionary** tab defines the metrics and terms used across all analytics tabs. Refer to this tab to understand how values are calculated and what each field represents.

<Frame>
  <img />
</Frame>

***

## Common dashboard actions

### Filter data according to your selection

To filter the data presented and only display a specific type of information, select that information type on the graph, open its context menu, and select **Filter**.

<Frame>
  <img />
</Frame>

The graph will be updated and will only display the information filtered.

<Frame>
  <img />
</Frame>

To remove the filter, select the information presented, open its context menu and select **Remove filter**.

<Frame>
  <img />
</Frame>

### Drill down and show underlying data

Embedded analytics allows you to drill down and view underlying data. You can use filters to filter across the visuals, providing you with a more customized view of your data.

<Frame>
  <img />
</Frame>

<Frame>
  <img alt="" />
</Frame>

This will open the **Show underlying data** modal where the underlying data is presented in a table.

<Frame>
  <img />
</Frame>

Select **Edit columns** to add or remove the columns displayed.

<Frame>
  <img alt="" />
</Frame>

The **Edit columns** modal opens and lists all the possible columns to display. Select your preferred columns.

<Frame>
  <img />
</Frame>

You can use the search functionality to locate the column you want to be displayed.

<Frame>
  <img />
</Frame>

Select the **Download CSV** link to download the data as a **.csv** file.

<Frame>
  <img alt="" />
</Frame>

### Drill down on data for further information

You can further investigate the data for a particular status by opening the context menu for the data you want to investigate and selecting **Drill down**.

For example, drill down on the **Failed** data and select **Primary Fail Reason**.

<Frame>
  <img />
</Frame>

In the example above, the primary fail reason is Partial KYC (a potential partial match in 1 data source; however, it's not enough for the required KYC ruleset, which may require 2 data sources to be matched) and a full KYC fail (no match at all). Refer to the image below.

<Frame>
  <img />
</Frame>

### Change the time series

To change the time series on a visual, select the time series selection menu at the bottom of the graph and select **Time Bucket**.

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

After you make a selection, the visual will be updated to reflect the new time series.

### Filter data by date

To display data for specific dates, select the time series selection menu and select **Filter**.

<Frame>
  <img alt="" />
</Frame>

This opens the **Select value** modal.

<Frame>
  <img />
</Frame>

Select whether the time series will be **Rolling** (relative to a period of time) or **Fixed** (based on specific period of time, or dates).

#### Specific date sample

You want to display the data for a specific date, such as 11-Nov-2024. To do so:

1. Open the **Select value** modal.
2. Select **Fixed**.
3. On the dropdown selection menus, select **On (=)**.
4. Select the date from the date selection menu.
5. Select **Apply**.

Refer to the image below.

<Frame>
  <img />
</Frame>

The filter will be applied and the visual will be updated. From this filtered view, you can further drill down or show underlying data.

## Additional features

In addition to the actions mentioned above, you can use additional features to fully exploit the capabilities of the Analytics page.

<Frame>
  <img />
</Frame>

### Generate highlights

Select **AI Highlights** to generate AI-powered highlights from the data. Select **View** to open the highlights and select any item to see more detail.

<Frame>
  <img />
</Frame>

Once the AI finishes generating the highlights, select **View**. The AI Highlights modal opens with the highlights.

<Frame>
  <img />
</Frame>

Review the highlights. Select any of the items to see more details.

<Frame>
  <img alt="" />
</Frame>

### Share the Liveboard

<Callout icon="thumbtack">
  Liveboard sharing is a premium feature. Email [thoughtspot@frankieone.com ](mailto:thoughtspot@frankieone.com)<Icon icon="arrow-up-right-from-square" /> if you're interested in registering for our premium offering.
</Callout>

Select **Share** to share the current dashboard with others.

<Frame>
  <img alt="" />
</Frame>

To share a link, add the recipients and an optional message or simply scroll to the bottom of the **Share** modal then select  **copy link**.

<Frame>
  <img alt="" />
</Frame>

### Save favorites

Select the star icon to add the current dashboard to your favorites. Select it again to remove it.

### Additional actions

Select the action menu (three dots icon) to access additional capabilities for the Analytics page.

<Frame>
  <img />
</Frame>

## Key considerations

* All data set timestamps are in UTC. The Portal's Entities tab displays time in your local browser time zone.
* The Individual tab uses the Latest Entity Data Asset, filtered on individuals only. Government ID checks use the ID Checks Data Asset as a secondary data asset.
* The Organization tab uses the Latest Entity Data Asset, filtered on Focus Organizations, Discovered Organizations, and Discovered Individuals. KYB transactional billing data is used as a secondary data asset.
* The Generate report capability is available for both the Individual and Organization tabs. Transaction and customer record extracts are available for download.

<Frame>
  <img />
</Frame>


# Document Upload
Source: https://docs.frankieone.com/docs/embedded-flows/doc-upload

File-based document collection using upload screens — supports required, partial, and optional document types with review.

## Overview

The Document Upload flow allows users to submit identity documents by uploading files instead of capturing them with a camera. Users progress through three upload stages — required documents, partial documents (pick at least N from a group), and optional documents — then review their uploads before submission. This flow is useful for desktop-first applications, pre-scanned documents, or when camera access is unavailable.

**Modules used:** [`form`](/docs/sdk-reference/form-module) (WELCOME, CONSENT, REQUIRED\_DOCUMENT\_UPLOAD, PARTIAL\_DOCUMENT\_UPLOAD, OPTIONAL\_DOCUMENT\_UPLOAD, REVIEW, RESULT screens)

<Callout icon="star">
  Instead of building from scratch, fork an existing flow from the [public sample codes](https://github.com/FrankieOne/frontend-onesdk-public-sample-codes/).
</Callout>

<Callout icon="bell">
  **Entity must already exist.** The document upload flow requires the entity used in the session to already exist — created via the [API](/docs/reference), the FrankieOne Portal, or a prior SDK flow. If you need to create the entity on the fly, use the [Individual module](/docs/sdk-reference/individual-module) or an [eKYC form flow](/docs/embedded-flows/ekyc) before starting the document upload.
</Callout>

## Flow Diagram

<Steps>
  <Step title="Welcome Screen">
    Initial greeting and introduction (type `doc_upload`).
  </Step>

  <Step title="Consent Screen">
    Capture user consent for data processing.
  </Step>

  <Step title="Required Document Upload">
    User uploads all mandatory documents.
  </Step>

  <Step title="Partial Document Upload">
    User uploads at least the minimum required number from a group of documents.
  </Step>

  <Step title="Optional Document Upload">
    User can optionally upload additional supporting documents.
  </Step>

  <Step title="Review Screen">
    Uploaded documents displayed for confirmation.
  </Step>

  <Step title="Result">
    Upload success or failure displayed.
  </Step>
</Steps>

## Full Implementation

<Tabs>
  <Tab title="Vanilla HTML/JS">
    ```html theme={null}
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>OneSDK Document Upload</title>
        <script src="https://assets.frankiefinancial.io/one-sdk/v1/oneSdk.umd.js"></script>
        <style>
          body { margin: 0; font-family: sans-serif; background: #fff; }
          #onesdk-container { width: 100%; min-height: 100vh; }
        </style>
      </head>
      <body>
        <div id="onesdk-container"></div>

        <script>
          async function startOneSDK() {
            try {
              // 1. Generate session token (move to your backend in production)
              const tokenResponse = await fetch(
                "https://backend.kycaml.uat.frankiefinancial.io/auth/v2/machine-session",
                {
                  method: "POST",
                  headers: {
                    authorization: "machine " + btoa("<CUSTOMER_ID>:<CUSTOMER_CHILD_ID>:<API_KEY>"),
                    "Content-Type": "application/json",
                  },
                  body: JSON.stringify({
                    permissions: {
                      preset: "one-sdk",
                      reference: "upload-" + Date.now(),
                    },
                  }),
                }
              );
              const session = await tokenResponse.json();

              // 2. Initialize OneSDK with docUpload recipe
              const oneSdk = await OneSDK({
                session: session,
                mode: "development",
                recipe: {
                  form: {
                    provider: { name: "react" },
                    docUpload: {
                      requestedDocuments: [
                        { documentType: "PROOF_OF_ADDRESS" },
                        { documentType: "BANK_STATEMENT" },
                      ],
                      partialDocuments: [
                        {
                          title: "Additional Identity Documents",
                          minimumRequirement: 1,
                          documents: [
                            { documentType: "BIRTH_CERTIFICATE" },
                            { documentType: "UTILITY_BILL" },
                            { documentType: "TAX_RETURN" },
                          ],
                        },
                      ],
                      optionalDocuments: [
                        { documentType: "EMPLOYMENT_LETTER" },
                      ],
                    },
                  },
                },
              });

              const appContainer = document.querySelector("#onesdk-container");

              // 3. Create form components
              const welcome = oneSdk.component("form", {
                name: "WELCOME",
                type: "doc_upload",
              });

              const consent = oneSdk.component("form", {
                name: "CONSENT",
              });

              const requiredDocUpload = oneSdk.component("form", {
                name: "REQUIRED_DOCUMENT_UPLOAD",
              });

              const partialDocUpload = oneSdk.component("form", {
                name: "PARTIAL_DOCUMENT_UPLOAD",
              });

              const optionalDocUpload = oneSdk.component("form", {
                name: "OPTIONAL_DOCUMENT_UPLOAD",
              });

              const reviewDocUpload = oneSdk.component("form", {
                name: "REVIEW",
                type: "doc_upload",
              });

              const success = oneSdk.component("form", {
                name: "RESULT",
                state: "UPLOAD_SUCCESS",
              });

              const fail = oneSdk.component("form", {
                name: "RESULT",
                state: "UPLOAD_FAIL",
              });

              // 4. Wire up form navigation
              welcome.on("form:welcome:ready", () => {
                consent.mount(appContainer);
              });

              consent.on("form:consent:ready", () => {
                requiredDocUpload.mount(appContainer);
              });

              requiredDocUpload.on("form:required_document_upload:ready", () => {
                partialDocUpload.mount(appContainer);
              });

              partialDocUpload.on("form:partial_document_upload:ready", () => {
                optionalDocUpload.mount(appContainer);
              });

              optionalDocUpload.on("form:optional_document_upload:ready", () => {
                reviewDocUpload.mount(appContainer);
              });

              // 5. Handle review results
              reviewDocUpload.on("form:review:ready", () => {
                success.mount(appContainer);
              });

              reviewDocUpload.on("form:review:failed", () => {
                fail.mount(appContainer);
              });

              // 6. Mount the welcome screen to start the flow
              welcome.mount(appContainer);
            } catch (error) {
              console.error("OneSDK initialization failed:", error);
            }
          }

          startOneSDK();
        </script>
      </body>
    </html>
    ```
  </Tab>

  <Tab title="React">
    ```jsx theme={null}
    import { useEffect, useRef } from "react";
    import OneSdk from "@frankieone/one-sdk";

    export default function DocUploadFlow({ session }) {
      const initRef = useRef(false);

      useEffect(() => {
        if (!session || initRef.current) return;
        initRef.current = true;

        (async () => {
          try {
            const oneSdk = await OneSdk({
              session,
              mode: "development",
              recipe: {
                form: {
                  provider: { name: "react" },
                  docUpload: {
                    requestedDocuments: [
                      { documentType: "PROOF_OF_ADDRESS" },
                      { documentType: "BANK_STATEMENT" },
                    ],
                    partialDocuments: [
                      {
                        title: "Additional Identity Documents",
                        minimumRequirement: 1,
                        documents: [
                          { documentType: "BIRTH_CERTIFICATE" },
                          { documentType: "UTILITY_BILL" },
                          { documentType: "TAX_RETURN" },
                        ],
                      },
                    ],
                    optionalDocuments: [
                      { documentType: "EMPLOYMENT_LETTER" },
                    ],
                  },
                },
              },
            });

            const appContainer = document.querySelector("#onesdk-container");

            const welcome = oneSdk.component("form", {
              name: "WELCOME",
              type: "doc_upload",
            });

            const consent = oneSdk.component("form", {
              name: "CONSENT",
            });

            const requiredDocUpload = oneSdk.component("form", {
              name: "REQUIRED_DOCUMENT_UPLOAD",
            });

            const partialDocUpload = oneSdk.component("form", {
              name: "PARTIAL_DOCUMENT_UPLOAD",
            });

            const optionalDocUpload = oneSdk.component("form", {
              name: "OPTIONAL_DOCUMENT_UPLOAD",
            });

            const reviewDocUpload = oneSdk.component("form", {
              name: "REVIEW",
              type: "doc_upload",
            });

            const success = oneSdk.component("form", {
              name: "RESULT",
              state: "UPLOAD_SUCCESS",
            });

            const fail = oneSdk.component("form", {
              name: "RESULT",
              state: "UPLOAD_FAIL",
            });

            welcome.on("form:welcome:ready", () => {
              consent.mount(appContainer);
            });

            consent.on("form:consent:ready", () => {
              requiredDocUpload.mount(appContainer);
            });

            requiredDocUpload.on("form:required_document_upload:ready", () => {
              partialDocUpload.mount(appContainer);
            });

            partialDocUpload.on("form:partial_document_upload:ready", () => {
              optionalDocUpload.mount(appContainer);
            });

            optionalDocUpload.on("form:optional_document_upload:ready", () => {
              reviewDocUpload.mount(appContainer);
            });

            reviewDocUpload.on("form:review:ready", () => {
              success.mount(appContainer);
            });

            reviewDocUpload.on("form:review:failed", () => {
              fail.mount(appContainer);
            });

            welcome.mount(appContainer);
          } catch (error) {
            console.error("OneSDK initialization failed:", error);
          }
        })();
      }, [session]);

      return <div id="onesdk-container" style={{ width: "100%", minHeight: "100vh" }} />;
    }
    ```
  </Tab>
</Tabs>

## Step-by-Step Breakdown

### 1. Initialize the SDK

Pass the session object to [`OneSDK()`](/docs/sdk-reference/sdk-initialization). Include the `form.provider` and `form.docUpload` recipe configuration. The `docUpload` property defines which documents appear at each upload stage.

### 2. Configure the docUpload Recipe

The [`docUpload` recipe](/docs/sdk-reference/form-module/configuration#document-upload-configuration) controls the three upload stages:

```javascript theme={null}
recipe: {
  form: {
    docUpload: {
      requestedDocuments: [
        { documentType: "PROOF_OF_ADDRESS" },
      ],
      partialDocuments: [
        {
          title: "Additional Identity Documents",
          minimumRequirement: 1,
          documents: [
            { documentType: "BIRTH_CERTIFICATE" },
            { documentType: "UTILITY_BILL" },
          ],
        },
      ],
      optionalDocuments: [
        { documentType: "EMPLOYMENT_LETTER" },
      ],
    },
  },
}
```

### 3. Create Upload Screen Components

Create a component for each upload stage using the dedicated screen names:

```javascript theme={null}
const requiredDocUpload = oneSdk.component("form", {
  name: "REQUIRED_DOCUMENT_UPLOAD",
});

const partialDocUpload = oneSdk.component("form", {
  name: "PARTIAL_DOCUMENT_UPLOAD",
});

const optionalDocUpload = oneSdk.component("form", {
  name: "OPTIONAL_DOCUMENT_UPLOAD",
});
```

### 4. Wire Up Events

Use [`.on(event)`](/docs/sdk-reference/events) listeners to navigate through the upload stages. Each stage emits a `form:<screen_name>:ready` event when complete.

### 5. Handle Results

The review screen emits `form:review:ready` on success and `form:review:failed` on failure. Use `UPLOAD_SUCCESS` and `UPLOAD_FAIL` [result states](/docs/sdk-reference/form-module/configuration) for the result screen. See [Error Scenarios](/docs/sdk-reference/error-scenarios) for details.

## Upload Screen Types

The document upload flow uses three distinct screen types, each configured through the [`docUpload` recipe](/docs/sdk-reference/form-module/configuration#document-upload-configuration):

| Screen                     | Recipe Property      | Behavior                                                                 |
| -------------------------- | -------------------- | ------------------------------------------------------------------------ |
| `REQUIRED_DOCUMENT_UPLOAD` | `requestedDocuments` | All listed documents **must** be uploaded                                |
| `PARTIAL_DOCUMENT_UPLOAD`  | `partialDocuments`   | At least `minimumRequirement` documents must be uploaded from each group |
| `OPTIONAL_DOCUMENT_UPLOAD` | `optionalDocuments`  | Documents **may** be uploaded but are not required                       |

## Required vs Optional Documents

Configure the three tiers in the `docUpload` recipe:

```javascript theme={null}
docUpload: {
  // All of these must be uploaded
  requestedDocuments: [
    { documentType: "PROOF_OF_ADDRESS" },
    { documentType: "BANK_STATEMENT" },
  ],
  // At least minimumRequirement from each group
  partialDocuments: [
    {
      title: "Additional Identity Documents",
      minimumRequirement: 1,
      documents: [
        { documentType: "BIRTH_CERTIFICATE" },
        { documentType: "UTILITY_BILL" },
        { documentType: "TAX_RETURN" },
      ],
    },
  ],
  // Completely optional
  optionalDocuments: [
    { documentType: "EMPLOYMENT_LETTER" },
  ],
}
```

See [Document Upload Configuration](/docs/sdk-reference/form-module/configuration#document-upload-configuration) for the full type reference and validation rules.

## Review After Upload

The review screen shows all uploaded documents for confirmation. Use `type: "doc_upload"` to render the upload-specific review UI:

```javascript theme={null}
const reviewDocUpload = oneSdk.component("form", {
  name: "REVIEW",
  type: "doc_upload",
});

reviewDocUpload.on("form:review:ready", () => {
  success.mount(appContainer);
});

reviewDocUpload.on("form:review:failed", () => {
  fail.mount(appContainer);
});
```

Use the `UPLOAD_SUCCESS` and `UPLOAD_FAIL` result states for the outcome screens:

```javascript theme={null}
const success = oneSdk.component("form", {
  name: "RESULT",
  state: "UPLOAD_SUCCESS",
});

const fail = oneSdk.component("form", {
  name: "RESULT",
  state: "UPLOAD_FAIL",
});
```

## Customization Reference

| Aspect                     | Reference                                                                                                    |
| -------------------------- | ------------------------------------------------------------------------------------------------------------ |
| SDK initialization options | [SDK Initialization](/docs/sdk-reference/sdk-initialization)                                                 |
| Form screen configuration  | [Form Module](/docs/sdk-reference/form-module)                                                               |
| Document upload recipe     | [Document Upload Configuration](/docs/sdk-reference/form-module/configuration#document-upload-configuration) |
| Screen names and types     | [Form Screens](/docs/sdk-reference/form-module/screens)                                                      |
| Custom field configuration | [Form Configuration](/docs/sdk-reference/form-module/configuration)                                          |
| Event names and payloads   | [Events](/docs/sdk-reference/events)                                                                         |
| Error handling patterns    | [Error Scenarios](/docs/sdk-reference/error-scenarios)                                                       |


# eKYC Flow
Source: https://docs.frankieone.com/docs/embedded-flows/ekyc

Build a full electronic Know Your Customer journey with manual form entry, document collection, verification, and optional fraud detection.

## Overview

The eKYC flow guides users through a multi-step manual verification journey: welcome, consent, personal details, document entry, review, and result screens. All data is entered via form fields (no camera capture). This flow is ideal when you need full control over each step and want to collect information through a traditional form-based experience.

**Modules used:** [`form`](/docs/sdk-reference/form-module)

<Callout icon="star">
  Instead of building from scratch, fork an existing flow from the [public sample codes](https://github.com/FrankieOne/frontend-onesdk-public-sample-codes/).
</Callout>

## Flow Diagram

<Steps>
  <Step title="Welcome Screen">
    Initial greeting and introduction to the verification process.
  </Step>

  <Step title="Consent Screen">
    Capture user consent for data processing and identity checks.
  </Step>

  <Step title="Personal Details">
    Collect name, date of birth, address, and other personal information.
  </Step>

  <Step title="Document Entry">
    Collect one or more identity document details (e.g., driver's licence, passport).
  </Step>

  <Step title="Review">
    Display all entered information for the user to confirm before submission.
  </Step>

  <Step title="Result">
    Show verification outcome — success, fail, pending, or partial.
  </Step>
</Steps>

<Callout icon="bell">
  This flow requires a **Google Places API key** (`googleApiKey`) in the form provider configuration. The key powers the address autocomplete field in the PERSONAL form screen. Without it, the address search will not work. Get a key from the [Google Cloud Console](https://console.cloud.google.com/apis/credentials) with the Places API enabled.
</Callout>

## Full Implementation

<Tabs>
  <Tab title="Vanilla HTML/JS">
    ```html theme={null}
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>OneSDK eKYC Flow</title>
        <script src="https://assets.frankiefinancial.io/one-sdk/v1/oneSdk.umd.js"></script>
        <style>
          body { margin: 0; font-family: sans-serif; background: #fff; }
          #onesdk-container { width: 100%; min-height: 100vh; }
        </style>
      </head>
      <body>
        <div id="onesdk-container"></div>

        <script>
          async function startOneSDK() {
            try {
              // 1. Generate session token (move to your backend in production)
              const tokenResponse = await fetch(
                "https://backend.kycaml.uat.frankiefinancial.io/auth/v2/machine-session",
                {
                  method: "POST",
                  headers: {
                    authorization: "machine " + btoa("<CUSTOMER_ID>:<CUSTOMER_CHILD_ID>:<API_KEY>"),
                    "Content-Type": "application/json",
                  },
                  body: JSON.stringify({
                    permissions: {
                      preset: "one-sdk",
                      reference: "ekyc-" + Date.now(),
                    },
                  }),
                }
              );
              const session = await tokenResponse.json();

              // 2. Initialize OneSDK
              const oneSdk = await OneSDK({
                session: session,
                mode: "development",
                recipe: {
                  form: {
                    provider: {
                      name: "react",
                      googleApiKey: "<YOUR_GOOGLE_API_KEY>",
                    },
                  },
                },
              });

              const appContainer = "#onesdk-container";

              // 3. Configure form components
              const welcome = oneSdk.component("form", {
                name: "WELCOME",
                type: "manual",
              });

              const consent = oneSdk.component("form", { name: "CONSENT" });

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

              const documentForm = oneSdk.component("form", {
                name: "DOCUMENT",
                type: "manual",
                numberOfIDs: 2,
              });

              const review = oneSdk.component("form", {
                name: "REVIEW",
                type: "manual",
                verify: true,
              });

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

              // 4. Wire up form navigation events
              welcome.mount(appContainer);

              welcome.on("form:welcome:failed", () => {
                console.error("Welcome screen failed to load");
              });

              welcome.on("form:welcome:ready", () => {
                consent.mount(appContainer);
              });

              consent.on("form:consent:ready", () => {
                personal.mount(appContainer);
              });

              personal.on("form:personal:ready", () => {
                documentForm.mount(appContainer);
              });

              documentForm.on("form:document:back", () => {
                personal.mount(appContainer);
              });

              documentForm.on("form:document:ready", () => {
                review.mount(appContainer);
              });

              // 5. Handle result screen CTA presses
              // The review component (verify: true) handles verification and shows
              // result screens automatically. These events fire when the user
              // presses the CTA on the result screen.
              review.on("form:result:success", () => {
                console.log("Verification complete");
              });

              review.on("form:result:failed", () => {
                console.log("Verification failed");
              });

              review.on("form:result:pending", () => {
                console.log("Verification pending");
              });

              // 6. Retry logic
              let retryCount = 0;
              review.on("form:result:partial", () => {
                if (retryCount < 2) {
                  retry.mount(appContainer);
                  retryCount++;
                } else {
                  console.log("Max retries reached");
                }
              });
            } catch (error) {
              console.error("OneSDK initialization failed:", error);
            }
          }

          startOneSDK();
        </script>
      </body>
    </html>
    ```
  </Tab>

  <Tab title="React">
    ```jsx theme={null}
    import { useEffect, useRef } from "react";
    import OneSdk from "@frankieone/one-sdk";

    export default function EKYCFlow({ session }) {
      const initRef = useRef(false);

      useEffect(() => {
        if (!session || initRef.current) return;
        initRef.current = true;

        (async () => {
          try {
            const oneSdk = await OneSdk({
              session,
              mode: "development",
              recipe: {
                form: {
                  provider: {
                    name: "react",
                    googleApiKey: import.meta.env.VITE_GOOGLE_PLACES_API_KEY,
                  },
                },
              },
            });

            const appContainer = "#onesdk-container";

            const welcome = oneSdk.component("form", { name: "WELCOME", type: "manual" });
            const consent = oneSdk.component("form", { name: "CONSENT" });
            const personal = oneSdk.component("form", { name: "PERSONAL", type: "manual" });
            const documentForm = oneSdk.component("form", {
              name: "DOCUMENT",
              type: "manual",
              numberOfIDs: 2,
            });
            const review = oneSdk.component("form", {
              name: "REVIEW",
              type: "manual",
              verify: true,
            });
            const retry = oneSdk.component("form", { name: "RETRY", type: "manual" });

            welcome.mount(appContainer);

            welcome.on("form:welcome:failed", () => {
              console.error("Welcome screen failed to load");
            });

            welcome.on("form:welcome:ready", () => consent.mount(appContainer));
            consent.on("form:consent:ready", () => personal.mount(appContainer));
            personal.on("form:personal:ready", () => documentForm.mount(appContainer));
            documentForm.on("form:document:back", () => personal.mount(appContainer));
            documentForm.on("form:document:ready", () => review.mount(appContainer));

            // Result screen CTA events — review shows result screens automatically
            review.on("form:result:success", () => console.log("Verification complete"));
            review.on("form:result:failed", () => console.log("Verification failed"));
            review.on("form:result:pending", () => console.log("Verification pending"));

            let retryCount = 0;
            review.on("form:result:partial", () => {
              if (retryCount < 2) {
                retry.mount(appContainer);
                retryCount++;
              } else {
                console.log("Max retries reached");
              }
            });
          } catch (error) {
            console.error("OneSDK initialization failed:", error);
          }
        })();
      }, [session]);

      return <div id="onesdk-container" style={{ width: "100%", minHeight: "100vh" }} />;
    }
    ```
  </Tab>
</Tabs>

## Step-by-Step Breakdown

### 1. Initialize the SDK

Pass the session object from your backend to [`OneSDK()`](/docs/sdk-reference/sdk-initialization). Include the `form.provider` recipe to enable React-rendered form components and optional Google Places address autocomplete.

### 2. Configure Form Components

Create form components using [`sdk.component("form", { name, type })`](/docs/sdk-reference/form-module). Each screen (WELCOME, CONSENT, PERSONAL, DOCUMENT, REVIEW, RESULT) is a separate component instance.

### 3. Wire Up Events

Use [`.on(event)`](/docs/sdk-reference/events) listeners to transition between screens. Each form emits a `form:<name>:ready` event when the user completes that step.

### 4. Handle Results

The review form with [`verify: true`](/docs/sdk-reference/form-module/configuration#page-configuration-types) handles verification and shows result screens automatically. `form:result:success`, `form:result:failed`, `form:result:pending`, and `form:result:partial` fire when the user presses the CTA on the corresponding result screen. Use these events for post-flow actions (redirects, analytics, retry logic). If you need to intercept the result before a screen is shown, use [`customResult: true`](/docs/sdk-reference/form-module/configuration#page-configuration-types) — see [Form Screens](/docs/sdk-reference/form-module/screens#review) for details.

## Adding Device Tracking (Fraud Detection)

To add fraud detection via device fingerprinting, initialize the [device component](/docs/sdk-reference/device-module) before mounting the welcome screen:

```javascript theme={null}
const device = oneSdk.component("device", {
  activityType: "REGISTRATION",
});
device.start();

// Then continue with the normal flow...
welcome.mount(appContainer);
```

The device component runs in the background, collecting signals that the FrankieOne platform uses for fraud risk scoring. No additional UI is rendered.

## Retry Logic

The retry mechanism allows users a configurable number of attempts before showing a final failure screen:

```javascript theme={null}
const retry = oneSdk.component("form", {
  name: "RETRY",
  type: "manual",
});

let retryCount = 0;

review.on("form:result:partial", () => {
  if (retryCount < 2) {
    retry.mount(appContainer);
    retryCount++;
  } else {
    console.log("Max retries reached");
  }
});
```

<Info>
  The retry form remounts the review step, giving the user another chance to correct any issues. After the maximum number of attempts, the failure screen is shown.
</Info>

## Customizing ID Documents

Configure which documents are accepted and how many are required:

```javascript theme={null}
const documentForm = oneSdk.component("form", {
  name: "DOCUMENT",
  type: "manual",
  numberOfIDs: 2,
  documents: [
    {
      type: "DRIVERS_LICENCE",
      countries: {
        default: {
          default: {
            fields: [
              {
                fieldType: "select",
                name: "country",
                options: [
                  { label: "Australia", value: "AUS" },
                  { label: "New Zealand", value: "NZL" },
                ],
              },
            ],
          },
        },
      },
    },
    {
      type: "PASSPORT",
      countries: {
        default: {
          default: {
            fields: [
              {
                fieldType: "select",
                name: "country",
                options: [
                  { label: "Australia", value: "AUS" },
                  { label: "New Zealand", value: "NZL" },
                ],
              },
            ],
          },
        },
      },
    },
  ],
});
```

See [Form Module Configuration](/docs/sdk-reference/form-module/configuration) for all available document and field options.

## Customization Reference

| Aspect                     | Reference                                                           |
| -------------------------- | ------------------------------------------------------------------- |
| SDK initialization options | [SDK Initialization](/docs/sdk-reference/sdk-initialization)        |
| Session token generation   | [Session Management](/docs/sdk-reference/session-management)        |
| Form screen configuration  | [Form Module](/docs/sdk-reference/form-module)                      |
| Screen names and types     | [Form Screens](/docs/sdk-reference/form-module/screens)             |
| Custom field configuration | [Form Configuration](/docs/sdk-reference/form-module/configuration) |
| Event names and payloads   | [Events](/docs/sdk-reference/events)                                |
| Error handling patterns    | [Error Scenarios](/docs/sdk-reference/error-scenarios)              |
| Device fraud detection     | [Device Module](/docs/sdk-reference/device-module)                  |


# IDV Flow
Source: https://docs.frankieone.com/docs/embedded-flows/idv

Camera-based identity document verification with automatic capture, processing, and result handling.

## Overview

The IDV (Identity Verification) flow uses camera-based document capture powered by Incode. The SDK handles the entire capture experience — the user points their camera at an ID document and the SDK automatically detects, captures, and processes it. This is the simplest embedded flow to implement.

**Modules used:** [`idv`](/docs/sdk-reference/idv-module), [`form`](/docs/sdk-reference/form-module) (WELCOME, CONSENT, LOADING screens)

<Callout icon="star">
  Instead of building from scratch, fork an existing flow from the [public sample codes](https://github.com/FrankieOne/frontend-onesdk-public-sample-codes/).
</Callout>

## Flow Diagram

<Steps>
  <Step title="Welcome Screen">
    Initial greeting and introduction to the verification process.
  </Step>

  <Step title="Consent Screen">
    Capture user consent for data processing.
  </Step>

  <Step title="IDV Capture">
    The SDK renders camera capture UI for document scanning.
  </Step>

  <Step title="Processing">
    The SDK processes the captured document and runs verification checks.
  </Step>

  <Step title="Result">
    Your application receives the verification result and displays the outcome.
  </Step>
</Steps>

## Full Implementation

<Tabs>
  <Tab title="Vanilla HTML/JS">
    ```html theme={null}
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>OneSDK IDV Flow</title>
        <script src="https://assets.frankiefinancial.io/one-sdk/v1/oneSdk.umd.js"></script>
        <style>
          body { margin: 0; font-family: sans-serif; background: #fff; }
          #onesdk-wrapper { position: relative; width: 100%; height: 100vh; }
          #onesdk-container { width: 100%; height: 100%; }
          #loading-overlay {
            position: absolute; top: 0; left: 0; width: 100%; height: 100%;
            z-index: 10; background: #fff;
          }
        </style>
      </head>
      <body>
        <div id="onesdk-wrapper">
          <div id="onesdk-container"></div>
          <div id="loading-overlay"></div>
        </div>

        <script>
          async function startOneSDK() {
            try {
              // 1. Generate session token (move to your backend in production)
              const tokenResponse = await fetch(
                "https://backend.kycaml.uat.frankiefinancial.io/auth/v2/machine-session",
                {
                  method: "POST",
                  headers: {
                    authorization: "machine " + btoa("<CUSTOMER_ID>:<CUSTOMER_CHILD_ID>:<API_KEY>"),
                    "Content-Type": "application/json",
                  },
                  body: JSON.stringify({
                    permissions: {
                      preset: "one-sdk",
                      reference: "idv-" + Date.now(),
                    },
                  }),
                }
              );
              const session = await tokenResponse.json();

              // 2. Initialize OneSDK
              const oneSdk = await OneSDK({
                session: session,
                mode: "development",
                recipe: {
                  form: {
                    provider: { name: "react" },
                  },
                },
              });

              const appContainer = "#onesdk-container";

              // 3. Create form and IDV components
              const welcome = oneSdk.component("form", {
                name: "WELCOME",
                type: "ocr",
              });

              const consent = oneSdk.component("form", { name: "CONSENT" });

              const idv = oneSdk.flow("idv");

              const idvLoading = oneSdk.component("form", {
                name: "LOADING",
                title: { label: "Loading..." },
                descriptions: [{ label: "" }],
              });

              const processingLoading = oneSdk.component("form", {
                name: "LOADING",
                title: { label: "Processing..." },
                descriptions: [
                  {
                    label: "Please do not refresh this page or click the back button.",
                  },
                ],
              });

              const submitLoading = oneSdk.component("form", {
                name: "LOADING",
                title: { label: "Submitting verification..." },
                descriptions: [
                  {
                    label: "Please do not refresh this page or click the back button.",
                  },
                ],
              });

              // 4. Wire up welcome → consent → IDV
              welcome.on("form:welcome:ready", () => {
                consent.mount(appContainer);
              });

              consent.on("form:consent:ready", () => {
                idvLoading.mount("#loading-overlay");
                idv.mount(appContainer);
              });

              // 5. Handle loading — IDV init and post-capture processing
              let detectionStarted = false;

              idv.on("loading", (isLoading) => {
                if (!detectionStarted && !isLoading) {
                  idvLoading.unmount();
                }
              });

              idv.on("detection_complete", () => {
                detectionStarted = true;
                processingLoading.mount("#loading-overlay");
              });

              // 6. Handle results
              idv.on("results", async ({ checkStatus }) => {
                processingLoading.unmount();
                if (checkStatus) {
                  submitLoading.mount(appContainer);
                  try {
                    await oneSdk.individual().submit({ verify: true });
                    document.getElementById("onesdk-container").innerHTML =
                      "<h2>Verification complete</h2><p>Your identity has been verified.</p>";
                  } catch (err) {
                    console.error("Submission error:", err);
                  }
                }
              });

              // 7. Handle errors
              idv.on("error", ({ message, payload }) => {
                console.error("IDV error:", message, payload);
                document.getElementById("onesdk-container").innerHTML =
                  "<h2>Verification error</h2><p>Please try again.</p>";
              });

              // 8. Mount welcome screen to start
              welcome.mount(appContainer);
            } catch (error) {
              console.error("OneSDK initialization failed:", error);
            }
          }

          startOneSDK();
        </script>
      </body>
    </html>
    ```
  </Tab>

  <Tab title="React">
    ```jsx theme={null}
    import { useEffect, useRef } from "react";
    import OneSdk from "@frankieone/one-sdk";

    export default function IDVFlow({ session }) {
      const initRef = useRef(false);

      useEffect(() => {
        if (!session || initRef.current) return;
        initRef.current = true;

        (async () => {
          try {
            const oneSdk = await OneSdk({
              session,
              mode: "development",
              recipe: {
                form: {
                  provider: { name: "react" },
                },
              },
            });

            const appContainer = "#onesdk-container";

            const welcome = oneSdk.component("form", { name: "WELCOME", type: "ocr" });
            const consent = oneSdk.component("form", { name: "CONSENT" });
            const idv = oneSdk.flow("idv");

            const idvLoading = oneSdk.component("form", {
              name: "LOADING",
              title: { label: "Loading..." },
              descriptions: [{ label: "" }],
            });

            const processingLoading = oneSdk.component("form", {
              name: "LOADING",
              title: { label: "Processing..." },
              descriptions: [
                {
                  label: "Please do not refresh this page or click the back button.",
                },
              ],
            });

            const submitLoading = oneSdk.component("form", {
              name: "LOADING",
              title: { label: "Submitting verification..." },
              descriptions: [
                {
                  label: "Please do not refresh this page or click the back button.",
                },
              ],
            });

            welcome.on("form:welcome:ready", () => consent.mount(appContainer));
            consent.on("form:consent:ready", () => {
              idvLoading.mount("#loading-overlay");
              idv.mount(appContainer);
            });

            let detectionStarted = false;

            idv.on("loading", (isLoading) => {
              if (!detectionStarted && !isLoading) {
                idvLoading.unmount();
              }
            });

            idv.on("detection_complete", () => {
              detectionStarted = true;
              processingLoading.mount("#loading-overlay");
            });

            idv.on("results", async ({ checkStatus }) => {
              processingLoading.unmount();
              if (checkStatus) {
                submitLoading.mount(appContainer);
                try {
                  await oneSdk.individual().submit({ verify: true });
                  document.getElementById("onesdk-container").innerHTML =
                    "<h2>Verification complete</h2>";
                } catch (err) {
                  console.error("Submission error:", err);
                }
              }
            });

            idv.on("error", ({ message }) => {
              console.error("IDV error:", message);
            });

            welcome.mount(appContainer);
          } catch (error) {
            console.error("OneSDK initialization failed:", error);
          }
        })();
      }, [session]);

      return (
        <div id="onesdk-wrapper" style={{ position: "relative", width: "100%", height: "100vh" }}>
          <div id="onesdk-container" style={{ width: "100%", height: "100%" }} />
          <div
            id="loading-overlay"
            style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", zIndex: 10, background: "#fff" }}
          />
        </div>
      );
    }
    ```
  </Tab>
</Tabs>

## Step-by-Step Breakdown

### 1. Initialize the SDK

Pass the session object to [`OneSDK()`](/docs/sdk-reference/sdk-initialization). Include the `recipe.form.provider` configuration since this flow uses [form components](/docs/sdk-reference/form-module) for the WELCOME and CONSENT screens.

### 2. Add Welcome and Consent Screens

Create WELCOME and CONSENT [form components](/docs/sdk-reference/form-module) to collect user consent before starting the IDV capture. Set `type: "ocr"` on the WELCOME screen. Consent must be collected before verification can proceed — without it, submission will fail.

### 3. Create the IDV Flow

Call [`sdk.flow("idv")`](/docs/sdk-reference/idv-module) to create the identity verification flow. This returns a component that manages the entire camera capture experience.

### 4. Wire Up Events

Listen for [events](/docs/sdk-reference/events):

* `form:welcome:ready` on welcome — user completed the welcome screen, mount consent
* `form:consent:ready` on consent — user gave consent, mount the IDV flow
* `loading` on IDV — show/hide loading screen while IDV component initializes (before capture)
* `detection_complete` on IDV — document capture finished, show processing loading screen
* `results` on IDV — processing complete, `checkStatus` indicates success
* `error` on IDV — an error occurred during capture or processing

<Callout icon="bell">
  **Unmount clears the container.** Calling `.unmount()` on a component removes **all content** from the element it was mounted to — not just the component itself. Loading screens in this flow are mounted to a **separate overlay element** (`#loading-overlay`) so that unmounting them does not destroy the IDV component underneath. See the [IDV with Review flow](/docs/embedded-flows/idv-review#loading-screens) for a detailed explanation.
</Callout>

### 5. Handle Results

When `results` fires with `checkStatus: true`, mount a loading screen then call [`sdk.individual().submit({ verify: true })`](/docs/sdk-reference/individual-module) to trigger the verification check. The loading screen prevents a blank screen during the async submission.

## Submitting Verification

After the IDV flow returns results, mount a loading screen then submit for verification:

```javascript theme={null}
idv.on("results", async ({ checkStatus }) => {
  processingLoading.unmount();
  if (checkStatus) {
    submitLoading.mount(appContainer);
    try {
      const result = await oneSdk.individual().submit({ verify: true });
      // Handle verification result
    } catch (error) {
      console.error("Verification submission failed:", error);
    }
  }
});
```

See [Individual Module](/docs/sdk-reference/individual-module) for all submission options.

## Provider Configuration

Configure the IDV provider in the SDK recipe:

```javascript theme={null}
const oneSdk = await OneSDK({
  session: session,
  mode: "production",
  recipe: {
    ocr: {
      provideReviewScreen: false,
      provider: { name: "incode" },
    },
    biometrics: {
      provider: { name: "incode" },
    },
  },
});
```

See [Vendor Customizations](/docs/sdk-reference/vendor-customizations) for all provider options.

## Customization Reference

| Aspect                     | Reference                                                          |
| -------------------------- | ------------------------------------------------------------------ |
| SDK initialization options | [SDK Initialization](/docs/sdk-reference/sdk-initialization)       |
| IDV flow configuration     | [IDV Module](/docs/sdk-reference/idv-module)                       |
| Form screen configuration  | [Form Module](/docs/sdk-reference/form-module)                     |
| Individual submission      | [Individual Module](/docs/sdk-reference/individual-module)         |
| Event names and payloads   | [Events](/docs/sdk-reference/events)                               |
| Error handling patterns    | [Error Scenarios](/docs/sdk-reference/error-scenarios)             |
| Provider configuration     | [Vendor Customizations](/docs/sdk-reference/vendor-customizations) |


# IDV with Review
Source: https://docs.frankieone.com/docs/embedded-flows/idv-review

IDV flow extended with an OCR review screen so users can verify extracted document data before submission.

## Overview

This flow extends the basic IDV flow by adding an OCR review screen after document capture. After the camera captures and processes the document, the extracted data is shown in a review form for the user to confirm or correct before verification is submitted. This is useful when you want users to verify OCR accuracy.

**Modules used:** [`idv`](/docs/sdk-reference/idv-module), [`form`](/docs/sdk-reference/form-module) (WELCOME, CONSENT, REVIEW, LOADING, RESULT screens)

<Callout icon="star">
  Instead of building from scratch, fork an existing flow from the [public sample codes](https://github.com/FrankieOne/frontend-onesdk-public-sample-codes/).
</Callout>

## Flow Diagram

<Steps>
  <Step title="Welcome Screen">
    Initial greeting and introduction to the verification process.
  </Step>

  <Step title="Consent Screen">
    Capture user consent for data processing.
  </Step>

  <Step title="IDV Capture">
    Camera capture UI for document scanning. Document is automatically detected and captured.
  </Step>

  <Step title="Loading / Extraction">
    SDK extracts data from the captured document. A loading screen is shown.
  </Step>

  <Step title="Review Screen">
    Extracted data is displayed in a review form for user confirmation.
  </Step>

  <Step title="Verification Submitted">
    After review confirmation, verification is submitted automatically.
  </Step>

  <Step title="Result">
    Verification outcome is shown.
  </Step>
</Steps>

<Callout icon="bell">
  This flow requires a **Google Places API key** (`googleApiKey`) in the form provider configuration. The key powers the address autocomplete field in the review form. Without it, the address search will not work. Get a key from the [Google Cloud Console](https://console.cloud.google.com/apis/credentials) with the Places API enabled.
</Callout>

## Full Implementation

<Tabs>
  <Tab title="Vanilla HTML/JS">
    ```html theme={null}
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>OneSDK IDV with Review</title>
        <script src="https://assets.frankiefinancial.io/one-sdk/v1/oneSdk.umd.js"></script>
        <style>
          body { margin: 0; font-family: sans-serif; background: #fff; }
          #onesdk-wrapper { position: relative; width: 100%; height: 100vh; }
          #onesdk-container { width: 100%; height: 100%; }
          #loading-overlay {
            position: absolute; top: 0; left: 0; width: 100%; height: 100%;
            z-index: 10; background: #fff;
          }
        </style>
      </head>
      <body>
        <div id="onesdk-wrapper">
          <div id="onesdk-container"></div>
          <div id="loading-overlay"></div>
        </div>

        <script>
          async function startOneSDK() {
            try {
              // 1. Generate session token (move to your backend in production)
              const tokenResponse = await fetch(
                "https://backend.kycaml.uat.frankiefinancial.io/auth/v2/machine-session",
                {
                  method: "POST",
                  headers: {
                    authorization: "machine " + btoa("<CUSTOMER_ID>:<CUSTOMER_CHILD_ID>:<API_KEY>"),
                    "Content-Type": "application/json",
                  },
                  body: JSON.stringify({
                    permissions: {
                      preset: "one-sdk",
                      reference: "idv-review-" + Date.now(),
                    },
                  }),
                }
              );
              const session = await tokenResponse.json();

              // 2. Initialize OneSDK
              const oneSdk = await OneSDK({
                session: session,
                mode: "development",
                recipe: {
                  form: {
                    provider: {
                      name: "react",
                      googleApiKey: "<YOUR_GOOGLE_API_KEY>",
                    },
                  },
                },
              });

              const appContainer = "#onesdk-container";

              // 3. Create form and IDV components
              const welcome = oneSdk.component("form", {
                name: "WELCOME",
                type: "ocr",
              });

              const consent = oneSdk.component("form", { name: "CONSENT" });

              const idv = oneSdk.flow("idv");

              const review = oneSdk.component("form", {
                name: "REVIEW",
                type: "ocr",
              });

              const idvLoading = oneSdk.component("form", {
                name: "LOADING",
                title: { label: "Loading..." },
                descriptions: [{ label: "" }],
              });

              const extractLoading = oneSdk.component("form", {
                name: "LOADING",
                title: { label: "Extracting data..." },
                descriptions: [
                  {
                    label: "Hold tight, this can take up to 30 seconds. Please do not refresh this page or click the back button.",
                  },
                ],
              });

              const submitLoading = oneSdk.component("form", {
                name: "LOADING",
                title: { label: "Submitting verification..." },
                descriptions: [
                  {
                    label: "Please do not refresh this page or click the back button.",
                  },
                ],
              });

              const result = oneSdk.component("form", {
                name: "RESULT",
                type: "manual",
                state: "SUCCESS",
                title: { label: "Thanks, you're all done" },
                cta: null,
              });

              // 4. Wire up welcome → consent → IDV
              welcome.on("form:welcome:ready", () => {
                consent.mount(appContainer);
              });

              consent.on("form:consent:ready", () => {
                idvLoading.mount("#loading-overlay");
                idv.mount(appContainer);
              });

              // 5. Hide IDV loading once IDV component is ready
              let detectionStarted = false;

              idv.on("loading", (isLoading) => {
                if (!detectionStarted && !isLoading) {
                  idvLoading.unmount();
                }
              });

              // 6. After document capture, show extraction loading
              idv.on("detection_complete", () => {
                detectionStarted = true;
                extractLoading.mount(appContainer);
              });

              // 7. Handle IDV completion — show review screen
              idv.on("results", ({ checkStatus }) => {
                if (checkStatus) {
                  extractLoading.unmount();
                  review.mount(appContainer);
                }
              });

              // 8. Handle review completion — submit and show result
              review.on("form:review:ready", async () => {
                submitLoading.mount(appContainer);
                try {
                  await oneSdk.individual().submit({ verify: true });
                  result.mount(appContainer);
                } catch (err) {
                  console.error("Verification submission failed:", err);
                  document.getElementById("onesdk-container").innerHTML =
                    "<h2>Verification error</h2><p>Please try again.</p>";
                }
              });

              // 9. Handle errors
              idv.on("error", ({ message }) => {
                console.error("IDV error:", message);
                document.getElementById("onesdk-container").innerHTML =
                  "<h2>Verification error</h2><p>Please try again.</p>";
              });

              // 10. Mount welcome screen to start
              welcome.mount(appContainer);
            } catch (error) {
              console.error("OneSDK initialization failed:", error);
            }
          }

          startOneSDK();
        </script>
      </body>
    </html>
    ```
  </Tab>

  <Tab title="React">
    ```jsx theme={null}
    import { useEffect, useRef } from "react";
    import OneSdk from "@frankieone/one-sdk";

    export default function IDVReviewFlow({ session }) {
      const initRef = useRef(false);

      useEffect(() => {
        if (!session || initRef.current) return;
        initRef.current = true;

        (async () => {
          try {
            const oneSdk = await OneSdk({
              session,
              mode: "development",
              recipe: {
                form: {
                  provider: {
                    name: "react",
                    googleApiKey: import.meta.env.VITE_GOOGLE_PLACES_API_KEY,
                  },
                },
              },
            });

            const appContainer = "#onesdk-container";

            const welcome = oneSdk.component("form", { name: "WELCOME", type: "ocr" });
            const consent = oneSdk.component("form", { name: "CONSENT" });
            const idv = oneSdk.flow("idv");

            const review = oneSdk.component("form", {
              name: "REVIEW",
              type: "ocr",
            });

            const idvLoading = oneSdk.component("form", {
              name: "LOADING",
              title: { label: "Loading..." },
              descriptions: [{ label: "" }],
            });

            const extractLoading = oneSdk.component("form", {
              name: "LOADING",
              title: { label: "Extracting data..." },
              descriptions: [
                {
                  label: "Hold tight, this can take up to 30 seconds. Please do not refresh this page or click the back button.",
                },
              ],
            });

            const submitLoading = oneSdk.component("form", {
              name: "LOADING",
              title: { label: "Submitting verification..." },
              descriptions: [
                {
                  label: "Please do not refresh this page or click the back button.",
                },
              ],
            });

            const result = oneSdk.component("form", {
              name: "RESULT",
              type: "manual",
              state: "SUCCESS",
              title: { label: "Thanks, you're all done" },
              cta: null,
            });

            welcome.on("form:welcome:ready", () => consent.mount(appContainer));
            consent.on("form:consent:ready", () => {
              idvLoading.mount("#loading-overlay");
              idv.mount(appContainer);
            });

            let detectionStarted = false;

            idv.on("loading", (isLoading) => {
              if (!detectionStarted && !isLoading) {
                idvLoading.unmount();
              }
            });

            idv.on("detection_complete", () => {
              detectionStarted = true;
              extractLoading.mount(appContainer);
            });

            idv.on("results", ({ checkStatus }) => {
              if (checkStatus) {
                extractLoading.unmount();
                review.mount(appContainer);
              }
            });

            review.on("form:review:ready", async () => {
              submitLoading.mount(appContainer);
              try {
                await oneSdk.individual().submit({ verify: true });
                result.mount(appContainer);
              } catch (err) {
                console.error("Verification submission failed:", err);
              }
            });

            idv.on("error", ({ message }) => {
              console.error("IDV error:", message);
            });

            welcome.mount(appContainer);
          } catch (error) {
            console.error("OneSDK initialization failed:", error);
          }
        })();
      }, [session]);

      return (
        <div id="onesdk-wrapper" style={{ position: "relative", width: "100%", height: "100vh" }}>
          <div id="onesdk-container" style={{ width: "100%", height: "100%" }} />
          <div
            id="loading-overlay"
            style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", zIndex: 10, background: "#fff" }}
          />
        </div>
      );
    }
    ```
  </Tab>
</Tabs>

## Step-by-Step Breakdown

### 1. Initialize the SDK

Pass the session object to [`OneSDK()`](/docs/sdk-reference/sdk-initialization). Include the `recipe.form.provider` configuration with a `googleApiKey` since this flow uses [form components](/docs/sdk-reference/form-module) for the WELCOME, CONSENT, REVIEW, LOADING, and RESULT screens. The Google Places API key is required for the address autocomplete field in the review form.

### 2. Configure Components

Create WELCOME and CONSENT [form components](/docs/sdk-reference/form-module) to collect user consent before starting capture. Create the [IDV flow](/docs/sdk-reference/idv-module) and form components for the REVIEW, LOADING, and RESULT screens.

### 3. Wire Up Events

Listen for [events](/docs/sdk-reference/events):

* `form:welcome:ready` on welcome — user completed the welcome screen, mount consent
* `form:consent:ready` on consent — user gave consent, mount the IDV flow
* `loading` on IDV — show/hide loading screen while IDV component initializes (before capture)
* `detection_complete` on IDV — document capture finished, show extraction loading screen
* `results` on IDV — extraction complete, mount the review screen
* `form:review:ready` on review — user confirmed data, submit verification

### 4. Handle Results

After the review form emits `form:review:ready`, mount a loading screen, then call [`sdk.individual().submit({ verify: true })`](/docs/sdk-reference/individual-module) and mount the result screen. The loading screen prevents a blank screen during the async submission. See [Error Scenarios](/docs/sdk-reference/error-scenarios) for details.

## Loading Screens

Three loading screens cover the async gaps in this flow:

<Callout icon="bell">
  **Unmount clears the container.** Calling `.unmount()` on a component removes **all content** from the element it was mounted to — not just the component itself. If you mount a LOADING screen and the IDV flow to the same container, unmounting the loading screen will also destroy the IDV content. Always mount loading screens to a **separate element** when they need to overlay another component.
</Callout>

**IDV loading** — shown while the IDV component initializes. The loading screen is mounted to a separate overlay div (`#loading-overlay`) that sits on top of the main container, so `unmount()` only clears the overlay without affecting the IDV content underneath:

```html theme={null}
<div id="onesdk-wrapper" style="position: relative;">
  <div id="onesdk-container"></div>
  <div id="loading-overlay"></div>
</div>
```

```javascript theme={null}
const idvLoading = oneSdk.component("form", {
  name: "LOADING",
  title: { label: "Loading..." },
  descriptions: [{ label: "" }],
});

// Mount loading to the overlay, IDV to the main container
idvLoading.mount("#loading-overlay");
idv.mount("#onesdk-container");

let detectionStarted = false;

idv.on("loading", (isLoading) => {
  if (!detectionStarted && !isLoading) {
    idvLoading.unmount(); // Safe — only clears #loading-overlay
  }
});
```

**Extraction loading** — shown after document capture while the SDK extracts data. Mount it on `detection_complete` and unmount when `results` fires:

```javascript theme={null}
const extractLoading = oneSdk.component("form", {
  name: "LOADING",
  title: { label: "Extracting data..." },
  descriptions: [
    {
      label: "Hold tight, this can take up to 30 seconds. Please do not refresh this page or click the back button.",
    },
  ],
});

idv.on("detection_complete", () => {
  detectionStarted = true;
  extractLoading.mount(appContainer);
});
```

**Submission loading** — shown after the user confirms the review while `submit()` completes. Mount it immediately in the `form:review:ready` handler before calling `submit()`:

```javascript theme={null}
const submitLoading = oneSdk.component("form", {
  name: "LOADING",
  title: { label: "Submitting verification..." },
  descriptions: [
    {
      label: "Please do not refresh this page or click the back button.",
    },
  ],
});
```

## Review Screen Configuration

The review screen displays extracted OCR data for user confirmation:

```javascript theme={null}
const review = oneSdk.component("form", {
  name: "REVIEW",
  type: "ocr",
});
```

Set `type: "ocr"` so the review form knows to display OCR-extracted fields. See [Form Screens](/docs/sdk-reference/form-module/screens) for customization options.

## Submitting After Review

When the user confirms the review, the `form:review:ready` event fires. Mount a loading screen first so the user is not left with a blank screen during submission:

```javascript theme={null}
review.on("form:review:ready", async () => {
  submitLoading.mount(appContainer);
  try {
    await oneSdk.individual().submit({ verify: true });
    resultScreen.mount(appContainer);
  } catch (error) {
    console.error("Verification submission failed:", error);
  }
});
```

## Customization Reference

| Aspect                     | Reference                                                    |
| -------------------------- | ------------------------------------------------------------ |
| SDK initialization options | [SDK Initialization](/docs/sdk-reference/sdk-initialization) |
| IDV flow configuration     | [IDV Module](/docs/sdk-reference/idv-module)                 |
| Form screen configuration  | [Form Module](/docs/sdk-reference/form-module)               |
| Screen names and types     | [Form Screens](/docs/sdk-reference/form-module/screens)      |
| Individual submission      | [Individual Module](/docs/sdk-reference/individual-module)   |
| Event names and payloads   | [Events](/docs/sdk-reference/events)                         |
| Error handling patterns    | [Error Scenarios](/docs/sdk-reference/error-scenarios)       |


# OCR Only
Source: https://docs.frankieone.com/docs/embedded-flows/ocr-only

Document capture and data extraction without biometrics — ideal when you only need to collect and verify document information.

## Overview

The OCR Only flow captures identity documents via camera and extracts structured data (name, date of birth, document number, etc.) without requiring biometric verification. This is useful when you need document data collection without facial matching — for example, collecting document details for a background check or credit application.

**Modules used:** [`ocr`](/docs/sdk-reference/ocr-module), [`form`](/docs/sdk-reference/form-module) (WELCOME, CONSENT, DOCUMENT, LOADING, RESULT screens)

<Callout icon="star">
  Instead of building from scratch, fork an existing flow from the [public sample codes](https://github.com/FrankieOne/frontend-onesdk-public-sample-codes/).
</Callout>

<Callout icon="bell">
  **Daon provider:** Document selection and the `documents` parameter are not required when using the Daon provider — Daon provides its own document type selection screen. To use custom document selection instead of Daon's built-in screen, contact your FrankieOne account team.
</Callout>

## Flow Diagram

<Steps>
  <Step title="Welcome Screen">
    Initial greeting and introduction.
  </Step>

  <Step title="Consent Screen">
    Capture user consent for data processing.
  </Step>

  <Step title="Document Selection">
    User selects the type of document to capture.
  </Step>

  <Step title="OCR Capture">
    Camera-based document capture and automatic data extraction.
  </Step>

  <Step title="Result">
    Capture outcome displayed.
  </Step>
</Steps>

## Full Implementation

<Tabs>
  <Tab title="Vanilla HTML/JS">
    ```html theme={null}
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>OneSDK OCR Only</title>
        <script src="https://assets.frankiefinancial.io/one-sdk/v1/oneSdk.umd.js"></script>
        <style>
          body { margin: 0; font-family: sans-serif; background: #fff; }
          #onesdk-wrapper { position: relative; width: 100%; height: 100vh; }
          #onesdk-container { width: 100%; height: 100%; }
          #loading-overlay {
            position: absolute; top: 0; left: 0; width: 100%; height: 100%;
            z-index: 10; background: #fff;
          }
        </style>
      </head>
      <body>
        <div id="onesdk-wrapper">
          <div id="onesdk-container"></div>
          <div id="loading-overlay"></div>
        </div>

        <script>
          async function startOneSDK() {
            try {
              // 1. Generate session token (move to your backend in production)
              const tokenResponse = await fetch(
                "https://backend.kycaml.uat.frankiefinancial.io/auth/v2/machine-session",
                {
                  method: "POST",
                  headers: {
                    authorization: "machine " + btoa("<CUSTOMER_ID>:<CUSTOMER_CHILD_ID>:<API_KEY>"),
                    "Content-Type": "application/json",
                  },
                  body: JSON.stringify({
                    permissions: {
                      preset: "one-sdk",
                      reference: "ocr-" + Date.now(),
                    },
                  }),
                }
              );
              const session = await tokenResponse.json();

              // 2. Initialize OneSDK
              const oneSdk = await OneSDK({
                session: session,
                mode: "development",
                recipe: {
                  ocr: {
                    maxDocumentCount: 3,
                  },
                  form: {
                    provider: { name: "react" },
                  },
                },
              });

              const appContainer = "#onesdk-container";

              // 3. Create form components
              const welcome = oneSdk.component("form", {
                name: "WELCOME",
                type: "ocr",
              });

              const consent = oneSdk.component("form", { name: "CONSENT" });

              const documentForm = oneSdk.component("form", {
                name: "DOCUMENT",
                showPreps: true,
              });

              const ocrLoading = oneSdk.component("form", {
                name: "LOADING",
                title: { label: "Loading..." },
                descriptions: [{ label: "" }],
              });

              const resultSuccess = oneSdk.component("form", {
                name: "RESULT",
                type: "manual",
                state: "SUCCESS",
                title: { label: "Document captured" },
                descriptions: [{ label: "Your document has been captured and data extracted." }],
                cta: { label: "Done" },
              });

              // 4. Wire up form navigation
              welcome.mount(appContainer);

              welcome.on("form:welcome:ready", () => {
                consent.mount(appContainer);
              });

              consent.on("form:consent:ready", () => {
                documentForm.mount(appContainer);
              });

              // 5. Handle document selection → OCR capture
              documentForm.on("form:document:ready", ({ inputInfo }) => {
                ocrLoading.mount("#loading-overlay");
                const docType = inputInfo.documentType;

                const ocr = oneSdk.component("ocr", {
                  documents: [{ type: docType, countries: ["AUS"] }],
                });

                ocr.mount(appContainer);

                ocr.on("loading", (isLoading) => {
                  if (!isLoading) {
                    ocrLoading.unmount();
                  }
                });

                ocr.on("error", (err) => {
                  console.error("OCR error:", err);
                });

                // 6. Handle OCR results → Result screen
                ocr.on("results", ({ document }) => {
                  if (document) {
                    resultSuccess.mount(appContainer);
                  }
                });
              });
            } catch (error) {
              console.error("OneSDK initialization failed:", error);
            }
          }

          startOneSDK();
        </script>
      </body>
    </html>
    ```
  </Tab>

  <Tab title="React">
    ```jsx theme={null}
    import { useEffect, useRef } from "react";
    import OneSdk from "@frankieone/one-sdk";

    export default function OCROnlyFlow({ session }) {
      const initRef = useRef(false);

      useEffect(() => {
        if (!session || initRef.current) return;
        initRef.current = true;

        (async () => {
          try {
            const oneSdk = await OneSdk({
              session,
              mode: "development",
              recipe: {
                ocr: { maxDocumentCount: 3 },
                form: {
                  provider: { name: "react" },
                },
              },
            });

            const appContainer = "#onesdk-container";

            const welcome = oneSdk.component("form", { name: "WELCOME", type: "ocr" });
            const consent = oneSdk.component("form", { name: "CONSENT" });
            const documentForm = oneSdk.component("form", { name: "DOCUMENT", showPreps: true });

            const ocrLoading = oneSdk.component("form", {
              name: "LOADING", title: { label: "Loading..." }, descriptions: [{ label: "" }],
            });

            const resultSuccess = oneSdk.component("form", {
              name: "RESULT", type: "manual", state: "SUCCESS",
              title: { label: "Document captured" },
              descriptions: [{ label: "Your document has been captured and data extracted." }],
              cta: { label: "Done" },
            });

            welcome.mount(appContainer);

            welcome.on("form:welcome:ready", () => consent.mount(appContainer));
            consent.on("form:consent:ready", () => documentForm.mount(appContainer));

            documentForm.on("form:document:ready", ({ inputInfo }) => {
              ocrLoading.mount("#loading-overlay");
              const ocr = oneSdk.component("ocr", {
                documents: [{ type: inputInfo.documentType, countries: ["AUS"] }],
              });

              ocr.mount(appContainer);

              ocr.on("loading", (isLoading) => {
                if (!isLoading) ocrLoading.unmount();
              });

              ocr.on("error", (err) => console.error("OCR error:", err));

              ocr.on("results", ({ document }) => {
                if (document) resultSuccess.mount(appContainer);
              });
            });
          } catch (error) {
            console.error("OneSDK initialization failed:", error);
          }
        })();
      }, [session]);

      return (
        <div id="onesdk-wrapper" style={{ position: "relative", width: "100%", height: "100vh" }}>
          <div id="onesdk-container" style={{ width: "100%", height: "100%" }} />
          <div
            id="loading-overlay"
            style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", zIndex: 10, background: "#fff" }}
          />
        </div>
      );
    }
    ```
  </Tab>
</Tabs>

## Step-by-Step Breakdown

### 1. Initialize the SDK

Pass the session object to [`OneSDK()`](/docs/sdk-reference/sdk-initialization). Include the `ocr` and `form.provider` recipe configuration.

### 2. Configure Components

Create [form components](/docs/sdk-reference/form-module) for the Welcome, Consent, Document, Loading, and Result screens. The [`ocr`](/docs/sdk-reference/ocr-module) component is created dynamically after document selection.

### 3. Wire Up Events

Use [`.on(event)`](/docs/sdk-reference/events) listeners to navigate through each step. A loading screen is shown on a [separate overlay](#loading-screen) while the OCR component initializes. After OCR emits `results`, mount the result screen.

### 4. Handle Results

After the OCR component emits `results` with extracted document data, display the result screen. See [Error Scenarios](/docs/sdk-reference/error-scenarios) for failure handling.

## Loading Screen

A loading screen is shown while the OCR component initializes. It is mounted to a separate overlay div so that `unmount()` does not clear the OCR component underneath.

```javascript theme={null}
const ocrLoading = oneSdk.component("form", {
  name: "LOADING",
  title: { label: "Loading..." },
  descriptions: [{ label: "" }],
});

ocrLoading.mount("#loading-overlay");
ocr.mount("#onesdk-container");

ocr.on("loading", (isLoading) => {
  if (!isLoading) {
    ocrLoading.unmount(); // Safe — only clears #loading-overlay
  }
});
```

<Callout icon="bell">
  **Unmount clears the container.** Calling `.unmount()` on a component removes **all content** from the element it was mounted to — not just the component itself. Always mount loading screens to a **separate element** when they need to overlay another component. See the [IDV with Review flow](/docs/embedded-flows/idv-review#loading-screens) for more details.
</Callout>

## Document Type Configuration

Configure which document types are accepted for OCR capture:

```javascript theme={null}
const ocr = oneSdk.component("ocr", {
  documents: [
    { type: "DRIVERS_LICENCE", countries: ["AUS"] },
    { type: "PASSPORT", countries: ["AUS", "NZL"] },
  ],
});
```

See [OCR Module](/docs/sdk-reference/ocr-module) for all supported document types and configuration options.

## Extracted Data Handling

The OCR `results` event provides structured document data:

```javascript theme={null}
ocr.on("results", ({ document }) => {
  if (document) {
    const { ocrResult } = document;

    // Available fields depend on document type
    const dateOfBirth = ocrResult.dateOfBirth;
    const fullName = ocrResult.fullName;
    const documentNumber = ocrResult.documentNumber;

    // Show result or process data directly
    resultSuccess.mount(appContainer);
  }
});
```

## Customization Reference

| Aspect                      | Reference                                                    |
| --------------------------- | ------------------------------------------------------------ |
| SDK initialization options  | [SDK Initialization](/docs/sdk-reference/sdk-initialization) |
| OCR component configuration | [OCR Module](/docs/sdk-reference/ocr-module)                 |
| Form screen configuration   | [Form Module](/docs/sdk-reference/form-module)               |
| Screen names and types      | [Form Screens](/docs/sdk-reference/form-module/screens)      |
| Event names and payloads    | [Events](/docs/sdk-reference/events)                         |
| Error handling patterns     | [Error Scenarios](/docs/sdk-reference/error-scenarios)       |


# Embedded Flows
Source: https://docs.frankieone.com/docs/embedded-flows/overview

Build fully customized identity verification experiences with OneSDK's embedded components.

Embedded OneSDK gives you complete control over the identity verification UI. Instead of using pre-built hosted pages, you mount individual SDK components into your own application and wire up the user journey exactly how you want it.

<Callout icon="star">
  New to embedded flows? Start with the [Quick Start guide](/docs/embedded-flows/quick-start) to get a working integration in minutes, then explore the flow guides below.
</Callout>

## Choose a Flow

<CardGroup>
  <Card title="eKYC Flow" icon="user-check" href="/docs/embedded-flows/ekyc">
    Full electronic Know Your Customer journey with manual form entry, document collection, and optional fraud detection via device tracking.
  </Card>

  <Card title="IDV Flow" icon="id-card" href="/docs/embedded-flows/idv">
    Camera-based identity document verification powered by Incode. Minimal setup with automatic document capture and processing.
  </Card>

  <Card title="IDV with Review" icon="id-card-clip" href="/docs/embedded-flows/idv-review">
    IDV flow extended with an OCR review screen so users can verify extracted data before submission.
  </Card>

  <Card title="Split Flow (OCR + Biometrics)" icon="code-branch" href="/docs/embedded-flows/split-flow">
    Separate OCR and Biometrics components wired together with form screens for maximum control over the capture journey.
  </Card>

  <Card title="OCR Only" icon="file-lines" href="/docs/embedded-flows/ocr-only">
    Document capture and data extraction without biometrics. Ideal when you only need to collect and verify document data.
  </Card>

  <Card title="Document Upload" icon="cloud-arrow-up" href="/docs/embedded-flows/doc-upload">
    File-based document collection using upload screens. Supports required and optional document types with review.
  </Card>
</CardGroup>

## Flow Comparison

| Flow                | Camera Capture | Biometrics | Manual Entry | Key Modules                 |
| ------------------- | :------------: | :--------: | :----------: | --------------------------- |
| **eKYC**            |        —       |      —     |      Yes     | `form`                      |
| **IDV**             |       Yes      |     Yes    |       —      | `idv`                       |
| **IDV with Review** |       Yes      |     Yes    |       —      | `idv`, `form` (REVIEW)      |
| **Split Flow**      |       Yes      |     Yes    |       —      | `ocr`, `biometrics`, `form` |
| **OCR Only**        |       Yes      |      —     |       —      | `ocr`, `form`               |
| **Doc Upload**      |        —       |      —     |      Yes     | `form` (doc\_upload type)   |

## Not Sure Which Flow to Use?

<Callout icon="lightbulb">
  * **Need camera-based document capture with facial matching?** Use [IDV](/docs/embedded-flows/idv) or [IDV with Review](/docs/embedded-flows/idv-review).
  * **Want full control over each capture step (OCR then biometrics)?** Use [Split Flow](/docs/embedded-flows/split-flow).
  * **Only need document data extraction, no biometrics?** Use [OCR Only](/docs/embedded-flows/ocr-only).
  * **Collecting documents via file upload instead of camera?** Use [Doc Upload](/docs/embedded-flows/doc-upload).
  * **Manual form-based KYC without camera capture?** Use [eKYC](/docs/embedded-flows/ekyc).
</Callout>

## Prerequisites

Before starting any embedded flow, make sure you have:

1. **API credentials** — a Customer ID and API Key from the FrankieOne portal
2. **Backend token endpoint** — a server-side endpoint that generates [session tokens](/docs/sdk-reference/session-management)
3. **OneSDK loaded** — either via the UMD script tag or the `@frankieone/one-sdk` npm package

See [SDK Initialization](/docs/sdk-reference/sdk-initialization) for full setup details.


# Quick Start
Source: https://docs.frankieone.com/docs/embedded-flows/quick-start

Get a working embedded OneSDK integration running in minutes with React or vanilla HTML/JS.

This guide walks you through setting up a minimal embedded IDV flow — from generating a session token to mounting the SDK in your page. Once you have this working, you can swap in any of the flow guides for more advanced journeys.

<Callout icon="star">
  Instead of building from scratch, you can fork an existing flow from the [public sample codes](https://github.com/FrankieOne/frontend-onesdk-public-sample-codes/).
</Callout>

## Prerequisites

* A **Customer ID** and **API Key** from the FrankieOne portal
* A backend endpoint that can generate [session tokens](/docs/sdk-reference/session-management) (or use the inline fetch shown below for development only)
* Node.js 16+ (for the React example)

## Architecture

<Frame>
  <img alt="Solution Architecture" />
</Frame>

<Accordion title="Component Flow">
  1. **Customer Web App** — your application hosting OneSDK
  2. **OneSDK** — manages the verification UI/UX
  3. **Incode IDV** — handles document and biometric capture
  4. **FrankieOne KYC** — processes verification checks
  5. **Portal** — displays verification results
</Accordion>

## Full Implementation

<Tabs>
  <Tab title="Vanilla HTML/JS">
    Copy this into an `.html` file and open it in a browser. Replace the placeholder credentials with your own.

    ```html theme={null}
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>OneSDK Quick Start</title>
        <script src="https://assets.frankiefinancial.io/one-sdk/v1/oneSdk.umd.js"></script>
        <style>
          body { margin: 0; font-family: sans-serif; background: #fff; }
          #onesdk-container { width: 100%; height: 100vh; }
        </style>
      </head>
      <body>
        <div id="onesdk-container"></div>

        <script>
          async function startOneSDK() {
            try {
              // 1. Generate session token (move to your backend in production)
              const tokenResponse = await fetch(
                "https://backend.kycaml.uat.frankiefinancial.io/auth/v2/machine-session",
                {
                  method: "POST",
                  headers: {
                    authorization: "machine " + btoa("<CUSTOMER_ID>:<CUSTOMER_CHILD_ID>:<API_KEY>"),
                    "Content-Type": "application/json",
                  },
                  body: JSON.stringify({
                    permissions: {
                      preset: "one-sdk",
                      reference: "quickstart-" + Date.now(),
                    },
                  }),
                }
              );
              const session = await tokenResponse.json();

              // 2. Initialize OneSDK
              const oneSdk = await OneSDK({
                session: session,
                mode: "development",
                recipe: {
                  form: {
                    provider: { name: "react" },
                  },
                },
              });

              const appContainer = "#onesdk-container";

              // 3. Create form and IDV components
              const welcome = oneSdk.component("form", {
                name: "WELCOME",
                type: "ocr",
              });

              const consent = oneSdk.component("form", { name: "CONSENT" });

              const idv = oneSdk.flow("idv");

              // 4. Wire up welcome → consent → IDV
              welcome.on("form:welcome:ready", () => {
                consent.mount(appContainer);
              });

              consent.on("form:consent:ready", () => {
                idv.mount(appContainer);
              });

              idv.on("results", async ({ checkStatus }) => {
                if (checkStatus) {
                  document.getElementById("onesdk-container").innerHTML =
                    "<h2>Verification complete</h2>";
                }
              });

              idv.on("error", ({ message }) => {
                console.error("IDV error:", message);
              });

              // 5. Mount welcome screen to start
              welcome.mount(appContainer);
            } catch (error) {
              console.error("OneSDK initialization failed:", error);
            }
          }

          startOneSDK();
        </script>
      </body>
    </html>
    ```
  </Tab>

  <Tab title="React">
    ### 1. Project Setup

    ```bash theme={null}
    npm create vite@latest onesdk-quickstart -- --template react
    cd onesdk-quickstart
    npm install @frankieone/one-sdk
    ```

    ### 2. Environment Variables

    Create a `.env` file:

    ```text theme={null}
    VITE_CUSTOMER_ID=your_customer_id
    VITE_API_KEY=your_api_key
    VITE_FRANKIE_BASE_URL=https://backend.kycaml.uat.frankiefinancial.io
    ```

    <Callout icon="bell">
      Never commit credentials to version control. Use environment variables in production.
    </Callout>

    ### 3. SDK Handler

    ```jsx OneSDKHandler.jsx theme={null}
    import OneSdk from "@frankieone/one-sdk";
    import { useEffect, useRef, useState } from "react";

    const CUSTOMER_ID = import.meta.env.VITE_CUSTOMER_ID;
    const API_KEY = import.meta.env.VITE_API_KEY;
    const BASE_URL = import.meta.env.VITE_FRANKIE_BASE_URL;

    export default function OneSDKHandler({ config }) {
      const [instance, setInstance] = useState(null);
      const [error, setError] = useState(null);
      const [loading, setLoading] = useState(true);
      const initRef = useRef(false);

      useEffect(() => {
        if (initRef.current) return;
        initRef.current = true;

        (async () => {
          try {
            const tokenRes = await fetch(`${BASE_URL}/auth/v2/machine-session`, {
              method: "POST",
              headers: {
                authorization: `machine ${btoa(`${CUSTOMER_ID}:${API_KEY}`)}`,
                "Content-Type": "application/json",
              },
              body: JSON.stringify({
                permissions: { preset: "one-sdk", reference: `demo-${Date.now()}` },
              }),
            });
            const session = await tokenRes.json();

            const sdk = await OneSdk({
              session,
              mode: "development",
              recipe: {
                form: {
                  provider: { name: "react" },
                },
              },
              ...config,
            });
            setInstance(sdk);
          } catch (err) {
            setError(err.message);
          } finally {
            setLoading(false);
          }
        })();
      }, []);

      return { instance, error, loading };
    }
    ```

    ### 4. IDV Flow Component

    ```jsx OneSDKFlow.jsx theme={null}
    import { useEffect, useRef } from "react";
    import OneSDKHandler from "./OneSDKHandler";

    export default function OneSDKFlow() {
      const { instance, error, loading } = OneSDKHandler({});
      const flowRef = useRef(false);

      useEffect(() => {
        if (!instance || flowRef.current) return;
        flowRef.current = true;

        const appContainer = "#onesdk-container";

        const welcome = instance.component("form", { name: "WELCOME", type: "ocr" });
        const consent = instance.component("form", { name: "CONSENT" });
        const idv = instance.flow("idv");

        welcome.on("form:welcome:ready", () => consent.mount(appContainer));
        consent.on("form:consent:ready", () => idv.mount(appContainer));

        idv.on("results", ({ checkStatus }) => {
          if (checkStatus) {
            document.getElementById("onesdk-container").innerHTML =
              "<h2>Verification complete</h2>";
          }
        });

        idv.on("error", ({ message }) => {
          console.error("IDV error:", message);
        });

        welcome.mount(appContainer);
      }, [instance]);

      if (error) return <div>Error: {error}</div>;
      if (loading) return <div>Loading...</div>;

      return <div id="onesdk-container" style={{ width: "100%", height: "100vh" }} />;
    }
    ```

    ### 5. App Entry Point

    ```jsx App.jsx theme={null}
    import OneSDKFlow from "./OneSDKFlow";

    export default function App() {
      return <OneSDKFlow />;
    }
    ```

    ### 6. Run

    ```bash theme={null}
    npm install && npm run dev
    ```
  </Tab>
</Tabs>

## Step-by-Step Breakdown

### 1. Generate a Session Token

Your backend calls the `/auth/v2/machine-session` endpoint with your credentials and returns the session object to the frontend. See [Session Management](/docs/sdk-reference/session-management) for details.

### 2. Initialize the SDK

Pass the session object to [`OneSDK()`](/docs/sdk-reference/sdk-initialization) along with configuration options like `mode` and `recipe`. Include the `recipe.form.provider` configuration for the WELCOME and CONSENT screens.

### 3. Add Welcome and Consent Screens

Create WELCOME and CONSENT [form components](/docs/sdk-reference/form-module) to collect user consent before starting verification. Consent must be collected before the IDV flow can proceed.

### 4. Create a Flow or Component

Use `sdk.flow("idv")` to create an [IDV flow](/docs/sdk-reference/idv-module), or create individual components like [`sdk.component("ocr")`](/docs/sdk-reference/ocr-module) for more granular control.

### 5. Wire Up Events

Listen for [events](/docs/sdk-reference/events) like `form:welcome:ready`, `form:consent:ready`, `results`, `error`, and `loading` to drive your UI transitions.

### 6. Mount to the DOM

Call `.mount("#onesdk-container")` on the welcome screen to start the flow. Each subsequent screen is mounted by event listeners.

## Next Steps

<CardGroup>
  <Card title="eKYC Flow" icon="user-check" href="/docs/embedded-flows/ekyc">
    Manual form-based KYC with document collection and fraud detection.
  </Card>

  <Card title="IDV Flow" icon="id-card" href="/docs/embedded-flows/idv">
    Camera-based identity document verification with minimal setup.
  </Card>

  <Card title="IDV with Review" icon="id-card-clip" href="/docs/embedded-flows/idv-review">
    IDV flow with OCR review screen for data verification.
  </Card>

  <Card title="Split Flow" icon="code-branch" href="/docs/embedded-flows/split-flow">
    Separate OCR and Biometrics components for maximum control.
  </Card>

  <Card title="OCR Only" icon="file-lines" href="/docs/embedded-flows/ocr-only">
    Document capture and data extraction without biometrics.
  </Card>

  <Card title="Document Upload" icon="cloud-arrow-up" href="/docs/embedded-flows/doc-upload">
    File-based document collection with upload screens.
  </Card>
</CardGroup>

## Additional Resources

<CardGroup>
  <Card title="Sample Code" icon="github" href="https://github.com/FrankieOne/frontend-onesdk-public-sample-codes">
    Browse reference implementations.
  </Card>

  <Card title="Live Demo" icon="play" href="https://stackblitz.com/edit/vitejs-vite-qknsbz">
    Try OneSDK in an interactive environment.
  </Card>

  <Card title="Test Data" icon="vial" href="/docs/test-data">
    Get test credentials and sample data.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Token Generation Failed">
    * Verify your Customer ID and API Key in the `.env` file
    * Check network connectivity to the FrankieOne API
    * Ensure you are using the correct endpoint (UAT vs production)
  </Accordion>

  <Accordion title="Component Not Rendering">
    * Confirm the mount target element exists in the DOM (e.g., `#onesdk-container`)
    * Check the browser console for initialization errors
    * Verify the session token has not expired
  </Accordion>

  <Accordion title="Best Practices">
    * Always generate session tokens on your backend — never expose API keys in client code
    * Implement error handling for all SDK operations
    * Use [test data](/docs/test-data) during development
  </Accordion>
</AccordionGroup>


# Split Flow (OCR + Biometrics)
Source: https://docs.frankieone.com/docs/embedded-flows/split-flow

Wire together separate OCR and Biometrics components with form screens for maximum control over the document capture and facial verification journey.

## Overview

The split flow uses the OCR and Biometrics components separately instead of the combined IDV flow. This gives you full control over the journey between document capture and facial verification — you can customize loading states, handle OCR results before proceeding to biometrics, and optionally insert a review screen between the two.

**Modules used:** [`ocr`](/docs/sdk-reference/ocr-module), [`biometrics`](/docs/sdk-reference/biometrics-module), [`form`](/docs/sdk-reference/form-module) (WELCOME, CONSENT, DOCUMENT, LOADING screens)

<Callout icon="star">
  Instead of building from scratch, fork an existing flow from the [public sample codes](https://github.com/FrankieOne/frontend-onesdk-public-sample-codes/).
</Callout>

<Callout icon="bell">
  **Daon provider:** Document selection and the `documents` parameter are not required when using the Daon provider — Daon provides its own document type selection screen. To use custom document selection instead of Daon's built-in screen, contact your FrankieOne account team.
</Callout>

## Flow Diagram

<Steps>
  <Step title="Welcome Screen">
    Initial greeting and introduction to the verification process.
  </Step>

  <Step title="Consent Screen">
    Capture user consent for data processing.
  </Step>

  <Step title="Document Selection">
    User selects the type of document to capture.
  </Step>

  <Step title="OCR Capture">
    Camera-based document capture and data extraction.
  </Step>

  <Step title="Biometrics Capture">
    Facial verification via selfie capture.
  </Step>

  <Step title="Result">
    Verification outcome displayed.
  </Step>
</Steps>

## Full Implementation

<Tabs>
  <Tab title="Vanilla HTML/JS">
    ```html theme={null}
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>OneSDK Split Flow</title>
        <script src="https://assets.frankiefinancial.io/one-sdk/v1/oneSdk.umd.js"></script>
        <style>
          body { margin: 0; font-family: sans-serif; background: #fff; }
          #onesdk-wrapper { position: relative; width: 100%; height: 100vh; }
          #onesdk-container { width: 100%; height: 100%; }
          #loading-overlay {
            position: absolute; top: 0; left: 0; width: 100%; height: 100%;
            z-index: 10; background: #fff;
          }
        </style>
      </head>
      <body>
        <div id="onesdk-wrapper">
          <div id="onesdk-container"></div>
          <div id="loading-overlay"></div>
        </div>

        <script>
          async function startOneSDK() {
            try {
              // 1. Generate session token (move to your backend in production)
              const tokenResponse = await fetch(
                "https://backend.kycaml.uat.frankiefinancial.io/auth/v2/machine-session",
                {
                  method: "POST",
                  headers: {
                    authorization: "machine " + btoa("<CUSTOMER_ID>:<CUSTOMER_CHILD_ID>:<API_KEY>"),
                    "Content-Type": "application/json",
                  },
                  body: JSON.stringify({
                    permissions: {
                      preset: "one-sdk",
                      reference: "split-" + Date.now(),
                    },
                  }),
                }
              );
              const session = await tokenResponse.json();

              // 2. Initialize OneSDK
              const oneSdk = await OneSDK({
                session: session,
                mode: "development",
                recipe: {
                  ocr: {
                    maxDocumentCount: 3,
                  },
                  form: {
                    provider: { name: "react" },
                  },
                },
              });

              const appContainer = "#onesdk-container";

              // 3. Create form components
              const welcome = oneSdk.component("form", {
                name: "WELCOME",
                type: "ocr",
              });

              const consent = oneSdk.component("form", { name: "CONSENT" });

              const documentForm = oneSdk.component("form", {
                name: "DOCUMENT",
                showPreps: true,
              });

              const loading = oneSdk.component("form", {
                name: "LOADING",
                title: { label: "Loading..." },
                descriptions: [{ label: "" }],
              });

              const biometrics = oneSdk.component("biometrics");

              // 4. Wire up form navigation
              welcome.mount(appContainer);

              welcome.on("form:welcome:ready", () => {
                consent.mount(appContainer);
              });

              consent.on("form:consent:ready", () => {
                documentForm.mount(appContainer);
              });

              // 5. Handle document selection → OCR capture
              documentForm.on("form:document:ready", ({ inputInfo }) => {
                loading.mount("#loading-overlay");
                const docType = inputInfo.documentType;

                const ocr = oneSdk.component("ocr", {
                  documents: [{ type: docType, countries: ["AUS"] }],
                });

                ocr.mount(appContainer);

                ocr.on("loading", (isLoading) => {
                  if (!isLoading) {
                    loading.unmount();
                  }
                });

                ocr.on("error", (err) => {
                  console.error("OCR error:", err);
                });

                // 6. Handle OCR results → Biometrics
                ocr.on("results", ({ document }) => {
                  if (document) {
                    loading.mount("#loading-overlay");
                    biometrics.mount(appContainer);
                  }
                });
              });

              // 7. Handle biometrics
              let biometricsError = false;

              biometrics.on("detection_failed", () => {
                biometricsError = true;
              });

              biometrics.on("session_closed", () => {
                if (biometricsError) {
                  biometrics.mount(appContainer);
                  biometricsError = false;
                }
              });

              biometrics.on("loading", (isLoading) => {
                if (!isLoading) {
                  loading.unmount();
                }
              });

              biometrics.on("results", (result) => {
                document.getElementById("onesdk-container").innerHTML =
                  "<h2>Verification complete</h2>";
              });

              biometrics.on("error", (err) => {
                console.error("Biometrics error:", err);
              });
            } catch (error) {
              console.error("OneSDK initialization failed:", error);
            }
          }

          startOneSDK();
        </script>
      </body>
    </html>
    ```
  </Tab>

  <Tab title="React">
    ```jsx theme={null}
    import { useEffect, useRef } from "react";
    import OneSdk from "@frankieone/one-sdk";

    export default function SplitFlow({ session }) {
      const initRef = useRef(false);

      useEffect(() => {
        if (!session || initRef.current) return;
        initRef.current = true;

        (async () => {
          try {
            const oneSdk = await OneSdk({
              session,
              mode: "development",
              recipe: {
                ocr: { maxDocumentCount: 3 },
                form: {
                  provider: { name: "react" },
                },
              },
            });

            const appContainer = "#onesdk-container";

            const welcome = oneSdk.component("form", { name: "WELCOME", type: "ocr" });
            const consent = oneSdk.component("form", { name: "CONSENT" });
            const documentForm = oneSdk.component("form", { name: "DOCUMENT", showPreps: true });

            const loading = oneSdk.component("form", {
              name: "LOADING", title: { label: "Loading..." }, descriptions: [{ label: "" }],
            });

            const biometrics = oneSdk.component("biometrics");

            welcome.mount(appContainer);

            welcome.on("form:welcome:ready", () => consent.mount(appContainer));
            consent.on("form:consent:ready", () => documentForm.mount(appContainer));

            documentForm.on("form:document:ready", ({ inputInfo }) => {
              loading.mount("#loading-overlay");
              const ocr = oneSdk.component("ocr", {
                documents: [{ type: inputInfo.documentType, countries: ["AUS"] }],
              });

              ocr.mount(appContainer);

              ocr.on("loading", (isLoading) => {
                if (!isLoading) loading.unmount();
              });

              ocr.on("error", (err) => console.error("OCR error:", err));

              ocr.on("results", ({ document }) => {
                if (document) {
                  loading.mount("#loading-overlay");
                  biometrics.mount(appContainer);
                }
              });
            });

            let biometricsError = false;
            biometrics.on("detection_failed", () => { biometricsError = true; });
            biometrics.on("session_closed", () => {
              if (biometricsError) {
                biometrics.mount(appContainer);
                biometricsError = false;
              }
            });

            biometrics.on("loading", (isLoading) => {
              if (!isLoading) loading.unmount();
            });

            biometrics.on("results", () => {
              document.getElementById("onesdk-container").innerHTML =
                "<h2>Verification complete</h2>";
            });

            biometrics.on("error", (err) => console.error("Biometrics error:", err));
          } catch (error) {
            console.error("OneSDK initialization failed:", error);
          }
        })();
      }, [session]);

      return (
        <div id="onesdk-wrapper" style={{ position: "relative", width: "100%", height: "100vh" }}>
          <div id="onesdk-container" style={{ width: "100%", height: "100%" }} />
          <div
            id="loading-overlay"
            style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", zIndex: 10, background: "#fff" }}
          />
        </div>
      );
    }
    ```
  </Tab>
</Tabs>

## Step-by-Step Breakdown

### 1. Initialize the SDK

Pass the session object to [`OneSDK()`](/docs/sdk-reference/sdk-initialization). Include the `ocr` and `form.provider` recipe configuration.

### 2. Configure Components

Create [form components](/docs/sdk-reference/form-module) for Welcome, Consent, Document selection, and a shared Loading screen. Create the [`ocr`](/docs/sdk-reference/ocr-module) and [`biometrics`](/docs/sdk-reference/biometrics-module) components separately.

### 3. Wire Up Events

Use [`.on(event)`](/docs/sdk-reference/events) listeners to navigate between screens and transition from OCR to biometrics. A single loading screen is reused for both OCR and biometrics initialization — mounted to the overlay before each component, and unmounted when the component is ready.

<Callout icon="bell">
  **Unmount clears the container.** Calling `.unmount()` on a component removes **all content** from the element it was mounted to — not just the component itself. Loading screens in this flow are mounted to a **separate overlay element** (`#loading-overlay`) so that unmounting them does not destroy the OCR or biometrics component underneath. See the [IDV with Review flow](/docs/embedded-flows/idv-review#loading-screens) for a detailed explanation.
</Callout>

### 4. Handle Results

Listen for `results` on both the OCR and biometrics components. See [Error Scenarios](/docs/sdk-reference/error-scenarios) for details on handling failures.

## OCR Results Handling

When the OCR component completes, it returns the extracted document data and the flow proceeds to biometrics:

```javascript theme={null}
ocr.on("results", ({ document }) => {
  if (document) {
    // Access extracted fields if needed
    const dob = document.ocrResult.dateOfBirth;
    const name = document.ocrResult.fullName;

    // Proceed to biometrics
    loading.mount("#loading-overlay");
    biometrics.mount(appContainer);
  }
});
```

See [OCR Module](/docs/sdk-reference/ocr-module) for all available result fields.

## Biometrics Error Recovery

The biometrics component may fail due to camera issues or detection problems. Implement automatic retry:

```javascript theme={null}
let biometricsError = false;

biometrics.on("detection_failed", () => {
  biometricsError = true;
});

biometrics.on("session_closed", () => {
  if (biometricsError) {
    biometrics.mount(appContainer);
    biometricsError = false;
  }
});
```

See [Biometrics Module](/docs/sdk-reference/biometrics-module) for all events and configuration options.

## Adding a Review Screen

To let users confirm extracted data before proceeding to biometrics, insert a review screen between OCR and biometrics:

```javascript theme={null}
const review = oneSdk.component("form", {
  name: "REVIEW",
  type: "ocr",
});

ocr.on("results", ({ document }) => {
  if (document) {
    review.mount(appContainer);
  }
});

review.on("form:review:ready", () => {
  loading.mount("#loading-overlay");
  biometrics.mount(appContainer);
});
```

## Customization Reference

| Aspect                      | Reference                                                    |
| --------------------------- | ------------------------------------------------------------ |
| SDK initialization options  | [SDK Initialization](/docs/sdk-reference/sdk-initialization) |
| OCR component configuration | [OCR Module](/docs/sdk-reference/ocr-module)                 |
| Biometrics configuration    | [Biometrics Module](/docs/sdk-reference/biometrics-module)   |
| Form screen configuration   | [Form Module](/docs/sdk-reference/form-module)               |
| Screen names and types      | [Form Screens](/docs/sdk-reference/form-module/screens)      |
| Event names and payloads    | [Events](/docs/sdk-reference/events)                         |
| Error handling patterns     | [Error Scenarios](/docs/sdk-reference/error-scenarios)       |


# Entities
Source: https://docs.frankieone.com/docs/entities-v2



### Entities

The **Entities** page contains a list of all profiles for that selected account. You can use the filters in each column to sort the lists.

| Column                  | Description                                                                                                                                                                                                               |
| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **NAME**                | This column displays the name of the individual or entity being verified.                                                                                                                                                 |
| **LATEST EVENT STATUS** | Shows Event status of the latest workflow execution.                                                                                                                                                                      |
| **ISSUES**              | Highlights any specific problems or flags raised during the verification process. <br /> - Each issue belongs to a specific category and type. <br /> - Issues can be cleared or updated by resolving any check failures. |
| **RISK LEVEL**          | Indicates latest risk level of a service profiles during workflow executions.                                                                                                                                             |
| **CREATED**             | Shows the date and time when the entity's case was created in the system.                                                                                                                                                 |
| **UPDATED**             | Displays the date and time of the last update to the entity's case.                                                                                                                                                       |
| **LATEST WORKFLOW**     | Indicates the latest workflow executed on the entity.                                                                                                                                                                     |
| **ASSIGNEE**            | Shows the initials of the user or team member assigned to review and manage the case.                                                                                                                                     |

### Needs Review

The **Needs Review** page contains a list of all profiles that haven't passed or needs to be manually reviewed to pass or fail checks. Similar to the Entities page, you can use the filters in each column to sort the lists. You can also use the search feature to find a profile within the list.

### Blocklist

The **Blocklist** page displays all profiles that FrankieOne automatically or manually adds to the blocklist. Learn more about blocklists [here](/docs/blocklists-overview). You can actively select and manage profiles on the blocklist.

### Analytics

The Analytics page contains the Dashboard and System Monitoring tabs.

The Dashboard tab provides a quick overview of the metrics for user onboarding, provide critical business intelligence to operators and customers. Learn more about the Dashboard [here](/docs/dashboard).

The System Monitoring tab provides an up-to-date monitoring and status of the FrankieOne platform and its core systems, and different services.

## Searching for entities

The FrankieOne Portal provides a convenient way to search for entities. A Search bar appears at the top of every page.

### Video Guide

<div>
  <iframe />
</div>

<img />

### How to search

To search for an entity in the Portal:

1. Click on the search field. The search bar will be expanded to show search options.

<img />

2. Enter the search term.
3. Select the type of entity identifier type, whether it's the **Individual name**, **Customer Ref**, or **Entity ID**. By default, **Individual name** is selected.
4. To perform the search using the information you entered, press **Enter** on your keyboard.
5. You can repeat a previous search by selecting it from the **Recent Searches**.
6. To perform a new search using a different search term, select the **x** icon, and enter your new search term.

<Callout icon="thumbtack">
  ##### Searchability of Fields by Entity Status

  FrankieOne v2 supports fuzzy search. Enter a first name or a last name to find matching records.
  To include archived records, turn on the Archived filter, then search by first name, last name, or the full name.
</Callout>

If you log out, your last search term and search entity identifier type will be saved. Once you log in again, your last search term will be listed in the recent searches, with the last entity identifier type selected.

<img />

If several searches produce results that aren't what you expect, you can select the **Give feedback** link to let us know how we can improve your search experience. You can also select the **learn how our search works** link to visit our public documentation page on global searches.

<Callout icon="thumbtack">
  ##### Search term character limits

  The Maximum character length is 100 & the minimum is 1.

  If you perform a search for an entity using a search term that's too long or too short, no search results will be displayed.
</Callout>

## Filtering entities

You can also filter the entities displayed in the entities table using the filtering options available under the search bar.

<Frame>
  <img alt="Filtering options for entities." />
</Frame>

### Filter by event status

Use the **Event status** dropdown menu to select the status types of the entities to display.

<Frame>
  <img alt="Entity status dropdown menu." />
</Frame>

Once you've selected the status types to display, select **Apply**. Select **Clear** to unselect all the status type.

### Filter by issue type

Use the **Issues** dropdown menu to select the issue types of the entities to display.

<Frame>
  <img alt="Issues status dropdown menu." />
</Frame>

Once you've selected the issue types to display, select **Apply**. Select **Clear** to unselect all the issue types.

### Filters overview modal

Select the **Filters** button to open the **Filters** modal. Using the Filters modal, you can view all the possible filters that can be applied to the entities displayed in the entities table.

<img />

The filters you can select are categorized according to the following:

* Entity status
* Issue
* Risk level
* Created date
* Last updated
* Workflow
* Event status
* Assignee

Select the filter criteria you prefer, and then select **Apply filters** to enable those filters. To start over, select the **Clear all** button to remove your selection.

You can search for assignee using the **Search user** field. To filter unassigned entities, select the **Unassigned** checkbox.

<img alt="" />

### Sorting entities

Select the sorting icons (up and down arrows) beside the **CREATED** and **UPDATED** column headers to sort the entities in the table. A single blue arrow highlights the current sort direction (ascending or descending):

* Single blue up arrow means the entities are displayed in ascending order.
* Single blue down arrow means the entities are displayed in descending order.

<img />


# Exporting entities as CSV
Source: https://docs.frankieone.com/docs/exporting-entities-as-csv



To export entities as a CSV file, follow these steps:

1. Select the entities you want to export by checking the boxes next to them. You can select multiple entities at once.

<Callout icon="thumbtack">
  When you choose to select all entities, you only get to select those that have been loaded. To select more, scroll down to load more entities.
</Callout>

2. Click on the **Actions** dropdown menu (represented by 3 dots) located at the top right of the entities list.
3. From the dropdown menu, select **Export as CSV**.
4. The system will generate a CSV file containing the selected entities' data.
5. Once the export is complete, a download link will be provided. Click on the link to download the CSV file to your computer.
6. Open the downloaded CSV file using a spreadsheet application like Microsoft Excel or Google Sheets to view the exported entities.


# Fraud Checks
Source: https://docs.frankieone.com/docs/fraud-checks



### Video Guide

<div>
  <iframe />
</div>

## Introduction

Fraud Prevention & Risk-Based Onboarding lets you screen every applicant during onboarding by analyzing device, email, and phone signals in real time. The API works with FrankieOne oneSDK to gather silent risk indicators and trigger additional checks only when needed, helping you:

* Block fraudulent sign-ups before they reach KYC
* Reduce friction for genuine customers
* Lower manual review and operational costs

## Key Features

<CardGroup>
  <Card title="Silent device intelligence & behavioural biometrics" icon="user-secret">
    Collects IP, user-agent, jailbreak status, VPN usage, and behavioural patterns without user interaction.
  </Card>

  <Card title="Silent email and phone checks" icon="id-card">
    Verifies deliverability, tenure, and risk signals behind the scenes.
  </Card>

  <Card title="Risk-based decisioning" icon="scale-balanced">
    Combines fraud and KYC scores, applies custom thresholds, and surfaces clear recommendations.
  </Card>

  <Card title="Intrusive verification when risk is high" icon="magnifying-glass">
    Triggers IDV, liveness, or OCR only for medium or high-risk users.
  </Card>

  <Card title="Rule-based risk engine" icon="list-check">
    Configure risk thresholds and scorecards in the portal—no code required.
  </Card>

  <Card title="Unified risk score" icon="shield-check">
    Combines Fraud and KYC risk into a single assessment for smarter decisions.
  </Card>
</CardGroup>

## What's a Fraud Check?

After the customer or entity has run the onboarding check, you can view any fraud-related issues in the workflow events tab. If there are any alerts found, these may include risks or issues related to email, phone, device, or IP checks. These alerts can be resolved individually.

## Reviewing Fraud Check Results

Filter the entities table with fraud as one of the selected issues. Selecting an entity that has fraud issues will take you to the entity view and show the workflow events tab with the onboarding fraud check result.

<img alt="Filter the entities table for Fraud issues" />

**Displaying Issues**: If the system detects potential fraud issues (known as PROs) in any of the checked sections (such as email, phone, device, IP), you will see a view similar to the image below, prompting you to check and resolve these items.

<img alt="" />

From here, you can view the risk level and overview of each section. Device and IP location are grouped together by `deviceId`.

## Fraud Check Details

**Visibility Requirement**: The onboarding fraud checks are only visible if enabled on your account. To enable them, please reach out to your Frankie Account Manager.

You can view the details by clicking on one of the `Review full details`, `Rules triggered badges`, or the `table rows under the device & IP location`. This will open a drawer with the content of the selected section.

Clicking on "more details" will redirect you to view the external link.

### Email Section:

<img alt="" />

### Phone Section:

<img alt="" />

### Device & IP Section:

<img alt="" />

## Resolving Fraud Check Issues

You can resolve issues by selecting the **Resolve** button on the right side of the onboarding fraud check container.

There may be cases where the resolve button is not visible. This is because there are no PROs that need to be resolved, meaning the email, phone, device, and IP sections are all cleared and nothing needs to be resolved.

If all of the checks need to be resolved, Selecting the **Resolve** link will open a modal. Decide whether to approve or reject and add a comment.

<img alt="" />

If the device is the only thing that needs to be resolved, then the option will only show the device session.

<img alt="" />

By marking all the signs of fraud as **No**, the decision will only show the **Approve** option.

<img alt="" />

After you click **Resolve alert** with the decision of **Approve**, it will show the status of `Manually approved` beside the onboarding fraud check title.

<img alt="" />

If you decide to reject, it will show the status of `Manually rejected` beside the onboarding fraud check title.

<img alt="" />

Hover over the comment icon to see the comment box.

<img alt="" />

## Fraud Check Comments

If you click on the comment icon, it will open the comment history box on the right side to see all previous comments after you have resolved an issue.

<img alt="" />

Please be aware that comments may be duplicated after you have resolved an issue. This is expected because answering yes and no in the resolve modal for each of the checks (email/phone/device) will call two APIs simultaneously.


# Getting Started with the FrankieOne Portal
Source: https://docs.frankieone.com/docs/getting-started-with-the-frankieone-portal

Need a hand interacting with our Portal? The articles included below show details about the FrankieOne Portal.

## What is the FrankieOne Portal?

The FrankieOne Portal is your single point of truth for all individual and business identity verification, AML, and Fraud checks. Use the Portal to manage your onboarding and compliance operations, investigate fraud and risky behaviour, and convert high-quality users.

Once you implement FrankieOne, at the end of your customer's onboarding or ongoing activity, your customer’s personal information will be sent to FrankieOne for us to assess their level of risk and perform a predefined sequence of steps (known as a “workflow”) to return an overall status for that customer.

You can use the FrankieOne Portal to check the status of customer checks, manually review high-risk or unclear customer profiles, or audit previous customer checks.

<Info>
  **Device Compatibility**

  The FrankieOne Portal is optimised for laptops and desktop computers.

  * **Supported:** Screen widths of 1024px and above (laptops and desktops)
  * **Not supported:** Mobile phones and tablets (screens below 1024px)

  For the best experience, please access the portal from a laptop or desktop device.
</Info>

## Logging into the Portal

To log in to the FrankieOne Portal, please visit [login page](https://portal.frankie.one/login). Enter your login credentials.

<Frame>
  <img alt="FrankieOne Portal login page." />
</Frame>

## Changing passwords

To change your password, go to your profile options and select **Change Password**.

<img />

An email with the password reset link will be sent to your registered email address. The link will be valid for one (1) hour.

<img alt="" />

If you don't see it in inbox, please check your spam folder. If it still hasn't arrived 10 minutes after you requested to change password, please try again.

<img alt="" />

Visit the link provided and enter your new password.

<img alt="" />

Make sure to meet all the password requirements listed on the page, otherwise you won't be able to create a new password.

<img alt="" />

A confirmation page will appear. Select **Continue** to login using your new password.

## Resetting passwords

If you encounter any issue with logging into your account using your current password, you can reset it.

<img alt="" />

Select **Reset your password** to open the **Reset password** page. Enter your email address, if it's not already filled in, then select **Send link**.

<img alt="" />

Check your email inbox for the password reset link and complete the process of resetting and [changing your password](/docs/getting-started-with-the-frankieone-portal#changing-passwords).

## Unlocking accounts

After multiple unsuccessful login attempts, your account will be temporarily locked for security purposes. If this occurs, please reach out to **your organization’s administrator** or **local IT admin** to unlock your account.

<img alt="Image" />

For system administrators to unlock a user, [read here](https://docs.frankieone.com/docs/manage-users#lock-a-user). If you need further assistance, [please contact us ](https://frankieone.atlassian.net/servicedesk/customer/portal/3/group/-1).


# Archive and Deactivate
Source: https://docs.frankieone.com/docs/how-to-archive-and-deactivate-a-customer-in-the-portal



The Portal allows you to either **archive** or **deactivate** an entity, depending on how you intend to manage the record.

<Note>
  You must have permission to “**Create and edit entities**” to carry out the steps below.
</Note>

## Archive an Entity

In an **Archive** state, the selected entity record remains accessible but will no longer display on the default **Entities** page. We suggest using this when setting aside entities you are not actively working on, but may want to keep as a record. When an entity is archived, all associated indexes are removed from the system.

You must have permission to **Create and edit entities** to perform this action.

### Instructions

To archive an entity:

1. Select the entity you wish to archive.
2. Select the **More** menu (...) next to the **Assignee** button, then select **Archive Entity**.
3. Enter a comment describing the reason for archiving.
4. Select **Archive** to confirm the action.

Once confirmed, the entity is moved to an **Archived** state.

## Deactivate an Entity

When an entity is deactivated, the system sets the entity status to **Inactive**. The selected entity record remains accessible but will no longer display on the default **Entities** page. All associated indexes are removed from the system.

Unlike archiving, deactivation is intended for entities that are no longer required and will not be used again in the future.

You must have permission to **Create and edit entities** to perform this action.

### Instructions

To deactivate an entity:

1. Select the entity you wish to deactivate.
2. Select the **More** menu (...) next to the **Assignee** button, then select **Deactivate Entity**.
3. Enter a comment describing the reason for deactivation.
4. Select **Deactivate** to confirm the action.

Once confirmed, the entity's Service Profile status is permanently updated to **INACTIVE**.

***

## Archive vs Deactivate

|                                   | Archive                        | Deactivate (Inactive)          |
| :-------------------------------- | :----------------------------- | :----------------------------- |
| Record remains accessible         | Yes                            | Yes                            |
| Displays on default Entities page | No                             | No                             |
| Indexes removed                   | Yes                            | Yes                            |
| Intended use                      | Set aside for future reference | Permanently no longer required |
| Service Profile state             | ARCHIVED                       | INACTIVE                       |

##


# Resources
Source: https://docs.frankieone.com/docs/introduction/resources



<CardGroup>
  <Card title="KYC Swagger / OpenAPI definition" icon="file-code" href="https://raw.githubusercontent.com/frankieone/openapi/refs/heads/main/specs/frankieOneKYCV2.json">
    Download our latest Swagger / OpenAPI for KYC definition **here**.
  </Card>

  <Card title="KYB Swagger / OpenAPI definition" icon="file-code" href="https://raw.githubusercontent.com/frankieone/openapi/refs/heads/main/specs/frankieOneKYBV2.json">
    Download our latest Swagger / OpenAPI for KYB definition **here**.
  </Card>

  <Card title="Core Swagger / OpenAPI definition" icon="file-code" href="https://raw.githubusercontent.com/frankieone/openapi/refs/heads/main/specs/frankieOneCoreV2.json">
    Download our latest Swagger / OpenAPI for Core API definition **here**.
  </Card>

  <Card title="Transaction and Activity Monitoring Swagger / OpenAPI definition" icon="file-code" href="https://raw.githubusercontent.com/frankieone/openapi/refs/heads/main/specs/frankieOneTxAMV2.json">
    Download our latest Swagger / OpenAPI for Transaction and Activity Monitoring definition **here**.
  </Card>

  <Card title="Postman Collection" icon="book" href="https://drive.google.com/file/d/103az4gnrGJhXTYlYaoIr7WWQ521RUBfN/view?usp=drive_link">
    Download our latest Postman collection **here**.
  </Card>
</CardGroup>


# Manage Internal Blocklist (Blocklist entries)
Source: https://docs.frankieone.com/docs/manage-internal-blocklist



Effectively managing your internal blocklist involves adding and removing profiles or attributes as necessary. Internal blocklist will have these attributes called as “entries” in the Frankie system.

Entries are “rules” that our Customers have setup that tells Frankie system to match with during Blocklist checks.

## Key capabilities

* List and Search

* Add to blocklist

* Remove from blocklist

* View a blocklist entry

* Update a blocklist entry

Access the Blocklist feature by clicking on the blocklist option located at the side navigation.

<Frame>
  <img alt="" />
</Frame>

Some customers might name their Internal Blocklist as something else.

<Frame>
  <img alt="" />
</Frame>

The icon above should be the indicator that it is the blocklist feature.

### Blocklisted attribute

* **Attributes** – These are entries created so that Frankie system will match against it

* **Matched profile** – These are entries created by manually “Add to blocklist” an EXISTING entity

Description and other columns – Entry details upon creation/update.

**Create Blocklist Entry**

Each new potential customer’s details will be compared with all of the profiles in your blocklist.

If a match is found, FrankieOne will block that customer from onboarding pending further review in the portal.

The rules that are used to find a blocklist match are configurable based on your specific business requirements. Speak to customer support to find out more about your blocklist rule matching.

#### Add to blocklist - trigger

<Frame>
  <img alt="" />
</Frame>

#### Add to blocklist - modal

Users can add a blocklist entry by selecting the attributes that suits their need. Attributes available are **Name**, **DoB**, **Phone Number**, **Email**, **Full Address**, **Identity Docs**.

Users can optionally add a Blocklist reason (configured per customer) and a comment.

Users can select multiple reasons.

<Frame>
  <img alt="Single attribute" />
</Frame>

<Frame>
  <img alt="Multiple attributes" />
</Frame>

#### Add to blocklist - loading state

<Frame>
  <img alt="" />
</Frame>

#### Various toast messages

<Frame>
  <img alt="" />
</Frame>

* Blocklist successfully added - no issues

* Blocklist failed to be added -

* Blocklist entry already exists - System found an existing entry that exactly matches the attributes of the entry being added

* Sorry, something went wrong. Please try again or contact support for help. – All other errors

### View and Update Blocklist entry

#### Blocklist entry view - Attribute

<Frame>
  <img alt="" />
</Frame>

View entry modal for entries created from the Blocklist module.

#### Blocklist entry view - Attribute  (Update modal)

<Frame>
  <img alt="" />
</Frame>

<Callout icon="thumbtack">
  Only applicable for Attribute entries.
</Callout>

If the change is updating attributes (values or types) then the system will mark the original entry as deleted. A new entry will be created on its behalf.

If the change is simply updating reasons, system will not create a new entry.

As part of Portal standards, any manual review action will require a **comment**.

#### Blocklist entry view - Matched profile

<Frame>
  <img alt="" />
</Frame>

View entry modal for entries created from “Add to blocklist” an existing entity **(Entity view > Actions > Add to Blocklist)**.

#### Blocklist entry view - Remove from blocklist

<Frame>
  <img alt="" />
</Frame>

<Frame>
  <img alt="" />
</Frame>

#### Blocklist > View entry > Remove from blocklist

As part of Portal standards, any manual review action will require a comment

#### Add to blocklist - loading state

<Frame>
  <img alt="" />
</Frame>

#### Various toast messages

<Frame>
  <img alt="" />
</Frame>

### Search Blocklist Entries

#### Search Blocklist Entries

<Frame>
  <img alt="" />
</Frame>

Users can search on a specific attribute like Name, DoB, Phone Number, Email Full Address, Identity Docs.

#### Search Blocklist Entries by Name

<Frame>
  <img alt="" />
</Frame>

#### Search Blocklist Entries by DoB

<Frame>
  <img alt="" />
</Frame>

#### Search Blocklist Entries by Phone Number

<Frame>
  <img alt="" />
</Frame>

#### Search Blocklist Entries by Email

<Frame>
  <img alt="" />
</Frame>

* Email address

* Email domain

#### Search Blocklist Entries by Address

<Frame>
  <img alt="" />
</Frame>

* Manual Address

* Address Search

#### Search Blocklist Entries by Identity Documents

<Frame>
  <img alt="" />
</Frame>

#### Multiple search criteria

<Frame>
  <img alt="" />
</Frame>

#### Update a search criteria

<Frame>
  <img alt="" />
</Frame>

#### Unable to retrieve default blocklist entries

<Frame>
  <img alt="" />
</Frame>

#### With search result

<Frame>
  <img alt="" />
</Frame>

#### No search result

<Frame>
  <img alt="" />
</Frame>

#### Search error

<Frame>
  <img alt="" />
</Frame>


# Managing your risk configuration
Source: https://docs.frankieone.com/docs/manage-risk-config



The Risk Policy page lets you see your risk model in one place: factors, scoring logic, levels and thresholds. See the exact configuration driving your verification decisions without digging through JSON files or waiting on support.

<Info>
  Only KYC risk factors are visible at the moment (KYB coming soon)
</Info>

<iframe title="Loom video player" />

## Accessing your risk configuration

You can view your account’s risk configuration by clicking **Risk Policy** on the sidebar. The page is only visible to users with any of these roles:

1. Administrator
2. Super Admin
3. Compliance Officer
4. Risk & Compliance Officer\*

<Info>
  **Important:** Only *Risk & Compliance Officers* have the permission to publish configuration changes, which can take effect immediately. Assign this role only to authorised members of your team. [Learn more about user roles and permissions here](https://docs.frankieone.com/docs/manage-user-roles-and-its-permissions-copy).
</Info>

## How to view your risk configuration

All the factors, scores, and values in the page are pulled directly from your account’s live risk configuration. On the top right side, you can also choose to download a PDF version for your reference.

<Frame>
  <img alt="Image" />
</Frame>

1. **Risk level thresholds**
2. **Risk categories**
3. **Risk factor name**
4. **Scoring logic**
5. **Risk factor levels**
6. **Level ranges** (applicable only to specific risk factors)
7. **Risk factor score**

 

For more information about different risk factors, see [**Risk Factors**](https://docs.frankieone.com/docs/risk-factors).

## How to update your risk configuration

You can publish changes to your live risk configuration directly from the Portal. 

1. Click **Edit Risk** on the top right. Only users with the *Risk & Compliance Officer* role will be able to see this button.

<Frame>
  <img alt="Image" />
</Frame>

2. Confirm that you’re authorized to make risk changes.

<Frame>
  <img alt="V2 Risk Edit 1" />
</Frame>

3. In the **Risk factors** tab, you can:
   * Update the score for each risk factor and see its live/current score for reference
   * Update the max values for ranges in specific risk factors like Age of Entity, PEP Count, etc.
   * Set the score to **0** if you prefer to exclude it from your customers' risk assessment

<Frame>
  <img alt="V2 Risk Edit 2" />
</Frame>

4. In the **Thresholds** tab:
   * You can set the max threshold for each risk level. Drag the slider or type the values directly.
   * These thresholds are automatically validated to prevent gaps or overlaps — each level's max must be lower than the next level's min.
   * You can also use the analytics section to see how existing entities are distributed across risk levels and calibrate your thresholds accordingly.

<Frame>
  <img alt="V2 Risk Edit 3" />
</Frame>

5. Click **Save draft** to keep your progress, or **Reset** **changes** to revert all the values to their current live scores.
6. Your changes remain in draft until you click **Publish policy**.

<Frame>
  <img alt="V2 Risk Edit 4" />
</Frame>

<Info>
  **Coming soon**

  * Detailed version history
  * Simulate changes before publishing
</Info>


# Manage User Roles and its Permissions
Source: https://docs.frankieone.com/docs/manage-user-roles-and-its-permissions-copy



To view roles in the FrankieOne Portal, select the **Profile** menu, then select **Settings**.

<Frame>
  <img alt="Settings menu" />
</Frame>

Select the **Role Management** tab. This displays the list of roles available.

<Frame>
  <img alt="Image" />
</Frame>

The default roles are **Administrator**, **Operator**, **Compliance Officer**, **Risk and Compliance Officer**, and **Super Admin**.

By default, all portal users should be able to view an entity and its audit report.

Additionally, they can:

1. Search and filter entities
2. Get workflow event details - check results, risk level
3. Get entity profile information - personal information, identity documents
4. Assign portal users to an entity - including bulk assignment
5. Create and manage custom views
6. See comments

Below is a breakdown of permissions for each default role:

| Permission                                   | Administrator | Operator | Compliance officer | Risk and Compliance officer | Super Admin |
| :------------------------------------------- | :------------ | :------- | :----------------- | --------------------------- | ----------- |
| **View Access**                              |               |          |                    |                             |             |
| Assigned Entities                            |               |          |                    |                             |             |
| Needs Review Entities                        |               |          |                    |                             |             |
| All Entities                                 | ✅             | ✅        | ✅                  | ✅                           | ✅           |
| **Create, Edit, and Download access**        |               |          |                    |                             |             |
| Create and edit entities                     | ✅             | ✅        |                    |                             | ✅           |
| Users and permissions                        | ✅             |          |                    |                             | ✅           |
| Modify AML monitoring                        | ✅             | ✅        |                    |                             | ✅           |
| Manage blocklists                            | ✅             | ✅        |                    |                             | ✅           |
| Manage duplicates                            | ✅             | ✅        |                    |                             | ✅           |
| Add Entity Comments                          | ✅             | ✅        |                    |                             | ✅           |
| Manage Documents                             | ✅             | ✅        |                    |                             | ✅           |
| Modify risk level                            | ✅             | ✅        |                    |                             |             |
| Modify transaction and entity alert statuses | ✅             | ✅        |                    |                             |             |
| **Reports**                                  |               |          |                    |                             |             |
| General Reports                              | ✅             |          | ✅                  | ✅                           | ✅           |
| Organisation Reports                         | ✅             | ✅        |                    |                             | ✅           |
| Customer Records                             |               |          |                    |                             | ✅           |
| **Configurations**                           |               |          |                    |                             |             |
| View Risk Configuration                      | ✅             |          | ✅                  | ✅                           | ✅           |
| Manage Risk Configuration                    |               |          |                    | ✅                           |             |
| **Settings**                                 |               |          |                    |                             |             |
| Account                                      | ✅             |          |                    |                             | ✅           |

## Permissions

### View Access

#### Assigned entities

Allow users to access only the entities assigned to them.

#### Needs review entities

Allow users to only access the Needs Review page, which includes all entities with Failed, Manually Failed, Unchecked, or Needs Attention status.

#### All entities

Allow users to access all entities.

### Create, Edit, and Download Access

#### Create and edit entities

Ability to create, edit, and verify individuals and organisations.

* Manage entities
  * Create and verify a new entity
  * Archive/Unarchive an entity
  * Assign the user to an entity
  * Update and/or verify an existing entity
  * Manual KYC for an existing entity
  * Electronic KYC for an existing entity
* Review entities
  * Allow override of workflow event status
  * Retrigger checks by clicking the Verify entity button
  * Update AML alert status
  * Override Document check results
  * Override Biometrics check results
  * Re-send links for re-verification
* Download the entities table as a CSV file
* Leave comments on manual review actions
* Resolve Visa check issues

#### Modify AML monitoring

Ability to enable or disable AML PEP, sanctions, adverse media and watchlist monitoring on entities.

#### Manage blocklists

Ability to manage blocklist entries and blocklist assignments.

* Create/Update/Remove blocklist entries
* Add an existing entity to a blocklist
* Remove an existing entity from a blocklist

#### Manage duplicates

Ability to resolve duplicate issues on entity records.

#### Add entity comments

Ability to add comments on an entity profile.

#### Manage documents

Ability to add, download, delete, and change the status of supporting documents.

#### Modify risk level

Ability to manually override an entity's risk level.

#### Modify transaction and activity alert statuses

Ability to resolve transaction and activity alerts related to AML, Fraud, and Behaviour issues.

### Reports

#### General reports

Ability to generate and download general reports such as audit reports and individual verification reports.

#### Organisation reports

Ability to generate and download organisation reports.

#### Customer records

Ability to generate and download customer PII extract reports.

### Configurations

#### View risk configuration

Ability to view and export this account's risk factors and rules.

#### Manage risk configuration

Ability to view, export, and edit this account's risk scoring logic and risk level thresholds, and to restore or publish a new version.

### Settings

#### Users and permissions

Ability to manage user accounts and role permissions.

* See all available roles
* See all users
* Create new user
* Edit existing user
* Delete a user
* Lock a user

#### Account

Ability to manage all account settings.

* View and update customer account data

### SSO

To learn more about [Single Sign-On (SSO)](/docs/configuring-sso-with-the-frankieone-portal), please refer to the documentation found [here](/docs/configuring-sso-with-the-frankieone-portal).


# Manage Users
Source: https://docs.frankieone.com/docs/manage-users



To manage roles in the FrankieOne Portal, select the **Profile** menu, then select **Settings**.

<Frame>
  <img />
</Frame>

From the **Settings** page, select **User Management**.

<Callout icon="bell">
  ##### Important

  For security, users in a **child account** cannot view or assign users from the parent account. This restriction is enabled for all customers by default.
  If your business case requires parent-level user management from a child account, contact [FrankieOne Support <Icon icon="arrow-up-right-from-square" />](https://frankieone.atlassian.net/servicedesk/customer/portal/3/group/17) to discuss activating the feature flag for your environment.
</Callout>

## User Management

The User Management tab displays a list of all users currently registered in your FrankieOne portal and the roles assigned to them.

<Frame>
  <img />
</Frame>

## Add a New user

Click the **Add new user** button and enter the name and email address.

<Frame>
  <img />
</Frame>

In the **Add new user** setup, ensure that at least one role is assigned to the new user, otherwise they won't be able to access the portal.

<Frame>
  <img />
</Frame>

Select the **Add user** button to create the new user.

<Frame>
  <img />
</Frame>

An email will be sent to the user with information on setting their password.

## Lock a User

Locking a user prevents the user from having access to the FrankieOne portal, however, it leaves their profile in the FrankieOne system for audit purposes.

<Frame>
  <img />
</Frame>

## Reset the Password

To send a reset password link to a user, click the lock icon associated with that user. This will email a link to the user with instructions on resetting their password.

<Frame>
  <img />
</Frame>


# Managing Duplicates
Source: https://docs.frankieone.com/docs/managing-duplicates



### Video Guide

<iframe />

## What are duplicates

Duplicates are two or more customer profiles that the portal flags as belonging to the same individual. The portal automatically looks for matching data points, such as:

* Document ID and date of birth
* Date of birth and family (last) name

Resolving duplicates prevents:

* Inaccurate reporting and analytics
* Double-handling of onboarding reviews
* Compliance risks linked to multiple identities for one person

<Callout icon="thumbtack">
  If duplicates are not yet enabled in your workspace, contact FrankieOne Support to switch the feature on.
</Callout>

## Where to find Duplicates

1. Sign in to FrankieOne Portal v2.
2. Open **Profiles › Entities**.
3. Look for the **Duplicate** badge in the **Onboarding Summary** column.
4. Select the customer row to open the profile.
5. In the profile header, choose the **Duplicates** tab to view side-by-side comparisons of the potential match.

You need the “Show duplicate page” and “Fetch duplicate entities” permissions to view this tab. Team admins can assign these in **Settings › Users › Roles**.

## How to resolve duplicates

| Action                  | Result                                                                                            |
| :---------------------- | :------------------------------------------------------------------------------------------------ |
| Mark **True Positive**  | Confirms the profiles belong to the same person. The duplicate record is blocked from onboarding. |
| Mark **False Positive** | Confirms the profiles are different people. Both records remain active.                           |

Follow these steps:

1. In the **Duplicates** tab, review the side-by-side data (name, document IDs, addresses, dates of birth).
2. Select **Change match status**.
3. Choose **True Positive** or **False Positive**.
4. Add a short explanatory comment—this is stored in the audit log.
5. Confirm.

After a **True Positive** decision, only the primary profile stays active. After a **False Positive** decision, the duplicate flag is cleared and no further action is required.

## FAQ

**Why did the portal miss a duplicate?** The match engine relies on the data you collect. Typos or missing fields can stop automatic detection. Edit the profile and re-run checks if needed.

**Can I customise the matching rules?** Yes. Contact Support to request additional or different matching criteria (for example, email + phone).

**Who can resolve duplicates?** Any user role that includes the “Set entity as duplicated” permission.

For more information about duplicates, see [Duplicate checks](/docs/duplicate-checks).


# Manual KYC Verification
Source: https://docs.frankieone.com/docs/manual-kyc-verification



Manual KYC does **NOT** check with our partners, this is purely an internal check and requires staff to attest they have cited enough evidence as per their own internal policies to “pass” a customer.

This option is generally used when the electronic KYC attempts have failed, but you have gained sufficient evidence and want to proceed to onboard this customer. This requires you to provide sufficient evidence to support identity verification.

## Perform manual KYC

To perform manual KYC create a new entity.

### Enter the necessary information

<Steps>
  <Step title="Create New Profile">
    Select the **New entity** button, then select **Create manually** to open the **Create new entity profile** page.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Select the Workflow">
    Select the workflow to run on the entity. The workflow will be used to perform the manual KYC verification.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Enter Entity Information">
    Enter the necessary information for the entity.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Configure ID Documents">
    In the **ID Documents** section, clear the **eKYC** button selection.

    <Frame>
      <img />
    </Frame>

    This will enable **mKYC**. Select the **Add another document** button to enter identification documents.
  </Step>

  <Step title="Add Document Details">
    Select the country of issuance for the ID document from the **Country** drop-menu, and the document type from the **ID Type** drop-down menu.

    <Frame>
      <img />
    </Frame>

    <Callout icon="thumbtack">
      ##### Biometrics Notes

      Please provide **one** of the following combinations of documents to fulfill manual KYC requirements:

      * At least 1 Primary Photographic ID document,
      * At least 2 Primary Non-photographic ID documents, or
      * 1 Primary Non-photographic ID document and 1 Secondary ID document.
    </Callout>

    Additional data entry fields will be displayed depending on the ID type. The following screenshot shows the detail fields for an Australian Driver Licence (Victoria).

    <Frame>
      <img />
    </Frame>

    The following screenshot displays the detail fields for an Australian passport.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Upload Documents">
    Drag and drop a copy of the required document into the image box. Alternatively, you can select the image box, which will open the file browser and allow you to locate the file to upload.

    <Callout icon="bell">
      ##### Important

      FrankieOne keeps every version of an uploaded document, but only the latest version is available in the Portal and API. This design ensures operators make decisions using the most current evidence and avoids confusion that could occur if outdated files were shown, without their related verification results.

      Building a full historical view that links each document version to its outcome is not supported today.

      If you need to override a decision, always use the latest document, not an older version.
    </Callout>
  </Step>

  <Step title="Manage Documents">
    To remove an ID document, hover on its row and select **Remove ID**.

    To update the uploaded document, hover on its preview image and select either **View** to see a larger version of the uploaded document, or **Replace** to browse and select the replacement document.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Add consent">
    You must consent to manual KYC using the information and documents you provided.

    Select the **Consent** tick box to attest that you have reviewed the customer identity documents and uploaded true copies of the reviewed documents for manual KYC verification.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step title="Add comments">
    Provide additional context and information for performing manual KYC on this entity.

    <Frame>
      <img />
    </Frame>

    The comments field is required.
  </Step>

  <Step title="Save and verify">
    To complete the manual KYC on this entity, select **Save & verify**.

    Alternatively, select **Save changes** to save the submitted information into the system. This allows you to return to the entity later to complete the manual KYC.

    The entity page for the new entity opens.
  </Step>
</Steps>

## Acceptable ID documents

### Primary Photographic

ID types with a photo such as driver's licence or passport are considered primary photographic ID documents.

### Primary Non-Photographic

ID types without a photo such as Medicare or birth certificate are considered primary non-photographic ID documents.

### Secondary

It is possible to provide Secondary types of ID to support the manual verification. ID documents such as Tax IDs can be used.


# Monitoring
Source: https://docs.frankieone.com/docs/monitoring



## What is monitoring?

This capability allows you to continuously check an entity’s profile or activity. Monitoring is allowed for AML checks.

## Enabling monitoring to an entity

### Who can toggle and resolve monitoring (Permissions)?

Operators and Administrators have permission to “Modify entity monitoring.” If you need access, please contact your administrator.

## Understanding Monitoring checks

### Entity view

From the entity view, workflow events will show all the workflows executed in the **Workflow navigation** including the **Monitoring workflow**. If your account has the monitoring feature enabled and has the monitoring workflows completely setup, you will be to see a similar screen below.

<img alt="" />

A banner is displayed indicating monitoring was automatically enabled because the entity has passed onboarding.

### AML monitoring

This only applies to onboarding workflows with AML step/checks configured. By default, when an onboarding workflow has passed the Monitoring workflow’s AML monitoring will be automatically enabled. Reach out Frankie support for any customisation.

<img alt="" />

When the AML service received updates via the monitoring webhook, the AML monitoring section will reflect the latest AML alerts accordingly.

<img alt="" />

When an entity has been verified with onboarding workflow without any AML checks, AML monitoring is not allowed.

<img alt="" />

## Manually toggle monitoring

When the system detected that an onboarding workflow has been manually passed or failed, a banner suggesting to toggle on or off the monitoring will be displayed.

<img alt="" />

A banner is displayed suggesting monitoring can be toggled on.

<img alt="" />

A banner is displayed suggesting monitoring can be toggled off.

Alternatively, viewing the Monitoring workflow and toggling on or off a check is also possible. Below is an example of a Monitoring workflow’s AML monitoring that was manually toggled off.

<img alt="" />

User manually toggled off the AML monitoring after getting alerts.

## Reviewing each monitoring check

When all of the monitoring checks have no outstanding issues or have been resolved, “No issues” will be displayed as an event status.

<img alt="" />

All monitoring checks have no issues found.

## Unauthorised users

A user without monitoring privileges will be unable to manage monitoring.

<img alt="" />

Tooltip is displayed indicating only authorised users can toggle monitoring.

### Other states

#### Unchecked entity

<img alt="" />

#### Customer account without monitoring workflows

<img alt="" />

Users can see only the Onboarding workflows.


# Multi-factor Authentication
Source: https://docs.frankieone.com/docs/multi-factor-authentication



## Introduction

### What's MFA?

Multi-factor authentication (MFA) is an authentication method that requires the user to provide two or more verification factors to gain access to a resource such as an application, online account, or a VPN. MFA is a core component of a strong identity and access management (IAM) policy.

A factor in authentication is a way of confirming your identity when you try to sign in. For example, a password is one kind of factor, it’s a thing you know. The three most common kinds of factors are:

* Something you know - Like a password, or a memorized PIN.
* Something you have - Like a smartphone, or a secure USB key.
* Something you are - Like a fingerprint, or facial recognition.

### Benefits of MFA

Adding MFA to login screens can provide several benefits, such as:

* Reducing fraud and identity theft by making it harder for hackers to access accounts with stolen passwords.
* Increasing customer trust by showing that their data is secure and protected.
* Achieving compliance with regulations and standards that require MFA for certain types of data or transactions.
* Reducing operating costs by minimizing the need for password resets, help desk calls, and breach remediation.
* Streamlining safe mobile transactions by enabling users to authenticate with their smartphones or other devices.
* Preventing password fatigue by allowing users to sign in with fewer passwords or no passwords at all.
* Simplifying the login process by offering users convenient and user-friendly options for authentication

## Enabling multi-factor authentication in the portal

To secure your account with MFA, you can enable the feature from the portal. Once you're logged in, select the **Profile** menu, then **Settings**.

<img alt="" />

In the **Settings** page, select the **Enable MFA** button to open the **Enable multi-factor authentication** modal.

<img alt="" />

Select the additional factor for authenticating your login to your account. Please note that you can only select to receive the security code from an authentication app or in your email and not both.

<Frame>
  <img alt="Enable multi-factor authentication modal." />
</Frame>

### Authentication app

If you selected to use an authentication app for MFA, a QR code or key will be displayed on the **Setting up MFA with an authentication app** modal.

<Frame>
  <img alt="The Setting up MFA with an authentication app modal." />
</Frame>

Scan the QR code using your preferred authentication app, or you can also enter the provided key.

<Frame>
  <img />
</Frame>

Once the QR code has been accepted and registered on your authentication app, it will generate a 6-digit security authentication code. Copy that code and enter it in the provided field in the **Setting up MFA with an authentication app** modal in the portal.

<Frame>
  <img alt="Enter the generated code from the authentication app." />
</Frame>

Select **Verify**. A new modal screen will open and provide you with your recovery codes. Make sure to follow the provided instructions and keep these codes safe and secure.

<img />

<Info>
  Secure your codes

  If you lose access to your authentication app, the recovery codes will be used to authenticate your login. If you lose access to both your authentication app and the recovery apps, you will lose access to your account. If this happens, contact your support team. For users with admin roles, contact [FrankieOne <Icon icon="arrow-up-right-from-square" />](https://www.frankieone.com/contact-us).
</Info>

Once you're done securing your recovery codes, select **Done**. An email will also be sent to your registered email address to inform you that you have enabled multi-factor authentication.

<Frame>
  <img alt="Sample email confirming MFA is enabled for account." />
</Frame>

### Email

If you selected to receive your authentication codes through email, the **Setting up MFA with email** will open.

<Frame>
  <img alt="The 'Setting up MFA with email' modal." />
</Frame>

Click **Next** to receive an authentication code in your email inbox.

<Frame>
  <img alt="Email with the 6-digit authentication code." />
</Frame>

Copy the 6-digit authentication code and enter it in the provided field in the **Enter the 6-digit authentication code** modal in the portal.

<Frame>
  <img alt="The 'Enter the 6-digit authentication code' modal." />
</Frame>

If you don't receive an email with the 6-digit code within 5 minutes, select **Resend code** to request a new one.

<Info>
  Resend code limit

  Please note that you can only request a new code 5 consecutive times per session. Afterwards, this option will be disabled for 30 minutes. Try again after the hold period, and make sure to check your inbox and spam folder for the email with the code.
</Info>

<Frame>
  <img alt="Resend code limit." />
</Frame>

Select **Verify**. A confirmation modal will appear to let you know that multi-factor authentication is now enabled for your account.

<Frame>
  <img alt="Multi-factor authentication is enabled." />
</Frame>

Select **Done**. An email will also be sent to your registered email address to inform you that you have enabled multi-factor authentication.

<Frame>
  <img alt="Sample email confirming MFA is enabled for account." />
</Frame>

Additionally, a pop-up notification will appear on the lower-right corner of the portal to let you know that multi-factor authentication has been enabled.

<Frame>
  <img alt="Pop-up notification when MFA is enabled." />
</Frame>

## Managing multi-factor authentication

Once MFA has been activated in your account, you can also disable it, if needed. One example would be when you need to change the MFA method from authentication app to email, or the other way around.

To disable MFA for your account, select **Disable MFA** on the **Settings** page, **Personal** tab.

<Frame>
  <img alt="Personal tab in Settings page." />
</Frame>

A modal appears to warn you about disabling MFA.

<Frame>
  <img alt="Disable multi-factor authentication modal." />
</Frame>

If you are sure you want to disable MFA, select **Confirm**. The feature will be disabled and a pop notification will appear on the lower-right corner of the page.

<Frame>
  <img alt="MFA has been disabled." />
</Frame>

An email will also be sent to your registered email confirming you have disabled MFA.

<Frame>
  <img alt="Confirmation email that MFA has been disabled for your account." />
</Frame>

### Checking users with MFA

If you have an admin account, you can check which users have MFA enabled for their accounts. This can be important if part of your security policy is ensuring all users have MFA enabled.

To check if MFA is enabled for users, visit the **User Management** tab, and check the column **MFA Status**. Users with MFA enabled will be marked **Enabled**, and those that don't will be marked **Disabled**.

<Frame>
  <img alt="User Management tab in the Settings page." />
</Frame>


# Multiple Workflows
Source: https://docs.frankieone.com/docs/multiple-workflows

Workflows in V2 are structured sequences of compliance checks and decisions that can be customized to suit an organization's specific requirements.

Workflows in V2 are structured sequences of compliance checks and decisions that can be customized to suit an organization's specific requirements. Each workflow consists of various steps that perform specific functions, from KYC verification to risk assessment.

At its core, workflows are sequences of steps that orchestrate compliance processes according to specific business needs. This is very different to entity profiles and recipes in v1 where composability and control over the flow was limited.

## Entity View

To learn more about the **Entity View**, visit [Entity View](/docs/overview)

### Reviewing an entity

* **Workflow events** - displays the workflow execution result which is a comprehensive result of all the all steps (checks) and outcome:

  * Step results capture specific verification activities

  * Process results contain detailed provider-specific outcomes

  * Process results are tied to the entity, not the workflow execution

  * Process results remain valid for future workflow executions unless they age out or are manually invalidated

* **Profile** - displays information that the was able to capture and store since the entity’s creation

* **Audit report** - captures important system events in a well-structured format. It serves as a comprehensive record of actions performed on customer data, helping to maintain transparency and accountability.

## Multiple workflows

### User Interface

<Frame>
  <img alt="" />
</Frame>

After selecting the entity from the Entities list, the Entity View is displayed.
Under **Workflow events** tab, the results of the workflows execution for that entity are displayed. Refer to the section on **Reviewing an entity** above for more context on the content of the Workflow event tab.

Selecting a workflow on the lefthand menu loads the information about that workflow's execution result.

You can perform several actions from the Workflow events tab:

* Select the **Risk score** button to view the risk score breakdown.
* Select the **Re-run** button to run the selected workflow again.
* Update the status by selecting the appropriate one from the Workflow status dropdown.

You can expand or collapse the lefthand menu to display the workflow event results optimally.

### Scenarios

#### Customer account is not configured to have multiple workflows

<Frame>
  <img alt="" />
</Frame>

On a customer configuration level, multiple workflows feature is not configured.

#### Customer account does not have a different workflow

When the same workflow is executed again, the Attempts badge will be increased

Portal users will be able to see the multiple workflows navigation when they’ve ran a different workflow (see following scenario).

#### Portal users decided to run another workflow

<Frame>
  <img alt="" />
</Frame>

1. New workflow navigation – see the latest and previous workflow executions for an entity.

2. Selecting a workflow would display the results of the workflow execution.

#### Entity is not yet verified

Unverified entities will see the following screen:

<Frame>
  <img alt="" />
</Frame>

A yellow warning banner is displayed with the text, "**No workflow checks to show yet, please verify this profile.**
Please manually complete and verify this entity to see workflow events."

## Assign users to an entity

To assign a user to a customer profile, locate the Assignee at top-right corner of the Entity View then select the icon beside it.

Selecting will allow you to search for the users to assign  the entity with. “Assign to me” is available as a action. By default, entities you created will be assigned to you.

<Frame>
  <img alt="" />
</Frame>

## Change Entity Workflow

To learn more about the changing an entity's workflow, visit [Change a Entity's workflow](/docs/change-entity-workflow).

## Manage Entity State

To learn more about managing an entity's state, visit [How to archive and deactivate an entity in the Portal](/docs/how-to-archive-and-deactivate-a-customer-in-the-portal).

## Comments

To learn more about comments, visit [Viewing comments](/docs/viewing-comments).


# Native Integration
Source: https://docs.frankieone.com/docs/native-integration

Learn how to integrate FrankieOne's Web SDK into native mobile apps via WebView. This approach lets you run your OneSDK web implementation within a native WebView container, combining web and native functionality.

<Callout icon="bell">
  ##### Prerequisites

  * You have installed OneSDK in your web app
  * Android/iOS development experience
  * Your Native App has Camera, Microphone, and Location permissions
  * Your Web App is live
</Callout>

## Implementation Steps

<Steps>
  <Step title="Setup Web WebAppInterface">
    First, ensure your web app is properly configured with OneSDK:

    ```html theme={null}
    <!-- Add our SDK to your web app -->
    <script>
        // Initialize OneSDK
        const oneSdk = await OneSDK({
    			session: {
    				token: YOUR_TOKEN
    			},
    			// Additional configuration options
        });

    		// rest of your OneSDK Implementation
    </script>
    ```
  </Step>

  <Step title="Implement in Native">
    <Tabs>
      <Tab title="Android">
        #### Permissions Setup

        First, add required permissions to your `AndroidManifest.xml`:

        ```xml theme={null}
        <?xml version="1.0" encoding="utf-8"?>
        <manifest xmlns:android="http://schemas.android.com/apk/res/android">
            <!-- Camera permissions -->
            <uses-permission android:name="android.permission.CAMERA" />
            <uses-feature android:name="android.hardware.camera" />
            
            <!-- Microphone permissions -->
            <uses-permission android:name="android.permission.RECORD_AUDIO" />
            
            <!-- Location permissions -->
            <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
            <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
        </manifest>
        ```

        #### WebView Implementation

        Add WebView support with device access permissions:

        ```kotlin theme={null}
        class WebViewActivity : AppCompatActivity() {
            private lateinit var webView: WebView
            private val PERMISSION_REQUEST_CODE = 1234

            override fun onCreate(savedInstanceState: Bundle?) {
                super.onCreate(savedInstanceState)
                setContentView(R.layout.activity_webview)

                // Request permissions
                requestPermissions()

                webView = findViewById(R.id.webView)
                
                // Enable JavaScript
                webView.settings.apply {
                    javaScriptEnabled = true
                    domStorageEnabled = true
                    allowFileAccess = true
                    allowContentAccess = true
                    mediaPlaybackRequiresUserGesture = false  // Allow media autoplay
                }

                // Configure WebChromeClient for handling permissions
                webView.webChromeClient = object : WebChromeClient() {
                    // Camera permission request
                    override fun onPermissionRequest(request: PermissionRequest) {
                        runOnUiThread {
                            request.grant(request.resources)
                        }
                    }

                    // Geolocation permission request
                    override fun onGeolocationPermissionsShowPrompt(
                        origin: String,
                        callback: GeolocationPermissions.Callback
                    ) {
                        callback.invoke(origin, true, false)
                    }
                }

                // Load your web app
                webView.loadUrl("https://your-webapp-url.com")
            }

            private fun requestPermissions() {
                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
                    requestPermissions(
                        arrayOf(
                            Manifest.permission.CAMERA,
                            Manifest.permission.RECORD_AUDIO,
                            Manifest.permission.ACCESS_FINE_LOCATION
                        ),
                        PERMISSION_REQUEST_CODE
                    )
                }
            }

            override fun onRequestPermissionsResult(
                requestCode: Int,
                permissions: Array<String>,
                grantResults: IntArray
            ) {
                super.onRequestPermissionsResult(requestCode, permissions, grantResults)
                when (requestCode) {
                    PERMISSION_REQUEST_CODE -> {
                        if (grantResults.isNotEmpty() && 
                            grantResults.all { it == PackageManager.PERMISSION_GRANTED }) {
                            // All permissions granted, proceed with WebView setup
                        } else {
                            // Handle permission denial
                        }
                    }
                }
            }
        }
        ```
      </Tab>

      <Tab title="iOS">
        #### Permissions Setup

        First, add required permissions to your `Info.plist`:

        ```xml theme={null}
        <?xml version="1.0" encoding="UTF-8"?>
        <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
        <plist version="1.0">
        <dict>
            <!-- Camera permissions -->
            <key>NSCameraUsageDescription</key>
            <string>We need access to your camera for [YOUR REASON]</string>
            
            <!-- Microphone permissions -->
            <key>NSMicrophoneUsageDescription</key>
            <string>We need access to your microphone for [YOUR REASON]</string>
            
            <!-- Location permissions -->
            <key>NSLocationWhenInUseUsageDescription</key>
            <string>We need access to your location for [YOUR REASON]</string>
            <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
            <string>We need access to your location for [YOUR REASON]</string>
        </dict>
        </plist>
        ```

        #### WebView Implementation

        Implement WebView with device access permissions:

        ```swift theme={null}
        import WebKit
        import AVFoundation
        import CoreLocation

        class WebViewController: UIViewController, WKNavigationDelegate, CLLocationManagerDelegate {
            var webView: WKWebView!
            private let locationManager = CLLocationManager()
            
            override func viewDidLoad() {
                super.viewDidLoad()
                
                // Configure WebView
                let configuration = WKWebViewConfiguration()
                configuration.allowsInlineMediaPlayback = true
                
                // Configure camera and microphone access
                configuration.mediaTypesRequiringUserActionForPlayback = []
                
                // Add script for location access
                let contentController = configuration.userContentController
                contentController.add(self, name: "locationHandler")
                
                webView = WKWebView(frame: view.bounds, configuration: configuration)
                webView.navigationDelegate = self
                webView.configuration.allowsInlineMediaPlayback = true
                
                // Set up location manager
                locationManager.delegate = self
                locationManager.desiredAccuracy = kCLLocationAccuracyBest
                
                view.addSubview(webView)
                
                // Request permissions
                requestPermissions()
                
                // Load your web app
                if let url = URL(string: "https://your-webapp-url.com") {
                    let request = URLRequest(url: url)
                    webView.load(request)
                }
            }
            
            private func requestPermissions() {
                // Request camera and microphone permissions
                AVCaptureDevice.requestAccess(for: .video) { granted in
                    if granted {
                        // Camera permission granted
                    }
                }
                
                AVCaptureDevice.requestAccess(for: .audio) { granted in
                    if granted {
                        // Microphone permission granted
                    }
                }
                
                // Request location permission
                locationManager.requestWhenInUseAuthorization()
            }
            
            // Handle location updates
            func locationManager(_ manager: CLLocationManager, 
                               didUpdateLocations locations: [CLLocation]) {
                guard let location = locations.last else { return }
                let script = "updateLocation(\(location.coordinate.latitude), \(location.coordinate.longitude))"
                webView.evaluateJavaScript(script, completionHandler: nil)
            }
        }

        // Extend for WKScriptMessageHandler to handle location requests
        extension WebViewController: WKScriptMessageHandler {
            func userContentController(_ userContentController: WKUserContentController,
                                     didReceive message: WKScriptMessage) {
                if message.name == "locationHandler" {
                    locationManager.startUpdatingLocation()
                }
            }
        }
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Establishing Communication Between Native and Web Layers

<Tabs>
  <Tab title="Android">
    To enable communication from web to native:

    ```kotlin theme={null}
    class WebAppInterface(private val context: Context) {
        @JavascriptInterface
        fun onEvent(data: String) {
            // Handle events from web app
        }
    }

    // Add the interface to WebView
    webView.addJavascriptInterface(WebAppInterface(this), "Android")
    ```
  </Tab>

  <Tab title="iOS">
    Enable web-to-native communication in iOS:

    ```swift theme={null}
    // Configure message handler
    configuration.userContentController.add(self, name: "iOSNative")

    // Handle messages
    extension WebViewController: WKScriptMessageHandler {
        func userContentController(_ userContentController: WKUserContentController,
                                 didReceive message: WKScriptMessage) {
            if message.name == "iOSNative" {
                // Handle message from web app
            }
        }
    }
    ```
  </Tab>
</Tabs>


# Needs review
Source: https://docs.frankieone.com/docs/needs-review



The Needs review list contains all profiles that require manual review.

<img />

| **Label**           | **Description**                                                                                                    |
| :------------------ | :----------------------------------------------------------------------------------------------------------------- |
| Name                | The customer’s full name as collected on the application. This name is used in KYC verification and AML screening. |
| Latest Event Status | Displays the status of executed workflow event.                                                                    |
| Issues              | Displays any issues found in the customer application.                                                             |
| Risk Level          | Risk level of customer.                                                                                            |
| Created             | Display the age of the customer application.                                                                       |
| Updated             | Displays when the last change was made to the customer application.                                                |
| Latest Workflow     | Displays the workflow used                                                                                         |
| Assignee            | Displays the user assigned to the customer application for review and decisioning.                                 |

## List Filtering & Sorting

You can also filter the entities displayed in the entities table using the filtering options available under the search bar.

<img alt="" />

### Filter by event status

Use the **event status** dropdown menu to select the status types of the entities to display.

<img alt="" />

Once you've selected the status types to display, select **Apply**. Select **Clear** to unselect all the status type.

### Filter by issue type

Use the **Issues** dropdown menu to select the issue types of the entities to display.

Once you've selected the issue types to display, select **Apply**. Select **Clear** to unselect all the issue types.

<img />

### Filters overview modal

Select the **Filters** button to open the **Filters** modal. Using the Filters modal, you can view all the possible filters that can be applied to the entities displayed in the entities table.

<img alt="" />

The filters you can select are categorized according to the following:

* Entity status
* Issue
* Risk level
* Created date
* Last updated
* Workflow
* Event status
* Assignee

Select the filter criteria you prefer, and then select **Apply filters** to enable those filters. To start over, select the **Clear all** button to remove your selection.

### Sorting entities

Select the sorting icons (up and down arrows) beside the **CREATED** and **UPDATED** column headers to sort the entities in the table. A single blue arrow highlights the current sort direction (ascending or descending):

* A single blue up arrow means the entities are displayed in ascending order.
* A single blue down arrow means the entities are displayed in descending order.


# Next.js
Source: https://docs.frankieone.com/docs/next-js-onesdk-integration

This guide walks you through integrating OneSDK with Next.js, providing you with a solid foundation for building secure and efficient KYC workflows.

## Quick Start Video

<div>
  <iframe />
</div>

## Setup Instructions

<Steps>
  <Step title="Create Next.js Project">
    ```bash theme={null}
    npx create-next-app@latest my-next-app
    cd my-next-app
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    npm install
    npm install @frankieone/one-sdk
    ```
  </Step>

  <Step title="Configure Environment">
    Create a `.env.local` file with your OneSDK credentials:

    ```env theme={null}
    NEXT_PUBLIC_CUSTOMER_ID=your_customer_id
    NEXT_PUBLIC_API_KEY=your_api_key
    NEXT_PUBLIC_CHILD_ID=your_child_id  # Optional
    ```
  </Step>
</Steps>

## Implementation Guide

<AccordionGroup>
  <Accordion title="1. Create OneSDK Hook">
    Create a new file `hooks/useOneSDK.js`:

    ```javascript theme={null}
    "use client";
    import OneSDK from "@frankieone/one-sdk";
    import { useEffect, useRef, useState } from "react";

    const useOneSDK = ({ config }) => {
      const [oneSDKInstance, setOneSDKInstance] = useState(null);
      const [error, setError] = useState(null);
      const [loading, setLoading] = useState(false);
      const initializedRef = useRef(false);

      const generateToken = async () => {
        try {
          const credentials = btoa(
            `${process.env.NEXT_PUBLIC_CUSTOMER_ID}:${process.env.NEXT_PUBLIC_API_KEY}`
          );
          
          const response = await fetch(
            "https://backend.latest.frankiefinancial.io/auth/v2/machine-session",
            {
              method: "POST",
              headers: {
                authorization: `machine ${credentials}`,
                "Content-Type": "application/json",
              },
              body: JSON.stringify({
                permissions: {
                  preset: "one-sdk",
                  reference: `demo-${new Date().toISOString()}`,
                },
              }),
            }
          );
          
          return await response.json();
        } catch (error) {
          setError(error.message);
          return null;
        }
      };

      const initializeSDK = async () => {
        setLoading(true);
        try {
          const token = await generateToken();
          if (!token) return;

          const instance = await OneSDK({
            session: token,
            ...config,
          });
          
          setOneSDKInstance(instance);
        } catch (error) {
          setError(error.message);
        } finally {
          setLoading(false);
        }
      };

      useEffect(() => {
        if (!initializedRef.current) {
          initializeSDK();
          initializedRef.current = true;
        }
      }, [config]);

      return { oneSDKInstance, error, loading };
    };

    export default useOneSDK;
    ```
  </Accordion>

  <Accordion title="2. Create End-to-End Component">
    Create a new component file `components/EndToEnd.js`:

    ```javascript theme={null}
    "use client";
    import { useEffect } from "react";
    import useOneSDK from "../hooks/useOneSDK";

    const EndToEnd = () => {
      const config = {
        mode: "development",
        recipe: {
          form: {
            provider: {
              name: "react",
            },
          },
        },
      };

      const { oneSDKInstance, error, loading } = useOneSDK({ config });

      const initializeComponents = () => {
        if (!oneSDKInstance) return;

        // Initialize Components
        const components = {
          welcome: oneSDKInstance.component("form", {
            name: "WELCOME",
            type: "manual",
          }),
          consent: oneSDKInstance.component("form", {
            name: "CONSENT"
          }),
          document: oneSDKInstance.component("form", {
            name: "DOCUMENT",
            showPreps: true,
          }),
          biometrics: oneSDKInstance.component("biometrics"),
        };

        // Mount Welcome Component
        components.welcome.mount("#form-container");

        // Setup Event Handlers
        setupEventHandlers(components);
      };

      const setupEventHandlers = (components) => {
        const { welcome, consent, document, biometrics } = components;

        welcome.on("form:welcome:ready", () => {
          consent.mount("#form-container");
        });

        consent.on("form:consent:ready", () => {
          document.mount("#form-container");
        });

        // Add more event handlers as needed
      };

      useEffect(() => {
        if (oneSDKInstance) {
          initializeComponents();
        }
      }, [oneSDKInstance]);

      if (loading) {
        return <div>Loading OneSDK...</div>;
      }

      if (error) {
        return <div>Error: {error}</div>;
      }

      return <div id="form-container" />;
    };

    export default EndToEnd;
    ```
  </Accordion>

  <Accordion title="3. Add Component to Page">
    Update your page file (e.g., `app/page.js`):

    ```javascript theme={null}
    import EndToEnd from '../components/EndToEnd';

    export default function Home() {
      return (
        <main>
          <EndToEnd />
        </main>
      );
    }
    ```
  </Accordion>
</AccordionGroup>

## Component Configuration

<Tabs>
  <Tab title="Welcome Form">
    ```javascript theme={null}
    const welcome = oneSDKInstance.component("form", {
      name: "WELCOME",
      type: "manual",
      descriptions: [
        { label: 'Welcome to our KYC process', style: {} },
        { label: 'Please follow the steps to verify your identity', style: {} },
      ],
    });
    ```
  </Tab>

  <Tab title="Document Form">
    ```javascript theme={null}
    const document = oneSDKInstance.component("form", {
      name: "DOCUMENT",
      showPreps: true,
      // Additional configuration options
    });
    ```
  </Tab>

  <Tab title="Biometrics">
    ```javascript theme={null}
    const biometrics = oneSDKInstance.component("biometrics", {
      // Add your biometrics configuration here
    });
    ```
  </Tab>
</Tabs>

## Event Handling

<AccordionGroup>
  <Accordion title="Form Events">
    ```javascript theme={null}
    // Welcome Form Events
    welcome.on("form:welcome:ready", () => {
      // Handle welcome form ready
    });

    welcome.on("form:welcome:failed", () => {
      // Handle welcome form failure
    });

    // Document Form Events
    document.on("form:document:ready", async ({ inputInfo }) => {
      // Handle document form ready
      const docType = inputInfo.documentType;
      // Initialize OCR component
    });
    ```
  </Accordion>

  <Accordion title="Biometrics Events">
    ```javascript theme={null}
    biometrics.on("detection_failed", () => {
      // Handle failed detection
    });

    biometrics.on("processing", () => {
      // Handle processing state
    });

    biometrics.on("results", (result) => {
      // Handle biometrics results
    });
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

<Columns>
  <Card title="Error Handling" icon="shield-check">
    Always implement proper error handling for both SDK initialization and
    component events.
  </Card>

  <Card title="Loading States" icon="spinner">
    Show appropriate loading states during initialization and between component
    transitions.
  </Card>

  <Card title="Event Cleanup" icon="broom">
    Properly clean up event listeners when components unmount to prevent memory
    leaks.
  </Card>

  <Card title="Security" icon="lock">
    Never expose credentials in client-side code. Use environment variables and
    server-side token generation.
  </Card>
</Columns>

<Callout icon="bell">
  Remember to handle cleanup in your components by implementing proper
  unmounting logic and removing event listeners when components are destroyed.
</Callout>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Common Issues">
    * **SDK Initialization Failed**: Check your credentials and network connection
    * **Component Mount Errors**: Ensure the container element exists in the DOM
    * **Event Handler Issues**: Verify event names and handler implementations
  </Accordion>

  <Accordion title="Debug Tips">
    ```javascript theme={null}
    // Enable debug logging
    const config = {
      mode: "development",
      debug: true,
      // ... other config options
    };

    // Listen to all events
    oneSDKInstance.on("*", (event) => {
      console.log("Event:", event);
    });
    ```
  </Accordion>
</AccordionGroup>


# Framework Integrations
Source: https://docs.frankieone.com/docs/onesdk-integration-methods

OneSDK offers flexible integration options to suit your application architecture and requirements. Choose from our embedded SDK, hosted SDK, or Web SDK solutions.

<Callout icon="bell">
  ###### Security Best Practice

  Never embed credentials directly in your app's environment variables. Use a
  separate service to generate session tokens instead. The example credentials
  in our sample code are for demonstration purposes only.
</Callout>

## Integration Options

<CardGroup>
  <Card title="Embedded OneSDK" icon="code" href="/docs/quick-start">
    Integrate OneSDK directly into your application codebase for maximum control
    and customization.
  </Card>

  <Card title="Hosted OneSDK" icon="cloud" href="/docs/using-hosted-onesdk">
    Use our hosted solution for quick implementation with minimal setup
    requirements.
  </Card>

  <Card title="Web SDK" icon="globe" href="/docs/quick-start">
    Lightweight web-specific implementation ideal for browser-based
    applications.
  </Card>
</CardGroup>

## Framework Integration

<Info>
  The OneSDK package is available via
  [NPM <Icon icon="arrow-up-right-from-square" />](https://www.npmjs.com/package/@frankieone/one-sdk)
</Info>

<CardGroup>
  <Card title="React Integration" icon="react" href="/docs/react-onesdk-integration">
    Seamless integration with React applications, including hooks and
    components.
  </Card>

  <Card title="Next.js Integration" icon="node-js" href="/docs/next-js-onesdk-integration">
    Server-side rendering support and optimized for Next.js applications.
  </Card>

  <Card title="Angular Integration" icon="angular" href="/docs/angular-onesdk-implementation">
    Angular-specific implementation with TypeScript support.
  </Card>

  <Card title="Vue.js Integration" icon="vuejs" href="/docs/vuejs-onesdk-implementation">
    Vue.js integration with Composition API support.
  </Card>
</CardGroup>

## Sample Code Repository

<Info>
  Explore our [public sample code
  repository <Icon icon="arrow-up-right-from-square" />](https://github.com/frankieone/frontend-onesdk-public-sample-codes)
  for complete integration examples across different frameworks and build tools.
</Info>

### React Examples

<AccordionGroup>
  <Accordion title="React with Different Build Tools">
    | Build Tool              | Description                 | Link                                                                                                                                                                                |
    | :---------------------- | :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Vanilla React + webpack | Basic React setup           | [View Example <Icon icon="arrow-up-right-from-square" />](https://github.com/FrankieOne/frontend-onesdk-public-sample-codes/tree/main/frontend-onesdk-sample-vanilla-react-webpack) |
    | webpack                 | Modern build tool setup     | [View Example <Icon icon="arrow-up-right-from-square" />](https://github.com/FrankieOne/frontend-onesdk-public-sample-codes/tree/main/frontend-onesdk-sample-react-webpack)         |
    | rollup                  | Alternative build tool      | [View Example <Icon icon="arrow-up-right-from-square" />](https://github.com/FrankieOne/frontend-onesdk-public-sample-codes/tree/main/frontend-onesdk-sample-react-rollup)          |
    | Vite                    | Fast development experience | [View Example <Icon icon="arrow-up-right-from-square" />](https://github.com/FrankieOne/frontend-onesdk-public-sample-codes/tree/main/frontend-onesdk-sample-react-vite)            |
  </Accordion>

  <Accordion title="Next.js Examples">
    | Build Tool | Description            | Link                                                                                                                                                                         |
    | :--------- | :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Webpack    | Production-ready setup | [View Example <Icon icon="arrow-up-right-from-square" />](https://github.com/frankieone/frontend-onesdk-public-sample-codes/tree/main/frontend-onesdk-sample-nextjs-webpack) |
    | Rollup     | Optimized bundling     | [View Example <Icon icon="arrow-up-right-from-square" />](https://github.com/frankieone/frontend-onesdk-public-sample-codes/tree/main/frontend-onesdk-sample-nextjs-rollup)  |
    | Vite       | Modern build tool      | [View Example <Icon icon="arrow-up-right-from-square" />](https://github.com/frankieone/frontend-onesdk-public-sample-codes/tree/main/frontend-onesdk-sample-nextjs-vite)    |
  </Accordion>

  <Accordion title="Angular Examples">
    | Build Tool | Description         | Link                                                                                                                                                                          |
    | :--------- | :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Webpack    | Standard setup      | [View Example <Icon icon="arrow-up-right-from-square" />](https://github.com/frankieone/frontend-onesdk-public-sample-codes/tree/main/frontend-onesdk-sample-angular-webpack) |
    | Rollup     | Performance focused | [View Example <Icon icon="arrow-up-right-from-square" />](https://github.com/frankieone/frontend-onesdk-public-sample-codes/tree/main/frontend-onesdk-sample-angular-rollup)  |
    | Vite       | Rapid development   | [View Example <Icon icon="arrow-up-right-from-square" />](https://github.com/frankieone/frontend-onesdk-public-sample-codes/tree/main/frontend-onesdk-sample-angular-vite)    |
  </Accordion>

  <Accordion title="Vue.js Examples">
    | Build Tool | Description        | Link                                                                                                                                                                      |
    | :--------- | :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | Webpack    | Vue optimized      | [View Example <Icon icon="arrow-up-right-from-square" />](https://github.com/frankieone/frontend-onesdk-public-sample-codes/tree/main/frontend-onesdk-sample-vue-webpack) |
    | Rollup     | Efficient bundling | [View Example <Icon icon="arrow-up-right-from-square" />](https://github.com/frankieone/frontend-onesdk-public-sample-codes/tree/main/frontend-onesdk-sample-vue-rollup)  |
    | Vite       | Native Vue support | [View Example <Icon icon="arrow-up-right-from-square" />](https://github.com/frankieone/frontend-onesdk-public-sample-codes/tree/main/frontend-onesdk-sample-vue-vite)    |
  </Accordion>
</AccordionGroup>

## Important Notes for Create-React-App Users

<Callout icon="bell">
  ##### TypeScript Compatibility

  OneSDK requires TypeScript 5. Create-React-App users may need to take
  additional steps for compatibility.
</Callout>

<Steps>
  <Step title="Check Your Options">
    You have two paths for Create-React-App compatibility:
  </Step>

  <Step title="Option 1: Upgrade TypeScript">
    ```bash theme={null}
    npm install typescript@latest
    ```
  </Step>

  <Step title="Option 2: Use Legacy Peer Dependencies">
    ```bash theme={null}
    npm install --legacy-peer-deps
    ```

    <Callout icon="bell">
      Using legacy peer dependencies may introduce breaking changes in your codebase.
    </Callout>
  </Step>
</Steps>

## Environment Configuration

<Accordion title="Environment Variables">
  Create a `.env` file based on the `.env.example` template in your project. Required variables:

  | Variable              | Description            | Example                                          |
  | :-------------------- | :--------------------- | :----------------------------------------------- |
  | `*_API_KEY`           | Your API key           | `your-api-key`                                   |
  | `*_CUSTOMER_ID`       | Your customer ID       | `customer-123`                                   |
  | `*_CUSTOMER_CHILD_ID` | Your customer child ID | `child-456`                                      |
  | `*_BFF_BASE_URL`      | Backend URL            | `https://backend.kycaml.uat.frankiefinancial.io` |

  <Callout icon="star">
    ##### Framework-Specific Prefixes

    Replace \* with your framework's prefix: - React: `REACT_APP_` - Next.js:
    `NEXT_PUBLIC_` - Vite: `VITE_`
  </Callout>
</Accordion>

<Callout icon="thumbtack">
  For production environments, use `https://backend.kycaml.frankiefinancial.io`
  as your BFF base URL. For UAT environments, use
  `https://backend.kycaml.uat.frankiefinancial.io`.
</Callout>


# Entity view
Source: https://docs.frankieone.com/docs/overview



## The Entity view

The entity view shows the entity details, events, and checks that have been run on an entity and the result of each of these checks.

<img alt="" />

### Video Guide

<iframe />

## Entity Page UI walkthrough

### Entity ID

Use the Entity ID found below the entity name on the Profile tab when speaking with our customer support team.

The type and order of checks that have been run on a particular customer are defined in the **Workflow** assigned to that entity.

### Workflow events

The [**Workflow events** tab](/docs/workflow-events-tab) displays all the relevant information related to the workflow assigned to the entity.

### Profile

The [**Profile** tab](/docs/personal-info) provides the personal information, and identity documents collected during KYC.

### Audit Report

The [Audit Report tab](/docs/audit-report) displays a record of all activity and status changes on the entity.

## Entity actions walkthrough

### **Assign a user to a profile**

#### Video Guide

<iframe />

To assign a user to an entity, use the dropdown box in the top right corner.

<img />

### View comments

To view comments on an entity, go to the **Profile** tab and select the **Comments** icon on the top right corner.

### Send a link

Use the **Send link** button to send an onboarding link to the end user. This will open the **Send link via SMS** modal where you can enter the details of the end user and send them a link to complete their onboarding.

### More button

The **More** button provides access to additional actions that can be performed on the selected entity. These actions allow operators to manage and maintain entity records beyond the standard review and verification workflows.

<img />

Depending on your permissions and configuration, the More menu may include actions below:

#### Edit profile

To edit the entity profile, select the **More** button and select **Edit profile**.

#### Add blocklist

To add a blocklist to an entity, select the **More** button and select **Add blocklist**. This will open the **Add blocklist** modal where you can select the blocklist to add to the entity.

#### Archive entity

In an **Archive** state, the selected entity record remains accessible but will no longer display on the default Entities page. We suggest using this when setting aside entities you are not actively working on, but may want to keep as a record.

In an **Archive** state, the selected entity record remains accessible but will no longer display on the default Entities page. We suggest using this when setting aside entities you are not actively working on, but may want to keep as a record.

To archive an entity, select the **More** button and select **Archive entity**. This will remove the entity from active usage but retain it in the system.

<Note>
  You must have the **"Create and edit entities"** permission to carry out this action.  See under Settings > Role management
</Note>

##### Video Guide to Archive an entity

<iframe />

#### Deactivate entity

When an entity is deactivated, the system sets the entity status to **Inactive**. The selected entity record is permanently disabled and all associated indexes are removed from the system. We suggest using this when you no longer need an entity and do not intend to use it again in the future.

To deactivate an entity, select the **More** button, select **Deactivate entity.** A confirmation dialog will appear, asking you to confirm the action. Once confirmed, the entity's Service Profile status will be permanently set to **INACTIVE**.

<img />

### **When to use Deactivate vs Archive**

|                                 | Archive                                                   | Deactivate (Inactive)                          |
| ------------------------------- | --------------------------------------------------------- | ---------------------------------------------- |
| Entity still accessible?        | Yes                                                       | Yes                                            |
| Shown in default Entities page? | No                                                        | No                                             |
| All indexes removed?            | Yes                                                       | Yes                                            |
| Suitable for?                   | Entities you're not actively working on but may return to | Entities that are permanently no longer in use |


# Profile tab
Source: https://docs.frankieone.com/docs/personal-info

Personal Information related to the applicant can now be found in the KYC/Personal Info Tab

The **Profile** tab provides the personal information, and identity documents collected during KYC.

<Frame>
  <img alt="" />
</Frame>

## Overview

The **Profile** tab is the single-sheet snapshot of an individual entity. Here you can:

* View personal data, identity documents, selfies, and AML screening history.
* Check the latest **Entity status** and **Risk level**.
* Edit details, upload new evidence, or change the workflow that will run on this profile. Use the tabs along the top of the entity view to switch between Profile, Workflow events, Audit report, and other sections.

## Entity State

The colored badge beside the entity name tells you whether that customer is active, archived, blocklisted, or duplicated. See [Portal Entity State](https://docs.frankieone.com/docs/portal-statuses-and-tags) for more details.

## Entity Risk

The current risk rating appears next to the status badge.

### Risk drawer UI walkthrough

1. Click the **Risk score** badge.
2. A drawer opens, showing:
   * Numeric **Risk score**.
   * **Risk level** (Low, Medium, High, Unacceptable).
   * List of contributing factors and their weights (country, sanctions match, device risk, and so on).
3. Use this insight to decide if enhanced due diligence is required.

## Single sheet on the individual

Everything gathered about the customer lives in one scrollable view.

### Personal info

Shows the latest name, date of birth, contact details, and address values—updated whenever you edit the entity or receive fresh data workflow updates.

* Other information – These are [custom attributes](https://docs.frankieone.com/docs/managing-individuals#custom-attributes) (`individual.customAttributes` )  that have been set during the creation or update of an entity. This makes additional entity-level information easy to review alongside standard KYC details.

<Frame>
  <img alt="Image" />
</Frame>

### Accounts

Shows any account-related references (type: `ACCOUNT`) linked to that customer, so operators can see:

* **Account name** – shown as the account header
* **Account ID and description** – shown as supporting text
* **Account details (metadata)** – such as status, type, dates, and other key attributes

If no accounts are linked to the individual, the **Accounts** section will not be displayed.

### Identity docs ever submitted or uploaded

Every document scan attached to the profile is listed with:

* Document type (Passport, Driver Licence).
* Date added and check result (Pass/Fail).
* Thumbnail preview.

### Selfies, including videos ever taken

Selfie images and liveness videos captured through Smart UI are stored here with timestamps and biometric match scores.

### AML result history

A timeline of all AML screening events appears below the documents section. Each entry includes:

* Screening date and source lists.
* Match count and resolved state (Cleared, Escalated).
* Link to open the detailed AML result screen.

<Callout icon="thumbtack">
  The Profile tab shows **all data ever collected** for the entity. The **Workflow events tab** only shows the data checked in that specific workflow run.
</Callout>

## Edit entity profile

To edit the entity profile, select the profile menu and select **Edit profile**.

<Frame>
  <img alt="" />
</Frame>

The **Edit entity details** page will be displayed.

<Frame>
  <img alt="" />
</Frame>

Apply the appropriate revisions to the profile. Once done, agree to the consent and select **Save & verify** to save the new information and run verification. Select **Save changes** if you to save the information but run verification later.

<Frame>
  <img alt="" />
</Frame>


# Key Concepts
Source: https://docs.frankieone.com/docs/portal-key-concepts



## V1 Recipes vs V2 Workflows

| Feature          | Recipes                                              | Workflows                                                                                       |
| :--------------- | :--------------------------------------------------- | :---------------------------------------------------------------------------------------------- |
| Platform version | V1                                                   | V2                                                                                              |
| Structure        | Linear order of checks                               | Can incorporate conditional logic ("if this, then that")                                        |
| Visualization    | JSON                                                 | More sophisticated with process flow diagrams for visualization                                 |
| Customisation    | More rigid configuration                             | Highly customizable and composable                                                              |
| Integration      | Require custom code for integrating certain services | Enable easier integration of services like enterprise applications through the Workflow Builder |

## Entities

An entity refers to a single individual or organization within the FrankieOne platform that exists separately from other entities. Entities house information about the individual or organization, primarily any personally identifiable information (PII). All stored processes involving an entity, like a verification result, are stored separately from the entity.

## Individual

An individual in the context of the FrankieOne platform refers to a single person who can be verified. Individuals can have service profiles, workflows, and risk assessments related to them, which are used to manage their lifecycle and compliance.

## Workflows

A workflow is an end-to-end process that involves a series of steps that, when triggered, will enrich or verify stored entity information. Workflows are customizable and can be built to satisfy the customer’s compliance requirements.

Several steps that can be added to a workflow execution:

* Know Your Customer (KYC) Verifications: verify the identity of clients to prevent fraud and comply with regulatory requirements
* Anti-Money Laundering (AML) Screening
* Blocklist Checks
* Duplicate Checks
* Liveness Verification (on roadmap)
* Facial Comparison Checks (on roadmap)
* Document Validation Checks
* OCR Mismatch Checks (on roadmap)

<Callout icon="thumbtack">
  In v2 you move from fixed Recipes to flexible Workflows, giving you full control over every verification step.

  A Workflow is a custom, end-to-end sequence you design—KYC, AML, liveness, document validation, and more—that can run at onboarding, monitoring, or any other lifecycle phase.

  A Recipe, by contrast, is FrankieOne’s pre-packaged list of checks that every customer must clear in one go and is stored in the API as an entityProfile.

  By adopting Workflows you can swap checks in or out, change their order, trigger them only when needed, and override results through new execution and monitoring endpoints, replacing the all-or-nothing approach of Recipes with a modular system that fits your exact compliance policy.
</Callout>

## Process Results

A process result is a granular piece of information that's used to determine the outcome of an action or step that has been performed. Typically, a process result represents the data retrieved from a 3rd party provider that's then validated by a workflow step to determine a successful or unsuccessful result.

For example, during a Know Your Customer (KYC) verification, third-party providers are consulted to verify if the provided individual’s information is present in recognized data sources, such as an Electoral Roll or Credit Header. Upon verification, if the entity’s provided name, date of birth, and address all correspond with a particular data source, three distinct process results will be generated: one each for the name, date of birth, and address. If matches are found across multiple data sources, additional process results will be generated for each match type across each data source. These process results are then evaluated by the KYC workflow step to determine whether the amount of matches meets the criteria defined in the policy you have defined.

In the context of Anti-Money Laundering (AML) screening, a process result will be generated for each potential match identified. These can then be subsequently marked as false positives or true positives on manual review.

## Service Profiles

A service profile provides a concise overview of an entity’s progress within the context of a specific product or service. These profiles encompass various risk levels, workflows, and statuses. Consequently, a single entity can undergo distinct evaluation processes based on the product or service they're seeking.

For example, consider an individual applying for both a credit card and a home loan from a bank. While minimal background checks may suffice for the credit card application, stricter criteria apply to the home loan. Despite the unchanged identity of the individual, the success criteria differ based on the product type.

Similarly, business owners face varying assessments. Applying as an individual for a credit card may yield approval, but seeking a business loan as a sole trader involves additional considerations. In essence, the entity remains constant, while the evaluation criteria adapt to the specific product or service.

Multiple service profiles can be arranged at time of onboarding to accommodate this requirement.

## Risks

FrankieOne utilizes granular risk metrics to determine a customer's risk profile and identify potential money laundering activities. Entities are scored on these risk factors during workflow execution with the cumulative risk score helping determine the overall risk level for that entity. Additionally, risk levels can influence the level of due diligence required. For instance, high-risk entities may undergo enhanced scrutiny.

Organizations can tailor risk factors to align with their specific compliance policies. You have the flexibility to add or remove risk elements based on your risk tolerance.

Several measurable risk factors include:

* **Personal Information**: This includes details such as an individual’s age, place of residence, workplace or birthplace.
* **KYC**: The status of the individual’s basic KYC checks - whether they passed, partially passed, or failed.
  **Identity Verification Flags**: Any signs of suspicious behavior or issues related to identity during the identity verification process.
* **PEP/Sanctions**: Occurrences where an individual is listed on a politically exposed persons or sanctions watchlist.
  **Negative News**: Instances where an individual appears in unfavorable news articles
* **Duplicate Entities**: Cases where parts of an entity are replicated from an existing entity, such as names, document numbers, phone numbers or email addresses
* **Blocked Entities**: Situations where parts of the entity have been blocked, such as a name, phone number, address, email, etc.

Ultimately, the decision to accept or reject an entity lies with you. Assess risk carefully and decide whether you’re willing to onboard an entity deemed high risk based on the risk policy defined by you.

## Issues

An issue refers to a problem encountered during the execution of a workflow that hinders its successful completion and necessitates manual intervention. This could encompass a wide range of scenarios, from a failed Know Your Customer (KYC) check during an entity’s onboarding process, to an entity appearing on an Anti-Money Laundering (AML) watchlist, or even technical failures such as the unavailability of data sources. Issues promptly provide information about the encountered problem and offer guidance on the subsequent steps to be taken.

It’s important to note that issues are only raised if a process has been executed. If a step within the workflow is skipped due to insufficient information or not meeting the necessary criteria for execution, no issues will be raised for that particular step. For instance, if basic KYC checks haven't been passed, and the workflow has been configured to bypass AML screening in such cases, no issues will be generated.


# Portal User Experience
Source: https://docs.frankieone.com/docs/portal-navigation-v2



## Navigating the Portal

The FrankieOne Portal provides users with the visual interface for managing their account.

<img alt="" />

This navigation provides a simple and intuitive interface, giving the user the option to expand and collapse the sidebar as needed, to display information better.

By default, the navigation bar is expanded to show the full text of menu options. To collapse it, select the collapse button.

<Frame>
  <img alt="The collapse button." />
</Frame>

To expand the navigation again, select the menu (burger) icon.

<Frame>
  <img alt="The menu icon." />
</Frame>

The side bar contains links to the different pages of the Portal. As you select any of the links, the main content section will display the selected page.


# Statuses and Tags
Source: https://docs.frankieone.com/docs/portal-statuses-and-tags



## Introduction

Every profile (entity) and every workflow in FrankieOne Portal carries clear labels— **entity state**, **event statuses**, **issue tags**, and a **risk level**.\
These labels help you spot successes, problems, and urgent risks at a glance. Use this guide to learn what each label means and how to act on it.

## Entity State

| State       | What it means                                                                 | Typical next step                                                                                                                                        |
| :---------- | :---------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Unchecked   | Entity has been created but no verification checks have been run yet.         | Initiate verification workflow to begin the checking process.                                                                                            |
| Active      | Entity has passed all required checks and is currently in good standing.      | Monitor for any changes or periodic re-verification as needed.                                                                                           |
| Archived    | Profile is stored but hidden from the default list.                           | For entities marked as "Archived," this is a reversible action that simply hides the profile from the default view. Unarchive if further work is needed. |
| Blocklisted | Entity has been added to a blocklist due to high risk or compliance concerns. | Review blocklist reason and determine if an appeal is possible or if permanent blocking is appropriate.                                                  |
| Duplicate   | Entity has been identified as a duplicate of another profile in the system.   | Compare both profiles and decide whether to merge or keep separate.                                                                                      |

<Callout icon="thumbtack">
  You can filter the Entities table by these statuses using **Entity status** in the Filters modal.
</Callout>

## Event Statuses

The event status tells you the current status of the entity. This is based on the status of the most recent workflow run on that entity.

| Status          | What it means                                        | Typical next step                                             |
| :-------------- | :--------------------------------------------------- | :------------------------------------------------------------ |
| Unchecked       | Checks are still running or queued.                  | Wait for workflow to finish or retrigger if stuck.            |
| Needs Attention | At least one check needs manual review.              | Open the profile, review issues, decide to Pass or Fail.      |
| Passed          | All required checks were met.                        | None—onboarding is complete.                                  |
| Manually Passed | A user reviewed the profile and marked it as Passed. | Record the reason for manual pass.                            |
| Failed          | Checks revealed blocking issues.                     | Review issues and decide if appeal or correction is possible. |
| Manually Failed | A user reviewed and failed the profile.              | Record the reason and notify the applicant if required.       |

<Callout icon="thumbtack">
  The Event status always reflects **the most recent workflow** run on the profile, so you instantly know the latest outcome.
</Callout>

## Entity Issues

High-level issue tags appear in the Entities list so you can decide which profile to open first.\
Inside the profile you will find **detailed sub-issues** (for example, which specific sanction list matched).

| Category          | What it means                                                                                                           | Typical next step                                                                    |
| :---------------- | :---------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- |
| **KYC**           | Issues related to Know Your Customer verification, such as no match or partial match found.                             | Review the specific KYC failure reason and request additional information if needed. |
| **BAD\_DATA**     | Problems with the data provided by the customer, such as incorrect name, DOB, address, ID, email, or mobile.            | Identify which specific data element is problematic and request correction.          |
| **AML**           | Anti-Money Laundering concerns including PEP status, adverse media, sanctions matches, or negative news.                | Review the match details and determine if enhanced due diligence is required.        |
| **IDV**           | Identity verification issues such as data consistency problems, document validation failures, or compromised documents. | Examine the specific IDV failure and request additional verification if appropriate. |
| **Blocklisted**   | The entity has been added to a blocklist, preventing further processing.                                                | Review the blocklist reason and determine if an appeal is possible.                  |
| **Duplicate**     | The system has detected this person may already have an account.                                                        | Compare both profiles and decide whether to merge or keep separate.                  |
| **System**        | Technical issues within the platform that prevented successful verification.                                            | Contact technical support or retry the verification process.                         |
| **Expiry**        | Documents or verifications have expired and need to be renewed.                                                         | Request updated documents or re-verification.                                        |
| **Informational** | Non-critical information that requires attention but doesn't necessarily block onboarding.                              | Review the information and take appropriate action if needed.                        |

<Callout icon="thumbtack">
  The **Entities list** shows only the **high-level tags** above. Open the profile for a breakdown of every failed check and exact match details.
</Callout>

## Risk Level

| Risk level   | Meaning                            | Typical business rule                    |
| ------------ | ---------------------------------- | ---------------------------------------- |
| Low          | Meets the safest score range.      | Auto-approve.                            |
| Medium       | Some moderate risk factors.        | May ask for extra documents.             |
| High         | Significant risk factors.          | Needs manual review and enhanced checks. |
| Unacceptable | Risk score exceeds your threshold. | Automatically fail profile.              |

<Callout icon="thumbtack">
  The Risk level shown in the entities list is **always based on the last completed workflow**, so it changes as new checks finish.
</Callout>


# Quick Start
Source: https://docs.frankieone.com/docs/quick-start

Get up and running with OneSDK in minutes. This guide walks you through implementing two common onboarding flows: eKYC and IDV verification.

## Prerequisites

<AccordionGroup>
  <Accordion title="Required Credentials">
    <div>
      <Card title="Essential Credentials" icon="key">
        * Customer ID
        * Child ID (if applicable)
        * API Key
        * Service Name — Required in the request body for V2 API calls.
      </Card>

      <Card title="Backend URLs" icon="server">
        * UAT: `https://backend.kycaml.uat.frankiefinancial.io/auth/v2/machine-session`
        * Prod: `https://backend.kycaml.frankiefinancial.io/auth/v2/machine-session`
      </Card>
    </div>

    <Note>
      **Important**: When using V2 endpoints, you must include "serviceName": "KYC" in the request body. Omitting this field will result in a 400 Bad Request error.
    </Note>

    <Note>
      Need credentials? Contact FrankieOne support to set up your account.
    </Note>
  </Accordion>
</AccordionGroup>

## Implementation Guide

<Steps>
  <Step title="Prepare Your Environment">
    <Callout icon="bell">
      ##### Security Best Practice

      Never expose API credentials in client-side code. Generate session tokens server-side and pass only the token to your frontend.
    </Callout>
  </Step>

  <Step title="Choose Your Integration Flow">
    Select the implementation that best fits your needs:

    <Tabs>
      <Tab title="eKYC Flow">
        Manual capture and verification flow.

        ```html ekycFlow.html theme={null}
        <html lang="en">
          <head>
            <meta name="viewport" content="width=device-width, initial-scale=1.0" />
            <title>OneSDK eKYC Onboarding</title>
            <script src="https://assets.frankiefinancial.io/one-sdk/v1/oneSdk.umd.js"></script>
            
            <script>
              async function startOneSDK() {
                // Configuration
                const config = {
                  CUSTOMER_ID: "your-customer-id",
                  CUSTOMER_CHILD_ID: "your-child-id", // Optional
                  API_KEY: "your-api-key"
                };

                // Initialize SDK
                const oneSdk = await initializeSDK(config);

                // Set up flow components
                setupFlowComponents(oneSdk);
              }

              async function initializeSDK(config) {
                // Get session token
                const session = await getSessionToken(config);

                // Initialize SDK
                return await OneSDK({
                  session: session,
                  mode: "development",
                  recipe: {
                    form: {
                      provider: {
                        name: "react"
                      }
                    }
                  }
                });
              }

              async function getSessionToken(config) {
                const response = await fetch(
                  "https://backend.kycaml.uat.frankiefinancial.io/auth/v1/machine-session",
                  {
                    method: "POST",
                    headers: {
                      authorization: "machine " + btoa(
                        `${config.CUSTOMER_ID}:${config.CUSTOMER_CHILD_ID}:${config.API_KEY}`
                      ),
                      "Content-Type": "application/json"
                    },
                    body: JSON.stringify({
                      permissions: {
                        preset: "one-sdk",
                        reference: "your-reference-id"
                      }
                    })
                  }
                );

                return await response.json();
              }

              function setupFlowComponents(oneSdk) {
                const individual = oneSdk.individual();

                // Initialize components
                const components = {
                  welcome: oneSdk.component("form", {
                    name: "WELCOME",
                    type: "manual"
                  }),
                  consent: oneSdk.component("form", {
                    name: "CONSENT"
                  }),
                  // ... other components
                };

                // Set up event handlers
                setupEventHandlers(components);
              }
            </script>
          </head>
          <body style="background-color: white" onload="startOneSDK()">
            <div id="form-container" style="position:fixed;top:0;left:0;width:100%;height:100%"></div>
          </body>
        </html>
        ```
      </Tab>

      <Tab title="IDV Flow">
        OCR and Biometrics verification flow.

        ```html idvFlow.html theme={null}
        <html lang="en">
          <head>
            <meta name="viewport" content="width=device-width, initial-scale=1.0" />
            <title>OneSDK IDV Onboarding</title>
            <script src="https://assets.frankiefinancial.io/one-sdk/v1/oneSdk.umd.js"></script>

            <script>
              async function startOneSDK() {
                // Configuration
                const config = {
                  CUSTOMER_ID: "your-customer-id",
                  CUSTOMER_CHILD_ID: "your-child-id", // Optional
                  API_KEY: "your-api-key"
                };

                // Initialize SDK
                const oneSdk = await initializeSDK(config);

                // Set up IDV flow
                setupIDVFlow(oneSdk);
              }

              async function initializeSDK(config) {
                // Similar to eKYC flow initialization
              }

              function setupIDVFlow(oneSdk) {
                const individual = oneSdk.individual();

                // Add required consents
                individual.addConsent("general");
                individual.addConsent("docs");
                individual.addConsent("creditheader");

                // Initialize IDV flow
                const idv = oneSdk.flow("idv");
                setupIDVComponents(oneSdk, idv);
              }

              function setupIDVComponents(oneSdk, idv) {
                // Initialize components
                const components = {
                  loading: oneSdk.component("form", {
                    name: "LOADING",
                    title: { label: "Processing..." }
                  }),
                  review: oneSdk.component("form", {
                    name: "REVIEW",
                    type: "ocr"
                  })
                };

                // Set up event handlers
                setupIDVEventHandlers(idv, components);
              }
            </script>
          </head>
          <body style="background-color: white" onload="startOneSDK()">
            <div id="idv-el" style="top:0;left:0;width:100%;height:100%;display:block"></div>
            <div id="loading1"></div>
            <div id="loading2"></div>
          </body>
        </html>
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure Your Credentials">
    <AccordionGroup>
      <Accordion title="Required Configuration">
        Replace the following placeholders with your credentials:

        ```javascript theme={null}
        const config = {
          CUSTOMER_ID: "your-customer-id",
          CUSTOMER_CHILD_ID: "your-child-id", // Remove if not applicable
          API_KEY: "your-api-key"
        };
        ```
      </Accordion>

      <Accordion title="Optional Configuration">
        <Tabs>
          <Tab title="Google Maps Integration">
            Add Google Maps support for address auto-completion:

            ```javascript theme={null}
            const oneSdk = await OneSDK({
              session: sessionObjectFromBackend,
              mode: "development",
              recipe: {
                form: {
                  provider: {
                    name: "react",
                    googleApiKey: "your-google-maps-api-key"
                  }
                }
              }
            });
            ```
          </Tab>

          <Tab title="Custom Reference">
            Add a unique customer reference:

            ```javascript theme={null}
            permissions: {
              preset: "one-sdk",
              reference: "your-unique-reference"
            }
            ```
          </Tab>
        </Tabs>
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Test Your Implementation">
    1. Save your code as an HTML file
    2. Open in a web browser
    3. Test on both desktop and mobile devices

    <Callout icon="star">
      ##### Development Tips

      * Use the browser console to monitor events (`oneSdk.on("*", console.log)`)
      * Test with different document types
      * Verify all flow stages work as expected
    </Callout>
  </Step>
</Steps>

<Callout icon="check">
  Congratulations! You've successfully set up OneSDK. Need help? Contact our support team for assistance.
</Callout>


# Windows Events For Hosted Flows
Source: https://docs.frankieone.com/docs/quickstart-guide/windows-events-hosted-flows



## Listening to Window Events with Hosted OneSDK

Hosted OneSDK will emit window events during specific stage of your onboarding experience. You can leverage this mechanism to handle error and success handling

<Tabs>
  <Tab title="Table of Events">
    <table>
      <thead>
        <tr>
          <td>flowId</td>
          <td>On which stage?</td>
          <td>Event Emitted</td>
          <td>Payload</td>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>ocr\_only</td>

          <td>
            failed uploading OCR
          </td>

          <td>`ocr_only:failed`</td>
          <td>-</td>
        </tr>

        <tr>
          <td>ocr\_only</td>

          <td>
            success uploading OCR
          </td>

          <td>`ocr_only:success`</td>
          <td>-</td>
        </tr>

        <tr>
          <td>manual\_kyc</td>

          <td>
            manual kyc is mounted
          </td>

          <td>`manual_kyc:mounted`</td>
          <td>-</td>
        </tr>

        <tr>
          <td>manual\_kyc</td>

          <td>
            success with manual kyc
          </td>

          <td>`manual_kyc:success`</td>
          <td>-</td>
        </tr>

        <tr>
          <td>manual\_kyc</td>

          <td>
            partial success with manual kyc
          </td>

          <td>`manual_kyc:partial`</td>
          <td>-</td>
        </tr>

        <tr>
          <td>manual\_kyc</td>

          <td>
            failed manual kyc
          </td>

          <td>`manual_kyc:failed`</td>
          <td>-</td>
        </tr>

        <tr>
          <td>idv</td>

          <td>
            idv is getting mounted
          </td>

          <td>`idv:mount`</td>
          <td>-</td>
        </tr>

        <tr>
          <td>idv</td>

          <td>
            idv process success
          </td>

          <td>`idv:success`</td>
          <td>-</td>
        </tr>

        <tr>
          <td>idv</td>

          <td>
            idv process failed
          </td>

          <td>`idv:failed`</td>
          <td>-</td>
        </tr>

        <tr>
          <td>idv</td>

          <td>
            idv getting rendered
          </td>

          <td>`idv:render`</td>
          <td>-</td>
        </tr>

        <tr>
          <td>idv\_review</td>

          <td>
            idv\_review is getting mounted
          </td>

          <td>`idv_review:mount`</td>
          <td>-</td>
        </tr>

        <tr>
          <td>idv\_review</td>

          <td>
            idv\_review getting rendered
          </td>

          <td>`idv_review:render`</td>
          <td>-</td>
        </tr>

        <tr>
          <td>idv\_review</td>

          <td>
            idv was failed on idv\_review flow
          </td>

          <td>`idv_review:idv_failed`</td>
          <td>(error message depends on error type)</td>
        </tr>

        <tr>
          <td>idv\_review</td>

          <td>
            after submitting review screen
          </td>

          <td>`idv_review:submit`</td>

          <td>
            *
          </td>
        </tr>

        <tr>
          <td>idv\_review</td>

          <td>
            idv\_review process is success
          </td>

          <td>`idv_review:success`</td>

          <td>
            result from calling `individual.submit()`

            sample:

            ```json theme={null}
                {
                  "payload": {
                    "checkDate": "0001-01-01T00:00:00.000Z",
                    "checkTypes": [
                      "id",
                      "namev",
                      "two_plus",
                      "pep",
                      "idvalidate"
                    ],
                    "personalChecks": {
                      "name": null,
                      "dateOfBirth": null,
                      "phoneNumber": null,
                      "email": null,
                      "chineseName": null,
                      "addresses": {
                        "4021e881-e51a-48ab-b8db-82cdc882d1a2": null
                      }
                    },
                    "status": {
                      "type": "unchecked",
                      "label": "Unchecked",
                      "key": "UNCHECKED"
                    },
                    "risk": {
                      "level": null,
                      "class": "HIGH"
                    },
                    "alertList": [],
                    "blocklistPotentialMatches": [],
                    "duplicatePotentialMatches": [],
                    "duplicateBlocklistMatches": [],
                    "checkCounts": {
                      "name": null,
                      "address": {
                        "4021e881-e51a-48ab-b8db-82cdc882d1a2": []
                      },
                      "document": {},
                      "dob": null
                    },
                    "kycMethod": "electronic",
                    "issues": {
                      "creditHeader": false,
                    },
                    "checkResults": [],
                    "rulesetsMatches": []
                  }
                }
            ```
          </td>
        </tr>

        <tr>
          <td>idv\_review</td>

          <td>
            during idv\_review, there are some issues occurred
          </td>

          <td>`idv_review:error`</td>

          <td>
            ```json theme={null}
            {
                error: {} // object of dumped errors
            }
            ```
          </td>
        </tr>
      </tbody>
    </table>
  </Tab>

  <Tab title="Implementation method">
    You can listen to Hosted OneSDK window events if you embed Hosted OneSDK inside an iframe

    ```html theme={null}
    <html lang="en">
        <head>
        	<meta name="viewport" content="width=device-width, initial-scale=1.0" charset="UTF-8"/>
        	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
        </head>

    	<script>
            // here, you add an event listener to listen to Hosted OneSDK window events
    		window.addEventListener('message', (e) => {
    			if (e.data['X-Frankie-Source'] === 'hosted-onesdk') {
    				console.log('---HOSTED OneSDK events', e.data)
    			}
    		});
    	</script>

    	<body>
    		<iframe
    		style="position: absolute; top: 0; left: 0; left: 0;right: 0;bottom: 0;border: 0;margin: 0; padding: 0;width: 100%; height: 100%; fontSize: 100%;font: inherit; vertical-align: baseline;"
    		src="https://verify.frankie.one?t=wy2BSoBrMYba7dB4cHS5dLjK" allow="camera;fullscreen;accelerometer;gyroscope;magnetometer;geolocation;microphone;" />
    	</body>
    </html>
    ```
  </Tab>
</Tabs>


# React
Source: https://docs.frankieone.com/docs/react-onesdk-integration

This guide walks you through integrating OneSDK with React, providing you with a solid foundation for building secure and efficient KYC workflows.

## Quick Start

<Steps>
  <Step title="Create Your React Project">
    Choose your preferred bundler:

    <Tabs>
      <Tab title="Vite">
        ```shell theme={null}
        npm create vite@latest my-react-app -- --template react
        ```
      </Tab>

      <Tab title="Create React App">
        ```shell theme={null}
        npx create-react-app my-app
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Install Dependencies">
    ```shell theme={null}
    cd my-react-app
    npm install
    npm install @frankieone/one-sdk
    ```
  </Step>

  <Step title="Start Development">
    ```shell theme={null}
    npm run dev  # for Vite
    # or
    npm start    # for Create React App
    ```
  </Step>
</Steps>

## Configuration

<AccordionGroup>
  <Accordion title="Vite Configuration">
    Add this configuration to your `vite.config.js`:

    ```javascript theme={null}
    import { defineConfig } from "vite";
    import react from "@vitejs/plugin-react";

    export default defineConfig({
      plugins: [react()],
      define: {
        "process.env": {},
      },
    });
    ```
  </Accordion>

  <Accordion title="Environment Setup">
    <Callout icon="star">
      Based on your build tool and/or framework, you may have a different prefix to the environment variables,
      e.g. if you're using Vite, your env prefix is going to be "VITE\_" instead of "REACT\_APP\_"
    </Callout>

    Create a `.env` file with your credentials:

    ```shell theme={null}
    REACT_APP_CUSTOMER_ID=your_customer_id
    REACT_APP_API_KEY=your_api_key
    REACT_APP_CHILD_ID=your_child_id    # optional
    ```
  </Accordion>
</AccordionGroup>

## Integration with React

### Custom Hook Implementation

<Tabs>
  <Tab title="useOneSDK Hook">
    ```typescript theme={null}
    import OneSDK from "@frankieone/one-sdk";
    import { useEffect, useRef, useState } from "react";

    interface OneSDKConfig {
      mode: 'development' | 'production';
      recipe: {
        form: {
          provider: {
            name: string;
          };
        };
      };
    }

    interface UseOneSDKProps {
      config?: OneSDKConfig;
    }

    const useOneSDK = ({ config }: UseOneSDKProps) => {
      const [oneSDKInstance, setOneSDKInstance] = useState(null);
      const [error, setError] = useState(null);
      const [loading, setLoading] = useState(false);
      const initializedRef = useRef(false);

      const generateToken = async () => {
        try {
          const tokenRawAsync = await fetch(
            "https://backend.latest.frankiefinancial.io/auth/v2/machine-session",
            {
              method: "POST",
              headers: {
                authorization: `machine ${btoa(
                  `${process.env.REACT_APP_CUSTOMER_ID}:${process.env.REACT_APP_API_KEY}`
                )}`,
                "Content-Type": "application/json",
              },
              body: JSON.stringify({
                permissions: {
                  preset: "one-sdk",
                  reference: `demo-${new Date().toISOString()}`,
                },
              }),
            }
          );
          return await tokenRawAsync.json();
        } catch (error) {
          setError(error.message);
          return null;
        }
      };

      const generateOneSDKInstance = async () => {
        setLoading(true);
        try {
          const token = await generateToken();
          if (!token) return;

          const defaultConfig = {
            mode: "development",
            recipe: {
              form: {
                provider: {
                  name: "react",
                },
              },
            },
          };

          const oneSDKInit = await OneSDK({
            session: token,
            ...(config || defaultConfig),
          });

          setOneSDKInstance(oneSDKInit);
        } catch (error) {
          setError(error.message);
        } finally {
          setLoading(false);
        }
      };

      useEffect(() => {
        if (!initializedRef.current) {
          generateOneSDKInstance();
          initializedRef.current = true;
        }
      }, [config]);

      return { oneSDKInstance, error, loading };
    };

    export default useOneSDK;
    ```
  </Tab>

  <Tab title="Usage Example">
    ```tsx theme={null}
    import useOneSDK from './hooks/useOneSDK';

    const KYCForm = () => {
      const { oneSDKInstance, error, loading } = useOneSDK({
        config: {
          mode: 'development',
          recipe: {
            form: {
              provider: {
                name: 'react',
              },
            },
          },
        },
      });

      if (loading) return <div>Loading OneSDK...</div>;
      if (error) return <div>Error: {error}</div>;
      if (!oneSDKInstance) return <div>OneSDK not initialized</div>;

      return (
        <div>
          {/* Your KYC form implementation using oneSDKInstance */}
        </div>
      );
    };

    export default KYCForm;
    ```
  </Tab>
</Tabs>

### Best Practices

<Columns>
  <Card title="Error Handling" icon="shield-check">
    * Always handle token generation errors - Provide meaningful error messages
    * Implement proper error boundaries
  </Card>

  <Card title="Security" icon="lock">
    * Never expose API keys in client-side code
    * Use environment variables
    * Implement proper token management
  </Card>

  <Card title="Performance" icon="bolt">
    * Use React.memo for expensive renders
    * Implement proper cleanup in `useEffect`
    * Avoid unnecessary re-renders
  </Card>

  <Card title="State Management" icon="database">
    * Use proper state management patterns
    * Implement loading states
    * Handle edge cases properly
  </Card>
</Columns>

<Callout icon="bell">
  Remember to handle token expiration and implement proper refresh mechanisms in
  a production environment.
</Callout>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Common Issues">
    * **Token Generation Fails**: Verify your credentials and network connection
    * **SDK Initialization Errors**: Check configuration object format
    * **Component Re-rendering**: Implement proper memoization
  </Accordion>

  <Accordion title="Environment Variables">
    * **Vite**: Ensure variables are prefixed with `VITE_`
    * **Create React App**: Ensure variables are prefixed with `REACT_APP_`
    * **Development**: Verify `.env` file location
  </Accordion>
</AccordionGroup>

## Next Steps

<Columns>
  <Card title="Sample Implementation" icon="code" href="/docs/embedded-flows/split-flow">
    View complete implementation examples
  </Card>

  <Card title="API Reference" icon="book" href="/docs/reference/authentication">
    Explore the complete API documentation
  </Card>
</Columns>


# API endpoints
Source: https://docs.frankieone.com/docs/reference/api-endpoints



## UAT Environment (Contracted customers only)

```text URL theme={null}
API
https://api.uat.frankie.one/v2

Portal
https://portal.uat.frankie.one/login
```

## Production (Contracted customers only)

```text URL theme={null}
API
https://api.frankie.one/v2

Portal
https://portal.frankie.one/login
```


# Authentication
Source: https://docs.frankieone.com/docs/reference/authentication



The FrankieOne API provides a simple, but secure mechanism for authentication.

As a user of the FrankieOne API, a **CustomerId** and potentially a **ChildId** will be allocated.

The ***CustomerID*** is the primary identifier.

The **ChildID** will be issued when accessing the service either as part of an organizational division (for example, a regional/country division) or as the agent of a service that uses FrankieOne for their KYC/AML needs.

A user will be issued an **API Key** that's tied to both the **CustomerID** and **ChildID**.

To authenticate each call, the user must supply the **CustomerID**, the **ChildID** (if used), and the **API Key** as headers in every call to the service. The headers to use are:

```http HTTP theme={null}
X-Frankie-CustomerID: 12345678-1234-1234-1234-123456789012
X-Frankie-CustomerChildID: 87654321-4321-4321-4321-210987654321
api_key: 245c765b124a098d09ef8765....
```

<Accordion title="Test your connection">
  The easiest way to verify that your credentials and connection are working is to call our simple health check endpoint: /ruok. This endpoint doesn’t require a request body and is used purely to confirm successful authentication.

  ### Request - Health check

  ```
  curl --location '[https://api.uat.frankie.one/v2/kyc/ruok](https://api.uat.frankie.one/v2/kyc/ruok)' \--header 'api_key: {{your_uat_api_key}}' \--header 'X-Frankie-CustomerId: {{your_uat_customer_id}}'
  ```

  ### Response

  ```
  {  "status": "OK"}
  ```

  If you receive an error, double-check that your API key and Customer ID are correct and that you are using the correct base URL for the environment.
</Accordion>


# Data Sources Codes
Source: https://docs.frankieone.com/docs/reference/datasource-codes



This list of data source codes covers the many different sources we check when verifying an identity.

As a general rule, one code will map to a single datasource. However in many cases, a data source can represent a number of combined sources. Where possible we list these individually.

| Country          | Source ID Code         | Description                                               |
| :--------------- | :--------------------- | :-------------------------------------------------------- |
| BUILTIN          | builtin                | FrankieOne Internal                                       |
| MANUAL\_OVERRIDE | manual\_override       | Manual Override                                           |
| AU               | au-asic                | ASIC                                                      |
| AU               | au-dz-residential      | DZ Commercial Database (multiple sources)                 |
| AU               | au-idmatrix            | IDMatrix                                                  |
| AU               | au-efax-cdh-commercial | Equifax Commercial Credit Data Header                     |
| AU               | au-efax-cdh-consumer   | Equifax Consumer Credit Data Header                       |
| AU               | au-efax-cdh-pub        | Equifax Public Credit Data Header                         |
| AU               | au-efax-fraud-address  | Equifax Fraud - Address                                   |
| AU               | au-efax-fraud-dl       | Equifax Fraud - Drivers Licence                           |
| AU               | au-efax-fraud-phone    | Equifax Fraud - Phone                                     |
| AU               | au-efax-fraud-pport    | Equifax Fraud - Passport                                  |
| AU               | au-efax-fraud-velocity | Equifax FraudCheck - Velocity                             |
| AU               | au-efax-phone          | Equifax Proprietary Phone Directory                       |
| AU               | au-elec-roll           | Australian Electoral Roll                                 |
| AU               | au-elec-roll-hist      | Australian Electoral Roll - Historical                    |
| AU               | au-expn-cdh-commercial | Experian Commercial Credit Data Header                    |
| AU               | au-gdc-commercial1     | GDC Commercial database (multiple sources) 1              |
| AU               | au-gdc-commercial2     | GDC Commercial database (multiple sources) 2              |
| AU               | au-gdc-commercial7     | GDC Commercial Database (multiple sources) 7              |
| AU               | au-govid1              | Australian Government ID                                  |
| AU               | au-govid1-bc           | Australian Gov ID - Birth Certificate                     |
| AU               | au-govid1-con          | Australian Gov ID - Certificate of Name Change            |
| AU               | au-govid1-ctl          | Australian Gov ID - Centrelink Card                       |
| AU               | au-govid1-ctzn         | Australian Gov ID - Citizenship                           |
| AU               | au-govid1-dl           | Australian Gov ID - Drivers Licence                       |
| AU               | au-govid1-immi         | Australian Gov ID - Immigration Card                      |
| AU               | au-govid1-mc           | Australian Gov ID - Marriage Certificate                  |
| AU               | au-govid1-medi         | Australian Gov ID - Medicare Card                         |
| AU               | au-govid1-pp           | Australian Gov ID - Passport                              |
| AU               | au-govid1-visa         | Australian Gov ID - Visa Check                            |
| AU               | au-govid2              | Australian Gov ID - Alt Source                            |
| AU               | au-govid2-bc           | Australian Gov ID - Alt Source - Birth Certificate        |
| AU               | au-govid2-dl           | Australian Gov ID - State Direct Source - Drivers Licence |
| AU               | au-govid2-mc           | Australian Gov ID - Alt Source - Medicare Card            |
| AU               | au-govid2-pp           | Australian Gov ID - Alt Source - Passport                 |
| AU               | au-ntd                 | Australian National Tenancy Database                      |
| AU               | au-phone-pub           | Australian Public Phone Directory                         |
| AU               | au-phone-scanned-dir   | Australian Scanned Phone Directory                        |
| AU               | au-vevo                | Australian VEVO                                           |
| FF               | ff-blacklist           | Internal Blocklist                                        |
| FF               | ff-duplicate           | Duplicate                                                 |
| FF               | ff-idvalidation        | Frankie ID Validation                                     |
| FF               | ff-manualkyc           | Manual KYC                                                |
| AR               | ar-afip                | AFIP (Administración Federal de Ingresos Públicos)        |
| AR               | ar-renaper             | RENAPER                                                   |
| AT               | at-ec-vies             | Euro Commission VIES                                      |
| AT               | at-consumer1           | Consumer DB 1                                             |
| AT               | at-cdh-commercial      | Credit Header Data.                                       |
| BE               | be-cham-com            | Chamber of Commerce                                       |
| BE               | be-ec-vies             | Euro Commission VIES                                      |
| BE               | be-commercial1         | Commercial Activity Database                              |
| BE               | be-consumer1           | Consumer Database (Govt Sources)                          |
| BE               | be-consumer2           | Consumer Database (Commercial)                            |
| BE               | be-bankruptcy          | Bankruptcy Database                                       |
| BE               | be-phone1              | Phonebook Data                                            |
| BE               | be-phone2              | Mobile Phone Data                                         |
| BR               | br-veh-rego            | Vehicle Registration                                      |
| BR               | br-rec-fed             | Receita Federal                                           |
| BR               | br-elecroll            | Electors Database                                         |
| BR               | br-retirees            | Retiree Registry                                          |
| BR               | br-city-job            | City Employee Databases                                   |
| BR               | br-fed-job             | Federal Employee Databases                                |
| BR               | br-military-job        | Military Employee Databases                               |
| BR               | br-sus                 | Sistema Único de Saúde (SUS)                              |
| BR               | br-elem-school         | Public Elementary School                                  |
| BR               | br-commercial1         | E-Com Activity Database                                   |
| BR               | br-commercial2         | Commercial Activity Database                              |
| BR               | br-electric            | Electric Company                                          |
| BR               | br-chd                 | Credit Header Data                                        |
| BR               | br-telco-land          | Landline Telco                                            |
| BR               | br-telco-mobile1       | Mobile Telco 1                                            |
| BR               | br-telco-mobile2       | Mobile Telco 2                                            |
| BR               | br-telco-mobile3       | Mobile Telco 3                                            |
| CA               | ca-chd                 | Credit Header Data                                        |
| CA               | ca-commercial1         | Commercial Database                                       |
| CA               | ca-efax-cdh-consumer   | Equifax CA Consumer Credit Data Header                    |
| CA               | ca-postal1             | Postal Database                                           |
| CA               | ca-telco               | Phonebook Database                                        |
| CH               | ch-commercial1         | Commercial Database                                       |
| CH               | ch-consumer1           | Consumer Database                                         |
| CH               | ch-chd                 | Credit Header Data                                        |
| CL               | cl-nis                 | National Institute of Statistics                          |
| CN               | cn-bankcard            | China Bank Card                                           |
| CN               | cn-nationalid          | China National ID                                         |
| CN               | cn-unionpay            | China Unionpay                                            |
| CN               | cn-phone               | China National Phone                                      |
| CO               | co-dane                | National Administrative Department of Statistics (DANE)   |
| CZ               | cz-ec-vies             | Euro Commission VIES                                      |
| CZ               | cz-biz-register        | Business Registries                                       |
| DE               | de-gov2                | Government Databases                                      |
| DE               | de-consumer1           | Consumer Database 1                                       |
| DE               | de-consumer2           | Consumer Database 2                                       |
| DE               | de-cdh-public1         | Public Credit Credit Data 1                               |
| DE               | de-cdh-public2         | Public Credit Credit Data 2                               |
| DK               | dk-cpr                 | CPR Register                                              |
| DK               | dk-ec-vies             | Euro Commission VIES                                      |
| DK               | dk-consumer1           | Consumer Database                                         |
| ES               | es-gov-pub             | Public Gov Database                                       |
| ES               | es-aeat                | Agencia Estatal de Administración Tributaria (AEAT)       |
| ES               | es-census              | Census and Borme Database                                 |
| ES               | es-telco1              | Commercial Phonebook Database                             |
| ES               | es-deceased            | Deceased Notices                                          |
| ES               | es-sgda                | SGDA Database                                             |
| FI               | fi-vrk                 | Population Register Centre (Väestörekisterikeskus, VRK)   |
| FI               | fi-ec-vies             | Euro Commission VIES                                      |
| FI               | fi-consumer1           | Conumer and Public Register                               |
| FI               | fi-teco                | Phonebook Database.                                       |
| FR               | fr-rego-consumer       | Consumer & Car Registration                               |
| FR               | fr-commercial1         | Commercial Activity Database 1                            |
| FR               | fr-commercial2         | Commercial Activity Database 2                            |
| FR               | fr-consumer1           | Consumer Database 1                                       |
| FR               | fr-consumer2           | Postal Service & Consumer                                 |
| FR               | fr-consumer3           | Consumer Database 3                                       |
| FR               | fr-consumer4           | Consumer Database 4                                       |
| FR               | fr-telco1              | Phonebook & Loyalty Database                              |
| FR               | fr-telco2              | Phonebook Database                                        |
| FR               | fr-postal              | Postal Service (La Poste)                                 |
| GB               | gb-rolling-elecroll    | Rolling Register of the Electoral Roll                    |
| GB               | gb-ec-vies             | Euro Commission VIES                                      |
| GB               | gb-elecroll            | Electoral Roll                                            |
| GB               | gb-regtrust            | Registry Trust                                            |
| GB               | gb-propscot            | Property Ownership Registers of Scotland.                 |
| GB               | gb-insolvancy          | Insolvency Service Database                               |
| GB               | gb-company-house       | Companies House Shareholder File                          |
| GB               | gb-expn-chd            | Credit Header Data (Experian UK)                          |
| GB               | gb-consumer1           | Consumer Database 1                                       |
| GB               | gb-telco-land          | Phonebook Database - Landline                             |
| GB               | gb-telco1              | Telco Database 1                                          |
| GB               | gb-telco2              | Telco Database 2                                          |
| GB               | gb-telco3              | Telco Database 3                                          |
| GB               | gb-telco4              | Telco Database 4                                          |
| GI               | gi-telco               | Telco Database 1                                          |
| GLOBAL           | global-dz-globaldb     | Global Data                                               |
| HK               | hk-chd                 | Credit Header Data                                        |
| HK               | hk-property            | Property Records                                          |
| HK               | hk-residential         | Hong Kong Residential Address                             |
| ID               | id-nationalid-resident | Indonesia Resident Id Card                                |
| IE               | ie-gov-db              | Government Databases                                      |
| IN               | in-dl                  | India Drivers Licence                                     |
| IN               | in-nationalid-aadhaar  | Indian National ID Aadhaar                                |
| IN               | in-nationalid-epic     | India National ID - EPIC                                  |
| IN               | in-nationalid-pan      | India National ID - PAN                                   |
| IN               | in-passport            | Indian Passport Authority                                 |
| KH               | kh-dz-consumer1        | Cambodia Consumer Data                                    |
| IT               | it-ec-vies             | Euro Commission VIES                                      |
| IT               | it-chamcom             | Chamber of Commerce                                       |
| IT               | it-housing             | Housing and Real Estate Registry                          |
| IT               | it-protesti            | Protesti (Court Registers)                                |
| IT               | it-phone               | Phonebook Database                                        |
| IT               | it-consumer1           | Consumer Database 1                                       |
| IT               | it-elec                | Electric Utilities                                        |
| IT               | it-chd                 | Credit Header Data                                        |
| IT               | it-antifraud           | Commercial Credit Data                                    |
| IT               | it-telco-land          | Phonebook - Landline                                      |
| KE               | ke-citizen             | Government Citizenship Data                               |
| LU               | lu-ec-vies             | Euro Commission VIES                                      |
| LU               | lu-telco               | Phonebook Database                                        |
| MX               | mx-gov-db              | Government Data                                           |
| MX               | mx-property            | Property and Commercial Database                          |
| MX               | mx-media               | Media Database                                            |
| MY               | my-dz-credit1          | Malaysia Credit Bureau                                    |
| MY               | my-nationalid          | Malaysia National ID                                      |
| NG               | ng-govid-dl            | Driver's License Data                                     |
| NG               | ng-govid-nimc          | National Identity Management Commission                   |
| NG               | ng-govid-id            | National ID database                                      |
| NG               | ng-govid-bio           | Biometric Verification Database                           |
| NG               | ng-bank                | Nigeria Bank Account Verification                         |
| NL               | nl-kadaster            | Kadaster (Gov Property Registry)                          |
| NL               | nl-ec-vies             | Euro Commission VIES                                      |
| NL               | nl-commercial1         | Commercial Database 1                                     |
| NL               | nl-commercial2         | Commercial Database 2                                     |
| NL               | nl-consumer1           | Consumer Database 1                                       |
| NL               | nl-credcheck           | Credit Check Database                                     |
| NL               | nl-chd-commercial      | Credit and COmmercial Data                                |
| NL               | nl-telco               | Phonebook Database                                        |
| NO               | no-consumer1           | Consumer Database 1                                       |
| NO               | no-telco1              | Phonebook Database                                        |
| NZ               | nz-companies-office    | New Zealand Companies Registry                            |
| NZ               | nz-cx-smartid          | Centrix SmartID (Comprehensive Bureau check)              |
| NZ               | nz-cx-smartidlite      | Centrix SmartID Lite (Bureau check)                       |
| NZ               | nz-cx-consumer1        | Centrix Consumer Database                                 |
| NZ               | nz-cx-energyaccount    | New Zealand Retail Energy Account                         |
| NZ               | nz-cx-creditbureau1    | New Zealand Credit Bureau (Centrix)                       |
| NZ               | nz-cx-creditacc1       | New Zealand Credit Account (Centrix)                      |
| NZ               | nz-cx-creditaccbank    | New Zealand Credit Account - Bank (Centrix)               |
| NZ               | nz-cx-creditaccutil    | New Zealand Credit Account - Utility (Centrix)            |
| NZ               | nz-cx-creditaccfin     | New Zealand Credit Account - Finance (Centrix)            |
| NZ               | nz-cx-creditaccbnpl    | New Zealand Credit Account - BNPL (Centrix)               |
| NZ               | nz-dia                 | New Zealand Gov ID                                        |
| NZ               | nz-dia-birth           | New Zealand Birth Registration (DIA)                      |
| NZ               | nz-dia-pp              | New Zealand Passport (DIA)                                |
| NZ               | nz-dz-credit1          | New Zealand Credit Bureau (Centrix)                       |
| NZ               | nz-dz-nad              | New Zealand National Address Database                     |
| NZ               | nz-dz-vehicle          | New Zealand Vehicle Registration Alt Source               |
| NZ               | nz-efx-idplus          | Equifax New Zealand IdentityPlus                          |
| NZ               | nz-linz-property       | New Zealand LINZ property registry                        |
| NZ               | nz-nzta-dl             | New Zealand Drivers Licence (DIA)                         |
| NZ               | nz-ta-rego             | New Zealand Vehicle Registration                          |
| NZ               | nz-yp                  | New Zealand Yellow Pages                                  |
| PH               | ph-nationalid          | Philippines National ID                                   |
| PH               | ph-passport            | Philippine Passport Authority                             |
| PL               | pl-chd-commercial      | Credit and Commercial Database                            |
| PT               | pt-ec-vies             | Euro Commission VIES                                      |
| PT               | pt-consumer1           | Consumer Database 1                                       |
| PT               | pt-consumer2           | Consumer Database 2                                       |
| PT               | pt-telco               | Phonebook Database                                        |
| SE               | se-spar                | SPAR Register                                             |
| SE               | se-consumer1           | Consumer Database 1                                       |
| SE               | se-consumer2           | Consumer Database 2                                       |
| SG               | sg-chd                 | Credit Header Data                                        |
| SG               | sg-singpass            | Singpass                                                  |
| SK               | sk-business            | Government Business Register                              |
| TH               | th-nationalid          | Thailand National ID                                      |
| US               | us-school              | School Data                                               |
| US               | us-commercial1         | Mobile, Utility and Credit Databases                      |
| US               | us-commercial2         | Credit, Voter, Property Databases                         |
| US               | us-commercial3         | Government, Credit, Proprietary Databases                 |
| VN               | vn-nationalid          | Vietnam National ID                                       |
| VN               | vn-socialsecurity      | Vietnam Social Security                                   |


# API Error Codes
Source: https://docs.frankieone.com/docs/reference/error-codes



The FrankieOne standard [ErrorObject](/docs/introduction/reference/errors) has a field called "ErrorCode" which is made up of a prefix and a 4 digit number.

The prefix is the **Issue Location** and describes the system domain, layer, or service where the issue has occurred.

<Callout icon="thumbtack">
  ##### Note on Error Codes

  The 4-digit number is the error code itself. These are shared across all domains.
</Callout>

The tables below will describe the issue locations and error codes. In a number of cases, it suggests you contact the developer support team for further assistance. If this is the case, see here: [Contacting Developer Support](docs/contacting-developer-support)

In the API responses the error number will come combined with the issue code for example `ENT-1065` or `VAL-1010`

## Issue Location Codes

| Issue Location | Description                                                                                                                                             |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CODE           | Errors detected in the code. Indicates something unexpected has occurred. Please contact support as per the details below.                              |
| AUTH           | Authorization/security related errors.                                                                                                                  |
| SYS            | System level errors. Please contact support if you repeatedly get these errors.                                                                         |
| API            | Errors in your API message. Indicates an incorrectly constructed message.                                                                               |
| VAL            | API Data validation errors. See the issue details for more.                                                                                             |
| DOC            | Errors related directly to Document functions                                                                                                           |
| ENT            | Errors related directly to Entity functions                                                                                                             |
| CHECK          | Errors related to Check/Verify functions - Indicates potential issues with a check you're trying to perform, rather than the results of a check per se. |
| ADMIN          | Admin API errors. Please contact developer support should you receive one of these errors                                                               |

## Error Numbers

The following sections cover the different groups of error numbers we use.

## System Errors (0000 - 0399)

Returned by internal processes. Generally indicate a temporary issue, but please contact developer support if the issue persists.

| Error Number | HTTP Error Code | Description                                                                                                               |
| :----------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------ |
| 0000         | 500             | Unknown internal error. Contact developer support                                                                         |
| 0001         | 500             | Internal error. Contact developer support.                                                                                |
| 0002         | 401             | Not authorised to perform this function                                                                                   |
| 0003         | 500             | Internal error. Contact developer support.                                                                                |
| 0004         | 500             | Internal error. Contact developer support.                                                                                |
| 0005         | 500             | Internal error. Contact developer support.                                                                                |
| 0006         | 500             | Internal error. Contact developer support.                                                                                |
| 0007         | 503             | No service providers available/configured. Contact developer support                                                      |
| 0008         | 503             | No document scanning service available/configured. Contact developer support                                              |
| 0009         | 503             | No document verification service available/configured. Contact developer support                                          |
| 0010         | 503             | No comparison service available/configured. Contact developer support                                                     |
| 0011         | 503             | No industry service available/configured. Contact developer support                                                       |
| 0012         | 501             | Requested service (comparison) isn't supported for your current configuration. Contact developer support.                 |
| 0013         | 501             | Requested service (scan) isn't supported for your current configuration. Contact developer support.                       |
| 0014         | 501             | Requested service (document verify) isn't supported for your current configuration. Contact developer support.            |
| 0015         | 501             | Requested service (industry function) isn't supported for your current configuration. Contact developer support.          |
| 0016         | 501             | Requested service (entity verify) isn't supported for your current configuration. Contact developer support.              |
| 0017         | 501             | Requested service (specific entity check type) isn't supported for your current configuration. Contact developer support. |
| 0018         | 503             | No entity verification service available/configured. Contact developer support                                            |
| 0019         | 503             | Internal error. Contact developer support.                                                                                |
| 0020         | 500             | Internal error. Contact developer support.                                                                                |
| 0021         | 500             | Internal error. Contact developer support.                                                                                |
| 0022         | 500             | Internal error. Contact developer support.                                                                                |
| 0023         | 500             | Internal error. Contact developer support.                                                                                |
| 0024         | 500             | Internal error. Contact developer support.                                                                                |
| 0025         | 500             | Internal error. Contact developer support.                                                                                |
| 0026         | 500             | Internal error. Contact developer support.                                                                                |
| 0027         | 500             | Internal error. Contact developer support.                                                                                |
| 0028         | 500             | Internal error. Contact developer support.                                                                                |
| 0029         | 500             | Internal error. Contact developer support.                                                                                |
| 0030         | 500             | Internal error. Contact developer support.                                                                                |
| 0031         | 500             | Internal error. Contact developer support.                                                                                |
| 0032         | 500             | Cache retrieve error. Contact developer support.                                                                          |
| 0033         | 500             | Internal error. Contact developer support.                                                                                |
| 0034         | 500             | Internal error. Contact developer support.                                                                                |
| 0035         | 503             | Push to mobile service not available                                                                                      |

## Generic Errors (0400 - 0599)

Returned when no distinct error code is available (usually internal framework generated)

| Error Number | HTTP Error Code | Description                                       |
| :----------- | :-------------- | :------------------------------------------------ |
| 400          | 400             | Generic 400 Error - See error message for details |
| 401          | 401             | Generic 401 Error - See error message for details |
| 404          | 404             | Generic 404 Error - See error message for details |
| 405          | 405             | Generic 405 Error - See error message for details |
| 415          | 415             | Generic 415 Error - See error message for details |
| 422          | 422             | Generic 422 Error - See error message for details |
| 429          | 429             | Generic 429 Error - See error message for details |
| 500          | 500             | Generic 500 Error - See error message for details |
| 501          | 501             | Generic 501 Error - See error message for details |
| 503          | 503             | Generic 503 Error - See error message for details |

## Header Errors (0800 - 0999)

Returned when unsupported/missing header data is supplied

| Error Number | HTTP Error Code | Description                 |
| :----------- | :-------------- | :-------------------------- |
| 801          | 400             | Missing header: RequestID   |
| 802          | 400             | Missing header: CheckID     |
| 901          | 400             | Malformed header: RequestID |
| 902          | 400             | Malformed header: CheckID   |

## Application & Service Errors (1000 - )

These errors are returned when there is an issue with a specific request

| Error Number | HTTP Error Code | Description                                                                                                                                |
| :----------- | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| 1001         | 400             | Blank value supplied when one needed                                                                                                       |
| 1002         | 400             | Data supplied is incorrect/badly formatted.                                                                                                |
| 1003         | 405             | Can't merge different documents or entities                                                                                                |
| 1004         | 400             | Can't set document ID                                                                                                                      |
| 1005         | 400             | Data conversion issue                                                                                                                      |
| 1006         | 422             | Document supplied is unparsable                                                                                                            |
| 1007         | 400             | Can't set entity ID                                                                                                                        |
| 1008         | 400             | Entity supplied is unparsable                                                                                                              |
| 1009         | 404             | Requested document isn't found                                                                                                             |
| 1010         | 404             | Requested entity isn't found                                                                                                               |
| 1011         | 422             | Not enough data supplied to perform requested check                                                                                        |
| 1012         | 500             | Can't mark record as deleted                                                                                                               |
| 1013         | 400             | Utility bill not supplied                                                                                                                  |
| 1014         | 400             | Document not a PDF when PDF expected                                                                                                       |
| 1015         | 400             | Scan data not supplied when scan expected                                                                                                  |
| 1016         | 501             | Error response returned from utility processor                                                                                             |
| 1017         | 202             | Verification results incomplete - expect a notification push                                                                               |
| 1018         | 415             | Media type not supported                                                                                                                   |
| 1019         | 400             | End date before start date                                                                                                                 |
| 1020         | 400             | Bad page number                                                                                                                            |
| 1021         | 400             | Bad page count request                                                                                                                     |
| 1022         | 404             | Requested check ID not found                                                                                                               |
| 1023         | 404             | Can't retrieve original document                                                                                                           |
| 1024         | 404             | Cache returned a nil result                                                                                                                |
| 1025         | 400             | Geocode empty                                                                                                                              |
| 1026         | 400             | Multiple geocode results or inexact address match                                                                                          |
| 1027         | 400             | Bad geocode result - Address not found                                                                                                     |
| 1028         | 400             | Invalid country or country code                                                                                                            |
| 1029         | 401             | Attempt to access unauthorised data                                                                                                        |
| 1030         | 400             | Entity state precludes requested flag setting                                                                                              |
| 1031         |                 | Reserved                                                                                                                                   |
| 1032         |                 | Reserved                                                                                                                                   |
| 1033         |                 | Reserved                                                                                                                                   |
| 1034         |                 | Reserved                                                                                                                                   |
| 1035         |                 | Reserved                                                                                                                                   |
| 1036         |                 | Reserved                                                                                                                                   |
| 1037         |                 | Reserved                                                                                                                                   |
| 1038         |                 | Reserved                                                                                                                                   |
| 1039         |                 | Reserved                                                                                                                                   |
| 1040         |                 | Reserved                                                                                                                                   |
| 1041         | 400             | Identity document required                                                                                                                 |
| 1042         | 400             | Incorrect ID type                                                                                                                          |
| 1043         | 400             | Missing mobile number                                                                                                                      |
| 1044         | 400             | Missing name                                                                                                                               |
| 1045         | 400             | Empty name                                                                                                                                 |
| 1046         | 400             | Entity ineligible for service or in unsupported jurisdiction                                                                               |
| 1047         | 400             | Push to Mobile service returned PTM service offline                                                                                        |
| 1048         | 404             | PTM service couldn't find the token requested                                                                                              |
| 1049         | 404             | Internal error. Contact developer support.                                                                                                 |
| 1050         | 503             | No business query service available at this time.                                                                                          |
| 1051         | 503             | Failed to schedule background job                                                                                                          |
| 1052         | 500             | Business processor returned empty result set                                                                                               |
| 1053         | 400             | Supplied entity isn't of a suitable type                                                                                                   |
| 1054         | 400             | The requested operation amounted to no work                                                                                                |
| 1055         | 400             | A required prior result has expired                                                                                                        |
| 1056         | 500             | The background operation couldn't continue because required data was modified                                                              |
| 1057         | 500             | The background operation couldn't continue because required data was missing                                                               |
| 1058         | 500             | No result was obtained in a reasonable time                                                                                                |
| 1059         | 500             | Inconsistent result from business processor                                                                                                |
| 1060         | 400             | Mismatch between ownership request and ABR response                                                                                        |
| 1061         | 400             | Can't change status of check result                                                                                                        |
| 1062         | 403             | Operation not permitted, entity is in inactive state                                                                                       |
| 1063         | 500             | Report service exists but failed to generate a report or we couldn't save the result                                                       |
| 1064         | 400             | Document not owned by entity requested in document/verify function                                                                         |
| 1065         | 400             | Named entity profile not configured                                                                                                        |
| 1066         | 400             | Entity doesn't have an assigned profile                                                                                                    |
| 1067         | 400             | Entity profiles aren't enabled for customer                                                                                                |
| 1068         | 400             | Missing application id or referrer when requesting an IDV token                                                                            |
| 1069         | 400             | Invalid request to token service for a token                                                                                               |
| 1070         | 422             | Invalid request (unprocessable) to token service for a token                                                                               |
| 1071         | 500             | Reserved                                                                                                                                   |
| 1072         | 400             | Refresh token with mismatch applicant id                                                                                                   |
| 1073         | 500             | The expected or default policy isn't configured                                                                                            |
| 1074         | 500             | Attempt to toggle entity monitoring failed                                                                                                 |
| 1075         | 422             | Importing past results failed                                                                                                              |
| 1076         | 400             | Unknown business reportType                                                                                                                |
| 1077         | 503             | No intl business service available                                                                                                         |
| 1078         | 400             | No intl business search/profile criteria provided                                                                                          |
| 1079         | 400             | Intl business service rejected request                                                                                                     |
| 1080         | 400             | No shared blocklist                                                                                                                        |
| 1081         | 400             | No shared blocklist reason                                                                                                                 |
| 1082         | 500             | Shared blocklist internal error                                                                                                            |
| 1083         | 500             | Failed to get JWT signer or JWK key set                                                                                                    |
| 1084         | 400             | Entity not in valid state for setting a manual state                                                                                       |
| 1085         | 404             | Requested entity isn't retrievable at this time. **NOTE:** This is *USUALLY* transient, so wait 5 seconds and then retry                   |
| 1086         | 404             | Requested association doesn't exist                                                                                                        |
| 1087         | 400             | Requested association isn't allowed                                                                                                        |
| 1088         | 400             | Object not found from non-primary key search                                                                                               |
| 1089         | 500             | Internal error. Contact developer support.                                                                                                 |
| 1090         | 400             | Device data supplied is either missing or incorrectly formatted                                                                            |
| 1091         | 500             | Internal service error - please contact technical support                                                                                  |
| 1092         | 404             | Organisation can't be found in the requested country's registry                                                                            |
| 1093         | 400             | The request contains an invalid parameter or argument                                                                                      |
| 1094         | 400             | Search criteria too broad and returned too many results. Please retry with narrower search criteria                                        |
| 1095         | 400             | Incorrectly formatted organisation number                                                                                                  |
| 1096         | 400             | The requested country registry is incorrect. Please ensure you have the right country registry code                                        |
| 1097         | 503             | Unknown response from the registry                                                                                                         |
| 1098         | 400             | No company registry for the requested country is available to query. This is often due to local regulations not making this data available |
| 1099         | 400             | Search by organisation\_number not available for the jurisdiction                                                                          |
| 1100         | 400             | This is reserved for future error handling                                                                                                 |
| 1101         | 400             | This is reserved for future error handling                                                                                                 |
| 1102         | 400             | This is reserved for future error handling                                                                                                 |
| 1103         | 400             | This is reserved for future error handling                                                                                                 |
| 1104         | 400             | This is reserved for future error handling                                                                                                 |
| 1105         | 400             | This is reserved for future error handling                                                                                                 |


# Errors
Source: https://docs.frankieone.com/docs/reference/errors



All errors returned from the FrankieOne API will be wrapped up in a standard format error object.

### ErrorObject

The ErrorObject consists of the following attributes:

* **ErrorCode**: One of the standard error codes (see below)
* **ErrorMsg**: A human-readable message describing the error
* **HttpStatusCode**: The HTTP result code
* **Issues**: An array of additional error helpers, used to define where errors have occurred. Each element in the array consist of:

**Issue**: This is a description of the issue.

**IssueLocation**: The location in the payload or process where the issue was found/occurred.

```json Error Object theme={null}
{
  "commit":"2af478ed"
  "errorCode":"CORE-5990"
  "errorMsg":"Everything went kaflooey. Stay clam."
  "httpStatusCode":501
  "issues":[
    {
    "issue":"Invalid format. Must be YYYY-MM-DD"
    "issueLocation":"dateOfBirth"
    }
  ]
  "requestId":"01BFJA617JMJXEW6G7TDDXNSHX"
}
```

See the [Full List of Error Codes](/docs/introduction/reference/error-codes)


# KYC API Enums Reference
Source: https://docs.frankieone.com/docs/reference/kyc-enums

Complete reference of all enum values in the FrankieOne KYC V2 API

This page documents all enumerated values found in the FrankieOne KYC V2 API OpenAPI specifications. All values are extracted from `v2-openapi.json` and `v2-fc-core-bundled_generated.yaml`.

***

## Entity & Profile Enums

### Entity-Type

**Source:** `v2-openapi.json` → `#/components/schemas/Entity-Type`

| Value          | Description                  |
| :------------- | :--------------------------- |
| `INDIVIDUAL`   | Individual person entity     |
| `ORGANIZATION` | Organization/business entity |
| `UNKNOWN`      | Entity type not determined   |

***

### Service-Profile-State

**Source:** `v2-openapi.json` → `#/components/schemas/Service-Profile-State`

| Value         | Description                                           |
| :------------ | :---------------------------------------------------- |
| `INIT`        | Initial state when profile is created                 |
| `AUTO`        | Automatically assigned state after initial processing |
| `ACTIVE`      | Profile is active and in use                          |
| `ARCHIVED`    | Profile has been archived and is no longer active     |
| `BLOCKLISTED` | Profile is blocked from further actions               |
| `INACTIVE`    | Profile is inactive, not currently in use             |
| `DELETED`     | Profile has been deleted                              |
| `DUPLICATE`   | Profile is a duplicate of another existing profile    |

***

## Workflow Execution Enums

### Workflow-Execution-ResultEnum

**Source:** `v2-openapi.json` → `#/components/schemas/Workflow-Execution-ResultEnum`

| Value            | Description                                                  |
| :--------------- | :----------------------------------------------------------- |
| `UNCHECKED`      | Workflow has not yet been run                                |
| `IN_PROGRESS`    | Workflow is currently running                                |
| `REVIEW`         | Workflow produced results requiring review                   |
| `PASS`           | Workflow completed with PASS recommendation                  |
| `FAIL`           | Workflow finished with FAIL recommendation                   |
| `COMPLETE`       | Workflow finished, results complete (PASS/FAIL not required) |
| `INCOMPLETE`     | Workflow finished, results incomplete                        |
| `NEEDS_APPROVAL` | Workflow requires approval process                           |
| `APPROVED`       | Workflow was approved (typically by human)                   |
| `REJECTED`       | Workflow was rejected (typically by human)                   |
| `BLOCKED`        | Workflow blocked from completing, manual review required     |
| `CLEAR`          | Workflow completed with no issues (often for monitoring)     |
| `URGENT`         | Workflow completed with urgent matters requiring review      |
| `MONITOR`        | Workflow completed, further monitoring required              |

***

### Workflow-Execution-StateEnum

**Source:** `v2-openapi.json` → `#/components/schemas/Workflow-Execution-StateEnum`

| Value         | Description                                     |
| :------------ | :---------------------------------------------- |
| `COMPLETED`   | Workflow execution completed successfully       |
| `CANCELED`    | Workflow execution was canceled                 |
| `TERMINATED`  | Workflow execution terminated before completion |
| `ERROR`       | Workflow execution encountered an error         |
| `TIMEOUT`     | Workflow execution timed out                    |
| `IN_PROGRESS` | Workflow execution currently in progress        |

***

### Workflow-LifecyclePhaseEnum

**Source:** `v2-openapi.json` → `#/components/schemas/Workflow-LifecyclePhaseEnum`

| Value        | Description                     |
| :----------- | :------------------------------ |
| `ONBOARDING` | Workflow is in onboarding stage |
| `MONITORING` | Workflow is in monitoring stage |
| `OTHER`      | Workflow is in another stage    |

***

### Workflow-Step-Type

**Source:** `v2-fc-core-bundled_generated.yaml` → `#/components/schemas/Workflow-Step-Type`

| Value            | Description                |
| :--------------- | :------------------------- |
| `BLOCKLIST`      | Blocklist check step       |
| `DUPLICATE`      | Duplicate detection step   |
| `DECISION`       | Decision step              |
| `BRANCH`         | Branch/routing step        |
| `MONITOR_TOGGLE` | Monitoring toggle step     |
| `OTHER`          | Other step type            |
| `KYC`            | Know Your Customer step    |
| `AML`            | Anti-Money Laundering step |
| `IDV`            | Identity Verification step |
| `START`          | Workflow start step        |
| `FINISH`         | Workflow finish step       |

***

### Workflow-Step-ResultEnum

**Source:** `v2-openapi.json` → `#/components/schemas/Workflow-Step-ResultEnum`

| Value            | Description                                        |
| :--------------- | :------------------------------------------------- |
| `UNCHECKED`      | Step not attempted                                 |
| `SKIPPED`        | Step skipped (not required or previously run)      |
| `MISSING_DATA`   | Step requires additional data                      |
| `PASS`           | Step completed, goals met                          |
| `FAIL`           | Step completed, goals not met                      |
| `COMPLETE`       | Step finished successfully (no pass/fail)          |
| `INCOMPLETE`     | Step unable to finish successfully                 |
| `MATCH`          | Fully successful match against source(s)           |
| `NO_MATCH`       | No match against source(s)                         |
| `PARTIAL`        | Partially successful match                         |
| `CLEAR`          | No match found on negative list (positive outcome) |
| `HIT`            | Match found on negative list                       |
| `CLEARED`        | Previously found matches have been resolved        |
| `EXPIRED`        | Data has expired                                   |
| `CLEAR_REVIEW`   | Cleared but requires review                        |
| `HIT_ACCEPTED`   | Hit found and accepted                             |
| `HIT_REJECTED`   | Hit found and rejected                             |
| `NOT_APPLICABLE` | Step unnecessary (e.g., visa check for citizen)    |
| `ERROR`          | Unrecoverable error, no useful result              |

***

## Process Result Enums

### Process-ResultEnum

**Source:** `v2-openapi.json` → `#/components/schemas/Process-ResultEnum`

| Value            | Description                             |
| :--------------- | :-------------------------------------- |
| `MATCH`          | Element check matched expected criteria |
| `PARTIAL_MATCH`  | Element check partially matched         |
| `INVALID_MATCH`  | Element check matched but was invalid   |
| `NO_MATCH`       | Element check did not match             |
| `CLEAR`          | Element check was cleared               |
| `HIT`            | Element check hit specific condition    |
| `BAD_DATA`       | Element check encountered bad data      |
| `CREATED`        | Element check resulted in creation      |
| `UPDATED`        | Element check resulted in update        |
| `DELETED`        | Element check resulted in deletion      |
| `FAIL`           | Element check failed                    |
| `NOT_APPLICABLE` | Element check not applicable            |
| `SUSPECTED`      | Element check raised suspicion          |
| `REJECTED`       | Element check was rejected              |
| `MANUAL`         | Element check manually reviewed         |
| `CLEAR_AUTO`     | Element check cleared automatically     |
| `OVERRIDE`       | Element check overridden                |

***

### Process-Result-StateEnum

**Source:** `v2-openapi.json` → `#/components/schemas/Process-Result-StateEnum`

| Value         | Description               |
| :------------ | :------------------------ |
| `IN_PROGRESS` | Process in progress       |
| `COMPLETED`   | Process completed         |
| `TIMEOUT`     | Process timed out         |
| `ERROR`       | Process encountered error |

***

### Process-Result-System-StatusEnum

**Source:** `v2-openapi.json` → `#/components/schemas/Process-Result-System-StatusEnum`

| Value            | Description                              |
| :--------------- | :--------------------------------------- |
| `VALID`          | Process result is valid                  |
| `EXPIRED`        | Process result has expired               |
| `STALE`          | Process result is stale/outdated         |
| `MARKED_INVALID` | Process result explicitly marked invalid |
| `MARKED_IGNORE`  | Process result marked to be ignored      |

***

### Process-Result-ClassEnum

**Source:** `v2-openapi.json` → `#/components/schemas/Process-Result-ClassEnum`

| Value            | Description           |
| :--------------- | :-------------------- |
| `KYC`            | Know Your Customer    |
| `ID`             | Identity document     |
| `IDV`            | Identity Verification |
| `AML`            | Anti-Money Laundering |
| `FRAUDLIST`      | Fraud list            |
| `FRAUDCHECK`     | Fraud check           |
| `FRAUD`          | Fraud                 |
| `DEVICE`         | Device                |
| `MOBILE`         | Mobile                |
| `EMAIL`          | Email                 |
| `LOOKUP`         | Lookup                |
| `CREATE`         | Create operation      |
| `UPDATE`         | Update operation      |
| `DELETE`         | Delete operation      |
| `KYB`            | Know Your Business    |
| `DUPLICATE`      | Duplicate             |
| `BLOCKLIST`      | Blocklist             |
| `SUPPORTING_DOC` | Supporting document   |
| `MATCHLIST`      | Matchlist             |
| `VISA`           | Visa                  |
| `ACTIVITY`       | Activity              |

***

### Process-Result-Manual-StatusEnum-AML

**Source:** `v2-openapi.json` → `#/components/schemas/Process-Result-Manual-StatusEnum-AML`

| Value                  | Description                               |
| :--------------------- | :---------------------------------------- |
| `TRUE_POSITIVE`        | Result is true positive (not resolved)    |
| `FALSE_POSITIVE`       | Result is false positive (not resolved)   |
| `TRUE_POSITIVE_ACCEPT` | True positive, resolved, accept activity  |
| `TRUE_POSITIVE_REJECT` | True positive, resolved, reject activity  |
| `UNKNOWN`              | Result unknown (not resolved)             |
| `UNKNOWN_ACCEPT`       | Unknown result, resolved, accept activity |
| `UNKNOWN_REJECT`       | Unknown result, resolved, reject activity |

***

### Process-Result-Manual-StatusEnum-KYC

**Source:** `v2-openapi.json` → `#/components/schemas/Process-Result-Manual-StatusEnum-KYC`

| Value  | Description                  |
| :----- | :--------------------------- |
| `PASS` | Result determined to be pass |
| `FAIL` | Result determined to be fail |

***

### Process-Result-Manual-StatusEnum-IDV

**Source:** `v2-openapi.json` → `#/components/schemas/Process-Result-Manual-StatusEnum-IDV`

| Value      | Description                      |
| :--------- | :------------------------------- |
| `CLEAR`    | Result determined to be clear    |
| `REJECTED` | Result determined to be rejected |

***

### Process-Result-Manual-StatusEnum-Duplicate

**Source:** `v2-openapi.json` → `#/components/schemas/Process-Result-Manual-StatusEnum-Duplicate`

| Value                  | Description                                           |
| :--------------------- | :---------------------------------------------------- |
| `FALSE_POSITIVE`       | Entities are not duplicates, keep both                |
| `TRUE_POSITIVE_ACCEPT` | Entities are duplicates, keep incoming (B) as primary |
| `TRUE_POSITIVE_REJECT` | Entities are duplicates, keep existing (A) as primary |

***

### Process-Result-Manual-StatusEnum-Matchlist

**Source:** `v2-openapi.json` → `#/components/schemas/Process-Result-Manual-StatusEnum-Matchlist`

| Value                  | Description                    |
| :--------------------- | :----------------------------- |
| `FALSE_POSITIVE`       | Result is false positive       |
| `TRUE_POSITIVE_REJECT` | True positive, reject activity |

***

### Process-Result-Manual-StatusEnum-Fraud

**Source:** `v2-openapi.json` → `#/components/schemas/Process-Result-Manual-StatusEnum-Fraud`

| Value                   | Description                       |
| :---------------------- | :-------------------------------- |
| `FALSE_POSITIVE_ACCEPT` | False positive, acceptable risk   |
| `FALSE_POSITIVE_REJECT` | False positive, unacceptable risk |
| `TRUE_POSITIVE_ACCEPT`  | True positive, acceptable risk    |
| `TRUE_POSITIVE_REJECT`  | True positive, unacceptable risk  |

***

## Risk Enums

### Risk-Level

**Source:** `v2-openapi.json` → `#/components/schemas/Risk-Level`

| Value          | Description               |
| :------------- | :------------------------ |
| `UNKNOWN`      | Risk level not determined |
| `LOW`          | Low risk                  |
| `MEDIUM`       | Medium risk               |
| `HIGH`         | High risk                 |
| `UNACCEPTABLE` | Unacceptable risk level   |

***

### Risk-Factor-Status

**Source:** `v2-openapi.json` → `#/components/schemas/Risk-Factor-Status`

| Value        | Description                                      |
| :----------- | :----------------------------------------------- |
| `VALID`      | Risk factor applicable to entity                 |
| `STALE`      | Risk factor no longer applicable                 |
| `OVERRIDDEN` | Risk factor manually overridden                  |
| `DISCARDED`  | Risk factor added but discarded in same workflow |

***

## Document Enums

### Document-Type

**Source:** `v2-openapi.json` → `#/components/schemas/Document-Type`

| Value                       | Description                                     |
| :-------------------------- | :---------------------------------------------- |
| `OTHER`                     | Generic/unspecified document                    |
| `DRIVERS_LICENSE`           | Driver's license                                |
| `PASSPORT`                  | Passport                                        |
| `VISA`                      | Visa document (not Visa payment card)           |
| `IMMIGRATION`               | Immigration card                                |
| `NATIONAL_ID`               | National ID card                                |
| `TAX_ID`                    | National tax identifier                         |
| `NATIONAL_HEALTH_ID`        | National health program ID (Medicare, NHS)      |
| `CONCESSION`                | State-issued concession card                    |
| `HEALTH_CONCESSION`         | State-issued health concession card             |
| `PENSION`                   | State-issued pension ID                         |
| `MILITARY_ID`               | Military ID                                     |
| `BIRTH_CERT`                | Birth certificate                               |
| `CITIZENSHIP`               | Citizenship certificate                         |
| `MARRIAGE_CERT`             | Marriage certificate                            |
| `DEATH_CERT`                | Death certificate                               |
| `NAME_CHANGE`               | Name change confirmation                        |
| `UTILITY_BILL`              | Regulated utility bill                          |
| `BANK_STATEMENT`            | Bank/card statement                             |
| `BANK_ACCOUNT`              | Bank account                                    |
| `INTENT_PROOF`              | Proof of intent (photo/video/letter)            |
| `ATTESTATION`               | Document of attestation (Statutory Declaration) |
| `SELF_IMAGE`                | Selfie for comparisons                          |
| `DEVICE`                    | Device ID                                       |
| `VEHICLE_REGISTRATION`      | Vehicle registration number                     |
| `PROOF_OF_ADDRESS`          | Proof of address document                       |
| `HOUSE_REGISTRATION`        | House registration document                     |
| `YELLOW_HOUSE_REGISTRATION` | Yellow House Registration Thor Ror 13           |
| `WORK_PERMIT`               | Work permit                                     |
| `EMPLOYMENT_CERTIFICATE`    | Certificate of employment                       |
| `NOTARY_PUBLIC_ID`          | Notary Public Identification                    |
| `EXTERNAL_ADMIN`            | Details of appointed administrator              |
| `CHARGES`                   | Details of charges against company/director     |
| `PRE_ASIC`                  | Pre-ASIC documents                              |
| `ANNUAL_RETURN`             | Company annual return                           |
| `REPORT`                    | Frankie-generated report                        |
| `TRUST_DEED`                | Corporate trust deed                            |
| `PARTNERSHIP_AGREEMENT`     | Partnership agreement documents                 |
| `ADMIN_CHANGE`              | Change of administrator                         |
| `COMPANY_REPORT`            | Registry-filed company reports                  |
| `CHECK_RESULTS`             | Results of checks completed outside Frankie     |
| `AVIATION_SECURITY_ID`      | Aviation Security Identification Card           |
| `MARITIME_SECURITY_ID`      | Maritime Security Identification Card           |

***

### Document-Class

**Source:** `v2-openapi.json` → `#/components/schemas/Document-Class`

| Value        | Description         |
| :----------- | :------------------ |
| `OTHER`      | Other/unspecified   |
| `IDENTITY`   | Identity document   |
| `SUPPORTING` | Supporting document |
| `REPORT`     | Report document     |

***

### Document-Attachment-Side

**Source:** `v2-openapi.json` → `#/components/schemas/Document-Attachment-Side`

| Value   | Description            |
| :------ | :--------------------- |
| `FRONT` | Front side of document |
| `BACK`  | Back side of document  |

***

### Document-Attachment-Retrieval-Status

**Source:** `v2-openapi.json` → `#/components/schemas/Document-Attachment-Retrieval-Status`

| Value      | Description                                   |
| :--------- | :-------------------------------------------- |
| `NORMAL`   | Data retrieved and included                   |
| `EXCLUDED` | Data not included (not requested or deleted)  |
| `FAILED`   | Data could not be retrieved from secure store |

***

## Individual Entity Enums

### Address-TypeEnum

**Source:** `v2-openapi.json` → `#/components/schemas/Address-TypeEnum`

| Value                     | Description                     |
| :------------------------ | :------------------------------ |
| `OTHER`                   | Other/unspecified address       |
| `RESIDENTIAL`             | Residential address             |
| `BUSINESS`                | Business address                |
| `POSTAL`                  | Postal address                  |
| `REGISTERED_OFFICE`       | Registered office address       |
| `PLACE_OF_BUSINESS`       | Place of business               |
| `OFFICIAL_CORRESPONDANCE` | Official correspondence address |
| `PLACE_OF_BIRTH`          | Place of birth                  |
| `OFFICE_LOCALITY`         | Office locality                 |

***

### Address-StatusEnum

**Source:** `v2-openapi.json` → `#/components/schemas/Address-StatusEnum`

| Value      | Description      |
| :--------- | :--------------- |
| `CURRENT`  | Current address  |
| `PREVIOUS` | Previous address |
| `FUTURE`   | Future address   |

***

### GenderEnum

**Source:** `v2-openapi.json` → `#/components/schemas/GenderEnum`

| Value         | Description |
| :------------ | :---------- |
| `MALE`        | Male        |
| `FEMALE`      | Female      |
| `NON_BINARY`  | Non-binary  |
| `OTHER`       | Other       |
| `UNSPECIFIED` | Unspecified |

***

### Date-Type

**Source:** `v2-openapi.json` → `#/components/schemas/Date-Type`

| Value           | Description                  |
| :-------------- | :--------------------------- |
| `BUDDHIST`      | Buddhist calendar            |
| `DISCORDIAN`    | Discordian calendar          |
| `GREGORIAN`     | Gregorian calendar (default) |
| `HEBREW`        | Hebrew calendar              |
| `ISLAMIC`       | Islamic calendar             |
| `JULIAN`        | Julian calendar              |
| `LUNAR`         | Lunar calendar               |
| `MESO_AMERICAN` | Meso-American calendar       |
| `PERSIAN`       | Persian calendar             |
| `OTHER`         | Other calendar system        |

***

## Contact Information Enums

### Phone Number Type

**Source:** `v2-openapi.json` → `#/components/schemas/Phone-Number` → `type`

| Value      | Description      |
| :--------- | :--------------- |
| `OTHER`    | Other phone type |
| `WORK`     | Work phone       |
| `HOME`     | Home phone       |
| `MOBILE`   | Mobile phone     |
| `BUSINESS` | Business phone   |
| `FAX`      | Fax number       |

***

### Email Type

**Source:** `v2-openapi.json` → `#/components/schemas/Email` → `type`

| Value      | Description      |
| :--------- | :--------------- |
| `OTHER`    | Other email type |
| `WORK`     | Work email       |
| `PERSONAL` | Personal email   |
| `BUSINESS` | Business email   |

***

## Consent Enums

### Consent-Type-Param

**Source:** `v2-openapi.json` → `#/components/schemas/Consent-Type-Param`

| Value            | Description            |
| :--------------- | :--------------------- |
| `GENERAL`        | General consent        |
| `DOCS`           | Document consent       |
| `CREDITHEADER`   | Credit header consent  |
| `UNDER18`        | Under 18 consent       |
| `PAYROLL`        | Payroll consent        |
| `INSURANCE`      | Insurance consent      |
| `SUPERANNUATION` | Superannuation consent |

***

## Workflow Issue Enums

### Workflow-Issue-Category

**Source:** `v2-openapi.json` → `#/components/schemas/Workflow-Issue-Category`

| Value           | Description                  |
| :-------------- | :--------------------------- |
| `AML`           | Anti-Money Laundering issues |
| `BAD_DATA`      | Invalid or incorrect data    |
| `BIOMETRICS`    | Biometrics check issues      |
| `BLOCKLISTED`   | Entity on blocklist          |
| `DECEASED`      | Entity is deceased           |
| `DEVICE`        | Device check issues          |
| `DOCUMENT`      | Document check issues        |
| `DUPLICATE`     | Entity has duplicates        |
| `EXPIRY`        | Process/document expired     |
| `FRAUD`         | Possible fraud detected      |
| `IDV`           | Identity Verification issues |
| `INFORMATIONAL` | Informational messages       |
| `KYC`           | Know Your Customer issues    |
| `SYSTEM`        | System-level issues          |
| `VERIFY`        | Verification issues          |
| `VISA`          | Visa check issues            |
| `WATCHLIST`     | Watchlist check issues       |
| `ACTIVITY`      | Activity process issues      |

***

### Workflow-Issue-Type

**Source:** `v2-openapi.json` → `#/components/schemas/Workflow-Issue-Type`

| Value                  | Category              | Description                        |
| :--------------------- | :-------------------- | :--------------------------------- |
| `AML_ISSUE`            | AML                   | AML issue                          |
| `BAD_DATA_ADDRESS`     | BAD\_DATA             | Address missing/unusable           |
| `BAD_DATA_DOB`         | BAD\_DATA             | Date of birth missing/unusable     |
| `BAD_DATA_EMAIL`       | BAD\_DATA             | Email missing/unusable             |
| `BAD_DATA_ID`          | BAD\_DATA             | ID missing/unusable                |
| `BAD_DATA_MOBILE`      | BAD\_DATA             | Mobile missing/unusable            |
| `BAD_DATA_NAME`        | BAD\_DATA             | Name missing/unusable              |
| `BLOCKED`              | BLOCKLISTED           | Entity blocked                     |
| `COMPROMISED_DOCUMENT` | IDV                   | Document is compromised            |
| `CREDIT_HEADER`        | INFORMATIONAL         | Credit header information          |
| `DATA_COMPARISON`      | IDV                   | Data comparison issue              |
| `DATA_CONSISTENCY`     | IDV                   | Data consistency issue             |
| `DATA_VALIDATION`      | IDV                   | Data validation issue              |
| `DENY_LIST`            | VISA                  | Visa deny list match               |
| `DECEASED`             | DECEASED              | Person is deceased                 |
| `DEVICE_FRAUD_MATCH`   | DEVICE                | Device fraud detected              |
| `DEVICE_INVALID`       | DEVICE                | Device is invalid                  |
| `DOCUMENT_COMPARISON`  | IDV                   | Document comparison issue          |
| `DUPLICATE`            | DUPLICATE             | Entity is duplicate                |
| `FRAUD_CHECK`          | FRAUD                 | Fraud detected during checks       |
| `FRAUD_DEVICE`         | FRAUD                 | Device fraud detected              |
| `FRAUD_IP_ADDRESS`     | FRAUD                 | IP address fraud detected          |
| `FRAUD_EMAIL_ADDRESS`  | FRAUD                 | Email address fraud detected       |
| `FRAUD_PHONE_NUMBER`   | FRAUD                 | Phone number fraud detected        |
| `FRAUD_ISSUE`          | FRAUD                 | Fraud issue                        |
| `FRAUD_LIST`           | FRAUD                 | Entity on fraud list               |
| `IMAGE_INTEGRITY`      | IDV                   | Image integrity issue              |
| `INTERNAL_MATCH`       | WATCHLIST/BLOCKLISTED | Internal watchlist/blocklist match |
| `LIVENESS_DETECTION`   | IDV                   | Liveness detection failed          |
| `MATCHED_EXTERNAL`     | BLOCKLISTED           | External blocklist match           |
| `MATCHED_INTERNAL`     | BLOCKLISTED           | Internal blocklist match           |
| `MATCHED_SHARED`       | BLOCKLISTED           | Shared blocklist match             |
| `MEDIA`                | AML                   | Adverse media hits                 |
| `NOT_FOUND`            | KYC                   | No match found                     |
| `OCR`                  | IDV                   | OCR data mismatch                  |
| `PARTIAL`              | KYC                   | Partially successful KYC           |
| `PEP`                  | AML                   | Politically Exposed Person hits    |
| `REQUIRES_AML`         | EXPIRY                | AML needs re-initiation            |
| `REQUIRES_IDV`         | EXPIRY                | IDV needs re-initiation            |
| `REQUIRES_KYC`         | EXPIRY                | KYC needs re-initiation            |
| `REQUIRES_VISA`        | EXPIRY                | Visa needs re-initiation           |
| `SANCTION`             | AML                   | Sanction hits                      |
| `SERVICE_ERROR`        | SYSTEM                | All providers returned error       |
| `SERVICE_TIMEOUT`      | SYSTEM                | All providers timed out            |
| `VISA_FAILED`          | VISA                  | Visa check failed                  |
| `VISUAL_AUTHENTICITY`  | IDV                   | Visual authenticity issue          |
| `WATCHLIST`            | AML                   | Watchlist hits                     |
| `ACTIVITY_AML`         | ACTIVITY              | AML-related activity issue         |
| `ACTIVITY_FRAUD`       | ACTIVITY              | Fraud-related activity issue       |
| `ACTIVITY_DEVICE`      | ACTIVITY              | Device-related activity issue      |

***

### Workflow-Issue-Severity

**Source:** `v2-openapi.json` → `#/components/schemas/Workflow-Issue-Severity`

| Value      | Description               |
| :--------- | :------------------------ |
| `INFO`     | Informational only        |
| `REVIEW`   | Requires review           |
| `BLOCK`    | Blocks further processing |
| `WARNING`  | Warning, not blocking     |
| `CRITICAL` | Critical issue            |
| `ERROR`    | Error encountered         |

***

## Monitoring & Subscription Enums

### Monitoring-Type / Subscription-Type

**Source:** `v2-openapi.json` → `#/components/schemas/Monitoring-Type`

| Value      | Description                      |
| :--------- | :------------------------------- |
| `AML`      | Anti-Money Laundering monitoring |
| `ACTIVITY` | Activity monitoring              |

***

### Subscription-Status

**Source:** `v2-fc-core-bundled_generated.yaml` → `#/components/schemas/Subscription-Status`

| Value      | Description                            |
| :--------- | :------------------------------------- |
| `ENABLED`  | Subscription is active and operational |
| `DISABLED` | Subscription is inactive               |

***

## IDV (Identity Verification) Enums

### IDV OCR Status

**Source:** `v2-openapi.json` → `#/components/schemas/IDV-OCR-Response` → `status`

| Value                                    | Description                               |
| :--------------------------------------- | :---------------------------------------- |
| `AWAITING_OCR_RESULTS_PROVIDER_OFFLINE`  | Provider offline, OCR results unavailable |
| `AWAITING_DOCUMENT_UPLOAD_INVALID_TYPE`  | Document type not supported               |
| `WAITING_DOCUMENT_UPLOAD_FAILED_OCR`     | Document upload failed                    |
| `AWAITING_DOCUMENT_OCR`                  | Document being processed by provider      |
| `DOCUMENT_INVALID_EXCEEDED_SIZE_LIMIT`   | Document too large                        |
| `DOCUMENT_INVALID_INCORRECT_FILE_FORMAT` | Document format not supported             |
| `AWAITING_DOCUMENT_UPLOAD_BACK`          | Back of document needs upload             |
| `AWAITING_DOCUMENT_UPLOAD_FRONT`         | Front of document needs upload            |
| `COMPLETE_OCR`                           | Document OCR valid and completed          |

***

### IDV Process Status

**Source:** `v2-openapi.json` → `#/components/schemas/IDV-InitProcess-Response` → `status`

| Value                                    | Description                                   |
| :--------------------------------------- | :-------------------------------------------- |
| `IN_PROGRESS`                            | Provider processing request                   |
| `CHECK_PROCESSING_DOWNLOAD_FAIL`         | Processing, image download issue (will retry) |
| `WAITING_SELFIE_UPLOAD`                  | Awaiting applicant selfie upload              |
| `CHECK_PROCESSING`                       | Provider processing request                   |
| `DOCUMENT_INVALID_EXCEEDED_SIZE_LIMIT`   | Document too large                            |
| `DOCUMENT_INVALID_INCORRECT_FILE_FORMAT` | Document format not supported                 |
| `PROVIDER_OFFLINE`                       | Provider not available                        |
| `COMPLETE`                               | Process valid and completed                   |

***

### Supplementary-Data-IDV-OCR-Comparison-Enum-Comparison-Source

**Source:** `v2-openapi.json` → `#/components/schemas/Supplementary-Data-IDV-OCR-Comparison-Enum-Comparison-Source`

| Value        | Description                |
| :----------- | :------------------------- |
| `ENTITY`     | Original entity data       |
| `OCR_UPDATE` | Updated data from OCR scan |

***

## Matchlist Enums

### Matchlist-Action

**Source:** `v2-openapi.json` → `#/components/schemas/Matchlist-Action`

| Value    | Description                       |
| :------- | :-------------------------------- |
| `BLOCK`  | Recommended action: block entity  |
| `ALERT`  | Recommended action: create alert  |
| `ALLOW`  | Recommended action: allow entity  |
| `REVIEW` | Recommended action: review entity |
| `NONE`   | No action, only use riskFactor    |

***

### Matchlist-State

**Source:** `v2-fc-core-bundled_generated.yaml` → `#/components/schemas/Matchlist-State`

| Value      | Description                                |
| :--------- | :----------------------------------------- |
| `ACTIVE`   | Matchlist active, can be used for matching |
| `ARCHIVED` | Matchlist archived, cannot be used         |

***

### Matchlist-Entry-State

**Source:** `v2-fc-core-bundled_generated.yaml` → `#/components/schemas/Matchlist-Entry-State`

| Value     | Description                                      |
| :-------- | :----------------------------------------------- |
| `ACTIVE`  | Entry active, can be used for matching           |
| `EXPIRED` | Entry expired, visible but not used for matching |
| `DELETED` | Entry deleted, unusable                          |

***

### Matchlist-Entry-Attribute-Type

**Source:** `v2-openapi.json` → `#/components/schemas/Matchlist-Entry-Attribute-Type`

| Value                          | Entity Type  | Description                           |
| :----------------------------- | :----------- | :------------------------------------ |
| `ENTITY_TYPE`                  | Both         | Entity type                           |
| `EMAIL_ADDRESS`                | Both         | Email address                         |
| `EMAIL_DOMAIN`                 | Both         | Email domain                          |
| `PHONE_NUMBER`                 | Both         | Phone number                          |
| `ADDR_STREET_NUMBER`           | Both         | Address street number                 |
| `ADDR_STREET_NAME`             | Both         | Address street name                   |
| `ADDR_STREET_TYPE`             | Both         | Address street type                   |
| `ADDR_NEIGHBORHOOD`            | Both         | Address neighborhood                  |
| `ADDR_LOCALITY`                | Both         | Address locality                      |
| `ADDR_DISTRICT`                | Both         | Address district                      |
| `ADDR_SUBDIVISION`             | Both         | Address subdivision                   |
| `ADDR_COUNTRY`                 | Both         | Address country                       |
| `ADDR_POSTAL_CODE`             | Both         | Address postal code                   |
| `ADDR_UNSTRUCTURED_LONG_FORM`  | Both         | Unstructured address                  |
| `DOC_CLASS`                    | Both         | Document class                        |
| `DOC_TYPE`                     | Both         | Document type                         |
| `DOC_SUBTYPE`                  | Both         | Document subtype                      |
| `DOC_PRIMARY_IDENTIFIER`       | Both         | Document primary ID                   |
| `DOC_SECONDARY_IDENTIFIER`     | Both         | Document secondary ID                 |
| `IND_DISPLAY_NAME`             | Individual   | Individual display name               |
| `IND_GIVEN_NAME`               | Individual   | Individual given name                 |
| `IND_FAMILY_NAME`              | Individual   | Individual family name                |
| `IND_MIDDLE_NAME`              | Individual   | Individual middle name                |
| `IND_DATE_OF_BIRTH`            | Individual   | Individual date of birth              |
| `IND_NATIONALITY`              | Individual   | Individual nationality                |
| `ORG_REGISTERED_SUBDIVISION`   | Organization | Organization registered subdivision   |
| `ORG_REGISTERED_COUNTRY`       | Organization | Organization registered country       |
| `ORG_REGISTRATION_NUMBER`      | Organization | Organization registration number      |
| `ORG_REGISTRATION_NUMBER_TYPE` | Organization | Organization registration number type |
| `ORG_NAME`                     | Organization | Organization name                     |

***

## Search Enums

### Search-Type

**Source:** `v2-fc-core-bundled_generated.yaml` → `#/components/schemas/Search-Type`

| Value   | Description                |
| :------ | :------------------------- |
| `EXACT` | Returns only exact matches |
| `FUZZY` | Returns similar matches    |

***

### Search-Field

**Source:** `v2-fc-core-bundled_generated.yaml` → `#/components/schemas/Search-Field`

| Value                 | Applies To   | Description                    |
| :-------------------- | :----------- | :----------------------------- |
| `NAME`                | Both         | All name parts                 |
| `GIVEN_NAME`          | Individual   | Given name                     |
| `FAMILY_NAME`         | Individual   | Family name                    |
| `MIDDLE_NAME`         | Individual   | Middle name                    |
| `DISPLAY_NAME`        | Individual   | Display name                   |
| `OTHER_NAME`          | Individual   | Other names                    |
| `ADDRESS`             | Both         | Address (planned)              |
| `EMAIL_ADDRESS`       | Both         | Email address (planned)        |
| `PHONE_NUMBER`        | Both         | Phone number (planned)         |
| `DOCUMENT_IDENTIFIER` | Both         | Document identifiers (planned) |
| `EXTERNAL_REFERENCE`  | Both         | External reference             |
| `REGISTERED_NAME`     | Organization | Registered name                |
| `ALTERNATE_NAME`      | Organization | Alternate name                 |
| `REGISTRATION_NUMBER` | Organization | Registration number            |

***

## Audit Enums

### AuditEvent-Type

**Source:** `v2-fc-core-bundled_generated.yaml` → `#/components/schemas/AuditEvent-Type`

| Value                          | Description                  |
| :----------------------------- | :--------------------------- |
| `CUSTOMER_SETUP`               | Customer setup               |
| `CUSTOMER_UPDATE`              | Customer update              |
| `ENTITY_CREATE`                | Entity creation              |
| `ENTITY_LOOKUP`                | Entity lookup                |
| `ENTITY_PURGE`                 | Entity deletion              |
| `ENTITY_RESULT_UPDATE`         | Manual result update         |
| `ENTITY_RESULT_INVALIDATE`     | Result invalidation          |
| `ENTITY_UPDATE`                | Entity update                |
| `GENERATE_REPORT`              | Report generation            |
| `LEGACY_AUDIT`                 | V1 audit event               |
| `MATCHLIST_ENTRY`              | Matchlist entry operation    |
| `PORTAL_ACTION`                | Portal event                 |
| `RISK_OVERRIDE`                | Risk override                |
| `SERVICE_PROFILE_CREATE`       | Service profile creation     |
| `SERVICE_PROFILE_UPDATE`       | Service profile update       |
| `SERVICE_PROFILE_STATE_CHANGE` | Service profile state change |
| `WORKFLOW_EVENT`               | Generic workflow event       |
| `WORKFLOW_COMPLETE`            | Workflow completion          |
| `WORKFLOW_RISK_CHANGE`         | Workflow risk change         |
| `WORKFLOW_STATUS_CHANGE`       | Workflow status change       |
| `OTHER`                        | Other event type             |

***

### AuditEvent-Channel

**Source:** `v2-fc-core-bundled_generated.yaml` → `#/components/schemas/AuditEvent-Channel`

| Value    | Description    |
| :------- | :------------- |
| `API`    | API channel    |
| `PORTAL` | Portal channel |
| `ONESDK` | OneSDK channel |
| `SYSTEM` | System channel |

***

### AuditEvent-Status

**Source:** `v2-fc-core-bundled_generated.yaml` → `#/components/schemas/AuditEvent-Status`

| Value     | Description             |
| :-------- | :---------------------- |
| `SUCCESS` | Event succeeded         |
| `ERROR`   | Event encountered error |
| `INFO`    | Informational event     |

***

## Object Type Enum

### Object-Type

**Source:** `v2-openapi.json` → `#/components/schemas/Object-Type`

| Value                 | Description                |
| :-------------------- | :------------------------- |
| `ADDRESS`             | Address object             |
| `NAME`                | Name object                |
| `PHONE_NUMBER`        | Phone number object        |
| `EMAIL`               | Email object               |
| `DATE_OF_BIRTH`       | Date of birth object       |
| `WEBSITE`             | Website object             |
| `SHAREHOLDER`         | Shareholder object         |
| `OFFICIAL`            | Official object            |
| `UBO`                 | Ultimate Beneficial Owner  |
| `REGISTRATION`        | Registration object        |
| `SHAREHOLDING`        | Shareholding object        |
| `SHARECAPITAL`        | Share capital object       |
| `DOCUMENT`            | Document object            |
| `DOCUMENT_ATTACHMENT` | Document attachment object |
| `RESULT_PROCESS`      | Process result object      |
| `RESULT_STEP`         | Step result object         |
| `RESULT_WORKFLOW`     | Workflow result object     |
| `SERVICE_PROFILE`     | Service profile object     |
| `AUDIT_EVENT`         | Audit event object         |
| `EXTERNAL_REFERENCE`  | External reference object  |
| `RISK_ASSESSMENT`     | Risk assessment object     |
| `MATCHLIST`           | Matchlist object           |

***

### Workflow-Execution-ObjectTypeEnum

**Source:** `v2-openapi.json` → `#/components/schemas/Workflow-Execution-ObjectTypeEnum`

| Value           | Description          |
| :-------------- | :------------------- |
| `NAME`          | Name object          |
| `ADDRESS`       | Address object       |
| `DATE_OF_BIRTH` | Date of birth object |
| `ORGANIZATION`  | Organization object  |
| `DOCUMENT`      | Document object      |
| `EMAIL_ADDRESS` | Email address object |
| `PHONE_NUMBER`  | Phone number object  |
| `DEVICE`        | Device object        |
| `INDIVIDUAL`    | Individual object    |

***

## Fraud & Activity Enums

### Fraud-Check-Types

**Source:** `v2-fc-core-bundled_generated.yaml` → `#/components/schemas/Fraud-Check-Types`

| Value           | Description               |
| :-------------- | :------------------------ |
| `DEVICE`        | Device fraud check        |
| `IP`            | IP address fraud check    |
| `EMAIL_ADDRESS` | Email address fraud check |
| `PHONE_NUMBER`  | Phone number fraud check  |

***

### Likelihood

**Source:** `v2-openapi.json` → `#/components/schemas/Likelihood`

| Value       | Description          |
| :---------- | :------------------- |
| `LOW`       | Low likelihood       |
| `MEDIUM`    | Medium likelihood    |
| `HIGH`      | High likelihood      |
| `VERY_HIGH` | Very high likelihood |
| `UNKNOWN`   | Unknown likelihood   |

***

## Supplementary Data Type Enums

### Supplementary-Data-Base Type

**Source:** `v2-openapi.json` → `#/components/schemas/Supplementary-Data-Base` → `type`

| Value                 | Description                |
| :-------------------- | :------------------------- |
| `AML`                 | Anti-Money Laundering data |
| `KYC_ADDRESS`         | KYC address data           |
| `KYC_DOB`             | KYC date of birth data     |
| `KYC_GENDER`          | KYC gender data            |
| `KYC_NAME`            | KYC name data              |
| `ID`                  | Identity document data     |
| `VISA`                | Visa data                  |
| `NAME_VALIDATION`     | Name validation data       |
| `KYB_ORGANIZATION`    | KYB organization data      |
| `MATCHLIST`           | Matchlist data             |
| `DUPLICATE`           | Duplicate data             |
| `FRAUD_DEVICE`        | Fraud device data          |
| `FRAUD_EMAIL_ADDRESS` | Fraud email address data   |
| `FRAUD_PHONE_NUMBER`  | Fraud phone number data    |
| `FRAUD_IP_ADDRESS`    | Fraud IP address data      |
| `FRAUD_LOOKUP`        | Fraud lookup data          |
| `ACTIVITY_AML`        | Activity AML data          |
| `ACTIVITY_DEVICE`     | Activity device data       |
| `ACTIVITY_FRAUD`      | Activity fraud data        |

***

## Query Parameter Enums

### Level Query Parameter

**Source:** `v2-openapi.json` → `#/components/parameters/levelQuery`

| Value    | Description                               |
| :------- | :---------------------------------------- |
| `id`     | Return just an ID                         |
| `meta`   | Return metadata only, no links or base64  |
| `base64` | Return metadata and data in base64 format |

***

### Level Query Parameter (No ID)

**Source:** `v2-openapi.json` → `#/components/parameters/levelNoIdQuery`

| Value    | Description                              |
| :------- | :--------------------------------------- |
| `meta`   | Return metadata only, no links or base64 |
| `base64` | Return metadata and images as base64     |

***

### X-Frankie-Background

**Source:** `v2-openapi.json` → `#/components/parameters/X-Frankie-Background`

| Value | Description                                          |
| :---- | :--------------------------------------------------- |
| `0`   | Synchronous request (wait for completion)            |
| `1`   | Asynchronous request (return 202, run in background) |

***

### Sort Order

**Source:** `v2-openapi.json` → `#/components/parameters/sort`

| Value  | Description      |
| :----- | :--------------- |
| `asc`  | Ascending order  |
| `desc` | Descending order |

***

## External Reference Enums

### External-Reference Type

**Source:** `v2-openapi.json` → `#/components/schemas/External-Reference` → `type`

| Value      | Description          |
| :--------- | :------------------- |
| `SYSTEM`   | System reference     |
| `CUSTOMER` | Customer reference   |
| `OTHER`    | Other reference type |

***

## Name Enums

### Individual-Name-Alternate Type

**Source:** `v2-openapi.json` → `#/components/schemas/Individual-Name-Alternate` → `type`

| Value      | Description     |
| :--------- | :-------------- |
| `OTHER`    | Other name type |
| `ALIAS`    | Alias name      |
| `PREVIOUS` | Previous name   |

***

## Supplementary Data Document Type Enums

### Document-Supplementary-Data Type

**Source:** `v2-openapi.json` → `#/components/schemas/Document-Supplementary-Data-Base` → `type`

| Value                | Description                             |
| :------------------- | :-------------------------------------- |
| `NATIONAL_HEALTH_ID` | National health ID supplementary data   |
| `BIRTH_CERT`         | Birth certificate supplementary data    |
| `NATIONAL_ID`        | National ID supplementary data          |
| `CITIZENSHIP`        | Citizenship supplementary data          |
| `PASSPORT`           | Passport supplementary data             |
| `MARRIAGE_CERT`      | Marriage certificate supplementary data |

***

## Visa Enums

### Visa Holder Type

**Source:** `v2-openapi.json` → `#/components/schemas/Supplementary-Data-Visa` → `holderType`

| Value       | Description                              |
| :---------- | :--------------------------------------- |
| `PRIMARY`   | Primary visa holder                      |
| `SECONDARY` | Secondary holder (spouse/partner/family) |

***

## Name Validation Enums

### Name Match Order

**Source:** `v2-openapi.json` → `#/components/schemas/Workflow-Step-Summary-NameValidation` → `nameMatchOrder`

| Value | Description                |
| :---- | :------------------------- |
| `FGO` | Family, Given, Other names |
| `OFG` | Other, Family, Given names |
| `GOF` | Given, Other, Family names |
| `FOG` | Family, Other, Given names |
| `GFO` | Given, Family, Other names |
| `OGF` | Other, Given, Family names |
| `FG`  | Family, Given names        |
| `FO`  | Family, Other names        |
| `GF`  | Given, Family names        |
| `OF`  | Other, Family names        |

***

## Result Reference Type

### Result-Reference-Type

**Source:** `v2-openapi.json` → `#/components/schemas/Result-Reference-Type`

| Value       | Description          |
| :---------- | :------------------- |
| `URL`       | URL reference        |
| `REFERENCE` | Reference identifier |

***

## Workflow Include Query

### Include Query Parameter

**Source:** `v2-openapi.json` → `#/components/parameters/includeQuery`

| Value                | Description                             |
| :------------------- | :-------------------------------------- |
| `workflowDefinition` | Include workflow definition in response |

***

## Workflow Execution Scope

### Workflow-Execution-ScopeEnum

**Source:** `v2-fc-core-bundled_generated.yaml` → `#/components/schemas/Workflow-Execution-ScopeEnum`

| Value  | Description                                          |
| :----- | :--------------------------------------------------- |
| `LAST` | Apply filters only to most recent workflow execution |
| `ANY`  | Search across all workflow executions                |

***

## Status Override Filter

### Status-Override-Type-Filter

**Source:** `v2-fc-core-bundled_generated.yaml` → `#/components/schemas/Status-Override-Type-Filter`

| Value                | Description                                     |
| :------------------- | :---------------------------------------------- |
| `ONLY_OVERRIDDEN`    | Only profiles with manually overridden statuses |
| `EXCLUDE_OVERRIDDEN` | Exclude profiles with overridden statuses       |
| `ALL`                | Both with and without overridden statuses       |

***

## Notes

### Enum Coverage

All enums documented above are **verified** from the OpenAPI specifications:

* `v2-openapi.json` (KYC V2 API)
* `v2-fc-core-bundled_generated.yaml` (Core V2 API)

### Missing from Spec

The following risk factor handlers mentioned in use case pages are **NOT IN SPEC**:

* `entity_age`
* `entity_type`
* `jurisdiction_lookup`
* `document_type_lookup`
* `num_sanctions`
* `pep_level_lookup`
* `pep_origin_lookup`
* `has_adverse_media`
* `on_watchlist`
* `idv_document_result`
* `idv_facial_comparison_result`
* `idv_ocr_comparison_result`
* `fraud_email`
* `fraud_phone_number`
* `fraud_ip_address`
* `fraud_device`
* `fraud_count_session`
* `unresolved_duplicates`
* `on_matchlist_internal`
* `workflow_attempts_counter`

These handlers appear to be internal risk engine configuration values not exposed in the public API schema.


# Outbound IP addresses
Source: https://docs.frankieone.com/docs/reference/outbound-ip-addresses



These are the IPs traffic from FrankieOne will come from.

## Testing (demo and UAT)

* 52.62.31.108
* 149.167.70.106
* 123.103.207.82

## Production

<Info title="Production IP Addresses">
  We use three of these IP addresses, you will need to whitelist three of them.
</Info>

* 13.236.159.198
* 13.237.83.115
* 16.50.141.56

<Callout icon="thumbtack">
  ##### Inbound IP Addresses

  We don't currently support inbound IP address filtering, meaning we can't limit what IP address would be able to authenticate using your FrankieOne API credentials
</Callout>


# Event Notifications & Webhooks
Source: https://docs.frankieone.com/docs/reference/webhooks



<Info>
  To set up webhooks, contact [help@frankieone.com ](mailto:help@frankieone.com) with your designated webhook endpoint URL(s) and contact email. You can configure multiple webhook endpoints for different notification types. Ensure your endpoint is accessible via HTTPS.
</Info>

FrankieOne uses webhooks to send real-time notifications about events in your system, such as a workflow completing or an entity's risk profile changing. This allows you to build automated, event-driven integrations.

## Available Notifications

<CardGroup>
  <Card title="Workflow Events" icon="arrows-rotate">
    Notifications triggered when a workflow execution completes, providing updates on the final status and outcome.
  </Card>

  <Card title="IDV Biometrics Events" icon="id-card">
    Notifications for IDV biometrics events, such as token requests, results retrieval, errors, and expirations.
  </Card>

  <Card title="Entity Events" icon="user">
    Notifications related to entity events, such as onboarding, updates, and errors.
  </Card>

  <Card title="Activity Monitoring Events" icon="chart-line">
    Notifications from financial transactions (deposits, withdrawals) or activities (registration, login) are checked for fraud, AML, or behavior risks and trigger alerts when operators act on them.
  </Card>
</CardGroup>

### Workflow Events

| Function           | Description                                                                                                                                                                                                     |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WorkflowComplete` | Sent when a workflow execution finishes, providing the final status and outcome. Also sent when there is an error during workflow execution — use the `functionResult` field to distinguish success from error. |

<Accordion title="Workflow Error Events">
  Notifications related to errors workflow events are sent to your webhook endpoint.

  | Notification Function | Description                                            |
  | --------------------- | ------------------------------------------------------ |
  | `WorkflowComplete`    | Sent when there is an error during workflow execution. |
</Accordion>

### IDV Biometrics Events

| Function            | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `TOKEN_REQUESTED`   | Sent when a token is requested for IDV biometrics.           |
| `ONB_URL_GENERATED` | Sent when an onboarding URL is successfully generated.       |
| `RESULTS_RETRIEVED` | Sent when IDV biometrics results are successfully retrieved. |
| `OCR_PROCESSED`     | Sent when OCR processing is completed.                       |

These IDV function names are also sent when errors occur during the corresponding operation. Use the `functionResult` field to distinguish success from error.

<Accordion title="IDV Biometrics Error Events">
  Notifications related to errors in IDV biometrics events are sent to your webhook endpoint.

  | Notification Function | Description                                                          |
  | --------------------- | -------------------------------------------------------------------- |
  | `TOKEN_REQUESTED`     | Sent when there is an error during token request for IDV biometrics. |
  | `RESULTS_RETRIEVED`   | Sent when there is an error retrieving IDV biometrics results.       |
  | `OCR_PROCESSED`       | Sent when there is an error during OCR processing.                   |
  | `ONB_URL_GENERATED`   | Sent when there is an error generating the onboarding URL.           |
</Accordion>

### Entity Profile Events

| Function                | Description                                                                                                                                                                                                                                                        |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `EntityStatusChanged`   | Sent when the event status of an entity changes.<br /><br /><u>How it works</u><br />- Triggered immediately following the completion of a v2 workflow execution.<br />- It monitors changes to individual Event Statuses rather than a singular "Overall Status". |
| `EntityRiskChanged`     | Sent when the risk level of an entity profile changes.                                                                                                                                                                                                             |
| `EntityProfileUpdated`  | Sent when an entity profile is updated.                                                                                                                                                                                                                            |
| `EntityAssigneeChanged` | Sent when the assignee of an entity profile changes.                                                                                                                                                                                                               |

<br />

<Tip>
  **Migrating from V1?**

  Some webhook function names differ from their V1 counterparts and do not follow the same naming conventions. For example, V1's `EntityStatusChange` is `EntityStatusChanged` in V2. Refer to the [Migrating from V1](https://docs.frankieone.com/#migrating-from-v1) to see the key differences.
</Tip>

<Callout icon="thumbtack">
  **Understanding Event Statuses**

  For a complete mapping of all values and their transition logic, please consult the [Event Statuses Reference Guide](https://docs.frankieone.com/docs/portal-statuses-and-tags#event-statuses).
</Callout>

<Callout icon="note">
  **Webhook Notification Model for Repeated Workflow Runs**

  Webhook notifications for workflow completion are sent per workflow execution. In the KYC webhook specification, the `WorkflowComplete `event is triggered each time a workflow execution finishes successfully. Each payload includes a unique `workflowExecutionId `representing that specific execution instance.

  If multiple workflow executions occur for the same entity, a separate webhook notification is generated for each execution. Webhooks are not aggregated across multiple runs.
</Callout>

### Transaction and Activity Monitoring Events

FrankieOne sends notifications to keep you informed about transaction and activity monitoring. These notifications are sent to your configured webhook endpoint.

| **Notification Function** | **Description**                                                                                                                                                                                                               |
| :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ActivityAlertCreated`    | Sent when an alert has been detected and created for an activity (financial or non-financial). Emitted before workflow execution.  This notifies customers that there is a potential issue to review for a particular entity. |
| `ActivityAlertUpdated`    | Sent when an activity alert has been resolved into a finalized state (e.g., TPA, TPR, FP). This allows customers to trigger actions like releasing or blocking payments after they have been held for review.                 |

<CodeGroup>
  ```json ActivityAlertCreated with a non-transaction activity - No transactionId theme={null}
  {
    "entityId": "12345678-1234-1234-4321-123487650912",
    "entityType": "INDIVIDUAL",
    "function": "ActivityAlertCreated",
    "message": "Activity alert created",
    "notificationType": "EVENT",
    "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
    "version": "2.0.0",
    "entityCustomerReference": "customer-ref-12345",
    "channel": "api",
    "customAttributes": {
      "activityId": {"type": "string", "value": "01KAWDS1NMC8J4RBDSSPF24NSV"},
      "evaluationId": {"type": "string", "value": "01KAWDS1NMC8J4RBDSSPGA67KD"},
      "activityResultId": {"type": "string", "value": "01KAWDS1PBM4BKBKVYDCP5EXBW"},
      "processResultId": {"type": "string", "value": "01KAWDS1PBM4BKBKVYDCP5EXBW"},
      "activityResultClass": {"type": "string", "value": "FRAUD"},
      "activityAt": {"type": "datetime", "value": "2025-09-02T05:38:02Z"}
    }
  }
  ```

  ```json ActivityAlertCreated with a transactional activity - Has transaction ID theme={null}
  {
    "entityId": "12345678-1234-1234-4321-123487650912",
    "entityType": "INDIVIDUAL",
    "function": "ActivityAlertCreated",
    "message": "Activity alert created",
    "notificationType": "EVENT",
    "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
    "version": "2.0.0",
    "entityCustomerReference": "customer-ref-12345",
    "channel": "api",
    "customAttributes": {
      "activityId": {"type": "string", "value": "01KAWDS1NMC8J4RBDSSPF24NSV"},
      "evaluationId": {"type": "string", "value": "01KAWDS1NMC8J4RBDSSPGA67KD"},
      "activityResultId": {"type": "string", "value": "01KAWDS1PBM4BKBKVYDCP5EXBW"},
      "processResultId": {"type": "string", "value": "01KAWDS1PBM4BKBKVYDCP5EXBW"},
      "activityResultClass": {"type": "string", "value": "FRAUD"},
      "transactionIdentifier": {"type": "string", "value": "TXN123456789"},
      "activityAt": {"type": "datetime", "value": "2025-09-02T05:38:02Z"},
    }
  }
  ```

  ```json ActivityAlertUpdated - Has transaction ID theme={null}
  {
      "entityId": "12345678-1234-1234-4321-123487650912",
      "entityType": "INDIVIDUAL",
      "serviceName": "DEFAULT",
      "function": "ActivityAlertUpdated",
      "functionResult": "SUCCESS",
      "notificationType": "EVENT",
      "message": "Activity alert updated",
      "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
      "version": "2.0.0",
      "entityCustomerReference": "customer-ref-12345",
      "overallStatus": "REVIEW",
      "channel": "api",
      "customAttributes": {
        "activityId": {"type": "string", "value": "01KAWDS1NMC8J4RBDSSPF24NSV"},
        "evaluationId": {"type": "string", "value": "01KAWDS1NMC8J4RBDSSPGA67KD"},
        "activityResultId": {"type": "string", "value": "01KAWDS1PBM4BKBKVYDCP5EXBW"},
        "activityResultClass": {"type": "string", "value": "FRAUD"},
        "activityAt ": {"type": "string", "value": "2025-09-02T05:38:02.00036Z"}
      }
  }
  ```
</CodeGroup>

## Webhook Structure

<Callout icon="bell">
  You can configure your webhook endpoint to receive all notifications or only specific types, depending on your integration requirements. The `notificationType` field in the payload identifies the category of each notification.

  Event-specific fields in the payload are always populated with relevant values based on the event type, ensuring you have the necessary context for processing.
</Callout>

All V2 webhooks share a consistent structure. The payload contains two key fields, notificationType and function, which you should use to determine how to process the event.

notificationType: Indicates the nature of the update. For most V2 use cases, this will be EVENT.

function: This field specifies the exact event that occurred.

The payload for every webhook consists of a base schema of common fields, with additional event-specific fields included depending on the function.

<Danger>
  **Some webhook function names differ from their V1 counterparts.** They also do not follow the same naming conventions. Refer to the tables above for the correct function names.
</Danger>

### Endpoint Format

FrankieOne appends the `requestID` to your configured webhook endpoint:

```text theme={null}
https://your-domain.com/webhook-endpoint/{requestID}
```

### Base Payload Schema

These fields are present on every webhook notification.

| Field                     | Type   | Always Present | Description                                                                                                                                                                                                 |
| ------------------------- | ------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version`                 | string | Yes            | The API version of the webhook payload.                                                                                                                                                                     |
| `entityId`                | string | Yes            | The unique identifier of the entity related to the event.                                                                                                                                                   |
| `function`                | string | Yes            | The specific event that triggered the notification. See [Available Notifications](#available-notifications).                                                                                                |
| `functionResult`          | string | Yes            | The outcome of the event. `SUCCESS` indicates the operation completed successfully. `FAILURE` indicates the operation encountered an error or could not be completed.                                       |
| `requestId`               | string | Yes            | The unique identifier of the API request that initiated the event.                                                                                                                                          |
| `notificationType`        | string | Yes            | The category of notification. One of `FUNCTION`, `RESULT`, `EVENT`, `ALERT`.                                                                                                                                |
| `message`                 | string | Yes            | A human-readable summary of the event.                                                                                                                                                                      |
| `entityCustomerReference` | string | No             | Your customer reference identifier, used for linking notifications to your internal records.                                                                                                                |
| `workflowExecutionId`     | string | No             | The unique identifier of the workflow execution. Present when a workflow triggers the event.                                                                                                                |
| `workflowName`            | string | No             | The name of the workflow that triggered the event.                                                                                                                                                          |
| `serviceName`             | string | No             | The name of the service profile involved.                                                                                                                                                                   |
| `entityType`              | string | No             | The type of entity (e.g., `INDIVIDUAL`).                                                                                                                                                                    |
| `overallRiskLevel`        | string | No             | The overall risk level of the entity. One of `UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, `UNACCEPTABLE`.                                                                                                            |
| `overallStatus`           | string | No             | The overall status of the entity. One of `UNCHECKED`, `IN_PROGRESS`, `REVIEW`, `PASS`, `FAIL`, `COMPLETE`, `INCOMPLETE`, `NEEDS_APPROVAL`, `APPROVED`, `REJECTED`, `BLOCKED`, `CLEAR`, `URGENT`, `MONITOR`. |
| `channel`                 | string | No             | The channel source from which the webhook was triggered. Present in v2 webhooks.                                                                                                                            |
| `assignee`                | string | No             | The assignee of the entity.                                                                                                                                                                                 |
| `customAttributes`        | object | No             | Custom attributes associated with the entity. Present in v2 webhooks when configured.                                                                                                                       |

### Event-Specific Fields

Depending on the `function`, additional fields may be present in the payload.

| Function              | Additional Fields                                      | Description                                             |
| --------------------- | ------------------------------------------------------ | ------------------------------------------------------- |
| `WorkflowComplete`    | `workflowExecutionId`, `workflowName`, `overallStatus` | Identifiers and final status of the completed workflow. |
| `EntityStatusChanged` | `overallStatus`                                        | The new overall status of the entity profile.           |
| `EntityRiskChanged`   | `overallRiskStatus`                                    | The new risk level of the entity profile.               |

### Payload Examples

<CodeGroup>
  ```json Workflow Complete theme={null}
  {
    "workflowExecutionId": "01JMX7F1Z61K0BP0KWY6MWAQ4J",
    "entityId": "12345678-1234-1234-4321-123487650912",
    "entityType": "INDIVIDUAL",
    "workflowName": "Onboarding",
    "serviceName": "DEFAULT",
    "function": "WorkflowComplete",
    "functionResult": "SUCCESS",
    "notificationType": "EVENT",
    "message": "Entity profile updated",
    "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
    "version": "2.0.0",
    "entityCustomerReference": "customer-ref-12345",
    "overallStatus": "REVIEW",
    "channel": "api"
  }
  ```

  ```json Entity Risk Changed theme={null}
  {
    "workflowExecutionId": "01JMX7F1Z61K0BP0KWY6MWAQ4J",
    "entityId": "12345678-1234-1234-4321-123487650912",
    "entityType": "INDIVIDUAL",
    "workflowName": "Onboarding",
    "serviceName": "DEFAULT",
    "function": "EntityRiskChanged",
    "functionResult": "SUCCESS",
    "notificationType": "EVENT",
    "message": "Entity profile updated",
    "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
    "version": "2.0.0",
    "entityCustomerReference": "customer-ref-12345",
    "overallRiskStatus": "LOW",
    "channel": "api"
  }
  ```

  ```json Entity Status Changed theme={null}
  {
    "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
    "version": "2.0.0",
    "entityId": "12345678-1234-1234-4321-123487650912",
    "entityType": "INDIVIDUAL",
    "entityCustomerReference": "customer-ref-12345",
    "function": "EntityStatusChanged",
    "functionResult": "SUCCESS",
    "notificationType": "EVENT",
    "channel": "api",
    "serviceName": "DEFAULT",
    "assignee": "john.doe@example.com",
    "workflowExecutionId": "01JMX7F1Z61K0BP0KWY6MWAQ4J",
    "workflowName": "Onboarding",
    "message": "Entity status changed from 'UNCHECKED' to 'PASS'",
    "overallStatus": "PASS"
  }
  ```

  ```json Entity Profile Updated theme={null}
  {
    "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
    "version": "2.0.0",
    "entityId": "12345678-1234-1234-4321-123487650912",
    "entityType": "INDIVIDUAL",
    "entityCustomerReference": "customer-ref-12345",
    "function": "EntityProfileUpdated",
    "functionResult": "SUCCESS",
    "notificationType": "EVENT",
    "channel": "api",
    "message": "Entity profile updated"
  }
  ```

  ```json Entity Assignee Changed theme={null}
  {
    "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
    "version": "2.0.0",
    "entityId": "12345678-1234-1234-4321-123487650912",
    "entityType": "INDIVIDUAL",
    "entityCustomerReference": "customer-ref-12345",
    "function": "EntityAssigneeChanged",
    "functionResult": "SUCCESS",
    "notificationType": "EVENT",
    "channel": "api",
    "serviceName": "DEFAULT",
    "assignee": "jane.smith@example.com",
    "workflowExecutionId": "01JMX7F1Z61K0BP0KWY6MWAQ4J",
    "workflowName": "Onboarding",
    "message": "Entity assignee changed from 'john.doe@example.com' to 'jane.smith@example.com'"
  }
  ```

  ```json Document Processing (IDV) theme={null}
  {
    "workflowExecutionId": "01JMX7F1Z61K0BP0KWY6MWAQ4J",
    "entityId": "12345678-1234-1234-4321-123487650912",
    "entityType": "INDIVIDUAL",
    "workflowName": "DocumentProcessing",
    "serviceName": "IDV",
    "function": "OCR_ERROR",
    "functionResult": "FAILURE",
    "notificationType": "EVENT",
    "message": "Error encountered while processing OCR data.",
    "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
    "version": "2.0.0",
    "entityCustomerReference": "customer-ref-12345",
    "overallStatus": "FAILED",
    "channel": "api"
  }
  ```
</CodeGroup>

***

## Handling Notifications

### 1. Receive the Webhook

Your endpoint should respond with a `200` or `202` HTTP status code to acknowledge receipt.

* If your endpoint returns a `5xx` or `4xx` status code (other than `400`), the system retries delivery.
* A `400` response stops retries immediately.

### 2. Process the Notification

Use the `notificationType` and `function` fields to determine the appropriate action. Use `functionResult` to distinguish successful events from errors.

### 3. Retrieve Workflow Execution Results

After receiving a `WorkflowComplete` notification, retrieve the full workflow execution results by calling:

```text theme={null}
GET /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions/{workflowExecutionId}
```

This endpoint is documented in the OpenAPI spec and available in the Postman collection. All path parameters (`entityId`, `serviceName`, `workflowName`, `workflowExecutionId`) are provided in the webhook payload.

Required headers:

| Header                 | Description                  |
| ---------------------- | ---------------------------- |
| `api_key`              | Your FrankieOne API key.     |
| `X-Frankie-CustomerID` | Your FrankieOne customer ID. |

## Security

### HTTPS and IP Whitelisting

All webhook payloads are delivered over HTTPS. FrankieOne supports IP whitelisting so you can restrict incoming requests to known FrankieOne IP addresses. See [Outbound IP Addresses](/reference/outbound-ip-addresses) for the list of IPs to whitelist.

### JWT Authentication (Optional)

You can enable JSON Web Token (JWT) signing for additional payload verification. Contact [support@frankieone.com](mailto:support@frankieone.com) to enable JWT verification for your account.

When enabled, the JWT is included in the `Authorization` header of the webhook request using the Bearer scheme:

```http theme={null}
Authorization: Bearer <base64 header>.<base64 body>.<base64 signature>
```

The JWT has the following structure:

**Header:**

```json theme={null}
{
  "alg": "RS256",
  "typ": "JWT"
}
```

**Body:**

```json theme={null}
{
  "sub": "[email protected]",
  "iat": 1516239022,
  "iss": "io.frankiefinancial.kycaml"
}
```

| Field | Description                                                   |
| ----- | ------------------------------------------------------------- |
| `sub` | The subject. Present for portal-triggered notifications only. |
| `iat` | Issued-at timestamp (UTC epoch, seconds).                     |
| `iss` | Issuer. Fixed value: `io.frankiefinancial.kycaml`.            |

**Security details:**

* RSA-4096 bit private key encryption.
* A customer-specific public key is provided for verification.
* HTTPS transport with secure algorithms.

***

## Retry Mechanism

FrankieOne retries failed webhook deliveries using the following approach:

1. **Initial Retry:** Immediately after the first failure.
2. **Exponential Backoff:** Subsequent retries occur at increasing intervals.
3. **Maximum Retries:** Up to 50 attempts over approximately 24 hours.

If all retries fail, the message is moved to a Dead Letter Queue (DLQ) and the FrankieOne support team is notified. Contact [support@frankieone.com](mailto:support@frankieone.com) to retrieve messages from the DLQ if necessary.

***

## Best Practices

* **Respond quickly.** Return a `200` or `202` from your webhook endpoint as fast as possible. Perform any heavy processing asynchronously after acknowledging receipt.
* **Handle duplicates.** Due to retries, your endpoint may receive the same notification more than once. Use the `requestId` field to deduplicate.
* **Check `functionResult`.** The same `function` name (e.g., `WorkflowComplete`, `TOKEN_REQUESTED`) is used for both success and error events. Always check `functionResult` to determine the outcome.
* **Use the retrieval endpoint.** Webhook payloads contain summary information. For full workflow execution details, always call the retrieval endpoint using the identifiers provided in the payload.

***

## Migrating from V1

Key differences between V1 and V2 webhook notifications:

| Aspect               | V1                                              | V2                                                                                                                       |
| -------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Function names**   | `EntityStatusChange`                            | `EntityStatusChanged`                                                                                                    |
|                      | `EntityRiskChange`                              | `EntityRiskChanged`                                                                                                      |
|                      | `EntityProfileChange`                           | `EntityProfileUpdated`                                                                                                   |
|                      | `EntityAssigneeChange`                          | `EntityAssigneeChanged`                                                                                                  |
|                      | Per-operation names (e.g., `CreateCheckEntity`) | `WorkflowComplete` (single event for all workflow completions)                                                           |
| **Payload fields**   | `checkId` present in some payloads              | `workflowExecutionId`, `workflowName`, `entityType`, `entityCustomerReference`, `serviceName`, `channel` added           |
| **Result retrieval** | `GET /v1/retrieve/{requestID}`                  | `GET /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions/{workflowExecutionId}` |


# Resolving a potential blocklist match
Source: https://docs.frankieone.com/docs/resolving-a-potential-blocklist-match



## Video Guide

<iframe />

## Overview

When an applicant submits their information, the system performs a blocklist check by matching the provided data against entries in the internal blocklist. The results will be seen as below while the process is governed by configurable matching rules/entries and risk scoring to determine the likelihood of a match.

<img alt="" />

A match would mean the entity to be onboarded will blocklisted.

* **Personal info** - all entity details

* **Blocklist match** - all blocklist entry details

* **Highlights** - these are the fields that matched for both Personal info and Blocklist match

If there are more than 3 attributes matched, user can see all by selecting **show full list**.

#### Resolving blocklist issues

If a potential blocklist match has been found, the blocklist check indicator turns red and user action is required to either confirm or remove the potential blocklist match.

1. **Review the Match**: The system displays both the incoming applicant's information and the blocklisted profile side by side in the FrankieOne portal. These matches are initially indicated as **Potential match**.

<img alt="" />

2. **Determine Match Status**:
   Once assessed if this is, in fact, a match, use the dropdown on the blocklisted profile to set as a True Positive or a Ignore this match.

<img alt="" />

3. a. **True Positive (True Positive Reject)**: Confirms the match; the application is rejected, and the profile remains on the blocklist. When a true positive blocklist match is found, the blocklist check will remain in the failed state and the workflow event status status will remain as configured.
   b. Ignore this match (False Positive): Indicates no actual match; the application proceeds to the next steps.

4. **Leave a comment**: As part of Portal standards, any manual review action will require a comment

5. A badge will appear beside the resolved match accordingly.


# Review AML matches
Source: https://docs.frankieone.com/docs/review-and-resolve-potential-aml-matches

If a new customer has a potential AML match, this guide will show you how to review and resolve it.

### Video Guide

<iframe />

## Issue Types

If a new customer has a potential AML match, it will show as AML in the **Entities list**.

<img alt="" />

## View potential AML matches

Navigate to the **AML screening** section within the Workflow events in the entity view by clicking the AML screening from the workflow summary. The entity's overall workflow status will be **Needs attention** as there are potential AML matches found.

<img alt="" />

If an entity has AML issues, it will show the AML screening section.

<img alt="" />

1. AML search - contains the parameters used in getting the AML matches
2. Match summary - shows the total of AML alerts for each of the statuses (Potential Match, Unknown, True Positive, False Positive)
3. Returned results - Filters
   1. Filter by AML match - filters the result based on the criteria selected against the AML search values
   2. Filter by Match status - filters the result based on the AML alert status selected
   3. Filter by AML issues - filters the result based on the Issues selected
4. Returned results - All AML alerts will be listed in the Returned results table with the following columns:
   1. AML Match - the Name, Year of birth, and Country for the AML alert
   2. Match Status - current AML alert status
   3. AML Issues - identified issue types for the AML match
   4. Match Strength - likelihood that the individual or entity flagged in the AML check
   5. Update - the date and time a user updated the alert status
   6. Resolved by - the user that updated the alert status
   7. Comments - note left by the user that updated the alert status

| **AML Issues**    | **Description**                                                                                          |
| :---------------- | :------------------------------------------------------------------------------------------------------- |
| **PEP**           | **Politically Exposed Persons** - A potential match has been found on a Politically Exposed Persons list |
| **Sanctions**     | **Sanctions** - A potential match has been found against a Sanctions list                                |
| **Watchlist**     | **Watchlist** - A potential match has been found on a Watchlist                                          |
| **Adverse media** | **Adverse media** - A potential match has been found against an Adverse Media list                       |

### Reviewing AML screening results

The AML screening is designed to help operators by providing an **icon** and a **border** that will change based of the AML alert review

| Icon           | Description                                                                                                                                                                                          |
| :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img alt="" /> | This status indicates a serious concern. It means that there is either an unknown reject or a true positive reject. It’s crucial for ensuring compliance and security.                               |
| <img alt="" /> | This status highlights that there is at least one unresolved issue, such as a potential match. It’s a call for careful review to ensure nothing is overlooked.                                       |
| <img alt="" /> | This status is given when all issues are resolved as false positives, or when true positives and unknowns are accepted. It signifies that everything have been resolved or risks have been accepted. |

## Change the AML alert status

An AML alert by default has status of **Potential match** and in some cases **Unknown** or **True positive**.

| Status         | Description                                                   |
| :------------- | :------------------------------------------------------------ |
| <img alt="" /> | A system assigned status when there is a potential AML match. |

Once a decision has been made, you can update the alert status to either confirm the match or mark it as any of the below statuses. Any of these statuses can be changed if corrections are needed.

| Status         | Description                                                                                                                                                                                                                       |
| :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img alt="" /> | **False positive** - indicates that a manual review has been carried out and the potential match Frankie has identified isn't the customer.                                                                                       |
| <img alt="" /> | **True Positive, Accept**- indicates that a manual review has been carried out and the true positive match has been acknowledged, however, the risk is deemed to be acceptable and want to continue doing business with the user. |
| <img alt="" /> | **True Positive, Reject**- indicates that a manual review has been carried out and the true positive match has been acknowledged, and, the risk is deemed to be unacceptable.                                                     |
| <img alt="" /> | **Unknown, Accept** - indicates that a manual review has been carried out however, the risk is deemed to be acceptable and want to continue doing business with the user.                                                         |
| <img alt="" /> | **Unknown, Reject** - indicates that a manual review has been carried out and the true positive match has been acknowledged, and, the risk is deemed to be unacceptable.                                                          |

One way of updating an alert status is from the Workflow events page - this allows users to select a single or multiple AML alerts.

<img alt="" />

<Frame>
  <img alt="" />
</Frame>

The updated **Alert status** will now be reflected in the returned results table and the overall workflow status will be updated to **Failed** or **Passed** depending on the results of other checks.

<img alt="" />

## Review Details of a single AML alert

Click an AML alert to open and view the details to manually review and make a decision if this is a **True positive**, **Unknown**, or a **False positive**.

From here, you can see all the AML data such as PEP, Sanction, Watchlist, Adverse media, and other data sources of the AML alert.

<img alt="" />


# Add/Remove Profile
Source: https://docs.frankieone.com/docs/reviewing-blocklist-check-results



<Callout icon="thumbtack">
  If Blocklist check is disabled or not configured for your workflow (or account), these views will not be shown.
  Speak to your account manager for pricing and further information on running Blocklist checks.
</Callout>

## Video Guide

<iframe />

## Blocklisting existing entities

From the Entity view, you can access the actions and select Add to blocklist. As part of Portal standards, any manual review action will require a comment

<img alt="" />

A blocklist match can be confirmed as a true positive, and the potential customer blocked from onboarding or marked as a false positive, which we explain how to resolve in later articles.

## Removing blocklisted entities

Users with appropriate permissions are able to remove an entire profile from your internal blocklist.

1. Open the profile of the person you would like to remove from your internal blocklist.

2. From the Entity view, you can access the actions and select Remove from blocklist.

3. As part of Portal standards, any manual review action will require a comment

<img alt="" />

<img alt="" />

<img alt="" />

### Comments

Hovering will display the latest comment, and clicking will expand and show all blocklist comments.


# Risk Assessment
Source: https://docs.frankieone.com/docs/risk-assessment-v2



### Video Guide

<iframe title="Loom video player" />

## Risk Assessment

FrankieOne calculates risk to help you assess customers and make informed decisions during onboarding, monitoring, and ongoing due diligence.

## Entity risk vs. Workflow risk

When viewing an entity in the Portal, you will see two related risk levels.

| **Level**         | **What it measures**                                                                                                                             | **When it updates**                           |
| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- |
| **Entity risk**   | The entity’s risk state, either based on the latest workflow run or as a cumulative risk across its lifetime (depending on configuration/model). | After each workflow run or a manual override. |
| **Workflow risk** | The risk score for a single workflow execution.                                                                                                  | At the end of that workflow run.              |

### How is entity risk calculated

1. Each check in a workflow returns one or more risk factors (for example, sanctions matches, device risk, jurisdiction).
2. Each risk factor is assigned a score based on your configuration.
3. FrankieOne aggregates these scores (sum or average, depending on your model) to produce a **workflow risk score** at the end of the workflow run.
4. The score is mapped to a **Risk Level** (Low, Medium, High, Unacceptable).

### How workflow risk and entity risk relate

1. Workflow risk represents the risk for a single workflow execution (for example, an onboarding attempt).
2. Entity risk represents the customer’s overall risk profile.
3. Entity risk is derived from workflow risk, either:
   * based on the latest workflow result, or
   * as a cumulative view over time, depending on your configuration.
4. A high workflow risk can increase the entity’s overall risk level (for example, from Medium to High).

### Entity risk vs Workflow risk

| **Aspect**            | **Workflow Risk**                                              | Entity Risk                                                             |
| --------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **Scope**             | Single workflow execution (point-in-time assessment)           | Overall customer risk profile                                           |
| **Purpose**           | Identifies risk in a specific onboarding or assessment attempt | Reflects ongoing risk across the customer lifecycle                     |
| **Calculation basis** | Risk factors from a single workflow run                        | Derived from one or more workflow results (latest or cumulative model)  |
| **Update timing**     | At the end of each workflow run                                | After each workflow run or manual override (depending on configuration) |
| **Typical use case**  | Detecting immediate issues during onboarding or screening      | Maintaining long-term risk posture for the entity                       |

<Callout icon="thumbtack">
  ***Risk accumulation over time***

  Entity risk is updated as new workflows are executed for the same entity. New workflows can change the risk score based on new or updated signals, so the entity risk may increase, decrease, or remain unchanged.

  **Example:** A customer is onboarded and assessed as **Low risk**. Later, during ongoing monitoring, new AML alerts are triggered and the workflow returns **High risk**. The entity’s risk level is then updated to **High**.
</Callout>

## Risk score and Risk levels

| Risk level   | Score range (example) | Typical action         |
| :----------- | :-------------------- | :--------------------- |
| Low          | 1–30                  | Auto-approve.          |
| Medium       | 31–50                 | Require extra checks.  |
| High         | 51–75                 | Manual review and EDD. |
| Unacceptable | >75                   | Auto-fail.             |

<Tip>
  Your risk score ranges and associated actions are configurable.
</Tip>

## Risk factors

[Risk factors](/docs/risk-factors) are defined in your **Risk Scorecard** and appear in the Risk drawer with their individual scores.

| Factor          | What it measures                      | Example values     |
| :-------------- | :------------------------------------ | :----------------- |
| `num_sanctions` | Count of sanctions matches.           | 0, 1+              |
| `num_pep`       | Count of PEP matches.                 | 0, 1+              |
| `device_risk`   | Fraud score from device intelligence. | Low, High          |
| `jurisdiction`  | Country risk tier.                    | Tier 1–4           |
| `document_age`  | Document expiry status.               | Valid, Expired     |
| `behaviour`     | Biometrics or usage anomalies.        | Normal, Suspicious |

## Overriding risk score

Authorised users can manually set a new Risk score in the Risk drawer (for example, lowering risk after enhanced due diligence).

<Callout icon="thumbtack">
  A manual override remains until **any underlying risk factor changes in a future workflow run**. When that happens, the system recalculates risk and clears the old override.
</Callout>

## Where to find risk information

* **Profile header** – shows the current *Entity risk* badge
* **Workflow events tab** – each event row displays its *Workflow risk* level
* **Risk score** – click to open a drawer with risk factor details


# Risk Factors
Source: https://docs.frankieone.com/docs/risk-factors



### Overview

Risk factors are components that contribute to an entity's overall risk assessment. Each risk factor evaluates to a numeric score that influences the final risk level assigned to an entity. Understanding these factors helps compliance officers make informed decisions about customer onboarding and ongoing monitoring.

### Risk Factors

Risk factors are generated by various steps or components within the workflow and can persist beyond a single workflow to enable continuity in risk assessment.

### KYC

| Factor      | Factor (API) | What it means                                                           | Typical next step                                                                                         |
| :---------- | :----------- | :---------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------- |
| Entity Age  | entity\_age  | Evaluates risk based on the customer's age category (Under 18, Over 18) | Apply appropriate due diligence based on age category; additional verification may be required for minors |
| Entity Type | entity\_type | Identifies the entity as an Individual or Other classification          | Apply appropriate due diligence measures based on entity type                                             |

### AML

#### Jurisdictional Risk

* **Factor:** Country
* **Factor (API):** country
* **What it means:** Assesses risk based on the customer's country of residence or operation
* **Typical next step:** Apply enhanced due diligence for high-risk jurisdictions according to your compliance policy

| Factor                        | Factor (API)        | What it means                                                        | Typical next step                                                                                   |
| :---------------------------- | :------------------ | :------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |
| Entity Has Adverse Media hits | has\_adverse\_media | Indicates negative news or information is associated with the entity | Review the findings and assess their relevance and severity                                         |
| Entity Has Sanctions Hits     | has\_sanctions      | Identifies if the entity appears on any sanctions lists              | Review match details to determine if it's a true or false positive; consider rejecting if confirmed |
| Entity Has Watchlist Hits     | on\_watchlist       | Shows if the entity appears on a watchlist                           | Review the watchlist match and determine appropriate action based on your risk policy               |
| Entity Has PEP Hits           | is\_pep             | Identifies if the entity is a Politically Exposed Person             | Apply enhanced due diligence measures if PEP status is confirmed                                    |
| Number of Adverse Media Hits  | num\_adverse        | Indicates the quantity of adverse media matches found                | Higher counts may require more thorough investigation                                               |
| Number of PEP Hits            | num\_pep            | Shows the number of PEP matches identified                           | Multiple matches may indicate higher risk requiring enhanced scrutiny                               |
| Number of Sanction Hits       | num\_sanctions      | Indicates the quantity of sanctions matches found                    | Multiple matches require thorough investigation; may be grounds for rejection                       |

### IDV (Identity Verification)

| Factor                     | Factor (API)                    | What it means                                                                                       | Typical next step                                                                         |
| :------------------------- | :------------------------------ | :-------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------- |
| Document validation result | idv\_document\_result           | Assesses if the identity document is genuine (Clear, Suspected, Rejected)                           | If Suspected or Rejected, request alternative documentation or escalate for manual review |
| Facial comparison result   | idv\_facial\_comparison\_result | Compares the customer's selfie with their ID photo (Clear, Suspected, Rejected)                     | If Suspected or Rejected, request new verification attempt or escalate for manual review  |
| OCR comparison result      | idv\_ocr\_comparison\_result    | Checks if extracted document data matches provided information (Clear, Suspected, Rejected)         | If Suspected or Rejected, request clarification or additional verification                |
| Facial liveness result     | idv\_facial\_liveness\_result   | Verifies that the selfie is of a live person, not a photo or recording (Clear, Suspected, Rejected) | If Suspected or Rejected, request new liveness verification or escalate for manual review |

### MATCHLIST

| Factor             | Factor (API)            | What it means                                                                                           | Typical next step                                                        |
| :----------------- | :---------------------- | :------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------- |
| Internal matchlist | on\_matchlist\_internal | Indicates if the entity appears on your organization's internal blocklist (Block, Alert, Review, Allow) | Take action based on the specified status block, alert, review, or allow |

### DUPLICATE

| Factor                    | Factor (API)           | What it means                                                                                               | Typical next step                                                                                                                                 |
| :------------------------ | :--------------------- | :---------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| Any unresolved duplicates | unresolved\_duplicates | Indicates potential duplicate matches that have not yet been reviewed or resolved                           | Review the matches to determine if they are true or false positives; compare entity details and documents to make an informed decision            |
| Any resolved duplicates   | resolved\_duplicates   | Shows duplicate matches that have been reviewed and marked as either confirmed duplicates or not duplicates | For confirmed duplicates, consider archiving one of the entities; for matches marked as not duplicates, document the reason for the determination |

When reviewing risk factors in the Portal, compliance officers can see the contribution of each factor to the overall risk score.  The system allows for manual override of risk levels when appropriate, with proper documentation of the override reason. Risk factors can become outdated when underlying values change, and new assessments will create updated factors. See Risk assessment for a better understanding.


# Biometrics Module
Source: https://docs.frankieone.com/docs/sdk-reference/biometrics-module

Complete reference for the Biometrics (Face Verification) module

## Overview

The Biometrics module provides face verification and liveness detection capabilities through third-party provider integrations. It manages facial capture and verification to confirm that the person completing verification matches their identity document and is physically present (not a photo or video).

## Accessing the Module

The Biometrics module is accessed through the SDK's component factory:

```javascript theme={null}
const sdk = await OneSdk({
  mode: 'production',
  session: { token: 'your-token' }
});

// Create Biometrics component instance
const biometricsComponent = sdk.component('biometrics', options);
```

## Supported Providers

The Biometrics module supports multiple face verification providers:

| Provider | Value       | Learn More                             |
| -------- | ----------- | -------------------------------------- |
| Onfido   | `'onfido'`  | [onfido.com](https://onfido.com)       |
| Sumsub   | `'sumsub'`  | [sumsub.com](https://sumsub.com)       |
| Incode   | `'incode'`  | [incode.com](https://incode.com)       |
| IDVerse  | `'idverse'` | [idverse.com](https://www.idverse.com) |
| Daon     | `'daon'`    | [daon.com](https://www.daon.com)       |

<Note>
  Each provider has different capabilities, UI/UX, liveness detection methods, and device support. Visit the provider's website to understand their specific features and limitations.
</Note>

***

## Configuration Options

### Basic Configuration

```javascript theme={null}
const biometricsComponent = sdk.component('biometrics', {
  provider: {
    name: 'onfido'
  }
});
```

### Common Options

In addition to provider-specific settings, you can configure:

| Option                | Type      | Description                                              |
| --------------------- | --------- | -------------------------------------------------------- |
| `checkProcessingPool` | `object`  | Configure check processing polling behavior (optional)   |
| `is_synchronous`      | `boolean` | Whether to run biometric checks synchronously (optional) |

**Check Processing Pool:**

```javascript theme={null}
checkProcessingPool: {
  enabled: true,      // Enable polling for check results
  wait_time: 5,       // Wait time between polls (seconds)
  max_attempts: 1     // Maximum polling attempts
}
```

### Provider-Specific Options

#### Onfido Provider

```javascript theme={null}
const biometricsComponent = sdk.component('biometrics', {
  provider: {
    name: 'onfido',
    sdkVersion: '13.0.0',                // Onfido SDK version
    theme: 'light',                       // 'light' or 'dark'
    language: 'en_GB',                    // UI language (optional)
    translations: {                       // Custom translation strings (optional)
      // See Onfido documentation for translation keys
    },
    biometricsVariant: 'standard',        // 'standard', 'video', or 'motion'
    fallback: 'standard',                 // Fallback method: 'standard' or 'video'
    showExitButton: true,                 // Show exit button in UI
    crossDevicePolicy: 'disable',         // Cross-device flow: 'force' or 'disable'
    customUI: {                           // Custom UI configuration
      // See Onfido Custom UI options below
    }
  }
});
```

**Onfido Options:**

| Option                    | Type                                | Description                                                                                                                                                                                                                                                      |
| ------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sdkVersion`              | `string`                            | Version of the Onfido SDK to use. Default: `'12'`. Refer to the [Onfido documentation](https://documentation.onfido.com/sdk/changelog/) for available versions.                                                                                                  |
| `theme`                   | `'light' \| 'dark'`                 | UI theme                                                                                                                                                                                                                                                         |
| `language`                | `string`                            | Language code for the Onfido UI. Requires `sdkVersion` 14 or later. See supported values below.                                                                                                                                                                  |
| `translations`            | `object`                            | Custom translation strings to override default Onfido copy. Keys must match Onfido's translation key schema — see the [Onfido language customisation docs](https://documentation.onfido.com/sdk/web/#language-customisation). Requires `sdkVersion` 14 or later. |
| `biometricsVariant`       | `'standard' \| 'video' \| 'motion'` | **Onfido-specific:** Biometric capture variant. `'standard'` uses photo-based liveness, `'video'` uses video liveness, `'motion'` uses motion-based liveness.                                                                                                    |
| `fallback`                | `'standard' \| 'video'`             | Fallback biometric method if primary method fails                                                                                                                                                                                                                |
| `showExitButton`          | `boolean`                           | Display exit button in the UI                                                                                                                                                                                                                                    |
| `crossDevicePolicy`       | `'force' \| 'disable'`              | Enable/disable cross-device flow                                                                                                                                                                                                                                 |
| `customUI`                | `object`                            | Custom UI styling configuration (see Custom UI section below)                                                                                                                                                                                                    |
| `onUserExit`              | `() => void`                        | Callback function when user exits the flow                                                                                                                                                                                                                       |
| `_crossDeviceLinkMethods` | `array`                             | Internal: cross-device link sharing methods                                                                                                                                                                                                                      |

**Supported `language` values:**

`ar`, `bg`, `cs`, `da`, `de`, `el`, `en_GB`, `en_US`, `es`, `es_419`, `es_DO`, `et`, `fa`, `fi`, `fr`, `fr_CA`, `he`, `hi`, `hr`, `hu`, `hy`, `id`, `it`, `ja`, `ko`, `lt`, `lv`, `ms`, `nl`, `no`, `pl`, `pt`, `pt_BR`, `ro`, `ru`, `sk`, `sl`, `sr`, `sv`, `th`, `tr`, `uk`, `vi`, `zh_CN`, `zh_TW`

**Onfido Custom UI Properties:**

The `customUI` object allows extensive styling customization:

```javascript theme={null}
customUI: {
  // Typography
  fontWeightBody: 400,
  fontSizeBody: '16px',
  fontSizeSubtitle: '18px',
  fontSizeTitle: '24px',

  // Colors - Background
  colorBackgroundSurfaceModal: '#FFFFFF',
  colorBackgroundIcon: '#353FF4',
  colorBackgroundInput: '#FFFFFF',

  // Colors - Content/Text
  colorContentBody: '#475467',
  colorContentTitle: '#101828',
  colorContentSubtitle: '#344054',
  colorContentInput: '#101828',

  // Colors - Buttons (Primary)
  colorContentButtonPrimaryText: '#FFFFFF',
  colorBackgroundButtonPrimary: '#353FF4',
  colorBackgroundButtonPrimaryHover: '#2835E5',
  colorBackgroundButtonPrimaryActive: '#1F2AD1',

  // Colors - Buttons (Secondary)
  colorContentButtonSecondaryText: '#344054',
  colorBackgroundButtonSecondary: '#FFFFFF',
  colorBackgroundButtonSecondaryHover: '#F9FAFB',
  colorBackgroundButtonSecondaryActive: '#F2F4F7',

  // Colors - Buttons (Tertiary)
  colorContentButtonTertiaryText: '#344054',

  // Borders
  borderRadiusButton: '8px',
  borderStyleSurfaceModal: '1px solid #E4E7EC',
  colorBorderInput: '#D0D5DD',
  colorInputOutline: '#353FF4',

  // Additional UI elements
  colorIcon: '#667085',
  colorBackgroundInfoPill: '#F2F4F7',
  colorContentInfoPill: '#344054',
  // ... see Onfido documentation for full list
}
```

***

#### Sumsub Provider

```javascript theme={null}
const biometricsComponent = sdk.component('biometrics', {
  provider: {
    name: 'sumsub',
    config: {
      theme: 'light',  // 'light' or 'dark'
      lang: 'en',      // Language code (optional)
      email: 'user@example.com',  // Pre-fill email (optional)
      phone: '+1234567890'        // Pre-fill phone (optional)
    },
    options: {
      addViewportTag: true,      // Add viewport meta tag
      adaptIframeHeight: true    // Auto-adjust iframe height
    }
  }
});
```

**Sumsub Options:**

| Option    | Type     | Description                                          |
| --------- | -------- | ---------------------------------------------------- |
| `config`  | `object` | Sumsub configuration object (see Config table below) |
| `options` | `object` | Sumsub SDK options (see Options table below)         |

**Sumsub Config Object:**

| Property | Type                | Required | Description                                  |
| -------- | ------------------- | -------- | -------------------------------------------- |
| `theme`  | `'dark' \| 'light'` | Yes      | UI theme                                     |
| `lang`   | `string`            | No       | Language code (e.g., `'en'`, `'es'`, `'fr'`) |
| `email`  | `string`            | No       | Pre-fill user's email address                |
| `phone`  | `string`            | No       | Pre-fill user's phone number                 |

**Sumsub Options Object:**

| Property            | Type      | Required | Description                                   |
| ------------------- | --------- | -------- | --------------------------------------------- |
| `addViewportTag`    | `boolean` | Yes      | Whether to add viewport meta tag to page      |
| `adaptIframeHeight` | `boolean` | Yes      | Whether to automatically adjust iframe height |

***

#### Incode Provider

```javascript theme={null}
const biometricsComponent = sdk.component('biometrics', {
  provider: {
    name: 'incode',
    sdkVersion: '1.0.0',  // Incode SDK version (optional)
    lang: 'es',           // UI language (optional)
    translations: {       // Custom translation strings (optional)
      // See Incode documentation for translation keys
    },
    renderCameraProps: {   // Raw options passed to the Incode SDK's renderCamera() call (optional)
      // See Incode Web SDK documentation for available renderCamera options
    }
  }
});
```

**Incode Options:**

| Option              | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sdkVersion`        | `string` | Version of the Incode SDK to use. Default: `'1.75.2'`. Refer to the [Incode documentation](https://docs.incode.com/docs/omni-web-sdk/release-notes) for available versions.                                                                                                                                                                                                                                                                |
| `lang`              | `string` | Language code for the Incode UI. See supported values below.                                                                                                                                                                                                                                                                                                                                                                               |
| `translations`      | `object` | Custom translation strings to override default Incode copy. See the [Incode language keys docs](https://documentation.identity.entrust.com/sdk/web/#identifying-language-keys) for available translation keys.                                                                                                                                                                                                                             |
| `renderCameraProps` | `object` | Advanced/raw options forwarded directly to the Incode SDK's `renderCamera()` call (optional). Unlike the OCR module's Incode provider, the Biometrics module's Incode provider does not expose a separate `renderCamera: { showDocSelector, showTutorial }` object — `renderCameraProps` is the only camera-rendering override available here, and it is passed straight through to the vendor SDK ahead of OneSDK's own capture handlers. |

**Supported `lang` values:**

`bn`, `ca`, `zh`, `hr`, `nl`, `en`, `en-BZ`, `en-DG`, `fr`, `de`, `ht`, `hi`, `hmn`, `hu`, `id`, `it`, `ms`, `pl`, `pt`, `pt-BR`, `pt-PT`, `ro`, `sr`, `sr-LATN`, `so`, `es`, `es-ES`, `tl-PH`, `tr`, `vi`

***

#### IDVerse Provider

```javascript theme={null}
const biometricsComponent = sdk.component('biometrics', {
  provider: {
    name: 'idverse',
    skipFaceScanIntro: false,     // Skip intro screen
    logoUrl: 'https://...',       // Custom logo URL
    retryCount: 3,                // Number of retry attempts
    skipLoad: false,              // Skip loading screen
    workerPathString: '/path',    // Custom worker path
    assetPathString: '/assets'    // Custom asset path
  }
});
```

**IDVerse Options:**

| Option              | Type      | Description                                        |
| ------------------- | --------- | -------------------------------------------------- |
| `skipFaceScanIntro` | `boolean` | Skip the face scan introduction screen (optional)  |
| `logoUrl`           | `string`  | URL to custom logo to display in the UI (optional) |
| `retryCount`        | `number`  | Number of retry attempts allowed (optional)        |
| `skipLoad`          | `boolean` | Skip the loading screen (optional)                 |
| `workerPathString`  | `string`  | Custom path to worker scripts (optional)           |
| `assetPathString`   | `string`  | Custom path to asset files (optional)              |

***

#### Daon Provider

```javascript theme={null}
const biometricsComponent = sdk.component('biometrics', {
  provider: {
    name: 'daon',
    products: ['faceLiveness']  // Array of Daon products to use
  }
});
```

**Daon Options:**

| Option     | Type       | Description                                 |
| ---------- | ---------- | ------------------------------------------- |
| `products` | `string[]` | Array of Daon product identifiers to enable |

***

## Methods

### `mount()`

Mounts the Biometrics component to a DOM element and starts the face verification flow.

**Signature:**

```typescript theme={null}
mount(domElementOrSelector: string | HTMLElement): void
```

**Parameters:**

| Parameter              | Type                    | Required | Description                                                                                                     |
| ---------------------- | ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `domElementOrSelector` | `string \| HTMLElement` | Yes      | CSS selector string (e.g., `'#biometrics-container'`) or HTMLElement object where the component will be mounted |

**Description:**
Mounts the biometric capture interface to the specified DOM element and initiates the face verification flow. The provider's camera interface will be displayed within this element.

**Example:**

```javascript theme={null}
// Mount to element by ID
biometricsComponent.mount('#biometrics-container');

// Mount to element reference
const container = document.getElementById('biometrics-container');
biometricsComponent.mount(container);
```

***

### `unmount()`

Unmounts the Biometrics component from the DOM.

**Signature:**

```typescript theme={null}
unmount(): void
```

**Description:**
Removes the Biometrics component from the DOM and cleans up resources, including stopping camera access. Call this when the user navigates away or the verification flow is complete.

**Example:**

```javascript theme={null}
biometricsComponent.unmount();
```

***

## Events

The Biometrics module emits events throughout the verification lifecycle:

<Warning>
  **Provider-Specific Behavior:** Events and statuses vary by provider. Not all providers emit all events, and some events are provider-specific. Always test with your chosen provider to understand which events are emitted and when.
</Warning>

### `vendor_sdk_loaded`

<Note>
  **Common Event:** This event is emitted by all vendor-based modules (IDV, OCR, Biometrics, Device).
</Note>

Emitted when the provider's SDK has been successfully loaded.

```typescript theme={null}
biometricsComponent.on('vendor_sdk_loaded', ({ vendor }) => {
  console.log('SDK loaded for:', vendor);
});
```

**Parameters:**

| Parameter | Type     | Description                                                      |
| --------- | -------- | ---------------------------------------------------------------- |
| `vendor`  | `string` | The provider whose SDK was loaded (`'onfido'`, `'sumsub'`, etc.) |

***

### `vendor_sdk_failed_loading`

<Note>
  **Common Event:** This event is emitted by all vendor-based modules (IDV, OCR, Biometrics, Device).
</Note>

Emitted when the provider's SDK fails to load.

```typescript theme={null}
biometricsComponent.on('vendor_sdk_failed_loading', ({ vendor, errorObject }) => {
  console.error(`Failed to load ${vendor} SDK:`, errorObject);
});
```

**Parameters:**

| Parameter     | Type      | Description                            |
| ------------- | --------- | -------------------------------------- |
| `vendor`      | `string`  | The provider whose SDK failed to load  |
| `errorObject` | `unknown` | The error that occurred during loading |

***

### `session_data_generated`

Emitted when a biometric verification session has been created with the provider.

```typescript theme={null}
biometricsComponent.on('session_data_generated', ({ session }) => {
  console.log('Session created for entity:', session.entityId);
  console.log('Vendor parameters:', session.vendorParameters);
});
```

**Parameters:**

| Parameter                  | Type      | Description                                 |
| -------------------------- | --------- | ------------------------------------------- |
| `session.entityId`         | `string`  | The entity ID for this verification session |
| `session.vendorParameters` | `unknown` | Provider-specific session parameters        |

***

### `session_data_failed_loading`

Emitted when session data fails to load.

```typescript theme={null}
biometricsComponent.on('session_data_failed_loading', ({ code, message }) => {
  console.error('Session failed:', message);
});
```

**Parameters:**

| Parameter | Type      | Description                          |
| --------- | --------- | ------------------------------------ |
| `code`    | `unknown` | Optional error code                  |
| `message` | `string`  | Error message describing the failure |

***

### `ready`

Emitted when the biometric capture interface is ready for user interaction.

```typescript theme={null}
biometricsComponent.on('ready', ({ domElement }) => {
  console.log('Biometrics UI ready');
  // Camera capture can begin
});
```

**Parameters:**

| Parameter    | Type          | Description                                    |
| ------------ | ------------- | ---------------------------------------------- |
| `domElement` | `HTMLElement` | The DOM element where the component is mounted |

***

### `input_required`

Emitted when a non-positive flow has occurred but is likely recoverable by retrying.

```typescript theme={null}
biometricsComponent.on('input_required', (info, status) => {
  console.log('Input required. Status:', status);
  console.log('User can retry to continue verification');

  // Handle different statuses
  showRetryMessage(status);
});
```

**Parameters:**

| Parameter       | Type                                                                                                             | Description                                                     |
| --------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `info.entityId` | `string \| null`                                                                                                 | The entity ID, or null if not yet available                     |
| `status`        | [`IDVStatus`](/docs/sdk-reference/idv-module#statuses) \| [`OCRStatus`](/docs/sdk-reference/ocr-module#statuses) | The current verification status indicating what input is needed |

**Description:**
This event indicates that verification cannot proceed in its current state, but the issue is typically recoverable. Common scenarios include:

* User closed the verification session
* Session timeout occurred
* Waiting for selfie capture
* Awaiting user consent
* Camera permission denied

The user can typically retry the verification process to resolve these issues.

***

### `detection_complete`

Emitted when the biometric capture process has completed successfully.

```typescript theme={null}
biometricsComponent.on('detection_complete', ({ provider }) => {
  console.log('Face captured successfully by:', provider);
  showMessage('Processing your biometric data...');
});
```

**Parameters:**

| Parameter  | Type     | Description                                                          |
| ---------- | -------- | -------------------------------------------------------------------- |
| `provider` | `string` | The provider that completed the capture (optional, may be undefined) |

***

### `detection_failed`

Emitted when the biometric capture process fails.

```typescript theme={null}
biometricsComponent.on('detection_failed', ({ message }) => {
  console.error('Capture failed:', message);
  showError(message || 'Biometric capture failed. Please try again.');
});
```

**Parameters:**

| Parameter | Type     | Description                                            |
| --------- | -------- | ------------------------------------------------------ |
| `message` | `string` | Error message describing why capture failed (optional) |

***

### `processing`

Emitted when biometric data is being processed by the provider.

```typescript theme={null}
biometricsComponent.on('processing', ({ checkStatus, entityId }) => {
  console.log('Processing biometric data:', checkStatus);
  showLoadingIndicator();
});
```

**Parameters:**

| Parameter     | Type                                                   | Description                               |
| ------------- | ------------------------------------------------------ | ----------------------------------------- |
| `checkStatus` | [`IDVStatus`](/docs/sdk-reference/idv-module#statuses) | The current status of the biometric check |
| `entityId`    | `string \| null`                                       | The entity ID being verified              |

***

### `results`

Emitted when the biometric verification process completes with results.

```typescript theme={null}
biometricsComponent.on('results', ({ provider, checkStatus, document, entityId }) => {
  console.log('Verification complete');
  console.log('Provider:', provider);
  console.log('Status:', checkStatus);

  if (checkStatus === 'COMPLETE') {
    console.log('✓ Biometric verification passed');
    navigateToSuccess();
  } else {
    console.log('✗ Verification status:', checkStatus);
    handleFailure(checkStatus);
  }
});
```

**Parameters:**

| Parameter     | Type                                                   | Description                                         |
| ------------- | ------------------------------------------------------ | --------------------------------------------------- |
| `provider`    | `string \| null`                                       | The provider that performed verification (optional) |
| `checkStatus` | [`IDVStatus`](/docs/sdk-reference/idv-module#statuses) | Final verification status                           |
| `document`    | `Document \| null`                                     | Associated document data, if any                    |
| `entityId`    | `string \| null`                                       | The entity ID that was verified                     |

***

### `session_closed`

Emitted when the verification session is closed normally.

```typescript theme={null}
biometricsComponent.on('session_closed', () => {
  console.log('Biometric session closed');
  cleanup();
});
```

**Parameters:** None

***

### `session_interrupted`

Emitted when the verification session is interrupted by the user.

```typescript theme={null}
biometricsComponent.on('session_interrupted', (interruptInfo) => {
  console.log('User interrupted verification');
  saveProgress();
  showMessage('You can resume verification later');
});
```

**Parameters:**

| Parameter       | Type     | Description                        |
| --------------- | -------- | ---------------------------------- |
| `interruptInfo` | `object` | Information about the interruption |

<Note>
  **Provider-Specific:**

  * **Onfido:** Emits this when the verification modal is closed.
</Note>

***

### `vendor_event`

Emitted for provider-specific events that don't map to standard events.

```typescript theme={null}
biometricsComponent.on('vendor_event', (eventData) => {
  console.log('Provider event:', eventData);
  // Handle provider-specific logic
});
```

**Parameters:**

| Parameter   | Type     | Description                  |
| ----------- | -------- | ---------------------------- |
| `eventData` | `object` | Provider-specific event data |

***

## Complete Example

```javascript theme={null}
import OneSdk from '@frankieone/one-sdk';

async function performBiometricVerification() {
  try {
    // Initialize SDK
    const sdk = await OneSdk({
      mode: 'production',
      session: { token: await getSessionToken() }
    });

    // Create Biometrics component with Onfido provider
    const biometricsComponent = sdk.component('biometrics', {
      provider: {
        name: 'onfido',
        theme: 'light',
        biometricsVariant: 'standard',
        showExitButton: true,
        fallback: 'video'
      },
      checkProcessingPool: {
        enabled: true,
        wait_time: 5,
        max_attempts: 3
      }
    });

    // Set up event listeners
    biometricsComponent.on('vendor_sdk_loaded', ({ vendor }) => {
      console.log(`${vendor} SDK loaded successfully`);
    });

    biometricsComponent.on('vendor_sdk_failed_loading', ({ vendor, errorObject }) => {
      console.error(`Failed to load ${vendor} SDK:`, errorObject);
      showError('Biometric verification unavailable. Please try again later.');
    });

    biometricsComponent.on('session_data_generated', ({ session }) => {
      console.log('Biometric session created for:', session.entityId);
    });

    biometricsComponent.on('session_data_failed_loading', ({ message }) => {
      console.error('Session failed:', message);
      showError('Failed to start biometric verification');
    });

    biometricsComponent.on('ready', ({ domElement }) => {
      console.log('Camera ready, please position your face');
      showInstruction('Position your face in the frame');
    });

    biometricsComponent.on('input_required', (info, status) => {
      console.log('Input required:', status);
      showRetryButton();
    });

    biometricsComponent.on('detection_complete', ({ provider }) => {
      console.log('Face captured successfully');
      showMessage('Processing your biometric data...');
      hideCamera();
    });

    biometricsComponent.on('detection_failed', ({ message }) => {
      console.error('Capture failed:', message);
      showError(message || 'Failed to capture face. Please try again.');
    });

    biometricsComponent.on('processing', ({ checkStatus }) => {
      console.log('Processing:', checkStatus);
      showLoadingIndicator();
    });

    biometricsComponent.on('results', ({ checkStatus, entityId }) => {
      console.log('Verification complete');

      if (checkStatus === 'COMPLETE') {
        console.log('✓ Biometric verification passed');
        navigateToSuccess();
      } else if (checkStatus === 'FAILED') {
        console.log('✗ Biometric verification failed');
        showFailureScreen();
      } else {
        console.log('Status:', checkStatus);
        handleOtherStatus(checkStatus);
      }
    });

    biometricsComponent.on('session_interrupted', () => {
      console.log('User interrupted verification');
      saveProgress();
    });

    biometricsComponent.on('session_closed', () => {
      console.log('Session closed');
      cleanup();
    });

    // Mount and start biometric verification
    biometricsComponent.mount('#biometrics-container');

  } catch (error) {
    console.error('Biometrics initialization failed:', error);
    throw error;
  }
}
```

***

## Best Practices

1. **Handle all events, not just `results`** - The `results` event only fires with `COMPLETE` or `FAILED`. Also listen to `input_required` (for recoverable states like INCOMPLETE or INTERRUPTED), `error` (for system failures), and `processing` (for intermediate states).

2. **Set up event listeners before mounting** - Register all event handlers before calling `mount()` to avoid missing events.

3. **Unmount on navigation** - Always call `unmount()` when the user leaves the page to clean up resources.

4. **Provider-specific configuration** - Review each provider's documentation for optimal configuration.

5. **Error handling** - Always listen to the `error` event and provide user-friendly error messages.

***

## Common Issues

### Component not displaying

Ensure the mount element exists in the DOM and has sufficient size:

```css theme={null}
#biometrics-container {
  width: 100%;
  min-height: 600px;
}
```

### Session data failed to load

This usually means the backend session setup failed. Ensure your backend is correctly generating biometric verification tokens.

### Provider-specific errors

Check the `vendor_event` emissions for provider-specific error details and consult the provider's documentation.

***

## Related Resources

* [SDK Initialization](/docs/sdk-reference/sdk-initialization) - OneSDK setup and configuration
* [IDV Module](/docs/sdk-reference/idv-module) - Combined document + biometric verification
* [OCR Module](/docs/sdk-reference/ocr-module) - Document capture (often used before biometrics)
* [Individual Module](/docs/sdk-reference/individual-module) - Entity data management


# Device Module
Source: https://docs.frankieone.com/docs/sdk-reference/device-module

Device fingerprinting and fraud detection integration

## Overview

The Device module provides device fingerprinting capabilities through third-party fraud detection providers. It collects device characteristics and behavioral data to help identify and prevent fraudulent activities.

Device fingerprinting works by analyzing hardware, software, and behavioral patterns to create a unique device identifier. This helps detect anomalies, prevent account takeover, and identify suspicious activity patterns.

## Initializing the Module

The Device module is created using the `component()` factory method:

```javascript theme={null}
const deviceComponent = oneSdkInstance.component('device', {
  activityType: 'REGISTRATION'
});
```

### Module Options

All options are passed during module initialization:

| Parameter      | Type           | Required | Description                                                                                           |
| -------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `activityType` | `ActivityType` | Yes      | The type of user activity being monitored. See [Activity Types](#activity-types) below.               |
| `sessionId`    | `string`       | No       | Custom session identifier. If not provided, a UUID will be generated automatically.                   |
| `token`        | `string`       | No       | Custom token for the fingerprinting session. If not provided, a UUID will be generated automatically. |

#### Activity Types

The activity type helps the fraud detection provider apply appropriate risk assessment rules:

| Value               | Description                           |
| ------------------- | ------------------------------------- |
| `REGISTRATION`      | User account creation or signup       |
| `LOGIN`             | User authentication or signin         |
| `CRYPTO_DEPOSIT`    | Cryptocurrency deposit transaction    |
| `CRYPTO_WITHDRAWAL` | Cryptocurrency withdrawal transaction |
| `FIAT_DEPOSIT`      | Fiat currency deposit transaction     |
| `FIAT_WITHDRAWAL`   | Fiat currency withdrawal transaction  |

Example with all options:

```javascript theme={null}
const deviceComponent = oneSdkInstance.component('device', {
  activityType: 'LOGIN',
  sessionId: 'custom-session-id',
  token: 'custom-token'
});
```

## Recipe Configuration

The Device module requires provider configuration in your recipe:

```javascript theme={null}
const oneSdkInstance = await OneSDK({
  session: { token: 'your-token' },
  recipe: {
    deviceCharacteristics: {
      provider: {
        name: 'sardine',
        clientID: 'your-client-id',
        environment: 'production'
      }
    }
  }
});
```

### Recipe Options

| Property                                     | Type                            | Required | Description                                                         |
| -------------------------------------------- | ------------------------------- | -------- | ------------------------------------------------------------------- |
| `deviceCharacteristics.provider.name`        | `'sardine'` \| `'threatmetrix'` | Yes      | The fraud detection provider to use.                                |
| `deviceCharacteristics.provider.clientID`    | `string`                        | Yes      | Your provider client ID. Contact FrankieOne support to obtain this. |
| `deviceCharacteristics.provider.environment` | `'production'` \| `'sandbox'`   | Yes      | The provider environment to use.                                    |

## Supported Providers

| Provider     | Value            | Learn More                                       |
| ------------ | ---------------- | ------------------------------------------------ |
| Sardine      | `'sardine'`      | [sardine.ai](https://sardine.ai)                 |
| ThreatMetrix | `'threatmetrix'` | [threatmetrix.com](https://www.threatmetrix.com) |

<Note>
  Each provider has different capabilities, data collection methods, and geographic coverage. Visit the provider's website to understand their specific features and limitations.
</Note>

## Methods

### start()

Begins the device fingerprinting process.

```typescript theme={null}
start(): void
```

This method:

1. Loads the provider's SDK asynchronously
2. Initializes a fingerprinting session
3. Begins collecting device characteristics
4. Emits events as data is collected

**Returns:** `void` - The method does not return a value. Use events to track progress.

**Example:**

```javascript theme={null}
const deviceComponent = oneSdkInstance.component('device', {
  activityType: 'REGISTRATION'
});

// Listen for events before starting
deviceComponent.on('device_characteristics_extracted', (data) => {
  console.log('Device data collected:', data.deviceCharacteristics);
});

deviceComponent.on('completed', (deviceDetails) => {
  console.log('Fingerprinting complete:', deviceDetails);
});

// Start the fingerprinting process
deviceComponent.start();
```

### on()

Registers an event listener.

```typescript theme={null}
on<EventName extends keyof Events>(
  eventName: EventName,
  handler: (...args: Events[EventName]) => void
): void
```

See [Events](#events) section for available events.

### off()

Removes an event listener.

```typescript theme={null}
off<EventName extends keyof Events>(
  eventName: EventName,
  handler: (...args: Events[EventName]) => void
): void
```

## Events

The Device module emits events throughout the fingerprinting lifecycle:

<Note>
  **Provider-Specific Behavior:** Event emissions and data structures may vary by provider. Not all providers emit all events. Always test with your chosen provider to understand which events are emitted and when.
</Note>

### configuration\_loaded

Emitted when the recipe configuration has been loaded and validated.

```typescript theme={null}
deviceComponent.on('configuration_loaded', (config) => {
  console.log('Configuration loaded:', config);
});
```

**Parameters:**

| Parameter | Type                  | Description                             |
| --------- | --------------------- | --------------------------------------- |
| `config`  | `RecipeConfiguration` | The loaded recipe configuration object. |

***

### vendor\_sdk\_loaded

<Note>
  **Common Event:** This event is emitted by all vendor-based modules (IDV, OCR, Biometrics, Device).
</Note>

Emitted when the provider's SDK has been successfully loaded.

```typescript theme={null}
deviceComponent.on('vendor_sdk_loaded', ({ vendor }) => {
  console.log('SDK loaded for:', vendor);
});
```

**Parameters:**

| Parameter | Type                            | Description                        |
| --------- | ------------------------------- | ---------------------------------- |
| `vendor`  | `'sardine'` \| `'threatmetrix'` | The provider whose SDK was loaded. |

***

### vendor\_sdk\_failed\_loading

<Note>
  **Common Event:** This event is emitted by all vendor-based modules (IDV, OCR, Biometrics, Device).
</Note>

Emitted when the provider's SDK fails to load.

```typescript theme={null}
deviceComponent.on('vendor_sdk_failed_loading', ({ vendor, errorObject }) => {
  console.error(`Failed to load ${vendor} SDK:`, errorObject);
});
```

**Parameters:**

| Parameter     | Type                            | Description                             |
| ------------- | ------------------------------- | --------------------------------------- |
| `vendor`      | `'sardine'` \| `'threatmetrix'` | The provider whose SDK failed to load.  |
| `errorObject` | `unknown`                       | The error that occurred during loading. |

***

### session\_data\_generated

Emitted when a fingerprinting session has been created with the provider.

```typescript theme={null}
deviceComponent.on('session_data_generated', ({ session }) => {
  console.log('Session created:', session);
});
```

**Parameters:**

| Parameter | Type      | Description                                                   |
| --------- | --------- | ------------------------------------------------------------- |
| `session` | `unknown` | Provider-specific session data. Structure varies by provider. |

***

### activity\_started

Emitted when an activity type has been set or updated.

```typescript theme={null}
deviceComponent.on('activity_started', ({ activityType }) => {
  console.log('Activity started:', activityType);
});
```

**Parameters:**

| Parameter      | Type           | Description                                                                |
| -------------- | -------------- | -------------------------------------------------------------------------- |
| `activityType` | `ActivityType` | The activity type that was started. See [Activity Types](#activity-types). |

***

### device\_characteristics\_extracted

Emitted when device characteristics have been collected by the provider.

```typescript theme={null}
deviceComponent.on('device_characteristics_extracted', ({ deviceCharacteristics }) => {
  console.log('Device data:', deviceCharacteristics);
});
```

**Parameters:**

| Parameter               | Type                                         | Description                                                                       |
| ----------------------- | -------------------------------------------- | --------------------------------------------------------------------------------- |
| `deviceCharacteristics` | `Record<string, string \| number \| object>` | Device data collected by the provider. Structure and properties vary by provider. |

***

### completed

Emitted when the fingerprinting process is complete.

```typescript theme={null}
deviceComponent.on('completed', (deviceDetails) => {
  console.log('Fingerprinting complete:', deviceDetails);
  // Proceed with your application flow
});
```

**Parameters:**

| Parameter       | Type                    | Description                                                   |
| --------------- | ----------------------- | ------------------------------------------------------------- |
| `deviceDetails` | `Record<string, never>` | Completion data. Currently empty but reserved for future use. |

## Complete Example

```javascript theme={null}
// Initialize OneSDK with device provider configuration
const oneSdkInstance = await OneSDK({
  session: {
    token: 'your-session-token'
  },
  recipe: {
    deviceCharacteristics: {
      provider: {
        name: 'sardine',
        clientID: 'your-sardine-client-id',
        environment: 'production'
      }
    }
  }
});

// Create device component
const deviceComponent = oneSdkInstance.component('device', {
  activityType: 'REGISTRATION'
});

// Listen for configuration load
deviceComponent.on('configuration_loaded', (config) => {
  console.log('Device module configured');
});

// Listen for SDK loading events
deviceComponent.on('vendor_sdk_loaded', ({ vendor }) => {
  console.log(`${vendor} SDK loaded successfully`);
});

deviceComponent.on('vendor_sdk_failed_loading', ({ vendor, errorObject }) => {
  console.error(`Failed to load ${vendor} SDK:`, errorObject);
  showError('Device fingerprinting unavailable');
});

// Listen for session creation
deviceComponent.on('session_data_generated', ({ session }) => {
  console.log('Fingerprinting session created');
});

// Listen for activity changes
deviceComponent.on('activity_started', ({ activityType }) => {
  console.log(`Activity: ${activityType}`);
});

// Listen for device data collection
deviceComponent.on('device_characteristics_extracted', ({ deviceCharacteristics }) => {
  console.log('Device characteristics collected:', deviceCharacteristics);
  // Data is automatically sent to FrankieOne backend
});

// Listen for completion
deviceComponent.on('completed', (deviceDetails) => {
  console.log('Device fingerprinting complete');
  // Continue with your verification flow
  proceedToNextStep();
});

// Start fingerprinting
deviceComponent.start();
```

## Best Practices

1. **Initialize Early**
   * Create the device component as early as possible in your user flow
   * Device data collection improves with more time to gather signals

2. **Handle SDK Loading Failures**
   * Always listen for `vendor_sdk_failed_loading` events
   * Have a fallback flow if device fingerprinting fails
   * Don't block user progress on fingerprinting completion

3. **Set Activity Type Appropriately**
   * Use the most specific activity type for your use case
   * Update activity type when user action changes (registration → transaction)
   * Accurate activity types improve fraud detection accuracy

## Common Issues

### Provider SDK fails to load

**Problem:** `vendor_sdk_failed_loading` event is emitted.

**Possible causes:**

* Network connectivity issues
* Content Security Policy (CSP) blocking the provider's SDK
* Invalid provider configuration (wrong clientID or environment)

**Solution:**

* Check your CSP headers allow the provider's domain
* Verify your `clientID` and `environment` are correct
* Check browser console for detailed error messages
* Contact FrankieOne support to verify your account configuration

***

### Configuration validation error

**Problem:** Module throws an error during initialization: "Your account is missing the environment configuration..."

**Cause:** The recipe configuration is missing required provider details.

**Solution:**

* Ensure `recipe.deviceCharacteristics.provider.name` is set
* Ensure `recipe.deviceCharacteristics.provider.environment` is set
* Ensure `recipe.deviceCharacteristics.provider.clientID` is set
* Contact FrankieOne support if you don't have these values

***

### Invalid activity type

**Problem:** Error thrown: "Activity Type should be one of the following..."

**Cause:** An invalid activity type was provided.

**Solution:**

* Use only the supported activity types: 'REGISTRATION', 'LOGIN', 'CRYPTO\_DEPOSIT', 'CRYPTO\_WITHDRAWAL', 'FIAT\_DEPOSIT', 'FIAT\_WITHDRAWAL'
* Check for typos in activity type strings
* Ensure you're using the exact string values (case-sensitive)

***

### Device data not appearing in dashboard

**Problem:** Fingerprinting completes but data doesn't appear in FrankieOne dashboard.

**Troubleshooting checklist:**

1. **Check environment** — Verify you are checking the correct environment (`sandbox` vs `production`) in the dashboard. A mismatch here is the most common cause.
2. **Check clientID** — Ensure the `clientID` in your recipe matches what FrankieOne has configured for your account.
3. **Provider configured** — Confirm with your FrankieOne account team that the device fingerprinting provider is enabled for your account before integrating.
4. **CSP blockage** — There is no direct client-side indicator that device data was blocked, other than the `vendor_sdk_failed_loading` event or CSP console errors. Check browser console for blocked requests.
5. **Success indicator** — Listen for `device_characteristics_extracted` to confirm device data was captured client-side. If this event fires, data collection succeeded.

```javascript theme={null}
deviceComponent.on('device_characteristics_extracted', ({ deviceCharacteristics }) => {
  console.log('Device data collected successfully');
});
```

6. **Timeline** — How quickly device data appears in the dashboard depends on the vendor. Contact your FrankieOne account team for expected timing.

## Related Resources

* [SDK Initialization](/docs/sdk-reference/sdk-initialization) - OneSDK setup and configuration
* [Individual Module](/docs/sdk-reference/individual-module) - Identity data collection
* [Session Management](/docs/sdk-reference/session-management) - Managing user sessions


# Error Scenarios & Non-Positive States
Source: https://docs.frankieone.com/docs/sdk-reference/error-scenarios

Complete reference for all error scenarios, failed states, and non-positive outcomes across OneSDK modules

## Overview

This page documents all non-positive scenarios across the OneSDK, including error events, failed verification states, timeouts, network issues, and recoverable conditions. Understanding these scenarios helps you build robust error handling and provide better user experiences.

<Note>
  For API error codes, see [API Error Codes](/docs/reference/error-codes). This page focuses on SDK-level errors and verification outcomes.
</Note>

***

## Global SDK Errors

### Network Events

#### `network_offline`

**Module:** SDK Context (Global)

**Description:** Emitted when network connection is lost.

**Example:**

```javascript theme={null}
oneSDKInstance.on('network_offline', () => {
  showBanner('You are offline. Verification will resume when connection is restored.');
});
```

**Recovery Steps:**

* Display offline indicator to user
* Queue pending operations
* Listen for `network_online` event to resume

***

#### `network_online`

**Module:** SDK Context (Global)

**Description:** Emitted when network connection is restored after being offline.

**Example:**

```javascript theme={null}
oneSDKInstance.on('network_online', () => {
  showBanner('Connection restored. Resuming verification...');
  resumePendingOperations();
});
```

***

### Error Event

**Event:** `error`

**Available On:** All modules (SDK context, Individual, IDV, OCR, Biometrics, Device, Form)

**Description:** Emitted when an error occurs in the SDK or any module.

**Error Structure:**

```typescript theme={null}
{
  message: string;      // Human-readable error description
  name: string;         // Error type identifier (empty string if not set)
  payload: unknown;     // Additional error context
}
```

**Example:**

```javascript theme={null}
oneSDKInstance.on('error', (error) => {
  console.error('SDK Error:', {
    message: error.message,
    name: error.name,
    payload: error.payload
  });

  showGenericError(error.message);
});
```

#### Known `error.name` Values

Some errors set a specific `name` value you can check programmatically. Many errors do not set `name` — for those, inspect `error.message` instead.

**Form Module:**

| `error.name`                        | Description                                                                          |
| ----------------------------------- | ------------------------------------------------------------------------------------ |
| `FORM:CONFIGURATION_MISSING`        | Form recipe is missing a provider name. Check your OneSDK form recipe configuration. |
| `FORM-LEGACY:CONFIGURATION_MISSING` | Legacy form provider is missing the required `version` field.                        |

**Individual Module:**

| `error.name` | Description                                                                                                                   |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `SUBMIT`     | A submit retry is in progress. Fires between retry attempts (not on final failure). `error.message` includes the retry delay. |

**IDV / OCR / Biometrics — IDVerse provider:**

| `error.name`                    | Description                                                                      |
| ------------------------------- | -------------------------------------------------------------------------------- |
| `IDVerseUnableToCreateSession`  | IDVerse backend could not create a session (backend error code `IDVERSE:001`).   |
| `IDVerseTransactionClosed`      | IDVerse session was closed before completion (backend error code `IDVERSE:002`). |
| `IDVerseTransactionFailed`      | IDVerse transaction failed during verification.                                  |
| `IDVerseScanFailed`             | IDVerse scan exceeded the maximum retry count.                                   |
| `IDVerseScanFailedAndDestroyed` | IDVerse scan failed and the SDK instance was destroyed.                          |
| `IDVerseFatalError`             | IDVerse reported a fatal internal error.                                         |
| `IDVerseErrorOnStart`           | IDVerse OCR or face scan failed to start.                                        |

**IDV — Truuth provider:**

| `error.name`                        | Description                                                                             |
| ----------------------------------- | --------------------------------------------------------------------------------------- |
| `window is undefined`               | Truuth SDK requires a browser environment — `window` is not defined (e.g. SSR context). |
| `Failed to install TruuthKYCWebSdk` | Truuth SDK failed to install.                                                           |

#### Errors Without a `name`

Most errors emit with an empty `name`. Use `error.message` to identify them:

| Module                             | Scenario                                                                                 | `error.message`                                                                                                                                                                                                                      |
| ---------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| IDV                                | Provider offline (`PROVIDER_OFFLINE` status)                                             | `"Provider is offline. Either switch providers and restart or skip IDV temporarily."`                                                                                                                                                |
| IDV                                | Consent not provided (`AWAITING_CONSENT` status)                                         | `"Consent was not provided to the IDV Api. We can't continue."`                                                                                                                                                                      |
| IDV / OCR / Biometrics             | Session creation network / HTTP error                                                    | The HTTP error message. `error.name` will be set if the backend returned a known IDVerse error code (see IDVerse named errors above); otherwise empty. `error.payload.issues` contains any issues from the backend.                  |
| IDV / OCR / Biometrics / Device    | Vendor SDK failed to load                                                                | `"Vendor sdk '{vendorName}' failed loading"` where `vendorName` is the configured provider. This fires alongside `vendor_sdk_failed_loading` — prefer handling that event instead.                                                   |
| IDV                                | Sumsub failed to launch                                                                  | `"Failed to launch IDV vendor 'Sumsub'"`                                                                                                                                                                                             |
| IDV                                | Mount failed (async error during mount)                                                  | Runtime error message from the caught exception                                                                                                                                                                                      |
| IDV                                | Mastercard reported an error                                                             | `error.message` is `msg` from the Mastercard iframe postMessage payload — content is determined by Mastercard                                                                                                                        |
| OCR                                | OCR results timed out after two polling attempts                                         | `"Two attempts to get OCR results failed with an unresolved 'AWAITING_DOCUMENT_OCR'."`                                                                                                                                               |
| OCR                                | Provider offline                                                                         | `"Provider is offline. Either switch providers and restart or skip OCR temporarily."`                                                                                                                                                |
| OCR                                | Sumsub failed to launch                                                                  | `"Failed to launch OCR vendor 'Sumsub'"`                                                                                                                                                                                             |
| OCR / Biometrics — Incode provider | Incode rejected the session because required consent hasn't been granted (added v1.9.36) | `"Incode consent was not given for this entity. Call oneSdk.utils.getVendorConsent() to find out which consent item(s) are currently required, then grant them via individual().addConsent('incode.<checkboxId>') before mounting."` |
| Biometrics                         | Generic vendor error                                                                     | `"Error from vendor SDK '{provider}'"` where `{provider}` is the configured provider name                                                                                                                                            |
| Biometrics                         | Biometrics submission error                                                              | `"Error from biometrics submission"`                                                                                                                                                                                                 |
| Biometrics                         | Provider offline                                                                         | `"Error initialising biometrics check with '{provider}'. The service doesn't appear to be available."`                                                                                                                               |
| Biometrics                         | OCR not run before biometrics                                                            | `"Error initialising biometrics check with '{provider}'. You might need to run the 'ocr' component before running 'biometrics'."`                                                                                                    |
| Biometrics                         | Selfie not captured before biometrics                                                    | `"Error initialising biometrics check with '{provider}'. You might need to capture selfie before running 'biometrics'."`                                                                                                             |
| Biometrics                         | Sumsub failed to launch                                                                  | `"Failed to launch Biometrics vendor 'Sumsub'"`                                                                                                                                                                                      |
| Individual                         | Submit failed (final attempt, retries exhausted)                                         | `error.response?.data?.message` from the API response body, or the raw network error message if no response body                                                                                                                     |
| Individual                         | Entity details failed to load (`search()`)                                               | `"Critical error! There was an issue loading the individual's details. Is the entityId ({entityId}) used to create this session valid?"` where `{entityId}` is the actual entity ID                                                  |
| IDV — Daon provider                | Unexpected error received from the Daon iframe                                           | `"DAON_ERROR"`                                                                                                                                                                                                                       |
| IDV — Daon provider                | Timeout from the Daon TrustX iframe                                                      | `"DAON_TIMEOUT"`                                                                                                                                                                                                                     |

**Recovery Steps:**

* Check `error.name` first if set; fall back to parsing `error.message`
* Use `error.payload` for additional context (e.g. HTTP response body, issues array)
* For session creation failures, `session_data_failed_loading` fires alongside `error` and includes the HTTP `code` and `message`
* For vendor SDK load failures, handle `vendor_sdk_failed_loading` directly — it carries the same information in a structured format
* For the Incode consent error, call [`oneSdk.utils.getVendorConsent()`](/docs/sdk-reference/sdk-initialization#utils-getvendorconsent) to find out which consent item(s) are required, grant them via `individual().addConsent('incode.<checkboxId>')`, then retry mounting

***

### Warning Event

**Event:** `warning`

**Module:** All modules

**Description:** Emitted for non-critical warnings that don't prevent operation but should be noted.

**Structure:**

```typescript theme={null}
{
  message: string;
  payload?: unknown;
}
```

**Example:**

```javascript theme={null}
oneSDKInstance.on('warning', (warning) => {
  console.warn('SDK Warning:', warning.message);
});
```

***

### Initialization Failures

**Scenario:** SDK initialization fails with Promise rejection

**Causes:**

* Invalid or expired session token
* Configuration error
* Network connectivity issues
* CSP policy blocking SDK resources

**Example:**

```javascript theme={null}
try {
  const sdk = await OneSdk({
    mode: 'production',
    session: { token: sessionToken }
  });
} catch (error) {
  console.error('Initialization failed:', error);

  // Generate fresh token and retry
  const newToken = await fetchNewTokenFromBackend();
  const sdk = await OneSdk({
    mode: 'production',
    session: { token: newToken }
  });
}
```

**Recovery Steps:**

1. Wrap initialization in try-catch
2. Generate fresh token from backend
3. Retry initialization with new token
4. Check browser console for CSP errors

***

### CSP (Content Security Policy) Errors

**Scenario:** Browser blocks OneSDK resources due to CSP policy

**Symptoms:** Browser console shows CSP violations when loading or running the SDK. Blocked resources may originate from FrankieOne's own domains or from third-party vendor SDKs (Onfido, Sumsub, Sardine, ThreatMetrix, etc.).

**Recovery Steps:**

Update your CSP headers based on what is being blocked:

| Blocked operation             | CSP directive to update |
| ----------------------------- | ----------------------- |
| Loading SDK scripts           | `script-src`            |
| API connections / XHR / fetch | `connect-src`           |
| Loading images from provider  | `img-src`               |
| Loading provider fonts        | `font-src`              |
| Vendor iframes (e.g. Sumsub)  | `frame-src`             |

Check the browser console for the specific blocked URL, then add the relevant domain to the appropriate directive. Both FrankieOne's domains and your chosen vendor's domains may need to be allowlisted.

```
Content-Security-Policy:
  script-src 'self' https://*.frankieone.com [vendor-domains];
  connect-src 'self' https://*.frankieone.com [vendor-domains];
  img-src 'self' https://*.frankieone.com [vendor-domains] data:;
```

Replace `[vendor-domains]` with the actual domains used by your chosen provider. See [Vendor CSP Settings](/docs/sdk-reference/vendor-customizations#content-security-policy-csp-settings) for vendor-specific domain lists.

***

## Session Management Errors

### Session Expiration

**Method:** `getExpirationEpoch()` returns timestamp in past

**Description:** User's session token has expired before verification completion.

**Example:**

```javascript theme={null}
const expirationEpoch = sdk.session.getExpirationEpoch();
const now = Date.now();

if (expirationEpoch && expirationEpoch * 1000 < now) {
  // Session expired — user must start over with a new token from your backend
  console.log('Session expired');
  showMessage('Your session has expired. Please start over.');
}
```

**Recovery Steps:**

1. Call `getExpirationEpoch()` to check expiration
2. Warn users when less than 5 minutes remaining
3. If the session expires mid-flow, the user must start over — there is no refresh token mechanism
4. Reinitialize SDK with a fresh token obtained from your backend

<Warning>
  There is no token refresh mechanism in OneSDK. If a session token expires while the user is mid-verification, you must generate a new token from your backend and reinitialize the SDK. Instruct users to start the verification flow again.
</Warning>

***

### Missing Entity ID

**Method:** `getEntityId()` returns `null`

**Description:** Session hasn't been associated with an entity yet.

**Example:**

```javascript theme={null}
const entityId = sdk.session.getEntityId();

if (!entityId) {
  console.log('Entity not yet created');
  // First-time user - proceed with data collection
} else {
  console.log('Existing entity:', entityId);
  // Returning user - load existing data
}
```

**Recovery Steps:**

* Always check for `null` before using entity ID
* Entity will be created after first data submission

***

## Individual Module (KYC) Errors

### Verification Status Failures

#### `failed`

**Property:** `CheckSummary.status.type`

**Description:** Verification failed automated checks.

**Example:**

```javascript theme={null}
const results = await individual.submit({ verify: true });

if (results.status.type === 'failed') {
  console.log('Verification failed');
  console.log('Failed checks:', results.checkResults.filter(c => c.result.type === 'failed'));

  // Check specific issues
  results.checkResults.forEach(check => {
    if (check.issues && check.issues.length > 0) {
      console.log(`Issues in ${check.type}:`, check.issues);
    }
  });
}
```

**Recovery Steps:**

1. Examine `checkResults` array for specific failed checks
2. Review `issues` object for detailed error information
3. Check `retryPages` for screens that can be retried
4. Allow user to correct data and resubmit

***

#### `fail_manual`

**Property:** `CheckSummary.status.type`

**Description:** Manually rejected after review by compliance staff.

**Recovery Steps:**

* Contact support for rejection reason
* May require completely new verification with different data
* User should be informed this is a final decision

***

#### `refer`

**Property:** `CheckSummary.status.type`

**Description:** Requires manual review; not automatically approved or denied.

**Example:**

```javascript theme={null}
if (results.status.type === 'refer') {
  showMessage('Your verification is under review. We\'ll notify you within 24-48 hours.');
}
```

**Recovery Steps:**

* Inform user that manual review is in progress
* Provide expected timeline (if known)
* Set up webhook to receive result notification
* Don't allow resubmission until review complete

***

#### `wait`

**Property:** `CheckSummary.status.type`

**Description:** Waiting for additional information from user.

**Example:**

```javascript theme={null}
if (results.status.type === 'wait') {
  // Check what actions are needed
  const actions = results.alertList.filter(alert => alert.type === 'action');

  actions.forEach(action => {
    console.log('Action required:', action.term);
    if (action.extra?.action) {
      console.log('Specific action:', action.extra.action);
    }
  });
}
```

**Recovery Steps:**

1. Check `alertList` for specific actions required
2. Implement handlers for common action types:
   * `additional_document_required` - Upload missing documents
   * `upload_proof_of_address` - Provide address verification
   * `document_expired` - Upload current document
3. Allow user to provide missing information
4. Resubmit verification after data provided

***

#### `unchecked`

**Property:** `CheckSummary.status.type`

**Description:** No checks have been run yet.

**Recovery Steps:**

* Call `submit({ verify: true })` or `runChecks()` to execute verification
* This is the initial state before any verification

***

#### `archived`

**Property:** `CheckSummary.status.type`

**Description:** Entity has been archived in the system.

**Recovery Steps:**

* Archiving is irreversible. You cannot unarchive an entity.
* Create a new entity and session to onboard the customer again.

***

#### `inactive`

**Property:** `CheckSummary.status.type`

**Description:** Entity has been deactivated.

**Recovery Steps:**

* Deactivation is irreversible. You cannot reactivate a deactivated entity.
* Create a new entity and session to onboard the customer again.

***

### Personal Information Validation Failures

**Properties:** `CheckSummary.personalChecks.*`

**Possible Values:**

* `true` - Field validated successfully
* `false` - Field failed validation
* `null` - Field was not checked

**Example:**

```javascript theme={null}
const { personalChecks } = results;

if (personalChecks.name === false) {
  showError('Name verification failed. Please check your name matches your ID.');
}

if (personalChecks.dateOfBirth === false) {
  showError('Date of birth verification failed.');
}

if (personalChecks.addresses) {
  Object.entries(personalChecks.addresses).forEach(([addressId, isValid]) => {
    if (isValid === false) {
      showError(`Address ${addressId} verification failed.`);
    }
  });
}
```

**Recovery Steps:**

1. Identify which specific fields failed (`=== false`)
2. Prompt user to correct the failed field
3. Resubmit verification with corrected data

***

### Risk Assessment Failures

**Properties:** `CheckSummary.risk.class`, `CheckSummary.risk.level`

**Risk Classes:** `low`, `medium`, `high`, `unacceptable`, `null`

**Risk Level:** Numeric value in the range 0–100. Lower numbers indicate lower risk.

<Note>
  The mapping between `risk.level` (numeric) and `risk.class` (categorical) depends on your risk configuration in FrankieOne and is not a fixed universal scale. When `risk.class` is `null`, `risk.level` is typically also absent. Contact your FrankieOne account team to understand your configured thresholds.
</Note>

**Example:**

```javascript theme={null}
const { risk } = results;

if (risk.class === 'high' || risk.class === 'unacceptable') {
  console.log('High risk detected, level:', risk.level);

  // Check for blocklist matches
  if (results.blocklistPotentialMatches.length > 0) {
    console.log('Blocklist matches found:', results.blocklistPotentialMatches);
  }

  // Check for duplicates
  if (results.duplicatePotentialMatches.length > 0) {
    console.log('Duplicate entities found:', results.duplicatePotentialMatches);
  }
}
```

**Recovery Steps:**

* `high` - May require manual review; check `blocklistPotentialMatches` and `duplicatePotentialMatches`
* `unacceptable` - Likely verification failure; escalate to compliance team
* Review `alertList` for specific risk factors

***

### Check Result Issues

**Property:** `CheckSummary.checkResults[].issues`

Each check result may include an `issues` array with `{ code, description }` entries identifying what failed. See [Individual Module — CheckSummary](/docs/sdk-reference/individual-module#checksummary-structure) for full structure.

**Recovery Steps:**

* Parse issues array to identify specific failures
* Display `issue.description` to user
* Use `issue.code` for programmatic handling

***

### Credit Header Issue

**Property:** `CheckSummary.issues.creditHeader`

**Accessor:** `individual.access('creditHeaderIssue')`

**Description:** A boolean flag set after `submit({ verify: true })` indicating the credit header check encountered an issue (e.g. the backend reported `hasCreditHeaderIssue` or a `creditHeaderIssueMessage`). Available on both the v1 and F2 API paths.

<Note>
  This is **not** a hard failure — it does not affect `CheckSummary.status.type`. Treat it as a data-quality signal about the credit header check rather than a blocking error.
</Note>

**Example:**

```javascript theme={null}
const results = await individual.submit({ verify: true });

if (results.issues?.creditHeader) {
  console.log('Credit header check flagged an issue — informational, not blocking');
}

// Or read it reactively via the accessor:
const hasCreditHeaderIssue = individual.access('creditHeaderIssue').getValue();
```

**Recovery Steps:**

* No user-facing action is required by default — the verification can still proceed based on `status.type`
* Optionally surface this to the user or your compliance team as an informational note
* Do not treat this flag alone as grounds to fail or block the applicant

***

### Alert List

#### Alert Types

All alerts in `alertList` have a `type` property that indicates severity:

| `type`    | Description                                                                   |
| --------- | ----------------------------------------------------------------------------- |
| `alert`   | High-priority issue requiring attention (fraud indicators, sanctions matches) |
| `action`  | User must take a specific action to proceed                                   |
| `warning` | Non-blocking concern that may affect approval                                 |
| `success` | Positive signal from a check                                                  |

The `term` property describes the specific topic of the alert. Known `term` values include:

| `term`      | Description                |
| ----------- | -------------------------- |
| `fraud`     | Fraud risk indicator       |
| `partial`   | Partial match found        |
| `media`     | Adverse media match        |
| `watchlist` | Watchlist match            |
| `sanction`  | Sanctions list match       |
| `blacklist` | Blocklist match            |
| `duplicate` | Potential duplicate entity |
| `risk`      | General risk indicator     |

<Note>
  The `term` value depends on the checks configured for your account. Handle unknown `term` values gracefully.
</Note>

#### Action Required

**Type:** `action`

**Property:** `CheckSummary.alertList`

**Common Actions:**

* `additional_document_required` - Upload supporting document
* `upload_proof_of_address` - Provide address verification document
* `document_expired` - Upload current/unexpired document

**Example:**

```javascript theme={null}
const actions = results.alertList.filter(alert => alert.type === 'action');

actions.forEach(action => {
  console.log('Action required:', action.term);

  if (action.extra?.action) {
    switch (action.extra.action) {
      case 'upload_proof_of_address':
        showUploadForm('Please upload proof of address');
        break;
      case 'additional_document_required':
        showUploadForm('Please upload additional document');
        break;
      case 'document_expired':
        showError('Your document has expired. Please upload a current document.');
        break;
    }
  }
});
```

**Recovery Steps:**

1. Filter `alertList` for `type === 'action'`
2. Implement handler for each action type
3. Collect required information from user
4. Resubmit verification

***

#### Warnings

**Type:** `warning`

**Example:**

```javascript theme={null}
const warnings = results.alertList.filter(alert => alert.type === 'warning');

warnings.forEach(warning => {
  console.warn('Warning:', warning.term);
});
```

**Recovery Steps:**

* Display warnings to user
* Assess if warnings prevent verification completion
* Some warnings may not block approval

***

### Duplicate Detection

#### Duplicate Potential Matches

**Property:** `CheckSummary.duplicatePotentialMatches`

**Description:** Entity may be a duplicate of an existing entity in the system. Each match includes `entityId`, `matchStrength` (0–1 confidence), and matched fields. See [Individual Module — CheckSummary](/docs/sdk-reference/individual-module#checksummary-structure) for full structure.

**Recovery Steps:**

1. Review duplicate matches manually
2. Verify if user already has an existing account
3. If legitimate duplicate, merge or link entities via backend API
4. If false positive, proceed with verification

***

#### Duplicate Blocklist Matches

**Property:** `CheckSummary.duplicateBlocklistMatches`

**Description:** Entity matches found across combined duplicate detection and blocklist/sanctions analysis. These represent entities flagged simultaneously in both checks and are high-priority alerts.

**Recovery Steps:**

* This is a critical alert
* Immediate investigation required
* Likely verification failure
* Escalate to compliance team

***

### Blocklist Matches

**Property:** `CheckSummary.blocklistPotentialMatches`

**Description:** Entity matched against blocklist/sanctions/AML databases.

**Example:**

```javascript theme={null}
if (results.blocklistPotentialMatches.length > 0) {
  console.log('BLOCKLIST MATCH DETECTED');

  results.blocklistPotentialMatches.forEach(match => {
    console.log('Matched entity:', match.entityId);
    console.log('Match confidence:', match.matchStrength);
    console.log('Matched personal fields:', match.matches.personal);
  });

  // Halt verification and escalate
  escalateToCompliance(results);
}
```

**Recovery Steps:**

* Stop verification process immediately
* Escalate to compliance/risk team
* Do NOT proceed with onboarding
* Perform manual investigation

***

### Retry Pages

**Property:** `CheckSummary.retryPages`

**Description:** Recommended pages where the user can retry their submission, so they don't need to go through the entire flow again. Can be empty if the backend cannot determine which pages should be retried.

**Example:**

```javascript theme={null}
if (results.status.type === 'failed') {
  if (results.retryPages.length > 0) {
    console.log('Recommended retry pages:', results.retryPages);
    // Navigate user to the first recommended retry page
    navigateToPage(results.retryPages[0].name);
  } else {
    // Backend couldn't determine retry pages - restart the full flow
    restartVerificationFlow();
  }
}
```

**Recovery Steps:**

* Navigate user to the recommended retry pages if provided
* User can correct specific data and resubmit
* If `retryPages` is empty, the user should restart the full verification flow

***

### `checkResults`, `checkTypes`, and `checkCounts`

For the relationship between `checkTypes`, `checkResults`, and `checkCounts`, see [Individual Module — CheckSummary](/docs/sdk-reference/individual-module#checksummary-structure).

Key points:

* `checkResults` depends on which checks are configured. A missing entry for a `checkType` typically means that check hasn't run yet.
* `checkCounts` lists data source names that verified each personal info field — not the check results themselves (those are in `personalChecks`).

***

### Submit Failures

**Method:** `submit()` or `submit({ verify: true })`

**Description:** Promise rejection on error.

**Causes:**

* Network error
* Validation error
* Server error
* Timeout

**Example:**

```javascript theme={null}
try {
  // retryOptions is NOT enabled by default — pass it explicitly to enable retry behavior
  const results = await individual.submit(
    { verify: true },
    {
      maxRetries: 3,
      backoffDelayMs: 1000
    }
  );
} catch (error) {
  console.error('Submit failed:', error);

  if (error.message.includes('network')) {
    showError('Network error. Please check your connection and try again.');
  } else if (error.message.includes('validation')) {
    showError('Please check your information and try again.');
  } else {
    showError('An error occurred. Please try again later.');
  }
}
```

**Recovery Steps:**

1. Pass `retryOptions` explicitly to enable automatic retries (not on by default)
2. Implement custom error handling in the `catch` block
3. Show user-friendly error messages
4. For persistent errors, contact support

***

### Accessor Usage

**Method:** `individual.access(fieldName)`

**Description:** Returns a reactive Accessor object for reading and writing individual entity fields. Use `access()` for reading or writing entity data within the module — you don't have direct access to the full raw entity data object.

**Accessor Interface:**

```typescript theme={null}
{
  getValue(): T;              // Read current value
  setValue(value: T): void;  // Write new value
  observable: Observable<T>; // Subscribe to reactive changes
}
```

Use `individual.search()` to refresh entity data from FrankieOne (fetches latest from backend). Use `individual.access()` for reading/writing the local entity state.

**Example:**

```javascript theme={null}
// Read
const name = individual.access('name').getValue();

// Write
individual.access('name').setValue({ givenName: 'John', familyName: 'Doe' });

// Subscribe to reactive changes
individual.access('name').observable.subscribe((newName) => {
  console.log('Name updated:', newName);
});
```

See [Individual Module - access()](/docs/sdk-reference/individual-module#access-fieldname) for the full list of available fields.

***

### Data Not Persisted

**Method:** `isPersisted()` returns `false`

**Description:** Changes haven't been submitted to the server yet.

**Example:**

```javascript theme={null}
if (!individual.isPersisted()) {
  showWarning('You have unsaved changes.');
}

// Before navigation
window.addEventListener('beforeunload', (e) => {
  if (!individual.isPersisted()) {
    e.preventDefault();
    e.returnValue = 'You have unsaved changes. Are you sure you want to leave?';
  }
});
```

**Recovery Steps:**

* Warn user before navigation
* Implement unsaved changes detection
* Prompt to save before leaving page

***

## Common Events: Vendor Modules

The following events are emitted by all vendor-based modules — IDV, OCR, Biometrics, and Device. See the respective module docs for full parameter details.

### `vendor_sdk_loaded`

Emitted when the third-party provider's SDK has been successfully loaded and is ready.

### `vendor_sdk_failed_loading`

Emitted when the provider's SDK fails to load. This is the primary signal that the module cannot function.

```javascript theme={null}
// Applies to: IDV, OCR, Biometrics, Device
module.on('vendor_sdk_failed_loading', ({ vendor, errorObject }) => {
  console.error(`Failed to load ${vendor} SDK:`, errorObject);
});
```

**Recovery Steps:**

* Check CSP headers allow the provider's domains
* Verify credentials (`clientID`, environment setting)
* Ensure the provider is configured for your account in FrankieOne
* Fall back to an alternative flow if possible

### `session_data_generated`

Emitted when a provider session has been created. Useful for logging or debugging.

### `session_data_failed_loading`

Emitted when session data fails to load from the provider. Usually indicates a backend configuration issue.

```javascript theme={null}
module.on('session_data_failed_loading', ({ code, message }) => {
  console.error('Session failed:', message);
  showError('Unable to start verification. Please try again.');
});
```

***

## IDV Module Errors

For `vendor_sdk_failed_loading`, `vendor_sdk_loaded`, `session_data_generated`, and `session_data_failed_loading`, see [Common Events: Vendor Modules](#common-events-vendor-modules).

### Status-to-Event Mapping

IDV statuses are delivered through different events depending on their nature:

| Status                  | Event            | Meaning                                                          |
| ----------------------- | ---------------- | ---------------------------------------------------------------- |
| `COMPLETE`              | `results`        | Verification completed successfully                              |
| `FAILED`                | `results`        | Verification failed                                              |
| `INCOMPLETE`            | `input_required` | Verification could not be completed due to incomplete user input |
| `DOCUMENTS_INVALID`     | `input_required` | Document provided was invalid or wrong type                      |
| `PROVIDER_OFFLINE`      | `error`          | The verification provider is unavailable                         |
| `AWAITING_CONSENT`      | `input_required` | User has not yet provided consent                                |
| `WAITING_SELFIE_UPLOAD` | `input_required` | Waiting for selfie capture                                       |
| `WAITING_DOC_UPLOAD`    | `input_required` | Waiting for document upload                                      |
| `INTERRUPTED`           | `input_required` | Verification flow was closed or interrupted                      |

<Note>
  The `results` event is only emitted with `COMPLETE` or `FAILED` status. All other statuses appear via `input_required`, `error`, or `processing` events. The Biometrics module uses the same `IDVStatus` enum — all statuses above apply to both IDV and Biometrics.
</Note>

### IDV Status Failures

#### `FAILED`

**Property:** `results.checkStatus`

**Example:**

```javascript theme={null}
idvFlow.on('results', (results) => {
  if (results.checkStatus === 'FAILED') {
    console.log('IDV verification failed');
    showFailureScreen();
  }
});
```

***

#### `INCOMPLETE`

**Description:** Verification could not be completed because of missing user input.

**Example:**

```javascript theme={null}
idvFlow.on('input_required', (info, status) => {
  if (status === 'INCOMPLETE') {
    showMessage('Verification incomplete. Please complete all required steps.');
    allowRetry();
  }
});
```

***

#### `DOCUMENTS_INVALID`

**Description:** Provided documents are invalid or of wrong type.

**Example:**

```javascript theme={null}
idvFlow.on('input_required', (info, status) => {
  if (status === 'DOCUMENTS_INVALID') {
    showError('Invalid document. Please select a different document type.');
    allowRetry();
  }
});
```

***

#### `PROVIDER_OFFLINE`

**Description:** IDV provider is offline/unavailable. This status surfaces as an `error` event.

**Recovery Steps:**

* Show unavailable message to user
* Retry after a delay
* If persistent, contact support

***

#### `AWAITING_CONSENT`

**Description:** Waiting for user consent to proceed.

**Example:**

```javascript theme={null}
idvFlow.on('input_required', (info, status) => {
  if (status === 'AWAITING_CONSENT') {
    showMessage('Please provide consent to continue verification.');
    allowRetry();
  }
});
```

***

#### `WAITING_SELFIE_UPLOAD`

**Description:** Waiting for selfie/biometric capture.

**Example:**

```javascript theme={null}
idvFlow.on('input_required', (info, status) => {
  if (status === 'WAITING_SELFIE_UPLOAD') {
    showMessage('Please capture your selfie to continue.');
    allowRetry();
  }
});
```

***

#### `WAITING_DOC_UPLOAD`

**Description:** Waiting for document upload.

**Example:**

```javascript theme={null}
idvFlow.on('input_required', (info, status) => {
  if (status === 'WAITING_DOC_UPLOAD') {
    showMessage('Please upload your document to continue.');
    allowRetry();
  }
});
```

***

#### `INTERRUPTED`

**Description:** Verification session was closed or interrupted by the user.

**Example:**

```javascript theme={null}
idvFlow.on('input_required', (info, status) => {
  if (status === 'INTERRUPTED') {
    // Remount the module to allow the user to resume
    showMessage('Verification was interrupted. Click retry to continue.');
    showRetryButton(() => idvFlow.mount('#idv-container'));
  }
});
```

***

### `input_required` — Semantics

**Event:** `input_required`

The `input_required` event is emitted when a check could not be completed due to user input — not because of a system failure. For example:

* The user uploaded the wrong document type
* The user closed the verification session before completing it
* Required captures (selfie, document) have not been provided

Retrying the step will always help resolve `input_required` — if the user closed the session, remounting the module allows them to continue. Whether to limit the number of retry attempts depends on your business process.

<Note>
  There is no way to differentiate between user abandonment (user deliberately closed the session) and session timeout within the SDK. Both emit `input_required` with `INTERRUPTED` status.
</Note>

**Example:**

```javascript theme={null}
idvFlow.on('input_required', (info, status) => {
  console.log('Input required:', status);

  // Show retry option — remounting the module resumes the flow
  showRetryButton(() => {
    idvFlow.unmount();
    idvFlow.mount('#idv-container');
  });
});
```

***

### Detection Failed

**Event:** `detection_failed`

**Example:**

```javascript theme={null}
idvFlow.on('detection_failed', ({ message, payload }) => {
  console.error('Detection failed:', message);
  console.error('Details:', payload);
  showError(message || 'Document capture failed. Please try again.');
});
```

**Recovery Steps:**

* Log error details from `payload`
* Show user-friendly error message
* Offer retry option

***

### Session Interrupted

**Event:** `session_interrupted`

**Provider:** Onfido-specific. Other providers do not emit this event — if you listen for it while using a non-Onfido provider, the handler will simply never fire.

**Example:**

```javascript theme={null}
// Only register this listener if using Onfido
idvFlow.on('session_interrupted', () => {
  console.log('User closed verification (Onfido)');
  saveProgress();
  showMessage('You can resume verification later.');
});
```

***

## OCR Module Errors

For `vendor_sdk_failed_loading`, `vendor_sdk_loaded`, `session_data_generated`, and `session_data_failed_loading`, see [Common Events: Vendor Modules](#common-events-vendor-modules).

<Note>
  **`isPreloaded()` in OCR:** The `isPreloaded()` method is not typically used in standard OCR integrations and can be safely ignored. Use events (`detection_complete`, `results`) to track document capture progress instead.
</Note>

### OCR Status Failures

#### `DOCUMENTS_INVALID`

**Example:**

```javascript theme={null}
ocrComponent.on('input_required', (info, status) => {
  if (status === 'AWAITING_DOCUMENT_UPLOAD_INVALID_TYPE') {
    showError('Invalid document type. Please select a different document.');
  }
});
```

***

#### `DOCUMENTS_UPLOAD_FAILED`

**Description:** Document upload failed during OCR processing.

**Recovery Steps:**

* Retry upload
* Check file size and format
* Verify network connection

***

#### `PROVIDER_OFFLINE`

**Description:** OCR provider is offline/unavailable.

**Recovery Steps:**

* Show provider unavailable message
* Retry after delay
* Fall back to manual data entry if available

***

#### `FAILED_FILE_SIZE`

**Description:** File size exceeds provider limit.

**Recovery Steps:**

* Show file size error
* Indicate maximum allowed size
* Ask user to provide smaller file or different format

***

#### `FAILED_FILE_FORMAT`

**Description:** Incorrect file format provided.

**Recovery Steps:**

* Show format error
* List accepted formats (JPG, PNG, PDF, etc.)
* Prompt user to select valid file

***

#### `INTERRUPTED`

**Description:** Capture flow was interrupted.

**Recovery Steps:**

* Allow user to restart capture\\

***

## Biometrics Module Errors

<Note>
  The Biometrics module uses the same `IDVStatus` enum as the IDV module. All statuses documented in the [IDV section](#idv-module-errors) (COMPLETE, FAILED, INCOMPLETE, DOCUMENTS\_INVALID, etc.) apply equally to Biometrics. There are no Biometrics-specific statuses.
</Note>

For `vendor_sdk_failed_loading`, `vendor_sdk_loaded`, `session_data_generated`, and `session_data_failed_loading`, see [Common Events: Vendor Modules](#common-events-vendor-modules).

***

### Session Data Failed Loading

**Event:** `session_data_failed_loading`

**Example:**

```javascript theme={null}
biometricsComponent.on('session_data_failed_loading', ({ code, message }) => {
  console.error('Session failed:', code, message);
  showError('Failed to start biometric verification. Please try again.');
});
```

***

### Input Required

**Event:** `input_required`

**Common Scenarios:**

* User closed verification session
* Session timeout occurred
* Waiting for selfie capture
* Camera permission denied

**Example:**

```javascript theme={null}
biometricsComponent.on('input_required', (info, status) => {
  console.log('Input required:', status);
  showMessage('Please complete the biometric capture to continue.');
  showRetryButton();
});
```

***

### Detection Failed

**Event:** `detection_failed`

**Example:**

```javascript theme={null}
biometricsComponent.on('detection_failed', ({ message }) => {
  console.error('Biometric capture failed:', message);
  showError(message || 'Face capture failed. Please try again.');
});
```

***

## Device Module Errors

For `vendor_sdk_failed_loading`, `vendor_sdk_loaded`, and `session_data_generated`, see [Common Events: Vendor Modules](#common-events-vendor-modules). For the Device module specifically, `vendor_sdk_failed_loading` means device fingerprinting is unavailable — you should fall back to proceeding without device data.

### Configuration Validation Errors

**Scenario:** Missing provider configuration

**Error Message:** "Your account is missing the environment configuration..."

**Recovery Steps:**

* Ensure `recipe.deviceCharacteristics.provider` is configured
* Verify `clientID` and `environment` are set and correct
* Contact FrankieOne support to verify the provider is enabled for your account

***

### Invalid Activity Type

**Scenario:** Invalid activity type provided to `start()`

**Error Message:** "Activity Type should be one of the following..."

**Valid Types:** `REGISTRATION`, `LOGIN`, `CRYPTO_DEPOSIT`, `CRYPTO_WITHDRAWAL`, `FIAT_DEPOSIT`, `FIAT_WITHDRAWAL`

**Example:**

```javascript theme={null}
// Incorrect
oneSdkInstance.component('device', { activityType: 'registration' }); // ✗ lowercase

// Correct
oneSdkInstance.component('device', { activityType: 'REGISTRATION' }); // ✓ uppercase
```

**Recovery Steps:**

* Use exact activity type string (case-sensitive)
* Verify spelling matches valid types

***

### Device Data Not Appearing in Dashboard

**Troubleshooting checklist:**

1. **Check environment** — Verify you are checking the correct environment (sandbox vs production) in the dashboard. A mismatch here is the most common cause.
2. **Check clientID** — Ensure the `clientID` matches what FrankieOne has configured for your account.
3. **Provider configured** — Confirm with your FrankieOne account team that the device fingerprinting provider is enabled and configured for your account before integrating.
4. **CSP blockage** — There is no direct client-side indicator that device data was blocked (other than the `vendor_sdk_failed_loading` event or CSP console errors). Check browser console for blocked requests.
5. **Success indicator** — Listen for the `device_characteristics_extracted` event to confirm device data was collected client-side. If this event fires, the data was captured successfully.
6. **Timeline** — How quickly device data appears in the dashboard depends on the vendor. Contact your FrankieOne account team for expected timing.

```javascript theme={null}
deviceComponent.on('device_characteristics_extracted', ({ deviceCharacteristics }) => {
  console.log('Device data collected — should appear in dashboard');
});
```

***

## Form Module Errors

### Screen Failed Events

**Event Pattern:** `form:{screen}:failed`

**Screens:** `welcome`, `start`, `consent`, `document`, `personal`, `review`, `loading`, `result`, `retry`, `doc_upload`, `required_document_upload`, `partial_document_upload`, `optional_document_upload`

**Example:**

```javascript theme={null}
formComponent.on('form:welcome:failed', (payload) => {
  console.error('Welcome screen failed to load');
  showError('Unable to start verification. Please refresh the page.');
});
```

**Recovery Steps:**

* Log error for investigation
* Show user-friendly error message
* Offer page refresh or retry
* Contact support if persists

***

### Review Events (`form:review:*`)

<Warning>
  `form:review:failed`, `form:review:success`, `form:review:partial`, and `form:review:pending` are **only emitted when [`customResult: true`](/docs/sdk-reference/form-module/configuration#page-configuration-types) is set in manual mode**. When `customResult` is `false` (the default), the form automatically navigates to and displays the configured result screen — no review events are emitted for you to handle.

  In OCR mode, the only review event is `form:review:ready`.

  See [`verify`](/docs/sdk-reference/form-module/configuration#page-configuration-types) and [`customResult`](/docs/sdk-reference/form-module/configuration#page-configuration-types) in the configuration reference.
</Warning>

Use `customResult: true` when you want to intercept the review outcome and handle navigation yourself (e.g., display a custom message or CTA):

#### `form:review:failed`

**Description:** Verification did not pass at review stage. Only emitted with `customResult: true`.

**Example:**

```javascript theme={null}
formComponent.on('form:review:failed', (payload) => {
  console.log('Verification failed');
  showCustomFailureUI();
});
```

***

#### `form:review:partial`

**Description:** Partial verification result. Only emitted with `customResult: true`.

**Example:**

```javascript theme={null}
formComponent.on('form:review:partial', (payload) => {
  showCustomPartialUI();
});
```

***

#### `form:review:pending`

**Description:** Result pending manual review. Only emitted with `customResult: true`.

**Example:**

```javascript theme={null}
formComponent.on('form:review:pending', (payload) => {
  showCustomPendingUI();
});
```

***

### Result Screen States

Result screen states are **display configurations** — not error events to handle. They control what message and CTA the built-in result screen shows. Set the state when initializing the RESULT screen to display the appropriate message to the user.

| State            | Description                                                   |
| ---------------- | ------------------------------------------------------------- |
| `SUCCESS`        | Verification passed                                           |
| `FAIL`           | Verification failed                                           |
| `PENDING`        | Verification pending manual review                            |
| `PARTIAL`        | Partial verification result                                   |
| `UPLOAD_FAIL`    | Document upload failed                                        |
| `PROVIDER_ERROR` | Provider encountered an error                                 |
| `TIMEOUT`        | The identity verification process took too long and timed out |

**Example — configure a failure result screen:**

```javascript theme={null}
const failResult = sdk.component('form', {
  name: 'RESULT',
  type: 'manual',
  state: 'FAIL',
  title: { label: 'Verification Failed' },
  descriptions: [{ label: 'We were unable to verify your information.' }]
});

failResult.on('form:result:loaded', () => {
  console.log('Failure screen displayed');
});
```

**Example — configure a timeout result screen:**

```javascript theme={null}
const timeoutResult = sdk.component('form', {
  name: 'RESULT',
  type: 'manual',
  state: 'TIMEOUT',
  title: { label: 'Your session has timed out' },
  descriptions: [{ label: 'The identity verification process took too long and has timed out. Please close this window and try again.' }]
});

timeoutResult.on('form:result:timeout', () => {
  console.log('Timeout screen displayed');
});
```

<Note>
  `TIMEOUT` uses its own icon and copy, distinct from `FAIL`. When the RESULT screen is configured with `state: 'TIMEOUT'`, the module emits a `form:result:timeout` event (in addition to the generic `form:result:loaded`) — listen for it if you want to handle the timeout case specifically, for example to log it separately from a hard verification failure.
</Note>

***

### Review Screen — Retry Configuration

When a form submission fails on the Review screen, the SDK has built-in retry behavior controlled by the Review screen's CTA (`cta`) configuration. This is **not** on the Retry screen.

**CTA Configuration (Review screen):**

```javascript theme={null}
{
  name: 'REVIEW',
  // ...
  cta: {
    label: 'Submit',
    timeoutRetryMiliseconds: 5000,  // Auto-retry delay ms — the form retries automatically after this
    retryAmount: 3,                 // Max retry attempts per submission
    retryAttemptString: 'Error submitting form. Give it a moment to retry.',
    maxRetryAttemptedString: 'Something went wrong, please contact customer service or try again.'
  }
}
```

* **`timeoutRetryMiliseconds`** — The form automatically retries submission after this delay. No user click needed.
* **`retryAmount`** — Maximum retry attempts. After exhausting retries, the user sees `maxRetryAttemptedString`.
* The retry counter is per submission, not persistent across sessions.
* No event is emitted per retry attempt.

### Retry Screen

**Screen:** `RETRY`

The Retry screen is specific to the eKYC flow — it is shown when verification fails and the user needs to re-enter data. It is not the same as the Review screen's submission retry.

**Example:**

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

retry.on('form:retry:loaded', (payload) => {
  console.log('User can correct data and retry eKYC');
});
```

***

## Best Practices

### 1. Always Handle Errors

```javascript theme={null}
// ✓ Good
oneSDKInstance.on('error', (error) => {
  logError(error);
  showUserFriendlyMessage(error);
});

// ✗ Bad - No error handler
oneSDKInstance.on('results', handleResults); // Missing error handler
```

***

### 2. Provide User-Friendly Messages

```javascript theme={null}
// ✓ Good
oneSDKInstance.on('error', (error) => {
  if (error.name === 'network_error') {
    showMessage('Please check your internet connection and try again.');
  } else {
    showMessage('Something went wrong. Please try again later.');
  }
});

// ✗ Bad - Technical jargon
oneSDKInstance.on('error', (error) => {
  alert(error.message); // May contain technical details
});
```

***

### 3. Check Status Before Acting

```javascript theme={null}
// ✓ Good
const results = await individual.submit({ verify: true });

switch (results.status.type) {
  case 'passed':
    navigateToSuccess();
    break;
  case 'failed':
    showFailureScreen(results);
    break;
  case 'refer':
    showPendingReview();
    break;
  case 'wait':
    showAdditionalInfoRequired(results.alertList);
    break;
  default:
    handleUnexpectedStatus(results.status.type);
}

// ✗ Bad - Only checking success
if (results.status.type === 'passed') {
  navigateToSuccess();
}
// Missing handling for all other states
```

***

### 4. Log Errors for Investigation

```javascript theme={null}
// ✓ Good
oneSDKInstance.on('error', (error) => {
  // Log to analytics/monitoring
  logToSentry({
    message: error.message,
    name: error.name,
    payload: error.payload,
    timestamp: Date.now()
  });

  // Show user-friendly message
  showError('An error occurred. Our team has been notified.');
});
```

***

### 5. Handle Network State

```javascript theme={null}
// ✓ Good
let isOnline = true;

oneSDKInstance.on('network_offline', () => {
  isOnline = false;
  showBanner('You are offline. Changes will be saved when connection is restored.');
  disableSubmitButton();
});

oneSDKInstance.on('network_online', () => {
  if (!isOnline) {
    isOnline = true;
    hideBanner();
    enableSubmitButton();
    retryPendingOperations();
  }
});
```

***

### 6. Validate Session Before Critical Operations

```javascript theme={null}
// ✓ Good
async function performVerification() {
  const expirationEpoch = sdk.session.getExpirationEpoch();
  const fiveMinutes = 5 * 60 * 1000;

  if (expirationEpoch && (expirationEpoch * 1000 - Date.now()) < fiveMinutes) {
    console.warn('Session expiring soon — request a new token from your backend');
    // There is no token refresh mechanism — must obtain new token from backend
    const newToken = await fetchNewTokenFromBackend();
    await reinitializeSDK(newToken);
  }

  // Proceed with verification
  const results = await individual.submit({ verify: true });
}
```

***

### 7. Ignore Telemetry Events in Production

Telemetry events (`telemetry`) are emitted internally by FrankieOne for diagnostic purposes. You do not need to listen to them in your application. Error handling should be done via the `error` event on each module, not via telemetry.

```javascript theme={null}
// ✗ Not needed in production
oneSDKInstance.on('telemetry', (event) => {
  console.log('Telemetry:', event); // Only useful for FrankieOne debugging
});
```

<Note>
  Before being included in `COMPONENT:INIT` / `COMPONENT:INIT:ERROR` (and other) telemetry events, sensitive values (tokens, API keys, secrets, `clientID`, etc.) are automatically redacted from the reported options and recipe data.
</Note>

***

## Provider Event Compatibility

Some events are provider-specific and will not fire when using a different provider. If your flow supports multiple providers, check the provider name before registering provider-specific event listeners.

| Event                       | Onfido | Sumsub | Incode | IDVerse | Daon |
| --------------------------- | ------ | ------ | ------ | ------- | ---- |
| `session_interrupted`       | ✓      | —      | —      | —       | —    |
| `detection_complete`        | ✓      | ✓      | ✓      | ✓       | ✓    |
| `vendor_event`              | ✓      | ✓      | ✓      | ✓       | ✓    |
| `vendor_sdk_loaded`         | ✓      | ✓      | ✓      | ✓       | ✓    |
| `vendor_sdk_failed_loading` | ✓      | ✓      | ✓      | ✓       | ✓    |

<Note>
  If you register a listener for `session_interrupted` while using Sumsub (or any non-Onfido provider), the handler will simply never fire. This is safe — it won't cause errors.
</Note>

***

## Document Selection

The Document Selection screen in the Form module is not deprecated and not tied to legacy flows. It is a standard part of the OCR and manual verification flows.

**Recommended patterns for document type selection:**

1. **Use OCR mode** — Specify document types in the `documents` array when creating the OCR component. The provider's built-in selector will guide the user.
2. **Hard code the document type** — If your flow requires a specific document type, specify it directly in configuration rather than letting the user choose.
3. **Use the provider's built-in selector** — Most IDV and OCR providers include their own document type selection UI.

***

## Vendor-Specific Errors

### Onfido

These errors are emitted via the `error` event when using Onfido as the IDV, OCR, or Biometrics provider. OneSDK surfaces these from Onfido's `onError` callback.

```javascript theme={null}
const idv = oneSdk.flow("idv");
idv.on('error', (error) => {
  console.error('Onfido error:', error);
});
```

| Error Code                | Description                                                | Recovery                                                                                                                           |
| ------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_token`           | The Onfido IDV token is invalid.                           | Re-generate the IDV token by remounting the component.                                                                             |
| `expired_token`           | The Onfido IDV token has expired.                          | Re-generate the IDV token by remounting the component.                                                                             |
| `expired_trial`           | The Onfido trial period has expired.                       | This is unexpected in production. Contact FrankieOne support if you encounter this error.                                          |
| `geoblocked_request`      | The request is not allowed from the user's location.       | The end-user may be in a geoblocked region. Ask them to disable any active VPN, or contact FrankieOne for details.                 |
| `permissions_unavailable` | Unable to retrieve or access required user permissions.    | This may occur when the SDK is loaded within a webview or custom browser that restricts permissions. Try using a standard browser. |
| `unsupported`             | A module is not supported in the current environment.      | Check the OneSDK documentation for environment requirements, or contact FrankieOne support.                                        |
| `unsupported_feature`     | The requested feature is no longer supported.              | Check the OneSDK documentation for current feature availability, or contact FrankieOne support.                                    |
| `invalid_sdk_parameter`   | The SDK was initialized with invalid parameters.           | Review your Onfido provider configuration and correct any invalid parameters.                                                      |
| `unsupported_sdk_version` | The workflow is not supported by the current SDK version.  | Verify that your configured `sdkVersion` (e.g., `"12"` or `"14"`) is compatible with your workflow.                                |
| `no_camera`               | No camera is available and no other capture method exists. | The user has not granted camera access or their device does not have a camera. Prompt the user to enable camera permissions.       |
| `user_consent_denied`     | The user declined the consent prompt.                      | The user must provide consent to proceed. Display a message explaining why consent is required and allow them to retry.            |

<Note>
  For Onfido provider configuration and customization options, see [Vendor Customizations](/docs/sdk-reference/vendor-customizations).
</Note>

***

## Related

* [API Error Codes](/docs/reference/error-codes) - Backend API error codes
* [Event System](/docs/sdk-reference/events) - Complete event reference
* [Individual Module](/docs/sdk-reference/individual-module) - KYC module documentation
* [IDV Module](/docs/sdk-reference/idv-module) - IDV module documentation
* [Form Module](/docs/sdk-reference/form-module) - Form module documentation


# Event System
Source: https://docs.frankieone.com/docs/sdk-reference/events

Complete reference for the OneSDK event system

## Overview

The OneSDK uses an event-driven architecture that allows you to listen for and respond to various events throughout the verification lifecycle. Every module and the SDK itself emit events that you can subscribe to.

## Event Methods

All modules and the SDK context provide these event methods:

### `on(eventName, callback)`

Registers an event listener for the specified event.

**Signature:**

```typescript theme={null}
on<EventName>(
  eventName: EventName | EventName[],
  callback: (...args: EventArguments) => void
): void
```

**Parameters:**

* `eventName`: String or array of strings representing event name(s)
* `callback`: Function to call when the event is emitted

**Example:**

```javascript theme={null}
// Single event
oneSDKInstance.on('error', (error) => {
  console.error('SDK error:', error);
});

// Multiple events
oneSDKInstance.on(['loading', 'info'], (data) => {
  console.log('Event received:', data);
});
```

***

### `off(eventName, callback)`

Removes a previously registered event listener.

**Signature:**

```typescript theme={null}
off<EventName>(
  eventName: EventName | EventName[],
  callback: (...args: EventArguments) => void
): void
```

**Parameters:**

* `eventName`: String or array of strings representing event name(s)
* `callback`: The exact function reference that was registered with `on()`

**Example:**

```javascript theme={null}
const errorHandler = (error) => {
  console.error('Error:', error);
};

// Register
oneSDKInstance.on('error', errorHandler);

// Later, remove
oneSDKInstance.off('error', errorHandler);
```

<Warning>
  Do not call `off()` without parameters on global event handlers. This removes ALL listeners and may break internal SDK functionality.
</Warning>

***

### `emit(eventName, ...args)`

Emits an event with optional arguments. Available only on the SDK context (not on module instances).

**Signature:**

```typescript theme={null}
emit<EventName>(
  eventName: EventName,
  ...args: EventArguments
): void
```

**Example:**

```javascript theme={null}
// Emit custom telemetry event
oneSDKInstance.emit('telemetry', {
  eventName: 'CUSTOM_EVENT',
  data: { action: 'button_clicked' }
});
```

***

## Global Events

These events are emitted by the SDK context and are available on all SDK instances.

### Common Events

Available on all modules and the SDK context:

| Event     | Arguments                                                         | Description                        |
| --------- | ----------------------------------------------------------------- | ---------------------------------- |
| `error`   | `(error: OneSDKError)`                                            | Emitted when an error occurs       |
| `warning` | `(warning: { message: string, payload?: unknown })`               | Emitted for non-critical warnings  |
| `info`    | `(info: { message?: string, payload?: unknown, name?: unknown })` | Emitted for informational messages |
| `loading` | `(isLoading: boolean, context: { message: string })`              | Emitted when loading state changes |
| `*`       | `(event: { eventName: string, arguments: unknown[] })`            | Wildcard - captures all events     |

### SDK-Specific Events

| Event                    | Arguments                                 | Description                                                                   |
| ------------------------ | ----------------------------------------- | ----------------------------------------------------------------------------- |
| `resolved_root_config`   | `(config: GlobalState)`                   | Emitted when root configuration is resolved                                   |
| `resolved_module_config` | `(state: InjectedState, config: unknown)` | Emitted when a module configuration is resolved                               |
| `telemetry`              | `(event: TelemetryEvent)`                 | Emitted for internal diagnostic data (used by FrankieOne for troubleshooting) |
| `network_offline`        | `()`                                      | Emitted when network connection is lost                                       |
| `network_online`         | `()`                                      | Emitted when network connection is restored                                   |

## Event Examples

### Handling Errors

```javascript theme={null}
oneSDKInstance.on('error', (error) => {
  console.error('SDK Error:', {
    message: error.message,
    code: error.code,
    details: error.details
  });

  // Show user-friendly message
  showErrorToUser('Verification error. Please try again.');
});
```

### Monitoring Loading States

```javascript theme={null}
oneSDKInstance.on('loading', (isLoading, context) => {
  if (isLoading) {
    showSpinner(context.message);
  } else {
    hideSpinner();
  }
});
```

### Telemetry Events

<Note>
  Telemetry events are used internally by FrankieOne for troubleshooting and diagnostic purposes. You generally don't need to listen to these events in your application.
</Note>

```javascript theme={null}
// For debugging purposes only
oneSDKInstance.on('telemetry', (event) => {
  if (typeof event === 'string') {
    console.log('Telemetry event:', event);
  } else {
    console.log('Telemetry event:', event.eventName, event.data);
  }
});
```

### Network Status Monitoring

```javascript theme={null}
let isOnline = true;

oneSDKInstance.on('network_offline', () => {
  isOnline = false;
  showBanner('You are offline. Verification will resume when connection is restored.');
});

oneSDKInstance.on('network_online', () => {
  if (!isOnline) {
    isOnline = true;
    showBanner('Connection restored. Resuming verification...');
  }
});
```

### Configuration Events

```javascript theme={null}
oneSDKInstance.on('resolved_root_config', (config) => {
  console.log('SDK configured with:', {
    mode: config.mode,
    recipe: config.recipe,
    session: config.session
  });
});
```

### Wildcard Event Listener

Capture all events for debugging:

```javascript theme={null}
oneSDKInstance.on('*', (event) => {
  console.log('Event emitted:', event.eventName, event.arguments);
});
```

## Module Events

Each module has its own set of events. Subscribe to module events through the module instance:

### Individual Module Events

```javascript theme={null}
const individual = oneSDKInstance.individual();

individual.on('data_loaded', () => {
  console.log('Individual data loaded');
});

individual.on('results', (results) => {
  console.log('Verification results:', results);
});

individual.on('detection_complete', (data) => {
  console.log('Detection complete:', data);
});
```

### Component Events

Dynamic components also emit events:

```javascript theme={null}
const documentComponent = oneSDKInstance.component('document', {
  countries: ['AUS', 'NZL']
});

documentComponent.on('results', (results) => {
  console.log('Document capture results:', results);
});

documentComponent.on('ready', () => {
  console.log('Document component ready');
  documentComponent.mount('#document-container');
});
```

## Event Patterns

### Async Event Handling

```javascript theme={null}
individual.on('results', async (results) => {
  try {
    // Send results to backend
    await sendToBackend(results);

    // Continue to next step
    startNextVerificationStep();
  } catch (error) {
    console.error('Failed to process results:', error);
  }
});
```

### Event Cleanup

Always clean up event listeners when components unmount:

```javascript theme={null}
// React example
useEffect(() => {
  const handleError = (error) => {
    console.error(error);
  };

  oneSDKInstance.on('error', handleError);

  // Cleanup on unmount
  return () => {
    oneSDKInstance.off('error', handleError);
  };
}, []);
```

### Event Chaining

Chain events to create verification flows:

```javascript theme={null}
const individual = oneSDKInstance.individual();

// Step 1: Wait for data to load
individual.on('data_loaded', () => {
  console.log('Step 1: Data loaded');

  // Step 2: Submit data
  individual.submit();
});

// Step 3: Handle results
individual.on('results', (results) => {
  console.log('Step 2: Results received');

  if (results.status.type === 'passed') {
    navigateToSuccess();
  } else {
    showErrorScreen(results);
  }
});
```

## Error Event Details

The `error` event provides a structured error object:

```typescript theme={null}
class OneSDKError<Payload = unknown> extends Error {
  readonly message: string;
  readonly name: string;
  readonly payload: Payload;
}
```

**Properties:**

* `message` - Human-readable error description
* `name` - Error type identifier (optional)
* `payload` - Additional error context (type varies by error)

### Error Handling Example

```javascript theme={null}
oneSDKInstance.on('error', (error) => {
  console.error('SDK Error:', {
    message: error.message,
    name: error.name,
    payload: error.payload
  });

  // Handle errors based on name and message patterns
  if (error.name === 'NetworkError') {
    showRetryButton();
  } else if (error.message.includes('token')) {
    redirectToLogin();
  } else {
    showGenericError(error.message);
  }
});
```

## Telemetry Event Structure

Telemetry events can be either a simple string or an object:

```typescript theme={null}
type TelemetryEvent =
  | string
  | {
      eventName: string;
      data?: Record<string, unknown>;
      error?: Error;
    };
```

### Telemetry Event Details

<Warning>
  Telemetry events are used internally by FrankieOne for diagnostic and troubleshooting purposes. These events are not intended for use in your application logic or analytics.
</Warning>

```javascript theme={null}
// For debugging purposes only - not recommended for production use
oneSDKInstance.on('telemetry', (event) => {
  console.log('Internal diagnostic event:', event);
});
```

## Best Practices

1. **Always handle errors**: Subscribe to the `error` event on all modules and the SDK context.

2. **Clean up listeners**: Remove event listeners when components unmount to prevent memory leaks.

3. **Use specific events**: Subscribe to specific events rather than relying on the wildcard (`*`) event.

4. **Avoid inline functions with `off`**: Store function references if you need to remove them later.

5. **Don't block event handlers**: Keep event handler logic lightweight. Use async handlers for heavy operations.

6. **Monitor network events**: Handle offline scenarios gracefully by listening to network events.

7. **Log telemetry in production**: Use telemetry events to monitor SDK behavior in production.

## Debugging Events

### Log All Events

```javascript theme={null}
if (process.env.NODE_ENV === 'development') {
  oneSDKInstance.on('*', (event) => {
    console.debug('[OneSDK Event]', event.eventName, event.arguments);
  });
}
```

### Event Timeline

```javascript theme={null}
const eventLog = [];

oneSDKInstance.on('*', (event) => {
  eventLog.push({
    timestamp: Date.now(),
    name: event.eventName,
    args: event.arguments
  });
});

// Later, inspect the timeline
console.table(eventLog);
```

## Related

* [SDK Initialization](/sdk-reference/sdk-initialization)
* [Error Handling](/sdk-reference/error-handling)
* [Individual Module](/sdk-reference/individual-module)
* [Component System](/sdk-reference/components)


# Form Module
Source: https://docs.frankieone.com/docs/sdk-reference/form-module

Pre-built eKYC form UI for identity verification

## Overview

The Form module provides a complete pre-built eKYC form UI that guides users through the identity verification process. It handles the full flow from welcome screen through document selection, data entry, review, submission, and results - all with a single component.

The form module supports three configuration types:

* **OCR** - Document capture with automatic data extraction
* **Manual** - Manual data entry by the user
* **Doc Upload** - Document file upload for verification

## Accessing the Module

The Form module is accessed through the SDK's component factory using the React provider:

```javascript theme={null}
const sdk = await OneSdk({
  mode: 'production',
  session: { token: 'your-token' }
});

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

## Configuration

### Module Options

Options are passed during module initialization:

| Option | Type                                | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------ | ----------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `ReactFormIdsKeys`                  | Yes      | The screen to start on. See [Screens](/docs/sdk-reference/form-module/screens).                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `mode` | `'individual'`                      | No       | Verification mode. Defaults to `'individual'` for personal KYC.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `type` | `'ocr' \| 'manual' \| 'doc_upload'` | No       | Configuration type. Determines the verification flow pattern. Primarily affects the [Document Selection](/docs/sdk-reference/form-module/screens#document-selection), [Personal Details](/docs/sdk-reference/form-module/screens#personal-details), [Review](/docs/sdk-reference/form-module/screens#review), and [Retry](/docs/sdk-reference/form-module/screens#retry) screens. Static screens (Welcome, Consent, Start) and progress screens (Loading, Result) are not affected. Doc upload screens are only shown when `type` is `'doc_upload'`. |

The module options also accept page-level configuration overrides. See [Configuration](/docs/sdk-reference/form-module/configuration) for all available customization options.

### Recipe Configuration

The Form module requires provider configuration in your recipe. Form configuration (screens, type, styling) is set through module options when calling `sdk.component('form', options)`, not in the recipe.

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

### Recipe Options

| Property                                   | Type      | Required | Description                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------ | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider.name`                            | `'react'` | Yes      | Must be `'react'` for the React form provider.                                                                                                                                                                                                                                                                                                    |
| `provider.googleApiKey`                    | `string`  | No       | Google API key that enables address autocomplete on `address` field types. Google Maps is optional — when no key is provided, users enter their address manually. The key must have **Geocoding API** and **Places API (New)** authorized. See [Google Maps setup](#google-maps-address-autocomplete) for GCP configuration steps.                |
| `provider.useGoogleAutoCompleteSuggestion` | `boolean` | No       | **Set to `true` for all integrations.** Switches from the deprecated `AutocompleteService` to the newer `AutocompleteSuggestion` API. The deprecated path causes address search failures (`REQUEST_DENIED`) on API keys that restrict by service. Requires `@frankieone/one-sdk` **v1.8.2 or later** and **Places API (New)** enabled on the key. |
| `docUpload`                                | `object`  | No       | Document upload configuration. See [Document Upload Configuration](/docs/sdk-reference/form-module/configuration#document-upload-configuration).                                                                                                                                                                                                  |

### Google Maps Address Autocomplete

<Warning>
  **Action required for all integrations using address search.** Google's Geocoding API now returns `REQUEST_DENIED` for keys that do not have it explicitly authorized. Address search will silently fail until the key is updated. Follow the steps below.
</Warning>

Address autocomplete requires two APIs enabled on your Google Cloud API key:

| API                  | Why it's needed                                                                                                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Geocoding API**    | Resolves a selected suggestion into structured address components. Required by both the old and new autocomplete paths — address search fails with `REQUEST_DENIED` without it. |
| **Places API (New)** | Powers the `AutocompleteSuggestion` lookup when `useGoogleAutoCompleteSuggestion` is `true`.                                                                                    |

#### GCP setup steps

1. Open [Google Cloud Console → APIs & Services → Library](https://console.cloud.google.com/apis/library).
2. Search for and enable **Geocoding API**.
3. Search for and enable **Places API (New)**.
4. Go to **APIs & Services → Credentials** and open your API key.
5. Under **API restrictions → Restrict key**, add both **Geocoding API** and **Places API (New)** to the allowed list.
6. Save.

#### Script tag

Load the Maps JavaScript API **before** initializing OneSdk:

```html theme={null}
<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_KEY&loading=async&libraries=places"></script>
```

#### OneSDK recipe configuration

```javascript theme={null}
const sdk = await OneSdk({
  session: { token: 'your-token' },
  recipe: {
    form: {
      provider: {
        name: 'react',
        googleApiKey: 'YOUR_GOOGLE_API_KEY',
        useGoogleAutoCompleteSuggestion: true
      }
    }
  }
});
```

<Note>
  `useGoogleAutoCompleteSuggestion` requires `@frankieone/one-sdk` **v1.8.2 or later**. Run `npm install @frankieone/one-sdk@latest` to upgrade.
</Note>

***

## Methods

### `mount()`

Mounts the Form component to a DOM element.

**Signature:**

```typescript theme={null}
mount(mountElement: string | HTMLElement): Promise<WrapperContext>
```

**Parameters:**

| Parameter      | Type                    | Required | Description                                                                                          |
| -------------- | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `mountElement` | `string \| HTMLElement` | Yes      | CSS selector string (e.g., `'#form-container'`) or HTMLElement object where the form will be mounted |

**Returns:** `Promise<WrapperContext>` - Resolves when the form is mounted. The `WrapperContext` contains a `cleanup()` method.

**Example:**

```javascript theme={null}
// Mount to element by ID
await formComponent.mount('#form-container');

// Mount to element reference
const container = document.getElementById('form-container');
await formComponent.mount(container);
```

***

### `unmount()`

Unmounts the Form component from the DOM.

**Signature:**

```typescript theme={null}
unmount(): void
```

<Warning>
  `unmount()` clears **all content** from the element the component was mounted to — not just the component itself. If another component (e.g., an IDV flow) is sharing the same container, unmounting will destroy its content too. When you need to show a loading screen alongside another component, mount the loading screen to a **separate element** so that unmounting it does not affect the other component. See the [IDV with Review flow](/docs/embedded-flows/idv-review#loading-screens) for an example.
</Warning>

**Example:**

```javascript theme={null}
formComponent.unmount();
```

***

### `provider`

Read-only property indicating the current vendor.

**Type:** `'react'`

```javascript theme={null}
console.log(formComponent.provider); // 'react'
```

***

## Events

The Form module uses a structured event system with two levels:

### Global Events

These events apply to the form module as a whole:

| Event        | Parameters                           | Description                                                                                     |
| ------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `ready`      | `{ domElement, config }`             | Form component is ready. Contains the mount element and resolved configuration.                 |
| `loaded`     | `{ domElement, provider }`           | Form component is loaded and rendered.                                                          |
| `results`    | `{ documents, applicant, entityId }` | Verification results received. Contains the submitted documents, applicant data, and entity ID. |
| `navigation` | `{ page }`                           | User navigated to a different screen. Contains the screen name.                                 |
| `destroy`    | (none)                               | Form component is being destroyed/unmounted.                                                    |

**Example:**

```javascript theme={null}
formComponent.on('ready', ({ domElement, config }) => {
  console.log('Form ready with config:', config);
});

formComponent.on('results', ({ documents, applicant, entityId }) => {
  console.log('Verification complete for:', entityId);
  console.log('Documents:', documents);
  console.log('Applicant:', applicant);
});

formComponent.on('navigation', ({ page }) => {
  console.log('User navigated to:', page);
});
```

### Screen Events

Each screen emits events following the pattern `form:{screen}:{stage}`. See [Screens](/docs/sdk-reference/form-module/screens) for the complete screen event reference.

**Event Pattern:**

```
form:welcome:ready
form:welcome:loaded
form:welcome:failed
form:consent:ready
form:review:success
form:result:pending
...
```

**Event Stages:**

| Stage      | Description                                                                                                                                                                              |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ready`    | User pressed the screen's CTA (call-to-action) button, completing the screen                                                                                                             |
| `loaded`   | Screen has been rendered                                                                                                                                                                 |
| `failed`   | Screen failed to load (except result — see [Result screen events](/docs/sdk-reference/form-module/screens#result))                                                                       |
| `success`  | CTA pressed on a SUCCESS-state result screen, or verification succeeded (review with [`customResult`](/docs/sdk-reference/form-module/configuration#page-configuration-types) only)      |
| `partial`  | CTA pressed on a PARTIAL-state result screen, or partial verification result (review with [`customResult`](/docs/sdk-reference/form-module/configuration#page-configuration-types) only) |
| `pending`  | CTA pressed on a PENDING-state result screen, or verification pending (review with [`customResult`](/docs/sdk-reference/form-module/configuration#page-configuration-types) only)        |
| `timeout`  | CTA pressed on a TIMEOUT-state result screen (result only)                                                                                                                               |
| `info`     | Non-fatal, informational screen event (result only) — currently emitted when a custom `resultImage` fails to load, before falling back to the default state icon                         |
| `back`     | User navigated back (document only)                                                                                                                                                      |
| `navigate` | User navigated to another screen (document, doc\_upload only)                                                                                                                            |

<Warning>
  **`form:review:*` events require `customResult: true`**

  The `form:review:success`, `form:review:failed`, `form:review:partial`, and `form:review:pending` events are **only emitted when `customResult: true` is set in manual mode**. When `customResult` is `false` (the default), the form automatically navigates to and displays the configured result screen without emitting these events.

  In OCR mode, the only terminal event is `ready` on the final screen.
</Warning>

**Event Payload:**

All screen events emit an `EventPayload`:

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

***

## Complete Example

```javascript theme={null}
import OneSdk from '@frankieone/one-sdk';

async function startVerificationForm() {
  // Initialize SDK
  const sdk = await OneSdk({
    mode: 'production',
    session: { token: await getSessionToken() },
    recipe: {
      form: {
        provider: {
          name: 'react',
          googleApiKey: 'your-google-api-key',
          useGoogleAutoCompleteSuggestion: true
        }
      }
    }
  });

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

  // Global events
  formComponent.on('ready', ({ domElement, config }) => {
    console.log('Form ready');
  });

  formComponent.on('loaded', ({ domElement, provider }) => {
    console.log('Form loaded with provider:', provider);
  });

  // Track navigation
  formComponent.on('navigation', ({ page }) => {
    console.log('Current screen:', page);
    updateProgressBar(page);
  });

  // Screen-level events
  formComponent.on('form:welcome:loaded', (payload) => {
    console.log('Welcome screen displayed');
  });

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

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

  formComponent.on('form:review:ready', (payload) => {
    console.log('User pressed CTA on review screen');
  });

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

  formComponent.on('form:review:partial', (payload) => {
    console.log('Partial match — handle custom result');
  });

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

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

  // Final results
  formComponent.on('results', ({ documents, applicant, entityId }) => {
    console.log('Verification complete');
    console.log('Entity:', entityId);
    handleVerificationResult({ documents, applicant, entityId });
  });

  // Mount the form
  await formComponent.mount('#form-container');
}
```

***

## Best Practices

1. **Set up event listeners before mounting** - Register all event handlers before calling `mount()` to avoid missing early events like `ready` and `loaded`.

2. **Handle all result screen CTA events** - Listen for `form:result:success`, `form:result:partial`, `form:result:pending`, and `form:result:failed` to detect when the user dismisses a result screen. If using `customResult: true` on the review component, also handle the corresponding `form:review:*` events.

3. **Use the `navigation` event for progress tracking** - The global `navigation` event fires on every screen change, making it ideal for progress bars, analytics, and conditional UI outside the form.

4. **Configure `type` to match your flow** - Choose `'ocr'`, `'manual'`, or `'doc_upload'` based on your integration. The type determines which screens are shown and how data is collected. See [Configuration Types](/docs/sdk-reference/form-module/configuration#configuration-types).

5. **Customize screens via page config, not DOM manipulation** - Use the [page configuration](/docs/sdk-reference/form-module/configuration#page-configuration-types) and [CSS class keys](/docs/sdk-reference/form-module/configuration#css-styling) to customize appearance and content rather than manipulating the DOM directly.

***

## Common Issues

### Component not displaying

Ensure the mount element exists in the DOM before calling `mount()` and has sufficient size:

```css theme={null}
#form-container {
  width: 100%;
  min-height: 600px;
}
```

### Google address autocomplete not working

**Symptoms** — one or both of these appear in the browser console:

```
Geocoding Service: This API key is not authorized to use this service or API. Status: REQUEST_DENIED
```

```
google.maps.places.AutocompleteService is not available to new customers. Please use google.maps.places.AutocompleteSuggestion instead.
```

**Root causes:**

* `REQUEST_DENIED` — the API key does not have the **Geocoding API** authorized. Both the old and new autocomplete paths call the Geocoding API after retrieving suggestions; without it, address search returns nothing.
* `AutocompleteService` warning — `useGoogleAutoCompleteSuggestion` is not set to `true`. The deprecated `AutocompleteService` is unavailable on keys created after March 1, 2025 and will eventually be removed for all customers.

**Fix:**

1. In Google Cloud Console, enable **Geocoding API** and **Places API (New)** on the key and add both to the key's API restrictions allow-list. See [Google Maps setup](#google-maps-address-autocomplete).
2. Set `useGoogleAutoCompleteSuggestion: true` in the recipe's `form.provider` config.
3. Ensure `@frankieone/one-sdk` is **v1.8.2 or later** — upgrade with `npm install @frankieone/one-sdk@latest` if needed.

### Form fields not matching expected document type

The fields shown on the Review and Personal Details screens depend on the `type` option and the document type selected. Ensure your [form field configuration](/docs/sdk-reference/form-module/configuration#form-fields) and [country-specific settings](/docs/sdk-reference/form-module/configuration#country-specific-field-configuration) match the document types available in your flow.

***

## Sub-Pages

<CardGroup>
  <Card title="Screens" icon="rectangle-list" href="/sdk-reference/form-module/screens">
    All 13 form screens, their events, and behavior
  </Card>

  <Card title="Configuration" icon="sliders" href="/sdk-reference/form-module/configuration">
    Page customization, CSS styling, document upload, and form fields
  </Card>
</CardGroup>

***

## Related

* [SDK Initialization](/docs/sdk-reference/sdk-initialization)
* [Individual Module](/docs/sdk-reference/individual-module)
* [OCR Module](/docs/sdk-reference/ocr-module)
* [IDV Module](/docs/sdk-reference/idv-module)
* [Event System](/docs/sdk-reference/events)


# Form Configuration
Source: https://docs.frankieone.com/docs/sdk-reference/form-module/configuration

Page customization, CSS styling, form fields, and document upload configuration

## Overview

The Form module's React provider supports extensive customization of each screen's content, styling, and behavior. Configuration is passed as module options when creating the form component.

## ReactFormConfig

The main configuration type for the React form provider:

```typescript theme={null}
type ReactFormConfig = {
  name: ReactFormIdsKeys;
  mode?: 'individual';
  type?: 'ocr' | 'manual' | 'doc_upload';
} & TPageConfig;
```

| Property | Type                                | Required | Description                                                                                                                                                                                                                                            |
| -------- | ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`   | `ReactFormIdsKeys`                  | Yes      | The starting screen. One of: `'WELCOME'`, `'CONSENT'`, `'DOCUMENT'`, `'REVIEW'`, `'PERSONAL'`, `'LOADING'`, `'RESULT'`, `'RETRY'`, `'DOC_UPLOAD'`, `'START'`, `'REQUIRED_DOCUMENT_UPLOAD'`, `'PARTIAL_DOCUMENT_UPLOAD'`, `'OPTIONAL_DOCUMENT_UPLOAD'`. |
| `mode`   | `'individual'`                      | No       | Verification mode. Defaults to `'individual'` for personal KYC.                                                                                                                                                                                        |
| `type`   | `'ocr' \| 'manual' \| 'doc_upload'` | No       | The verification flow type. `'ocr'` for document capture with auto-extraction, `'manual'` for manual data entry, `'doc_upload'` for file uploads. See [Configuration Types](#configuration-types) for details on which screens are affected.           |

Additional page-level properties from [TPageConfig](#page-configuration-types) can be included to customize individual screens.

***

## Configuration Types

The `type` option determines the overall verification flow and primarily affects the **Document Selection**, **Personal Details**, **Review**, and **Retry** screens. Static screens (Welcome, Consent, Start) and progress screens (Loading, Result) are not affected by `type`. Doc upload screens are only shown when `type` is `'doc_upload'`.

### OCR Type

Used to display and review data that was automatically extracted by the [IDV](/docs/sdk-reference/idv-module) or [OCR](/docs/sdk-reference/ocr-module) modules. In a typical OCR flow, the IDV flow handles document capture, and the form module is used to present the extracted data on the Review screen for user confirmation.

**Screens affected:**

* **Review** - Displays OCR-extracted data for user review and submission
* **Document Selection** - Shows document type selection. Useful for specifying document type before mounting the OCR module. Unlike manual mode, OCR mode does not show manual input fields after selection.

```javascript theme={null}
// OCR capture is handled by the IDV flow
const idv = sdk.flow('idv');

// The form module is used for the review screen
const review = sdk.component('form', {
  name: 'REVIEW',
  mode: 'individual',
  type: 'ocr'
});
```

### Manual Type

For manual data entry flows. Users select their document type and manually enter their details.

**Screens affected:**

* **Document Selection** - Shows `numberOfIDs` and document options with `cta` button. After selection, displays manual input fields for the selected document.
* **Personal Details** - Shown for manual data entry with [country-specific field configurations](#country-specific-field-configuration)
* **Review** - Displays manually entered data with `verify`, `hiddenForms`, and `readOnlyForms` options
* **Retry** - Allows re-entry of data that failed verification

```javascript theme={null}
const welcome = sdk.component('form', {
  name: 'WELCOME',
  mode: 'individual',
  type: 'manual'
});
```

### Doc Upload Type

For supporting document file upload flows. Requires [document upload configuration](#document-upload-configuration) in the recipe.

**Screens affected:**

* **Required/Partial/Optional Document Upload** - These screens are only shown in this type
* **Review** - Displays document upload summary
* **Personal Details** - Not shown

```javascript theme={null}
const welcome = sdk.component('form', {
  name: 'WELCOME',
  mode: 'individual',
  type: 'doc_upload'
});
```

***

## Page Configuration Types

The Form module uses four page configuration types depending on the screen:

### IStaticPageConfig

Used by: Welcome, Consent, Start, Document Upload screens

```typescript theme={null}
type IStaticPageConfig = IBasicInfo & {
  cta?: ActionContent;
  instructions?: ListInfo;      // Instruction items
  checkbox?: Content;           // Consent checkbox content
  additionalInstructions?: ListInfo;
}
```

| Property                 | Type                              | Description                                       |
| ------------------------ | --------------------------------- | ------------------------------------------------- |
| `cta`                    | [`ActionContent`](#actioncontent) | Call-to-action button configuration               |
| `instructions`           | [`ListInfo`](#listinfo)           | List of instruction items displayed on the screen |
| `checkbox`               | [`Content`](#content-object)      | Consent checkbox content (used on Consent screen) |
| `additionalInstructions` | [`ListInfo`](#listinfo)           | Additional instruction items                      |

### IIdCardPageConfig

Used by: Document Selection (manual, ocr, and doc\_upload modes), Retry screens

<Note>
  **OCR mode vs Manual mode:** In OCR mode, Document Selection shows only the document type picker, useful for specifying the document type before mounting the OCR module. In manual mode, Document Selection shows the document type picker followed by manual input fields for the selected document.
</Note>

```typescript theme={null}
type IIdCardPageConfig = IBasicInfo & {
  type: 'ocr' | 'manual' | 'doc_upload';
  showPreps?: boolean;          // Show document preparation tips
  documents: IDocuments[];      // Available document types
  numberOfIDs?: number;         // Required IDs (manual mode)
  cta?: ActionContent;          // Action button (manual mode)
}
```

| Property      | Type                                | Description                                                                                                                   |
| ------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `type`        | `'ocr' \| 'manual' \| 'doc_upload'` | Required. Determines the document selection behavior. See [Configuration Types](#configuration-types).                        |
| `showPreps`   | `boolean`                           | Show document preparation tips before capture                                                                                 |
| `documents`   | [`IDocuments[]`](#idocuments)       | Available document types for selection. Each entry configures a document type with optional country-specific field overrides. |
| `numberOfIDs` | `number`                            | Number of required identity documents (manual mode only)                                                                      |
| `cta`         | [`ActionContent`](#actioncontent)   | Action button (manual mode only)                                                                                              |

### IProgressPageConfig

Used by: Loading, Result screens

```typescript theme={null}
type IProgressPageConfig = {
  name: string;
  title?: Content;
  descriptions?: Content[];
  style?: Styles;
  logo?: { src: string };
  icon?: string;
  spinnerSrc?: string;
  state?: keyof RESULT_STATE;                // Result only
  creditHeaderIssueTitle?: { label, style }; // Result only
  creditHeaderIssueDescriptions?: { label }[]; // Result only
  cta?: ActionContent;                       // Result only
  resultImage?: {                            // Result only
    src: string;
    width?: string | number;
    height?: string | number;
  };
}
```

| Property                        | Type                               | Description                                                                                                                                                                                                                                                                                           |
| ------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                          | `string`                           | Screen identifier                                                                                                                                                                                                                                                                                     |
| `title`                         | [`Content`](#content-object)       | Screen title                                                                                                                                                                                                                                                                                          |
| `descriptions`                  | [`Content[]`](#content-object)     | Description items                                                                                                                                                                                                                                                                                     |
| `style`                         | `Styles`                           | Custom [CSS styles](#css-styling)                                                                                                                                                                                                                                                                     |
| `logo`                          | `{ src: string }`                  | Logo image URL                                                                                                                                                                                                                                                                                        |
| `icon`                          | `string`                           | Icon to display                                                                                                                                                                                                                                                                                       |
| `spinnerSrc`                    | `string`                           | Custom image URL shown in place of the built-in animated spinner while the Loading screen (or a stateless Result/Loading render) is active. Ignored once a `state` is set, since the per-state icon (or `resultImage`) takes priority.                                                                |
| `state`                         | `keyof RESULT_STATE`               | Result screen state. One of: `'SUCCESS'`, `'FAIL'`, `'PENDING'`, `'PARTIAL'`, `'UPLOAD_SUCCESS'`, `'UPLOAD_FAIL'`, `'PROVIDER_ERROR'`, `'TIMEOUT'`. Result screen only.                                                                                                                               |
| `creditHeaderIssueTitle`        | `{ label, style }`                 | Credit issue header title. Result screen only.                                                                                                                                                                                                                                                        |
| `creditHeaderIssueDescriptions` | `{ label }[]`                      | Credit issue descriptions. Result screen only.                                                                                                                                                                                                                                                        |
| `cta`                           | [`ActionContent`](#actioncontent)  | Call-to-action button. Result screen only.                                                                                                                                                                                                                                                            |
| `resultImage`                   | `{ src: string, width?, height? }` | Custom image shown instead of the built-in per-state icon on the Result screen. Supplements (does not replace) `icon`/`state` — if the image fails to load, the screen automatically falls back to the default icon for the current `state` and emits a `form:result:info` event. Result screen only. |

### IFormPageConfig

Used by: Review, Personal Details, Retry screens

```typescript theme={null}
type IFormPageConfig = {
  name: string;
  title: Content;
  style?: Styles;
  logo?: { src: string };
  cta?: ActionContent;
  descriptions?: Content[];
  type?: 'ocr' | 'manual' | 'doc_upload';
  // Document fields (Review, Retry) — one entry per document type
  documents?: {
    type: DocumentTypes;
    countries?: CountryConfig;
    documentSourceLabel?: string;
  }[];
  // Personal detail fields (Personal, Retry)
  personal?: {
    countries?: CountryConfig;
  };
  // Manual mode options (Review)
  verify?: boolean;
  customResult?: boolean;
  hiddenForms?: string[];
  readOnlyForms?: string[];
}
```

| Property        | Type                                                                                                                              | Description                                                                                                                                                                                                                                      |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`          | `string`                                                                                                                          | Screen identifier                                                                                                                                                                                                                                |
| `title`         | [`Content`](#content-object)                                                                                                      | Screen title (required)                                                                                                                                                                                                                          |
| `style`         | `Styles`                                                                                                                          | Custom [CSS styles](#css-styling)                                                                                                                                                                                                                |
| `logo`          | `{ src: string }`                                                                                                                 | Logo image URL                                                                                                                                                                                                                                   |
| `cta`           | [`ActionContent`](#actioncontent)                                                                                                 | Call-to-action button                                                                                                                                                                                                                            |
| `descriptions`  | [`Content[]`](#content-object)                                                                                                    | Description items                                                                                                                                                                                                                                |
| `type`          | `'ocr' \| 'manual' \| 'doc_upload'`                                                                                               | Verification flow type. See [Configuration Types](#configuration-types).                                                                                                                                                                         |
| `documents`     | `{ type: DocumentTypes, countries?: `[`CountryConfig`](#country-specific-field-configuration)`, documentSourceLabel?: string }[]` | Per-document-type field configuration. Used on Review and Retry screens. `documentSourceLabel` labels each document's section when the Review screen shows more than one scanned document — see [Multi-Document Review](#multi-document-review). |
| `personal`      | `{ countries?: `[`CountryConfig`](#country-specific-field-configuration)` }`                                                      | Personal detail form fields, configured per country/state. Used on Personal Details and Retry screens. Not affected by configuration type.                                                                                                       |
| `verify`        | `boolean`                                                                                                                         | Enable verification on submit. Manual mode Review screen only.                                                                                                                                                                                   |
| `customResult`  | `boolean`                                                                                                                         | Use custom result handling. Manual mode Review screen only.                                                                                                                                                                                      |
| `hiddenForms`   | `string[]`                                                                                                                        | Form section names to hide. Review screen only.                                                                                                                                                                                                  |
| `readOnlyForms` | `string[]`                                                                                                                        | Form section names to make read-only. Review screen only.                                                                                                                                                                                        |

### Multi-Document Review

When more than one document was scanned during the OCR/IDV capture flow (for example, a passport and a driver's licence submitted for the same applicant), the Review screen renders one review section per scanned document instead of a single combined section. If only one document was scanned, the Review screen falls back to the original single-section behavior.

* **Section heading** — each section's heading is controlled by `documentSourceLabel` on the matching entry in `documents` (matched by `type`). If not set, built-in default labels are used for `PASSPORT` (`'From your passport'`) and `DRIVERS_LICENCE` (`"From your driver's licence"`); other document types have no default label unless you set one.
* **Section order** — sections are ordered with the **primary document** first. The primary document is determined by the individual's `extraData.idv_primary_document` value (set during the IDV flow), matched against each scanned document's type. Ordering is a no-op when only one document was scanned or when `idv_primary_document` is not set.

```javascript theme={null}
const review = sdk.component('form', {
  name: 'REVIEW',
  type: 'ocr',
  documents: [
    { type: 'PASSPORT', documentSourceLabel: 'From your passport' },
    { type: 'DRIVERS_LICENCE', documentSourceLabel: "From your driver's licence" }
  ]
});
```

***

## Content Customization

### Content Object

Most text elements use the `Content` type for customization:

```typescript theme={null}
type Content = {
  icon?: string | ReactComponent | null;
  label?: string;
  shortLabel?: string;
  subText?: string;
  labelDescriptions?: string[];
  style?: Styles;
  hidden?: boolean;
  image?: string;   // For document types only
}
```

| Property            | Type                               | Description                                                                                                                                                                                                                                                             |
| ------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `icon`              | `string \| ReactComponent \| null` | Icon to display. Can be a string (icon name/URL) or React component.                                                                                                                                                                                                    |
| `label`             | `string`                           | Primary text content                                                                                                                                                                                                                                                    |
| `shortLabel`        | `string`                           | Shortened version of the label                                                                                                                                                                                                                                          |
| `subText`           | `string`                           | Secondary text displayed below the label. Used for per-item subtext (e.g. document list rows), not the Review screen's page heading — see `labelDescriptions` below.                                                                                                    |
| `labelDescriptions` | `string[]`                         | Array of description lines rendered under the screen's title/heading, one paragraph per string. Currently only wired up on the Review screen's `title` (`config.title.labelDescriptions`), where it replaces a single `subText` string with support for multiple lines. |
| `style`             | `Styles`                           | Custom CSS styles                                                                                                                                                                                                                                                       |
| `hidden`            | `boolean`                          | Whether to hide this content element                                                                                                                                                                                                                                    |
| `image`             | `string`                           | Image URL (available for document type content)                                                                                                                                                                                                                         |

### IBasicInfo

Base configuration shared by all static and card-based screens:

```typescript theme={null}
type IBasicInfo = {
  name: string;
  mode?: 'individual';
  logo?: { src: string };
  title?: Content;
  subtitle?: Content;
  descriptions?: Content[];
  style?: Styles;
  type?: 'ocr' | 'manual' | 'doc_upload';
  // Font configuration
  name?: string;   // Font family name
  url?: string;    // Font URL
}
```

| Property       | Type                                | Description                                                              |
| -------------- | ----------------------------------- | ------------------------------------------------------------------------ |
| `name`         | `string`                            | Screen identifier                                                        |
| `mode`         | `'individual'`                      | Verification mode. Defaults to `'individual'`.                           |
| `logo`         | `{ src: string }`                   | Logo image URL                                                           |
| `title`        | [`Content`](#content-object)        | Screen title                                                             |
| `subtitle`     | [`Content`](#content-object)        | Screen subtitle                                                          |
| `descriptions` | [`Content[]`](#content-object)      | Description items                                                        |
| `style`        | `Styles`                            | Custom [CSS styles](#css-styling)                                        |
| `type`         | `'ocr' \| 'manual' \| 'doc_upload'` | Verification flow type. See [Configuration Types](#configuration-types). |
| `name` (font)  | `string`                            | Font family name (within font configuration)                             |
| `url` (font)   | `string`                            | Font URL (within font configuration)                                     |

### ActionContent

Used for buttons and call-to-action elements:

```typescript theme={null}
type ActionContent = Content & {
  onClick?: () => void;
  timeoutRetryMiliseconds?: number;
  retryAmount?: number;
  retryAttemptString?: string;
  maxRetryAttemptedString?: string;
  inline?: boolean;
}
```

| Property                  | Type         | Description                                                                                                                                                                                              |
| ------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onClick`                 | `() => void` | Click handler for the action                                                                                                                                                                             |
| `timeoutRetryMiliseconds` | `number`     | Timeout before retry is enabled                                                                                                                                                                          |
| `retryAmount`             | `number`     | Number of retry attempts allowed                                                                                                                                                                         |
| `retryAttemptString`      | `string`     | Text shown during retry countdown                                                                                                                                                                        |
| `maxRetryAttemptedString` | `string`     | Text shown when max retries reached                                                                                                                                                                      |
| `inline`                  | `boolean`    | Default: `false`. Result screen only. When `true`, the CTA button renders inline within the result content (below the title/descriptions) instead of the sticky button pinned to the bottom of the page. |

### ListInfo

Used for instruction lists on static screens:

```typescript theme={null}
type ListInfo = Content[];
```

An array of [`Content`](#content-object) objects. Each item represents an instruction or list entry, rendered with the `ff-instruction-item` and `ff-instruction-icon` CSS classes.

### IDocuments

Configures a document type available for selection on the [Document Selection](#iidcardpageconfig) screen, with optional country and state-specific field overrides.

```typescript theme={null}
type IDocuments = {
  type: string;
  countries?: CountryConfig;
}
```

| Property    | Type                                                     | Description                                                                                                                                            |
| ----------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`      | `string`                                                 | Document type identifier. Supported values include `'DRIVERS_LICENCE'`, `'PASSPORT'`, `'NATIONAL_ID'`, `'NATIONAL_HEALTH_ID'`.                         |
| `countries` | [`CountryConfig`](#country-specific-field-configuration) | Country and state-specific field overrides for this document type. Allows different fields to be shown based on the user's selected country and state. |

***

## CSS Styling

The Form module provides CSS class keys for styling customization through the `style` property on configuration objects.

### CSS Class Keys

| Key               | CSS Class             | Description                  |
| ----------------- | --------------------- | ---------------------------- |
| `wrapper`         | `ff-wrapper`          | Main form wrapper            |
| `innerWrapper`    | `ff-inner-wrapper`    | Inner content wrapper        |
| `description`     | `ff-description`      | Description text container   |
| `instructions`    | `ff-instructions`     | Instructions list container  |
| `documents`       | `ff-documents`        | Document list container      |
| `checkbox`        | `ff-checkbox`         | Checkbox container           |
| `label`           | `ff-label`            | Label text elements          |
| `title`           | `ff-title`            | Title text elements          |
| `subtitle`        | `ff-subtitle`         | Subtitle text elements       |
| `button`          | `ff-button`           | Primary button               |
| `disabledButton`  | `ff-disabled-button`  | Disabled button state        |
| `cancelButton`    | `ff-cancel-button`    | Cancel/back button           |
| `checkboxItem`    | `ff-checkbox-item`    | Individual checkbox items    |
| `descriptionItem` | `ff-description-item` | Individual description items |
| `instructionItem` | `ff-instruction-item` | Individual instruction items |
| `instructionIcon` | `ff-instruction-icon` | Instruction item icons       |
| `checkboxInput`   | `ff-checkbox-input`   | Checkbox input elements      |
| `documentItem`    | `ff-document-item`    | Individual document items    |
| `font`            | `font`                | Font configuration           |
| `formWrapper`     | `ff-form-wrapper`     | Form fields wrapper          |
| `formField`       | `ff-form-field`       | Individual form fields       |
| `progressWrapper` | `ff-progress-wrapper` | Progress indicator wrapper   |
| `progressItem`    | `ff-progress-item`    | Individual progress items    |
| `loading`         | `ff-loading`          | Loading indicator            |
| `noteContainer`   | `ff-note-container`   | Note/info box container      |
| `noteTitle`       | `ff-note-title`       | Note title                   |
| `noteDescription` | `ff-note-description` | Note description text        |
| `editIcon`        | `ff-edit-button`      | Edit icon/button             |
| `logo`            | `ff-logo`             | Logo element                 |

**Example:**

```javascript theme={null}
const formComponent = sdk.component('form', {
  name: 'WELCOME',
  mode: 'individual',
  type: 'manual',
  style: {
    'ff-title': {
      color: '#1a1a1a',
      fontSize: '28px',
      fontWeight: 700
    },
    'ff-button': {
      backgroundColor: '#4F46E5',
      borderRadius: '8px'
    },
    'ff-wrapper': {
      padding: '24px',
      maxWidth: '600px',
      margin: '0 auto'
    },
    font: {
      name: 'Inter',
      url: 'https://fonts.googleapis.com/css2?family=Inter'
    }
  }
});
```

***

## Form Fields

Form-based screens (Review, Personal Details, Retry) use configurable form fields.

### Field Types

| Type             | Description                     |
| ---------------- | ------------------------------- |
| `input`          | Standard text input             |
| `label`          | Read-only label display         |
| `number`         | Numeric input                   |
| `date`           | Date picker                     |
| `select`         | Dropdown select                 |
| `multiselect`    | Multi-option select             |
| `textarea`       | Multi-line text area            |
| `checkbox`       | Checkbox                        |
| `radio`          | Radio button group              |
| `contact-number` | Contact number with formatting  |
| `address`        | Address input with autocomplete |
| `phone`          | Phone number with country code  |
| `hidden`         | Hidden field                    |

### FormField Type

```typescript theme={null}
type FormField = {
  name: string;                // Field identifier
  fieldType: InputConfigType;  // Field type (see table above)
  dataType?: FormFieldDataType;  // Data category
  hide?: boolean;              // Hide this field
  style?: Styles;              // Custom CSS styles
  showToggle?: boolean;        // Show toggle control
  image?: string;              // Field image/icon
  title?: Content;             // Field title/label
  helperText?: string;         // Helper text below field
  disabledVisually?: boolean;  // Visual disabled state (input only)
  // + validation rules
  // + field-type-specific props
}
```

| Property           | Type                              | Description                                               |
| ------------------ | --------------------------------- | --------------------------------------------------------- |
| `name`             | `string`                          | Field identifier used for data binding                    |
| `fieldType`        | `InputConfigType`                 | Field type. See [Field Types](#field-types).              |
| `dataType`         | `FormFieldDataType`               | Data category. See [Field Data Types](#field-data-types). |
| `hide`             | `boolean`                         | Hide this field from the form                             |
| `style`            | `Styles`                          | Custom [CSS styles](#css-styling)                         |
| `showToggle`       | `boolean`                         | Show a toggle control for this field                      |
| `image`            | `string`                          | Field image or icon URL                                   |
| `title`            | [`Content`](#content-object)      | Field title/label                                         |
| `helperText`       | `string`                          | Helper text displayed below the field                     |
| `disabledVisually` | `boolean`                         | Visual disabled state (input fields only)                 |
| `rules`            | [`FieldRules`](#validation-rules) | Validation rules for the field                            |

### Field-Type-Specific Properties

In addition to the common `FormField` properties above, each `fieldType` supports its own specific properties.

#### `input` / `number` / `textarea` / `hidden`

| Property      | Type               | Description                                                                                            |
| ------------- | ------------------ | ------------------------------------------------------------------------------------------------------ |
| `placeholder` | `string`           | Placeholder text shown when the field is empty                                                         |
| `type`        | `string`           | HTML input type: `'email'`, `'password'`, `'tel'`, `'text'`, `'url'`, `'search'`, `'date'`, `'number'` |
| `maxLength`   | `number`           | Maximum character length                                                                               |
| `minLength`   | `number`           | Minimum character length                                                                               |
| `min`         | `string \| number` | Minimum value (for number inputs)                                                                      |
| `max`         | `string \| number` | Maximum value (for number inputs)                                                                      |
| `pattern`     | `string`           | Regex pattern for validation                                                                           |

#### `date`

Date fields support a `calendarConfig` property that controls the calendar system, locale, and age validation.

| Property         | Type     | Description                        |
| ---------------- | -------- | ---------------------------------- |
| `calendarConfig` | `object` | Calendar configuration (see below) |

**`calendarConfig` properties:**

| Property      | Type     | Default       | Description                                                                      |
| ------------- | -------- | ------------- | -------------------------------------------------------------------------------- |
| `type`        | `string` | `'gregorian'` | Calendar system to use. Supported values: `'gregorian'`, `'nepali'`.             |
| `locale`      | `string` | `'en'`        | Calendar locale. Supported values: `'en'`, `'np'`.                               |
| `day`         | `object` | —             | Day field config: `{ hide?: boolean, placeholder?: string }`                     |
| `month`       | `object` | —             | Month field config: `{ hide?: boolean, placeholder?: string }`                   |
| `year`        | `object` | —             | Year field config: `{ placeholder?: string }`                                    |
| `age`         | `object` | —             | Age validation constraints                                                       |
| `age.min`     | `number` | —             | Minimum allowed age                                                              |
| `age.max`     | `number` | —             | Maximum allowed age                                                              |
| `age.message` | `string` | —             | Validation message when age is outside the allowed range                         |
| `dateRange`   | `object` | —             | Date range constraints: `{ min?: { value, message }, max?: { value, message } }` |

```javascript theme={null}
{
  fieldType: 'date',
  name: 'dateOfBirth',
  label: 'Date of Birth',
  calendarConfig: {
    type: 'gregorian',
    locale: 'en',
    age: {
      min: 18,
      max: 85,
      message: 'Age must be between 18 and 85'
    }
  }
}
```

#### `select` / `multiselect`

| Property       | Type                                      | Description                                                                                     |
| -------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `options`      | `Array<{ label: string, value: string }>` | **Required.** List of selectable options. Each option has a `label` (display text) and `value`. |
| `placeholder`  | `string`                                  | Placeholder text when no option is selected                                                     |
| `autocomplete` | `boolean`                                 | Enable type-ahead search within options                                                         |
| `emptyText`    | `string`                                  | Text shown when no options match a search. Default: `'No record'`                               |
| `clearable`    | `boolean`                                 | Allow clearing the selected value                                                               |

<Note>
  **Matching and auto-select behavior when `autocomplete: true`:**

  * **Matching** — as the user types, options are filtered to those whose `label` **or** `value` starts with the typed text (case-insensitive). Matching against `value` lets you use short codes as options (e.g. state codes like `NSW`) so users can filter by typing the code even though the displayed label is the full name (e.g. "New South Wales").
  * **Select on blur** — when the field loses focus, if the typed text is an **exact** match (case-insensitive) to an option's `value`, that option is automatically selected and the input is updated to show its `label`. Partial/prefix matches are not auto-selected on blur — only an exact `value` match triggers this.
</Note>

#### `address`

| Property                | Type          | Description                                                                                                                                                                                                                        |
| ----------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `placeholder`           | `string`      | Placeholder text for the autocomplete input                                                                                                                                                                                        |
| `manualFieldConfig`     | `FormField[]` | **Required.** Array of `FormField` objects defining the manual address entry fields (country, unit number, street, suburb, state, postal code). When customizing, you must override **all** fields — not just individual ones.     |
| `isManual`              | `boolean`     | Default: `false`. When `true`, shows only the manual entry fields (skips autocomplete).                                                                                                                                            |
| `actionLabel`           | `string`      | Label for the manual entry toggle link. Default: `'Enter address manually'`                                                                                                                                                        |
| `acceptedCountries`     | `string[]`    | Restrict address autocomplete to specific countries (ISO 3166-1 alpha-2 codes)                                                                                                                                                     |
| `addressSearchPosition` | `number`      | Index into the **visible** manual fields at which the "Enter address manually" / address-search link is inserted. Default: end of the list (after all visible manual fields). The value is clamped to `[0, visibleFields.length]`. |

<Note>
  **Hidden `streetNumber`/`streetName` fields and auto-hide of `streetAddress`**

  The default `manualFieldConfig` for the address field type includes two additional fields, hidden by default, alongside the single free-text `streetAddress` field: `address.streetNumber` (label "Street Number") and `address.streetName` (label "Street Name"). They let you split the street line into two inputs instead of one.

  If you override `manualFieldConfig` and set `hide: false` on **either** `address.streetNumber` or `address.streetName`, the `address.streetAddress` field is automatically force-hidden — you don't need to hide it yourself, and the three fields are not intended to be shown together.
</Note>

#### `phone`

| Property      | Type                                      | Description                                                                                                           |
| ------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `placeholder` | `{ cc: string, phoneNumber: string }`     | **Required.** Placeholder text for the country code and phone number inputs.                                          |
| `options`     | `Array<{ label: string, value: string }>` | **Required.** Country code options. Example: `[{ label: 'AU +61', value: '+61' }, { label: 'NZ +64', value: '+64' }]` |

#### `checkbox` / `radio`

| Property  | Type                                      | Description                   |
| --------- | ----------------------------------------- | ----------------------------- |
| `options` | `Array<{ label: string, value: string }>` | List of options for selection |

#### `contact-number`

| Property      | Type     | Description                                   |
| ------------- | -------- | --------------------------------------------- |
| `placeholder` | `string` | Placeholder text for the contact number input |

#### `label`

The `label` fieldType renders static display text. It has no additional field-type-specific properties beyond the common `FormField` properties.

### Field Data Types

| DataType           | Description                 |
| ------------------ | --------------------------- |
| `phone`            | Phone number data           |
| `email`            | Email address data          |
| `individual_extra` | Extra individual-level data |
| `document_extra`   | Extra document-level data   |
| `previous_addr`    | Previous address            |
| `current_addr`     | Current address             |
| `text`             | Generic text                |
| `number`           | Numeric data                |

### Validation Rules

Fields support validation through the `rules` property:

```typescript theme={null}
type FieldRules = {
  rules?: {
    required?: string | { value: boolean; message: string };
    min?: { value: number; message: string };
    max?: { value: number; message: string };
    minLength?: { value: number; message: string };
    maxLength?: { value: number; message: string };
    pattern?: { value: string; message: string };
    validate?: (value) => string | boolean;
  }
}
```

***

## Default Screen Configurations

The form module provides built-in default configurations for each screen. When you pass custom configuration, your values are **merged** with the defaults — you only need to specify the properties you want to override. Properties not included in your configuration retain their defaults.

<Warning>
  Configuration overrides are **shallow-merged** at each level. If you override a specific country or state key (e.g., `AUS.NSW`), only that key is replaced — all other country/state keys remain with their defaults. This means overriding just one country/state will leave all others using the built-in default configuration, which may produce unexpected behavior if the defaults don't match your requirements. To ensure consistency, override **all** country/state keys you intend to support.
</Warning>

### Welcome

<Accordion title="OCR mode default">
  ```javascript theme={null}
  {
    name: 'WELCOME',
    mode: 'individual',
    type: 'ocr',
    title: { label: "Let's verify your identity" },
    descriptions: [
      {
        label: "We need to collect some personal information to verify your identity. It's important you enter your details as accurately as possible."
      }
    ],
    instructions: {
      label: 'You will need',
      content: [
        { label: "An ID on you (this could be a driver's licence, passport or Medicare card)" },
        { label: 'Grant access permission on the camera of your phone so we can capture your ID' },
        { label: 'You must be an Australian citizen, permanent resident or Visa holder.' }
      ]
    },
    cta: { label: 'Start identity verification' }
  }
  ```
</Accordion>

<Accordion title="Manual mode default (1 ID, AU)">
  ```javascript theme={null}
  {
    name: 'WELCOME',
    mode: 'individual',
    type: 'manual',
    numberOfIDs: 1,
    title: { label: "Let's verify your identity" },
    descriptions: [
      {
        label: 'We need to collect some personal information to verify your identity. All fields must be filled and it is important you enter your details accurately.'
      }
    ],
    instructions: {
      label: 'You will need',
      content: [
        { label: 'A few mins to complete this application' },
        { label: "An ID on you (this could be a driver's licence, passport or Medicare card)" },
        { label: 'You must be over 18 years of age' },
        { label: 'You must be an Australian citizen, permanent resident or Visa holder.' }
      ]
    },
    cta: { label: 'Start identity verification' }
  }
  ```
</Accordion>

<Accordion title="Doc Upload mode default">
  ```javascript theme={null}
  // Doc upload welcome is dynamically generated from the recipe's docUpload config.
  // The requested/partial/optional documents are listed as instructions.
  {
    name: 'WELCOME',
    mode: 'individual',
    type: 'doc_upload',
    title: { label: 'Document request' },
    descriptions: [
      {
        label: 'The following documents are required as part of our verification process. Please ensure you have these documents on hand:'
      }
    ],
    instructions: {
      label: 'Requested documents',
      content: [/* generated from requestedDocuments in recipe */]
    },
    additionalInstructions: [/* generated from partialDocuments and optionalDocuments in recipe */],
    cta: { label: 'Next' }
  }
  ```
</Accordion>

### Consent

<Accordion title="Manual mode default">
  ```javascript theme={null}
  {
    name: 'CONSENT',
    mode: 'individual',
    type: 'manual',
    title: { label: 'Your consent matters' },
    descriptions: [
      {
        label: "Your personal information being collected and used in accordance with [Company]'s <a href=\"https://www.frankieone.com/privacy\" target=\"_blank\">Privacy Policy</a>."
      },
      {
        label: 'In addition, for the purposes of verifying your identity, you consent to: a) the verification of my personal information with credit bureau header files (for verification only); b) against records held by official document issues or official record holders via third party systems; and c) verification agent(s) acting as a nominated intermediary in accordance with Australian Privacy Principles.'
      },
      {
        label: 'You consent to the use by third parties of the results of any verification checks on my identity for the purposes of monitoring and improving their verification services.'
      }
    ],
    checkbox: {
      content: [
        { label: 'I have read and agree the above disclosure' }
      ]
    },
    cta: { label: 'Continue' }
  }
  ```
</Accordion>

### Start

```javascript theme={null}
{
  name: 'START',
  mode: 'individual',
  type: 'manual',
  cta: { label: 'Get Started' }
}
```

### Document Selection (Manual)

<Accordion title="Full default config">
  ```javascript theme={null}
  {
    name: 'DOCUMENT',
    mode: 'individual',
    type: 'manual',
    numberOfIDs: 1,
    title: { label: 'Select your first ID' },
    subtitle: { label: 'Your ID must be valid and not expired' },
    descriptions: [
      { label: 'We need one form of ID document to verify your identity.' }
    ],
    documents: [
      {
        type: 'DRIVERS_LICENCE',
        label: "Driver's licence",
        subtitle: '(recommended)',
        countries: {
          default: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en' }
                }
              ]
            }
          },
          AUS: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 6, message: 'Licence number must be at least 6 characters' },
                    maxLength: { value: 8, message: 'Licence number must not exceed 8 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 10, message: 'Card number must be at least 10 digits' },
                    maxLength: { value: 10, message: 'Card number must not exceed 10 digits' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en' }
                }
              ]
            },
            NSW: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 6, message: 'Licence number must be at least 6 characters' },
                    maxLength: { value: 8, message: 'Licence number must not exceed 8 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. 1234567890',
                  helperText: 'You will find your Card Number on the front of your card, in the top right corner above your photo.',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 10, message: 'Card number must be at least 10 digits' },
                    maxLength: { value: 10, message: 'Card number must not exceed 10 digits' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' }
                  },
                  standardDate: true, configYear: true
                }
              ]
            },
            ACT: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 1, message: 'Licence number must be at least 1 character' },
                    maxLength: { value: 10, message: 'Licence number must not exceed 10 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 10, message: 'Card number must be at least 10 digits' },
                    maxLength: { value: 10, message: 'Card number must not exceed 10 digits' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' }
                  },
                  standardDate: true, configYear: true
                }
              ]
            },
            VIC: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 1, message: 'Licence number must be at least 1 character' },
                    maxLength: { value: 10, message: 'Licence number must not exceed 10 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. P1234567',
                  helperText: 'You will find your Card Number on the back of your card, either in the top right corner or middle right.',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 8, message: 'Card number must be at least 8 characters' },
                    maxLength: { value: 8, message: 'Card number must not exceed 8 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' }
                  },
                  standardDate: true, configYear: true
                }
              ]
            },
            QLD: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 8, message: 'Licence number must be at least 8 characters' },
                    maxLength: { value: 9, message: 'Licence number must not exceed 9 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. 1234567890',
                  helperText: 'You will find your Card Number on the front of your card, in the bottom middle, or the back of your card, on the bottom right side.',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 10, message: 'Card number must be at least 10 digits' },
                    maxLength: { value: 10, message: 'Card number must not exceed 10 digits' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' }
                  },
                  standardDate: true, configYear: true
                }
              ]
            },
            SA: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 6, message: 'Licence number must be at least 6 characters' },
                    maxLength: { value: 6, message: 'Licence number must not exceed 6 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. 1234567890',
                  helperText: 'You will find your Card Number on the back of your card, in the top right corner.',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 9, message: 'Card number must be at least 9 characters' },
                    maxLength: { value: 9, message: 'Card number must not exceed 9 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' }
                  },
                  standardDate: true, configYear: true
                }
              ]
            },
            TAS: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 6, message: 'Licence number must be at least 6 characters' },
                    maxLength: { value: 8, message: 'Licence number must not exceed 8 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. 1234567890',
                  helperText: 'You will find your Card Number on the back of your card, in the top right corner.',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 9, message: 'Card number must be at least 9 characters' },
                    maxLength: { value: 9, message: 'Card number must not exceed 9 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' }
                  },
                  standardDate: true, configYear: true
                }
              ]
            },
            NT: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 1, message: 'Licence number must be at least 1 character' },
                    maxLength: { value: 10, message: 'Licence number must not exceed 10 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. 1234567890',
                  helperText: 'The card number is located on the back of your card, either in the bottom left corner or bottom middle.',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 6, message: 'Card number must be at least 6 digits' },
                    maxLength: { value: 8, message: 'Card number must not exceed 8 digits' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' }
                  },
                  standardDate: true, configYear: true
                }
              ]
            },
            WA: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 7, message: 'Licence number must be at least 7 characters' },
                    maxLength: { value: 7, message: 'Licence number must not exceed 7 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. 1234567890',
                  helperText: 'You will find your Card Number on the back of your card, in the middle of the right side.',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 8, message: 'Card number must be at least 8 characters' },
                    maxLength: { value: 10, message: 'Card number must not exceed 10 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' }
                  },
                  standardDate: true, configYear: true
                }
              ]
            }
          },
          NZL: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'extraData.licence_version',
                  label: 'Version Number', placeholder: 'e.g. 123',
                  rules: {
                    required: { value: true, message: 'Please enter your version number' },
                    minLength: { value: 3, message: 'Version number must be at least 3 characters' },
                    maxLength: { value: 3, message: 'Version number must not exceed 3 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en' }
                }
              ]
            }
          }
        }
      },
      {
        type: 'PASSPORT',
        label: 'Passport',
        countries: {
          default: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Passport Issuing Country',
                  options: [
                    // All ISO 3166-1 alpha-3 countries, sorted alphabetically by label.
                    // Contains ~250 entries in the format { label: 'Country Name', value: 'ALPHA3_CODE' }.
                    // First few: { label: 'Afghanistan', value: 'AFG' }, { label: 'Albania', value: 'ALB' }, ...
                    // Last: { label: 'Zambia', value: 'ZMB' }, { label: 'Zimbabwe', value: 'ZWE' }
                  ],
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Passport Number', placeholder: 'e.g. A1234567890',
                  rules: { required: { value: true, message: 'Please enter your passport number' } }
                },
                {
                  // Added in v1.9.36 (FDEL-50763). Optional — no `rules`, unlike NZL's required expiry field above.
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en' }
                }
              ]
            }
          },
          AUS: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Passport Issuing Country',
                  options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Passport Number', placeholder: 'e.g. A1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your passport number' },
                    minLength: { value: 8, message: 'Passport number must be at least 8 characters' },
                    maxLength: { value: 9, message: 'Passport number must not exceed 9 characters' }
                  }
                },
                {
                  // Added in v1.9.36 (FDEL-50763). Optional — no `rules`, unlike NZL's required expiry field above.
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en' }
                }
              ]
            }
          },
          NZL: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Passport Issuing Country',
                  options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Passport Number', placeholder: 'e.g. A1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your passport number' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Date of Expiry',
                  rules: {
                    required: { value: true, message: "Please enter your passport's expiry date" }
                  },
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' },
                    dateRange: {
                      min: { value: 'now' },
                      max: { value: '+10 years' }
                    },
                    message: "Please enter your passport's expiry date"
                  }
                }
              ]
            }
          },
          IND: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Passport Issuing Country',
                  options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Passport Number', placeholder: 'e.g. A1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your passport number' }
                  }
                },
                {
                  fieldType: 'input', name: 'extraData.document_number', dataType: 'document_extra',
                  label: 'File Number', placeholder: 'e.g. ABCD12345678',
                  rules: {
                    required: { value: true, message: 'Please enter your File Number' }
                  }
                },
                {
                  // Added in v1.9.36 (FDEL-50763). Optional — no `rules`, unlike NZL's required expiry field above.
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en' }
                }
              ]
            }
          }
        }
      },
      {
        type: 'NATIONAL_HEALTH_ID',
        label: 'Medicare card',
        countries: {
          default: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'idSubType',
                  label: 'Medicare Card Colour',
                  options: [
                    { label: 'Green', value: 'G' },
                    { label: 'Blue', value: 'B' },
                    { label: 'Yellow', value: 'Y' }
                  ],
                  placeholder: 'Select Medicare Card Colour',
                  rules: { required: { value: true, message: 'Please select your Medicare card colour' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Medicare Card Number',
                  rules: {
                    required: { value: true, message: 'Please enter your Medicare card number' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' },
                    minLength: { value: 10, message: 'Medicare card number must be at least 10 digits' },
                    maxLength: { value: 10, message: 'Medicare card number must be not exceed 10 digits' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'document_extra', name: 'extraData.reference',
                  label: 'Position on Card',
                  rules: {
                    required: { value: true, message: 'Please enter your position on card' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' },
                    maxLength: { value: 1, message: 'Position on card must not exceed 1 digit' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Date of Expiry',
                  rules: { required: { value: true, message: 'Please enter your Medicare expiry date' } },
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    message: 'Please enter valid Medicare expiry date'
                  }
                },
                {
                  fieldType: 'select', dataType: 'text', name: 'middleNameDisplayType',
                  label: 'How is middle name displayed on the card?',
                  options: [
                    { label: 'No Middle Name', value: 'No middle name' },
                    { label: 'Initial Only', value: 'Initial only' },
                    { label: 'Full Middle Name', value: 'Full middle name' }
                  ]
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.display_name_line1',
                  label: 'Name displayed on card',
                  disabledVisually: true
                },
                {
                  fieldType: 'hidden', dataType: 'text', name: 'extraData.display_middle_name',
                  label: 'Middle name displayed on card'
                }
              ]
            }
          }
        }
      }
    ],
    cta: { label: 'Next' }
  }
  ```
</Accordion>

### Personal Details

<Accordion title="Full default config">
  ```javascript theme={null}
  {
    name: 'PERSONAL',
    title: { label: 'Personal details' },
    descriptions: [
      {
        label: 'The details you provide below will be used to verify your identity – make sure they match your ID documents.'
      }
    ],
    personal: {
      countries: {
        default: {
          default: {
            fields: [
              {
                fieldType: 'input', dataType: 'text', name: 'givenName',
                hide: false, label: 'Given Name',
                rules: {
                  required: { value: true, message: 'Please enter your given name' },
                  pattern: {
                    value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$",
                    message: 'Please enter alphabetic characters with apostrophe only'
                  }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'middleName',
                hide: false, label: 'Middle Name(s)',
                showToggle: true,
                rules: {
                  required: { value: true, message: 'Please enter your middle name' },
                  pattern: {
                    value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$",
                    message: 'Please enter alphabetic characters with apostrophe only'
                  }
                },
                toggleConfig: {
                  label: 'Do you have any Middle Names?',
                  rules: {
                    required: { value: true, message: 'Please let us know if you have any middle names' }
                  }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'familyName',
                hide: false, label: 'Family Name',
                rules: {
                  required: { value: true, message: 'Please enter your family name' },
                  pattern: {
                    value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$",
                    message: 'Please enter alphabetic characters with apostrophe only'
                  }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'extraData.otherName',
                hide: true, label: 'Other Name(s)',
                showToggle: true,
                rules: {
                  pattern: {
                    value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$",
                    message: 'Please enter alphabetic characters with apostrophe only'
                  }
                },
                toggleConfig: {
                  label: 'Do you have any Other Names?'
                }
              },
              {
                fieldType: 'phone', dataType: 'number', name: 'extraData.phone',
                hide: true, label: 'Phone Number',
                options: [
                  { label: 'AU +61', value: '+61' },
                  { label: 'NZ +64', value: '+64' }
                ],
                placeholder: { cc: 'Code', phoneNumber: 'e.g. 0400 000 000' },
                rules: {
                  required: { value: true, message: 'Please enter the phone number' },
                  minLength: { value: 10, message: 'Phone number must be at least 10 digits' },
                  maxLength: { value: 10, message: 'Phone number must not exceed 10 characters' },
                  pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'extraData.email',
                hide: true, label: 'Email',
                rules: {
                  required: { value: true, message: 'Please enter the email' },
                  pattern: {
                    value: '^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}$',
                    message: 'Please enter a valid email address'
                  }
                }
              },
              {
                fieldType: 'date', dataType: 'text', name: 'dateOfBirth',
                hide: false, label: 'Date of Birth',
                rules: { required: { value: true, message: 'Please enter your date of birth' } },
                calendarConfig: {
                  type: 'gregory', locale: 'en',
                  day: { placeholder: 'Day' },
                  month: { placeholder: 'Month' },
                  year: { placeholder: 'Year' },
                  message: 'Please enter your date of birth'
                }
              },
              {
                fieldType: 'address', dataType: 'current_addr', name: 'address.fullAddress',
                hide: false, label: 'Residential Address',
                placeholder: 'Type in your address',
                helperText: 'Cannot be a PO Box',
                rules: { required: { value: true, message: 'Please enter your residential address' } },
                manualFieldConfig: [
                  {
                    fieldType: 'select', dataType: 'text', name: 'address.country',
                    hide: false, label: 'Country',
                    options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                    rules: { required: { value: true, message: 'Please select your country' } }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.unitNumber',
                    hide: false, label: 'Unit Number (optional)'
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.streetAddress',
                    hide: false, label: 'Street Address',
                    rules: { required: { value: true, message: 'Please enter your street address' } }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.town',
                    hide: false, label: 'Suburb / Town',
                    rules: { required: { value: true, message: 'Please enter your suburb/town.' } }
                  },
                  {
                    fieldType: 'select', dataType: 'text', name: 'address.state',
                    hide: false, label: 'State',
                    placeholder: 'Select Your State',
                    options: [
                      { label: 'Australian Capital Territory', value: 'ACT' },
                      { label: 'New South Wales', value: 'NSW' },
                      { label: 'Northern Territory', value: 'NT' },
                      { label: 'Queensland', value: 'QLD' },
                      { label: 'South Australia', value: 'SA' },
                      { label: 'Tasmania', value: 'TAS' },
                      { label: 'Victoria', value: 'VIC' },
                      { label: 'Western Australia', value: 'WA' }
                    ],
                    rules: { required: { value: true, message: 'Please select your state' } }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.postalCode',
                    hide: false, label: 'Postcode',
                    rules: {
                      required: { value: true, message: 'Please enter your postal code' },
                      minLength: { value: 0, message: '' },
                      maxLength: { value: 100, message: '' }
                    }
                  }
                ]
              }
            ]
          }
        },
        AUS: {
          default: {
            fields: [
              {
                fieldType: 'input', dataType: 'text', name: 'givenName',
                hide: false, label: 'Given Name',
                rules: {
                  required: { value: true, message: 'Please enter your given name' },
                  pattern: { value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$", message: 'Please enter alphabetic characters with apostrophe only' }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'middleName',
                hide: false, label: 'Middle Name(s)',
                showToggle: true,
                rules: {
                  required: { value: true, message: 'Please enter your middle name' },
                  pattern: { value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$", message: 'Please enter alphabetic characters with apostrophe only' }
                },
                toggleConfig: {
                  label: 'Do you have any Middle Names?',
                  rules: { required: { value: true, message: 'Please let us know if you have any middle names' } }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'familyName',
                hide: false, label: 'Family Name',
                rules: {
                  required: { value: true, message: 'Please enter your family name' },
                  pattern: { value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$", message: 'Please enter alphabetic characters with apostrophe only' }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'extraData.otherName',
                hide: true, label: 'Other Name(s)',
                showToggle: true,
                rules: { pattern: { value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$", message: 'Please enter alphabetic characters with apostrophe only' } },
                toggleConfig: { label: 'Do you have any Other Names?' }
              },
              {
                fieldType: 'phone', dataType: 'number', name: 'extraData.phone',
                hide: true, label: 'Phone Number',
                options: [{ label: 'AU +61', value: '+61' }, { label: 'NZ +64', value: '+64' }],
                placeholder: { cc: 'Code', phoneNumber: 'e.g. 0400 000 000' },
                rules: {
                  required: { value: true, message: 'Please enter the phone number' },
                  minLength: { value: 10, message: 'Phone number must be at least 10 digits' },
                  maxLength: { value: 10, message: 'Phone number must not exceed 10 characters' },
                  pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'extraData.email',
                hide: true, label: 'Email',
                rules: {
                  required: { value: true, message: 'Please enter the email' },
                  pattern: { value: '^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}$', message: 'Please enter a valid email address' }
                }
              },
              {
                fieldType: 'date', dataType: 'text', name: 'dateOfBirth',
                hide: false, label: 'Date of Birth',
                rules: { required: { value: true, message: 'Please enter your date of birth' } },
                calendarConfig: {
                  type: 'gregory', locale: 'en',
                  day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' },
                  message: 'Please enter your date of birth'
                }
              },
              {
                fieldType: 'address', dataType: 'current_addr', name: 'address.fullAddress',
                hide: false, label: 'Residential Address',
                placeholder: 'Type in your address',
                helperText: 'Cannot be a PO Box',
                rules: { required: { value: true, message: 'Please enter your residential address' } },
                manualFieldConfig: [
                  {
                    fieldType: 'select', dataType: 'text', name: 'address.country',
                    hide: false, label: 'Country',
                    options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                    rules: { required: { value: true, message: 'Please select your country' } }
                  },
                  { fieldType: 'input', dataType: 'text', name: 'address.unitNumber', hide: false, label: 'Unit Number (optional)' },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.streetAddress',
                    hide: false, label: 'Street Address',
                    rules: { required: { value: true, message: 'Please enter your street address' } }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.town',
                    hide: false, label: 'Suburb / Town',
                    rules: { required: { value: true, message: 'Please enter your suburb/town.' } }
                  },
                  {
                    fieldType: 'select', dataType: 'text', name: 'address.state',
                    hide: false, label: 'State', placeholder: 'Select Your State',
                    options: [
                      { label: 'Australian Capital Territory', value: 'ACT' },
                      { label: 'New South Wales', value: 'NSW' },
                      { label: 'Northern Territory', value: 'NT' },
                      { label: 'Queensland', value: 'QLD' },
                      { label: 'South Australia', value: 'SA' },
                      { label: 'Tasmania', value: 'TAS' },
                      { label: 'Victoria', value: 'VIC' },
                      { label: 'Western Australia', value: 'WA' }
                    ],
                    rules: { required: { value: true, message: 'Please select your state' } }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.postalCode',
                    hide: false, label: 'Postcode',
                    rules: {
                      required: { value: true, message: 'Please enter your postal code' },
                      minLength: { value: 4, message: 'Postal code must be at least 4 characters' },
                      maxLength: { value: 4, message: 'Postal code must not exceed 4 characters' }
                    }
                  }
                ]
              }
            ]
          }
        }
      }
    },
    cta: { label: 'Next' }
  }
  ```
</Accordion>

<Warning>
  When customizing the address `manualFieldConfig`, you must override **all** fields in `manualFieldConfig`, not just individual ones. This is because the `manualFieldConfig` array is replaced entirely, not merged field-by-field. Additionally, if you have specified `acceptedCountries` on the address field, you will need to define the configuration for each country in the `personal.countries` property.
</Warning>

### Review

<Accordion title="OCR mode default">
  ```javascript theme={null}
  {
    name: 'REVIEW',
    type: 'ocr',
    verify: false,
    title: { label: 'Are your details correct?' },
    personal: {
      countries: {
        default: {
          default: {
            fields: [
              {
                fieldType: 'input', dataType: 'text', name: 'givenName',
                hide: false, label: 'Given Name',
                rules: {
                  required: { value: true, message: 'Please enter your given name' },
                  pattern: { value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$", message: 'Please enter alphabetic characters with apostrophe only' }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'middleName',
                hide: false, label: 'Middle Name(s)',
                rules: {
                  pattern: { value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$", message: 'Please enter alphabetic characters with apostrophe only' }
                },
                helperText: 'As displayed on your ID'
              },
              {
                fieldType: 'input', dataType: 'text', name: 'familyName',
                hide: false, label: 'Family Name',
                rules: {
                  required: { value: true, message: 'Please enter your family name' },
                  pattern: { value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$", message: 'Please enter alphabetic characters with apostrophe only' }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'extraData.otherName',
                hide: true, label: 'Other Name(s)',
                rules: { pattern: { value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$", message: 'Please enter alphabetic characters with apostrophe only' } },
                helperText: 'As displayed on your ID'
              },
              {
                fieldType: 'date', dataType: 'text', name: 'dateOfBirth',
                hide: false, label: 'Date of Birth',
                rules: { required: { value: true, message: 'Please enter your date of birth' } },
                calendarConfig: {
                  type: 'gregory', locale: 'en',
                  day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' },
                  message: 'Please enter your date of birth'
                },
                standardDate: true, configYear: true
              },
              {
                fieldType: 'address', name: 'address.fullAddress', dataType: 'current_addr',
                hide: false, label: 'Residential Address',
                placeholder: 'Type in your address',
                helperText: 'Cannot be a PO Box',
                rules: { required: { value: true, message: 'Please enter your residential address' } },
                isManual: true,
                manualFieldConfig: [
                  {
                    fieldType: 'select', dataType: 'text', name: 'address.country',
                    hide: false, label: 'Country',
                    options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                    rules: {
                      required: { value: true, message: 'Please select your country' },
                      pattern: { value: "^(?! )[a-zA-Z0-9 ]+(?<! )$", message: 'Please enter alphanumeric values only' }
                    }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.unitNumber',
                    hide: false, label: 'Unit Number (optional)',
                    rules: { pattern: { value: "^(?! )[a-zA-Z0-9 ]+(?<! )$", message: 'Please enter alphanumeric values only' } }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.streetAddress',
                    hide: false, label: 'Street Address',
                    rules: {
                      required: { value: true, message: 'Please enter your street address' },
                      pattern: { value: "^(?! )[a-zA-Z0-9,. - \\-() \\-[\\] /]+(?<! )$", message: 'Please enter valid characters only' }
                    }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.town',
                    hide: false, label: 'Suburb / Town',
                    rules: {
                      required: { value: true, message: 'Please enter your suburb/town.' },
                      pattern: { value: "^(?! )[a-zA-Z0-9 ]+(?<! )$", message: 'Please enter alphanumeric values only' }
                    }
                  },
                  {
                    fieldType: 'select', dataType: 'text', name: 'address.state',
                    hide: false, label: 'State', placeholder: 'Select Your State',
                    options: [
                      { label: 'Australian Capital Territory', value: 'ACT' },
                      { label: 'New South Wales', value: 'NSW' },
                      { label: 'Northern Territory', value: 'NT' },
                      { label: 'Queensland', value: 'QLD' },
                      { label: 'South Australia', value: 'SA' },
                      { label: 'Tasmania', value: 'TAS' },
                      { label: 'Victoria', value: 'VIC' },
                      { label: 'Western Australia', value: 'WA' }
                    ],
                    rules: {
                      required: { value: true, message: 'Please select your state' },
                      pattern: { value: "^(?! )[a-zA-Z0-9 ]+(?<! )$", message: 'Please enter alphanumeric values only' }
                    }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.postalCode',
                    hide: false, label: 'Postcode',
                    rules: {
                      required: { value: true, message: 'Please enter your postal code' },
                      pattern: { value: "^(?! )[a-zA-Z0-9 ]+(?<! )$", message: 'Please enter alphanumeric values only' },
                      minLength: { value: 0, message: '' },
                      maxLength: { value: 100, message: '' }
                    }
                  }
                ]
              }
            ]
          }
        },
        AUS: {
          default: {
            fields: [
              {
                fieldType: 'input', dataType: 'text', name: 'givenName',
                hide: false, label: 'Given Name',
                rules: {
                  required: { value: true, message: 'Please enter your given name' },
                  pattern: { value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$", message: 'Please enter alphabetic characters with apostrophe only' }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'middleName',
                hide: false, label: 'Middle Name(s)',
                rules: {
                  pattern: { value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$", message: 'Please enter alphabetic characters with apostrophe only' }
                },
                helperText: 'As displayed on your ID'
              },
              {
                fieldType: 'input', dataType: 'text', name: 'familyName',
                hide: false, label: 'Family Name',
                rules: {
                  required: { value: true, message: 'Please enter your family name' },
                  pattern: { value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$", message: 'Please enter alphabetic characters with apostrophe only' }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'extraData.otherName',
                hide: true, label: 'Other Name(s)',
                rules: { pattern: { value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$", message: 'Please enter alphabetic characters with apostrophe only' } },
                helperText: 'As displayed on your ID'
              },
              {
                fieldType: 'date', dataType: 'text', name: 'dateOfBirth',
                hide: false, label: 'Date of Birth',
                rules: { required: { value: true, message: 'Please enter your date of birth' } },
                calendarConfig: {
                  type: 'gregory', locale: 'en',
                  day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' },
                  message: 'Please enter your date of birth'
                },
                standardDate: true, configYear: true
              },
              {
                fieldType: 'address', name: 'address.fullAddress', dataType: 'current_addr',
                hide: false, label: 'Residential Address',
                placeholder: 'Type in your address',
                helperText: 'Cannot be a PO Box',
                rules: { required: { value: true, message: 'Please enter your residential address' } },
                isManual: true,
                manualFieldConfig: [
                  {
                    fieldType: 'select', dataType: 'text', name: 'address.country',
                    hide: false, label: 'Country',
                    options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                    rules: {
                      required: { value: true, message: 'Please select your country' },
                      pattern: { value: "^(?! )[a-zA-Z0-9 ]+(?<! )$", message: 'Please enter alphanumeric values only' }
                    }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.unitNumber',
                    hide: false, label: 'Unit Number (optional)',
                    rules: { pattern: { value: "^(?! )[a-zA-Z0-9 ]+(?<! )$", message: 'Please enter alphanumeric values only' } }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.streetAddress',
                    hide: false, label: 'Street Address',
                    rules: {
                      required: { value: true, message: 'Please enter your street address' },
                      pattern: { value: "^(?! )[a-zA-Z0-9,. - \\-() \\-[\\] /]+(?<! )$", message: 'Please enter valid characters only' }
                    }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.town',
                    hide: false, label: 'Suburb / Town',
                    rules: {
                      required: { value: true, message: 'Please enter your suburb/town.' },
                      pattern: { value: "^(?! )[a-zA-Z0-9 ]+(?<! )$", message: 'Please enter alphanumeric values only' }
                    }
                  },
                  {
                    fieldType: 'select', dataType: 'text', name: 'address.state',
                    hide: false, label: 'State', placeholder: 'Select Your State',
                    options: [
                      { label: 'Australian Capital Territory', value: 'ACT' },
                      { label: 'New South Wales', value: 'NSW' },
                      { label: 'Northern Territory', value: 'NT' },
                      { label: 'Queensland', value: 'QLD' },
                      { label: 'South Australia', value: 'SA' },
                      { label: 'Tasmania', value: 'TAS' },
                      { label: 'Victoria', value: 'VIC' },
                      { label: 'Western Australia', value: 'WA' }
                    ],
                    rules: {
                      required: { value: true, message: 'Please select your state' },
                      pattern: { value: "^(?! )[a-zA-Z0-9 ]+(?<! )$", message: 'Please enter alphanumeric values only' }
                    }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.postalCode',
                    hide: false, label: 'Postcode',
                    rules: {
                      required: { value: true, message: 'Please enter your postal code' },
                      pattern: { value: "^(?! )[a-zA-Z0-9 ]+(?<! )$", message: 'Please enter alphanumeric values only' },
                      minLength: { value: 4, message: 'Postal code must be at least 4 characters' },
                      maxLength: { value: 4, message: 'Postal code must not exceed 4 characters' }
                    }
                  }
                ]
              }
            ]
          }
        }
      }
    },
    documents: [
      {
        type: 'DRIVERS_LICENCE',
        countries: {
          default: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Document Issuing Country',
                  placeholder: 'Select issuing country',
                  options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                  rules: { required: { value: true, message: 'Please select your issuing country' } }
                },
                { fieldType: 'input', dataType: 'number', name: 'idNumber', label: 'Document Number',
                  rules: { required: { value: true, message: 'Please enter your document number' }, minLength: { value: 1, message: 'Document number must be at least 1 character' } } },
                { fieldType: 'date', name: 'idExpiry', label: 'Expiry Date', calendarConfig: { type: 'gregory', locale: 'en' } }
              ]
            }
          },
          AUS: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Document Issuing Country',
                  placeholder: 'Select issuing country',
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  rules: { required: { value: true, message: 'Please select your issuing country' } }
                },
                {
                  fieldType: 'select', dataType: 'text', name: 'region',
                  label: "Driver's Licence State or Territory",
                  placeholder: 'Select DL State or Territory',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  rules: {
                    required: { value: true, message: "Please select your driver's licence state or territory" },
                    pattern: { value: '^(NSW|ACT|NT|QLD|SA|TAS|VIC|WA)$', message: "Please select your driver's licence state or territory" }
                  }
                },
                { fieldType: 'input', name: 'idNumber', label: 'Licence Number',
                  rules: { required: { value: true, message: "Please enter your driver's licence number" },
                    minLength: { value: 1, message: 'Licence number must be at least 1 characters' },
                    maxLength: { value: 15, message: 'Licence number must not exceed 15 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' } } },
                { fieldType: 'input', name: 'extraData.document_number', label: 'Card Number',
                  rules: { required: { value: true, message: "Please enter your driver's licence card number" },
                    minLength: { value: 1, message: 'Card number must be at least 1 characters' },
                    maxLength: { value: 15, message: 'Card number must not exceed 15 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' } } },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en', day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' } },
                  standardDate: true, configYear: true
                }
              ]
            },
            NSW: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Document Issuing Country',
                  placeholder: 'Select issuing country',
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  rules: { required: { value: true, message: 'Please select your issuing country' } }
                },
                {
                  fieldType: 'select', dataType: 'text', name: 'region',
                  label: "Driver's Licence State or Territory",
                  placeholder: 'Select DL State or Territory',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  rules: {
                    required: { value: true, message: "Please select your driver's licence state or territory" },
                    pattern: { value: '^(NSW|ACT|NT|QLD|SA|TAS|VIC|WA)$', message: "Please select your driver's licence state or territory" }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en', day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' } },
                  standardDate: true, configYear: true
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'idNumber',
                  label: 'Licence Number',
                  rules: {
                    required: { value: true, message: "Please enter your driver's licence number" },
                    minLength: { value: 6, message: 'Licence number must be at least 6 characters' },
                    maxLength: { value: 8, message: 'Licence number must not exceed 8 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'extraData.document_number',
                  label: 'Card Number',
                  rules: {
                    required: { value: true, message: "Please enter your driver's licence card number" },
                    minLength: { value: 10, message: 'Card number must be at least 10 characters' },
                    maxLength: { value: 10, message: 'Card number must not exceed 10 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                }
              ]
            },
            ACT: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Document Issuing Country',
                  placeholder: 'Select issuing country',
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  rules: { required: { value: true, message: 'Please select your issuing country' } }
                },
                {
                  fieldType: 'select', dataType: 'text', name: 'region',
                  label: "Driver's Licence State or Territory",
                  placeholder: 'Select DL State or Territory',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  rules: {
                    required: { value: true, message: "Please select your driver's licence state or territory" },
                    pattern: { value: '^(NSW|ACT|NT|QLD|SA|TAS|VIC|WA)$', message: "Please select your driver's licence state or territory" }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en', day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' } },
                  standardDate: true, configYear: true
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'idNumber',
                  label: 'Licence Number',
                  rules: {
                    required: { value: true, message: "Please enter your driver's licence number" },
                    minLength: { value: 1, message: 'Licence number must be at least 1 character' },
                    maxLength: { value: 10, message: 'Licence number must not exceed 10 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'extraData.document_number',
                  label: 'Card Number',
                  rules: {
                    required: { value: true, message: "Please enter your driver's licence card number" },
                    minLength: { value: 10, message: 'Card number must be at least 10 characters' },
                    maxLength: { value: 10, message: 'Card number must not exceed 10 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                }
              ]
            },
            VIC: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Document Issuing Country',
                  placeholder: 'Select issuing country',
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  rules: { required: { value: true, message: 'Please select your issuing country' } }
                },
                {
                  fieldType: 'select', dataType: 'text', name: 'region',
                  label: "Driver's Licence State or Territory",
                  placeholder: 'Select DL State or Territory',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  rules: {
                    required: { value: true, message: "Please select your driver's licence state or territory" },
                    pattern: { value: '^(NSW|ACT|NT|QLD|SA|TAS|VIC|WA)$', message: "Please select your driver's licence state or territory" }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en', day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' } },
                  standardDate: true, configYear: true
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'idNumber',
                  label: 'Licence Number',
                  rules: {
                    required: { value: true, message: "Please enter your driver's licence number" },
                    minLength: { value: 1, message: 'Licence number must be at least 1 character' },
                    maxLength: { value: 10, message: 'Licence number must not exceed 10 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'extraData.document_number',
                  label: 'Card Number',
                  rules: {
                    required: { value: true, message: "Please enter your driver's licence card number" },
                    minLength: { value: 8, message: 'Card number must be at least 8 characters' },
                    maxLength: { value: 8, message: 'Card number must not exceed 8 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                }
              ]
            },
            QLD: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Document Issuing Country',
                  placeholder: 'Select issuing country',
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  rules: { required: { value: true, message: 'Please select your issuing country' } }
                },
                {
                  fieldType: 'select', dataType: 'text', name: 'region',
                  label: "Driver's Licence State or Territory",
                  placeholder: 'Select DL State or Territory',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  rules: {
                    required: { value: true, message: "Please select your driver's licence state or territory" },
                    pattern: { value: '^(NSW|ACT|NT|QLD|SA|TAS|VIC|WA)$', message: "Please select your driver's licence state or territory" }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en', day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' } },
                  standardDate: true, configYear: true
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'idNumber',
                  label: 'Licence Number',
                  rules: {
                    required: { value: true, message: "Please enter your driver's licence number" },
                    minLength: { value: 8, message: 'Licence number must be at least 8 characters' },
                    maxLength: { value: 9, message: 'Licence number must not exceed 9 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'extraData.document_number',
                  label: 'Card Number',
                  rules: {
                    required: { value: true, message: "Please enter your driver's licence card number" },
                    minLength: { value: 10, message: 'Card number must be at least 10 characters' },
                    maxLength: { value: 10, message: 'Card number must not exceed 10 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                }
              ]
            },
            SA: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Document Issuing Country',
                  placeholder: 'Select issuing country',
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  rules: { required: { value: true, message: 'Please select your issuing country' } }
                },
                {
                  fieldType: 'select', dataType: 'text', name: 'region',
                  label: "Driver's Licence State or Territory",
                  placeholder: 'Select DL State or Territory',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  rules: {
                    required: { value: true, message: "Please select your driver's licence state or territory" },
                    pattern: { value: '^(NSW|ACT|NT|QLD|SA|TAS|VIC|WA)$', message: "Please select your driver's licence state or territory" }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en', day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' } },
                  standardDate: true, configYear: true
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'idNumber',
                  label: 'Licence Number',
                  rules: {
                    required: { value: true, message: "Please enter your driver's licence number" },
                    minLength: { value: 6, message: 'Licence number must be at least 6 characters' },
                    maxLength: { value: 6, message: 'Licence number must not exceed 6 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'extraData.document_number',
                  label: 'Card Number',
                  rules: {
                    required: { value: true, message: "Please enter your driver's licence card number" },
                    minLength: { value: 9, message: 'Card number must be at least 9 characters' },
                    maxLength: { value: 9, message: 'Card number must not exceed 9 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                }
              ]
            },
            TAS: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Document Issuing Country',
                  placeholder: 'Select issuing country',
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  rules: { required: { value: true, message: 'Please select your issuing country' } }
                },
                {
                  fieldType: 'select', dataType: 'text', name: 'region',
                  label: "Driver's Licence State or Territory",
                  placeholder: 'Select DL State or Territory',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  rules: {
                    required: { value: true, message: "Please select your driver's licence state or territory" },
                    pattern: { value: '^(NSW|ACT|NT|QLD|SA|TAS|VIC|WA)$', message: "Please select your driver's licence state or territory" }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en', day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' } },
                  standardDate: true, configYear: true
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'idNumber',
                  label: 'Licence Number',
                  rules: {
                    required: { value: true, message: "Please enter your driver's licence number" },
                    minLength: { value: 6, message: 'Licence number must be at least 6 characters' },
                    maxLength: { value: 8, message: 'Licence number must not exceed 8 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'extraData.document_number',
                  label: 'Card Number',
                  rules: {
                    required: { value: true, message: "Please enter your driver's licence card number" },
                    minLength: { value: 9, message: 'Card number must be at least 9 characters' },
                    maxLength: { value: 9, message: 'Card number must not exceed 9 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                }
              ]
            },
            NT: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Document Issuing Country',
                  placeholder: 'Select issuing country',
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  rules: { required: { value: true, message: 'Please select your issuing country' } }
                },
                {
                  fieldType: 'select', dataType: 'text', name: 'region',
                  label: "Driver's Licence State or Territory",
                  placeholder: 'Select DL State or Territory',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  rules: {
                    required: { value: true, message: "Please select your driver's licence state or territory" },
                    pattern: { value: '^(NSW|ACT|NT|QLD|SA|TAS|VIC|WA)$', message: "Please select your driver's licence state or territory" }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en', day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' } },
                  standardDate: true, configYear: true
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'idNumber',
                  label: 'Licence Number',
                  rules: {
                    required: { value: true, message: "Please enter your driver's licence number" },
                    minLength: { value: 1, message: 'Licence number must be at least 1 character' },
                    maxLength: { value: 10, message: 'Licence number must not exceed 10 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'extraData.document_number',
                  label: 'Card Number',
                  rules: {
                    required: { value: true, message: "Please enter your driver's licence card number" },
                    minLength: { value: 6, message: 'Card number must be at least 6 characters' },
                    maxLength: { value: 8, message: 'Card number must not exceed 8 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                }
              ]
            },
            WA: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Document Issuing Country',
                  placeholder: 'Select issuing country',
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  rules: { required: { value: true, message: 'Please select your issuing country' } }
                },
                {
                  fieldType: 'select', dataType: 'text', name: 'region',
                  label: "Driver's Licence State or Territory",
                  placeholder: 'Select DL State or Territory',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  rules: {
                    required: { value: true, message: "Please select your driver's licence state or territory" },
                    pattern: { value: '^(NSW|ACT|NT|QLD|SA|TAS|VIC|WA)$', message: "Please select your driver's licence state or territory" }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en', day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' } },
                  standardDate: true, configYear: true
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'idNumber',
                  label: 'Licence Number',
                  rules: {
                    required: { value: true, message: "Please enter your driver's licence number" },
                    minLength: { value: 7, message: 'Licence number must be at least 7 characters' },
                    maxLength: { value: 7, message: 'Licence number must not exceed 7 characters' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'extraData.document_number',
                  label: 'Card Number',
                  rules: {
                    required: { value: true, message: "Please enter your driver's licence card number" },
                    minLength: { value: 8, message: 'Card number must be at least 8 characters' },
                    maxLength: { value: 10, message: 'Card number must not exceed 10 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                }
              ]
            }
          },
          NZL: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Document Issuing Country',
                  placeholder: 'Select issuing country',
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  rules: { required: { value: true, message: 'Please select your issuing country' } }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en', day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' } },
                  standardDate: true, configYear: true
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  hide: false, label: 'Licence Number',
                  rules: {
                    required: { value: true, message: "Please enter your driver's licence number" },
                    minLength: { value: 6, message: 'Licence number must be at least 6 characters' },
                    maxLength: { value: 8, message: 'Licence number must not exceed 8 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'extraData.licence_version',
                  label: 'Version Number', placeholder: 'e.g. 123',
                  rules: {
                    required: { value: true, message: 'Please enter your version number' },
                    minLength: { value: 3, message: 'Version number must be at least 3 characters' },
                    maxLength: { value: 3, message: 'Version number must not exceed 3 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                }
              ]
            }
          }
        }
      },
      {
        type: 'NATIONAL_HEALTH_ID',
        countries: {
          default: {
            default: {
              fields: [
                { fieldType: 'select', name: 'country', label: 'Country of Medicare Card' },
                { fieldType: 'select', name: 'idSubType', label: 'Medicare Card Colour',
                  options: [
                    { label: 'Green', value: 'G' },
                    { label: 'Blue', value: 'B' },
                    { label: 'Yellow', value: 'Y' }
                  ], placeholder: 'Select Medicare Card Colour' },
                { fieldType: 'input', name: 'idNumber', label: 'Medicare Card Number',
                  rules: { required: { value: true, message: 'Please enter your Medicare card number' },
                    pattern: { value: '^[0-9]+$' }, minLength: { value: 10 }, maxLength: { value: 10 } } },
                { fieldType: 'input', dataType: 'document_extra', name: 'extraData.reference',
                  label: 'Position on Card',
                  rules: { required: { value: true }, pattern: { value: '^[0-9]+$' }, maxLength: { value: 1 } } },
                { fieldType: 'date', name: 'idExpiry', label: 'Medicare Date of Expiry',
                  calendarConfig: { type: 'gregory', locale: 'en', message: 'Please select your Medicare expiry date' } }
              ]
            }
          }
        }
      },
      {
        type: 'PASSPORT',
        countries: {
          default: {
            default: {
              fields: [
                { fieldType: 'select', name: 'country', label: 'Country of Passport', options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */] },
                { fieldType: 'input', name: 'idNumber', label: 'Passport Number',
                  rules: { required: { value: true, message: 'Please enter your passport number' },
                    pattern: { value: '^[a-zA-Z0-9]+$' }, minLength: { value: 1 }, maxLength: { value: 9 } } }
              ]
            }
          },
          AUS: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Country of Passport',
                  placeholder: 'Select issuing country',
                  options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                  rules: { required: { value: true, message: 'Please select your issuing country' } }
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'idNumber',
                  label: 'Passport Number',
                  rules: {
                    required: { value: true, message: 'Please enter your passport number' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' },
                    minLength: { value: 8, message: 'Passport number must be at least 8 characters' },
                    maxLength: { value: 9, message: 'Passport number must not exceed 9 characters' }
                  }
                }
              ]
            }
          },
          NZL: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Country of Passport',
                  placeholder: 'Select issuing country',
                  options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                  rules: { required: { value: true, message: 'Please select your issuing country' } }
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'idNumber',
                  label: 'Passport Number',
                  rules: {
                    required: { value: true, message: 'Please enter your passport number' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' },
                    minLength: { value: 1, message: 'Passport number must be at least 1 character' },
                    maxLength: { value: 9, message: 'Passport number must not exceed 9 characters' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Date of Expiry',
                  rules: { required: { value: true, message: "Please enter your passport's expiry date" } },
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' },
                    dateRange: { min: { value: 'current date' }, max: { value: '+10 years from current date' } },
                    message: "Please enter your passport's expiry date"
                  }
                }
              ]
            }
          },
          IND: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Country of Passport',
                  placeholder: 'Select issuing country',
                  options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                  rules: { required: { value: true, message: 'Please select your issuing country' } }
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'idNumber',
                  label: 'Passport Number',
                  rules: {
                    required: { value: true, message: 'Please enter your passport number' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' },
                    minLength: { value: 1, message: 'Passport number must be at least 1 character' },
                    maxLength: { value: 9, message: 'Passport number must not exceed 9 characters' }
                  }
                },
                {
                  fieldType: 'input', name: 'extraData.document_number', dataType: 'document_extra',
                  label: 'File Number',
                  rules: { required: { value: true, message: 'Please enter your File Number' } }
                }
              ]
            }
          }
        }
      },
      {
        type: 'NATIONAL_ID',
        countries: {
          default: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Document Issuing Country',
                  placeholder: 'Select issuing country',
                  options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                  rules: { required: { value: true, message: 'Please select your issuing country' } }
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'idNumber',
                  label: 'Document Number',
                  rules: {
                    required: { value: true, message: 'Please enter your document number' },
                    minLength: { value: 1, message: 'Document number must be at least 1 character' }
                  }
                }
              ]
            }
          }
        }
      }
    ],
    instruction: {
      content: [
        { label: 'I confirm that all provided information is accurate.' }
      ]
    },
    cta: {
      label: 'Looks good, submit',
      timeoutRetryMiliseconds: 3000,
      retryAmount: 3,
      retryAttemptString: 'Error submitting form. Give it a moment to retry.',
      maxRetryAttemptedString: 'Something went wrong, please contact customer service or try again in a few moments.'
    }
  }
  ```
</Accordion>

<Accordion title="Doc Upload mode default">
  ```javascript theme={null}
  {
    name: 'REVIEW',
    type: 'doc_upload',
    title: { label: 'Review your documents' },
    cta: { label: 'Submit documents' }
  }
  ```
</Accordion>

### Loading

The Loading screen has different defaults per mode:

```javascript theme={null}
// OCR mode
{ name: 'LOADING', title: { label: 'Loading...' }, descriptions: [{ label: 'Data extracting...' }] }

// Manual mode
{
  name: 'LOADING',
  title: { label: 'Verifying your identity' },
  descriptions: [
    { label: "Hold tight, this can take a few seconds. Please do not refresh this page or click the 'back' button on your browser." }
  ]
}

// Doc Upload mode
{
  name: 'LOADING',
  title: { label: 'Submitting documents' },
  descriptions: [{ label: 'Please do not close this tab while your documents are being processed...' }]
}
```

### Result

The Result screen defaults vary by state. The initial state is `PENDING`.

<Note>
  **v1.9.36:** Removed the "get in touch with our customer service team" sentence from the default `creditHeaderIssueDescriptions` for every state — it implied action was needed even for recipes that don't run a credit check.
</Note>

<Accordion title="Full default config per state">
  ```javascript theme={null}
  // Base config
  { name: 'RESULT', state: 'PENDING' }

  // Defaults per state (merged based on the state value):

  // SUCCESS
  {
    title: { label: 'Congratulations, your identity has been successfully verified', shortLabel: 'Your identity has been verified' },
    creditHeaderIssueTitle: { label: 'Please Note' },
    creditHeaderIssueDescriptions: [
      { label: "The details you provided didn't match the records held on file by one or all of the credit reporting agencies we checked (Illion, Equifax and/or Experian)." },
      { label: "Don't worry, this doesn't mark or affect credit history in any way." },
      { label: 'You may now safely navigate away from this page.' }
    ],
    cta: { label: 'Done' }
  }

  // FAIL
  {
    title: { label: 'Unfortunately we are unable to verify your identity' },
    descriptions: [{ label: 'Please contact the customer support team to help you with creating your account.' }],
    creditHeaderIssueTitle: { label: 'Please Note' },
    creditHeaderIssueDescriptions: [
      { label: "The details you provided didn't match the records held on file by one or all of the credit reporting agencies we checked (Illion, Equifax and/or Experian)." },
      { label: "Don't worry, this doesn't mark or affect credit history in any way. However this could be why we've had trouble verifying your identity." },
      { label: 'You may now safely navigate away from this page.' }
    ],
    cta: { label: 'Done' }
  }

  // PENDING
  {
    title: { label: 'Thanks, your information has been submitted for verification' },
    descriptions: [{ label: "You're all done. We will be in touch once we have your results." }],
    creditHeaderIssueTitle: { label: 'Please Note' },
    creditHeaderIssueDescriptions: [
      { label: "The details you provided didn't match the records held on file by one or all of the credit reporting agencies we checked (Illion, Equifax and/or Experian)." },
      { label: "Don't worry, this doesn't mark or affect credit history in any way. However this could be why we've had trouble verifying your identity." },
      { label: 'You may now safely navigate away from this page.' }
    ],
    cta: { label: 'Done' }
  }

  // PARTIAL
  {
    title: { label: 'We are having trouble verifying your identity' },
    descriptions: [{ label: "Most of the time it's just a typo, let's check your ID details have been entered correctly." }],
    creditHeaderIssueTitle: { label: 'Please Note' },
    creditHeaderIssueDescriptions: [
      { label: "The details you provided didn't match the records held on file by one or all of the credit reporting agencies we checked (Illion, Equifax and/or Experian)." },
      { label: "Don't worry, this doesn't mark or affect credit history in any way. However this could be why we've had trouble verifying your identity." },
      { label: 'You may now safely navigate away from this page.' }
    ],
    cta: { label: 'Review details' }
  }

  // UPLOAD_SUCCESS
  {
    title: { label: 'Thanks, your document has been uploaded' },
    descriptions: [{ label: "You're all done, and can close the page." }]
  }

  // UPLOAD_FAIL
  {
    title: { label: 'There was an issue uploading your document' },
    descriptions: [{ label: 'This could be a technical issue with the upload. Please retry submitting document.' }],
    cta: { label: 'Retry submitting documents' }
  }

  // PROVIDER_ERROR
  {
    title: { label: 'We are having trouble verifying your identity' },
    descriptions: [{ label: 'Please try again a few minutes.' }],
    creditHeaderIssueTitle: { label: 'Please Note' },
    creditHeaderIssueDescriptions: [
      { label: "The details you provided didn't match the records held on file by one or all of the credit reporting agencies we checked (Illion, Equifax and/or Experian)." },
      { label: "Don't worry, this doesn't mark or affect credit history in any way. However this could be why we've had trouble verifying your identity." },
      { label: 'You may now safely navigate away from this page.' }
    ],
    cta: { label: 'Retry' }
  }

  // TIMEOUT
  {
    title: { label: 'Your session has timed out' },
    descriptions: [
      { label: 'The identity verification process took too long and has timed out. Please close this window and try again.' }
    ],
    cta: { label: 'Done' }
  }
  ```
</Accordion>

<Note>
  Unlike `SUCCESS`/`FAIL`/`PARTIAL`/`PROVIDER_ERROR`, the `TIMEOUT` state has no `creditHeaderIssueTitle`/`creditHeaderIssueDescriptions` — it isn't a credit-check-related outcome. The Result screen's `state` must be set explicitly (e.g. by the host application) when a verification attempt has timed out; the form module does not have built-in polling-timeout logic that sets this state automatically.
</Note>

### Retry

The Retry screen extends the Review config with the Personal Details fields and Document Selection documents. It adds a previous address toggle field.

<Accordion title="Full default config">
  ```javascript theme={null}
  {
    name: 'RETRY',
    title: { label: 'Review personal details' },
    descriptions: [{ label: 'We need one form of ID document to verify your identity.' }],
    personal: {
      countries: {
        default: {
          default: {
            fields: [
              {
                fieldType: 'input', dataType: 'text', name: 'givenName',
                hide: false, label: 'Given Name',
                rules: {
                  required: { value: true, message: 'Please enter your given name' },
                  pattern: {
                    value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$",
                    message: 'Please enter alphabetic characters with apostrophe only'
                  }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'middleName',
                hide: false, label: 'Middle Name(s)',
                showToggle: true,
                rules: {
                  required: { value: true, message: 'Please enter your middle name' },
                  pattern: {
                    value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$",
                    message: 'Please enter alphabetic characters with apostrophe only'
                  }
                },
                toggleConfig: {
                  label: 'Do you have any Middle Names?',
                  rules: {
                    required: { value: true, message: 'Please let us know if you have any middle names' }
                  }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'familyName',
                hide: false, label: 'Family Name',
                rules: {
                  required: { value: true, message: 'Please enter your family name' },
                  pattern: {
                    value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$",
                    message: 'Please enter alphabetic characters with apostrophe only'
                  }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'extraData.otherName',
                hide: true, label: 'Other Name(s)',
                showToggle: true,
                rules: {
                  pattern: {
                    value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$",
                    message: 'Please enter alphabetic characters with apostrophe only'
                  }
                },
                toggleConfig: {
                  label: 'Do you have any Other Names?'
                }
              },
              {
                fieldType: 'phone', dataType: 'number', name: 'extraData.phone',
                hide: true, label: 'Phone Number',
                options: [
                  { label: 'AU +61', value: '+61' },
                  { label: 'NZ +64', value: '+64' }
                ],
                placeholder: { cc: 'Code', phoneNumber: 'e.g. 0400 000 000' },
                rules: {
                  required: { value: true, message: 'Please enter the phone number' },
                  minLength: { value: 10, message: 'Phone number must be at least 10 digits' },
                  maxLength: { value: 10, message: 'Phone number must not exceed 10 characters' },
                  pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'extraData.email',
                hide: true, label: 'Email',
                rules: {
                  required: { value: true, message: 'Please enter the email' },
                  pattern: {
                    value: '^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}$',
                    message: 'Please enter a valid email address'
                  }
                }
              },
              {
                fieldType: 'date', dataType: 'text', name: 'dateOfBirth',
                hide: false, label: 'Date of Birth',
                rules: { required: { value: true, message: 'Please enter your date of birth' } },
                calendarConfig: {
                  type: 'gregory', locale: 'en',
                  day: { placeholder: 'Day' },
                  month: { placeholder: 'Month' },
                  year: { placeholder: 'Year' },
                  message: 'Please enter your date of birth'
                }
              },
              {
                fieldType: 'address', dataType: 'current_addr', name: 'address.fullAddress',
                hide: false, label: 'Residential Address',
                placeholder: 'Type in your address',
                helperText: 'Cannot be a PO Box',
                rules: { required: { value: true, message: 'Please enter your residential address' } },
                manualFieldConfig: [
                  {
                    fieldType: 'select', dataType: 'text', name: 'address.country',
                    hide: false, label: 'Country',
                    options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                    rules: { required: { value: true, message: 'Please select your country' } }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.unitNumber',
                    hide: false, label: 'Unit Number (optional)'
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.streetAddress',
                    hide: false, label: 'Street Address',
                    rules: { required: { value: true, message: 'Please enter your street address' } }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.town',
                    hide: false, label: 'Suburb / Town',
                    rules: { required: { value: true, message: 'Please enter your suburb/town.' } }
                  },
                  {
                    fieldType: 'select', dataType: 'text', name: 'address.state',
                    hide: false, label: 'State',
                    placeholder: 'Select Your State',
                    options: [
                      { label: 'Australian Capital Territory', value: 'ACT' },
                      { label: 'New South Wales', value: 'NSW' },
                      { label: 'Northern Territory', value: 'NT' },
                      { label: 'Queensland', value: 'QLD' },
                      { label: 'South Australia', value: 'SA' },
                      { label: 'Tasmania', value: 'TAS' },
                      { label: 'Victoria', value: 'VIC' },
                      { label: 'Western Australia', value: 'WA' }
                    ],
                    rules: { required: { value: true, message: 'Please select your state' } }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.postalCode',
                    hide: false, label: 'Postcode',
                    rules: {
                      required: { value: true, message: 'Please enter your postal code' },
                      minLength: { value: 0, message: '' },
                      maxLength: { value: 100, message: '' }
                    }
                  }
                ]
              },
              {
                fieldType: 'address', dataType: 'previous_addr', name: 'address1.fullAddress',
                hide: true, label: 'What was your previous residential address?',
                showToggle: true,
                title: { label: 'Residential address' },
                placeholder: 'Type in your previous address',
                rules: { required: { value: true, message: 'Please enter your previous address' } },
                toggleConfig: {
                  label: 'Have you been at your current residential address for less than 6 months?',
                  rules: { required: { value: true, message: 'Please let us know if you have any previous address' } }
                },
                manualFieldConfig: [
                  { fieldType: 'select', dataType: 'text', name: 'address1.country', hide: false, label: 'Country',
                    options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                    rules: { required: { value: true, message: 'Please select your country' } } },
                  { fieldType: 'input', dataType: 'text', name: 'address1.unitNumber', hide: false, label: 'Unit Number (optional)' },
                  { fieldType: 'input', dataType: 'text', name: 'address1.streetAddress', hide: false, label: 'Street Address',
                    rules: { required: { value: true, message: 'Please enter your street address' } } },
                  { fieldType: 'input', dataType: 'text', name: 'address1.town', hide: false, label: 'Suburb / Town',
                    rules: { required: { value: true, message: 'Please enter your suburb/town.' } } },
                  { fieldType: 'select', dataType: 'text', name: 'address1.state', hide: false, label: 'State',
                    placeholder: 'Select Your State',
                    options: [
                      { label: 'Australian Capital Territory', value: 'ACT' },
                      { label: 'New South Wales', value: 'NSW' },
                      { label: 'Northern Territory', value: 'NT' },
                      { label: 'Queensland', value: 'QLD' },
                      { label: 'South Australia', value: 'SA' },
                      { label: 'Tasmania', value: 'TAS' },
                      { label: 'Victoria', value: 'VIC' },
                      { label: 'Western Australia', value: 'WA' }
                    ],
                    rules: { required: { value: true, message: 'Please select your state' } } },
                  { fieldType: 'input', dataType: 'text', name: 'address1.postalCode', hide: false, label: 'Postcode',
                    rules: { required: { value: true, message: 'Please enter your postal code' }, minLength: { value: 0, message: '' }, maxLength: { value: 100, message: '' } } }
                ]
              }
            ]
          }
        },
        AUS: {
          default: {
            fields: [
              {
                fieldType: 'input', dataType: 'text', name: 'givenName',
                hide: false, label: 'Given Name',
                rules: {
                  required: { value: true, message: 'Please enter your given name' },
                  pattern: { value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$", message: 'Please enter alphabetic characters with apostrophe only' }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'middleName',
                hide: false, label: 'Middle Name(s)',
                showToggle: true,
                rules: {
                  required: { value: true, message: 'Please enter your middle name' },
                  pattern: { value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$", message: 'Please enter alphabetic characters with apostrophe only' }
                },
                toggleConfig: {
                  label: 'Do you have any Middle Names?',
                  rules: { required: { value: true, message: 'Please let us know if you have any middle names' } }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'familyName',
                hide: false, label: 'Family Name',
                rules: {
                  required: { value: true, message: 'Please enter your family name' },
                  pattern: { value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$", message: 'Please enter alphabetic characters with apostrophe only' }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'extraData.otherName',
                hide: true, label: 'Other Name(s)',
                showToggle: true,
                rules: { pattern: { value: "^[a-zA-Z]+(?:[''][a-zA-Z]+)*(?:\\s+[a-zA-Z]+(?:[''][a-zA-Z]+)*)*$", message: 'Please enter alphabetic characters with apostrophe only' } },
                toggleConfig: { label: 'Do you have any Other Names?' }
              },
              {
                fieldType: 'phone', dataType: 'number', name: 'extraData.phone',
                hide: true, label: 'Phone Number',
                options: [{ label: 'AU +61', value: '+61' }, { label: 'NZ +64', value: '+64' }],
                placeholder: { cc: 'Code', phoneNumber: 'e.g. 0400 000 000' },
                rules: {
                  required: { value: true, message: 'Please enter the phone number' },
                  minLength: { value: 10, message: 'Phone number must be at least 10 digits' },
                  maxLength: { value: 10, message: 'Phone number must not exceed 10 characters' },
                  pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                }
              },
              {
                fieldType: 'input', dataType: 'text', name: 'extraData.email',
                hide: true, label: 'Email',
                rules: {
                  required: { value: true, message: 'Please enter the email' },
                  pattern: { value: '^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}$', message: 'Please enter a valid email address' }
                }
              },
              {
                fieldType: 'date', dataType: 'text', name: 'dateOfBirth',
                hide: false, label: 'Date of Birth',
                rules: { required: { value: true, message: 'Please enter your date of birth' } },
                calendarConfig: {
                  type: 'gregory', locale: 'en',
                  day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' },
                  message: 'Please enter your date of birth'
                }
              },
              {
                fieldType: 'address', dataType: 'current_addr', name: 'address.fullAddress',
                hide: false, label: 'Residential Address',
                placeholder: 'Type in your address',
                helperText: 'Cannot be a PO Box',
                rules: { required: { value: true, message: 'Please enter your residential address' } },
                manualFieldConfig: [
                  {
                    fieldType: 'select', dataType: 'text', name: 'address.country',
                    hide: false, label: 'Country',
                    options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                    rules: { required: { value: true, message: 'Please select your country' } }
                  },
                  { fieldType: 'input', dataType: 'text', name: 'address.unitNumber', hide: false, label: 'Unit Number (optional)' },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.streetAddress',
                    hide: false, label: 'Street Address',
                    rules: { required: { value: true, message: 'Please enter your street address' } }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.town',
                    hide: false, label: 'Suburb / Town',
                    rules: { required: { value: true, message: 'Please enter your suburb/town.' } }
                  },
                  {
                    fieldType: 'select', dataType: 'text', name: 'address.state',
                    hide: false, label: 'State', placeholder: 'Select Your State',
                    options: [
                      { label: 'Australian Capital Territory', value: 'ACT' },
                      { label: 'New South Wales', value: 'NSW' },
                      { label: 'Northern Territory', value: 'NT' },
                      { label: 'Queensland', value: 'QLD' },
                      { label: 'South Australia', value: 'SA' },
                      { label: 'Tasmania', value: 'TAS' },
                      { label: 'Victoria', value: 'VIC' },
                      { label: 'Western Australia', value: 'WA' }
                    ],
                    rules: { required: { value: true, message: 'Please select your state' } }
                  },
                  {
                    fieldType: 'input', dataType: 'text', name: 'address.postalCode',
                    hide: false, label: 'Postcode',
                    rules: {
                      required: { value: true, message: 'Please enter your postal code' },
                      minLength: { value: 4, message: 'Postal code must be at least 4 characters' },
                      maxLength: { value: 4, message: 'Postal code must not exceed 4 characters' }
                    }
                  }
                ]
              },
              {
                fieldType: 'address', dataType: 'previous_addr', name: 'address1.fullAddress',
                hide: true, label: 'What was your previous residential address?',
                showToggle: true,
                title: { label: 'Residential address' },
                placeholder: 'Type in your previous address',
                rules: { required: { value: true, message: 'Please enter your previous address' } },
                toggleConfig: {
                  label: 'Have you been at your current residential address for less than 6 months?',
                  rules: { required: { value: true, message: 'Please let us know if you have any previous address' } }
                },
                manualFieldConfig: [
                  { fieldType: 'select', dataType: 'text', name: 'address1.country', hide: false, label: 'Country',
                    options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                    rules: { required: { value: true, message: 'Please select your country' } } },
                  { fieldType: 'input', dataType: 'text', name: 'address1.unitNumber', hide: false, label: 'Unit Number (optional)' },
                  { fieldType: 'input', dataType: 'text', name: 'address1.streetAddress', hide: false, label: 'Street Address',
                    rules: { required: { value: true, message: 'Please enter your street address' } } },
                  { fieldType: 'input', dataType: 'text', name: 'address1.town', hide: false, label: 'Suburb / Town',
                    rules: { required: { value: true, message: 'Please enter your suburb/town.' } } },
                  { fieldType: 'select', dataType: 'text', name: 'address1.state', hide: false, label: 'State',
                    placeholder: 'Select Your State',
                    options: [
                      { label: 'Australian Capital Territory', value: 'ACT' },
                      { label: 'New South Wales', value: 'NSW' },
                      { label: 'Northern Territory', value: 'NT' },
                      { label: 'Queensland', value: 'QLD' },
                      { label: 'South Australia', value: 'SA' },
                      { label: 'Tasmania', value: 'TAS' },
                      { label: 'Victoria', value: 'VIC' },
                      { label: 'Western Australia', value: 'WA' }
                    ],
                    rules: { required: { value: true, message: 'Please select your state' } } },
                  { fieldType: 'input', dataType: 'text', name: 'address1.postalCode', hide: false, label: 'Postcode',
                    rules: { required: { value: true, message: 'Please enter your postal code' }, minLength: { value: 4, message: 'Postal code must be at least 4 characters' }, maxLength: { value: 4, message: 'Postal code must not exceed 4 characters' } } }
                ]
              }
            ]
          }
        }
      }
    },
    documents: [
      {
        type: 'DRIVERS_LICENCE',
        label: "Driver's licence",
        subtitle: '(recommended)',
        countries: {
          default: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en' }
                }
              ]
            }
          },
          AUS: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 6, message: 'Licence number must be at least 6 characters' },
                    maxLength: { value: 8, message: 'Licence number must not exceed 8 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 10, message: 'Card number must be at least 10 digits' },
                    maxLength: { value: 10, message: 'Card number must not exceed 10 digits' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en' }
                }
              ]
            },
            NSW: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 6, message: 'Licence number must be at least 6 characters' },
                    maxLength: { value: 8, message: 'Licence number must not exceed 8 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. 1234567890',
                  helperText: 'You will find your Card Number on the front of your card, in the top right corner above your photo.',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 10, message: 'Card number must be at least 10 digits' },
                    maxLength: { value: 10, message: 'Card number must not exceed 10 digits' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' }
                  },
                  standardDate: true, configYear: true
                }
              ]
            },
            ACT: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 1, message: 'Licence number must be at least 1 character' },
                    maxLength: { value: 10, message: 'Licence number must not exceed 10 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 10, message: 'Card number must be at least 10 digits' },
                    maxLength: { value: 10, message: 'Card number must not exceed 10 digits' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' }
                  },
                  standardDate: true, configYear: true
                }
              ]
            },
            VIC: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 1, message: 'Licence number must be at least 1 character' },
                    maxLength: { value: 10, message: 'Licence number must not exceed 10 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. P1234567',
                  helperText: 'You will find your Card Number on the back of your card, either in the top right corner or middle right.',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 8, message: 'Card number must be at least 8 characters' },
                    maxLength: { value: 8, message: 'Card number must not exceed 8 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' }
                  },
                  standardDate: true, configYear: true
                }
              ]
            },
            QLD: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 8, message: 'Licence number must be at least 8 characters' },
                    maxLength: { value: 9, message: 'Licence number must not exceed 9 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. 1234567890',
                  helperText: 'You will find your Card Number on the front of your card, in the bottom middle, or the back of your card, on the bottom right side.',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 10, message: 'Card number must be at least 10 digits' },
                    maxLength: { value: 10, message: 'Card number must not exceed 10 digits' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' }
                  },
                  standardDate: true, configYear: true
                }
              ]
            },
            SA: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 6, message: 'Licence number must be at least 6 characters' },
                    maxLength: { value: 6, message: 'Licence number must not exceed 6 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. 1234567890',
                  helperText: 'You will find your Card Number on the back of your card, in the top right corner.',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 9, message: 'Card number must be at least 9 characters' },
                    maxLength: { value: 9, message: 'Card number must not exceed 9 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' }
                  },
                  standardDate: true, configYear: true
                }
              ]
            },
            TAS: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 6, message: 'Licence number must be at least 6 characters' },
                    maxLength: { value: 8, message: 'Licence number must not exceed 8 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. 1234567890',
                  helperText: 'You will find your Card Number on the back of your card, in the top right corner.',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 9, message: 'Card number must be at least 9 characters' },
                    maxLength: { value: 9, message: 'Card number must not exceed 9 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' }
                  },
                  standardDate: true, configYear: true
                }
              ]
            },
            NT: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 1, message: 'Licence number must be at least 1 character' },
                    maxLength: { value: 10, message: 'Licence number must not exceed 10 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. 1234567890',
                  helperText: 'The card number is located on the back of your card, either in the bottom left corner or bottom middle.',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 6, message: 'Card number must be at least 6 digits' },
                    maxLength: { value: 8, message: 'Card number must not exceed 8 digits' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' }
                  },
                  standardDate: true, configYear: true
                }
              ]
            },
            WA: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  options: [{ label: 'Australia', value: 'AUS' }, { label: 'New Zealand', value: 'NZL' }],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'select', name: 'region', dataType: 'text',
                  label: 'State or Territory of Issue',
                  options: [
                    { label: 'Australian Capital Territory', value: 'ACT' },
                    { label: 'New South Wales', value: 'NSW' },
                    { label: 'Northern Territory', value: 'NT' },
                    { label: 'Queensland', value: 'QLD' },
                    { label: 'South Australia', value: 'SA' },
                    { label: 'Tasmania', value: 'TAS' },
                    { label: 'Victoria', value: 'VIC' },
                    { label: 'Western Australia', value: 'WA' }
                  ],
                  placeholder: 'Please select',
                  rules: { required: { value: true, message: 'Please select your state' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number', placeholder: 'e.g. 1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    minLength: { value: 7, message: 'Licence number must be at least 7 characters' },
                    maxLength: { value: 7, message: 'Licence number must not exceed 7 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.document_number',
                  label: 'Card Number', placeholder: 'e.g. 1234567890',
                  helperText: 'You will find your Card Number on the back of your card, in the middle of the right side.',
                  rules: {
                    required: { value: true, message: 'Please enter your card number' },
                    minLength: { value: 8, message: 'Card number must be at least 8 characters' },
                    maxLength: { value: 10, message: 'Card number must not exceed 10 characters' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' }
                  },
                  standardDate: true, configYear: true
                }
              ]
            }
          },
          NZL: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: "Country of Driver's Licence",
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Licence Number',
                  rules: {
                    required: { value: true, message: 'Please enter your licence number' },
                    pattern: { value: '^[a-zA-Z0-9]+$', message: 'Please enter alphanumeric values only' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'number', name: 'extraData.licence_version',
                  label: 'Version Number', placeholder: 'e.g. 123',
                  rules: {
                    required: { value: true, message: 'Please enter your version number' },
                    minLength: { value: 3, message: 'Version number must be at least 3 characters' },
                    maxLength: { value: 3, message: 'Version number must not exceed 3 characters' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Expiry Date',
                  calendarConfig: { type: 'gregory', locale: 'en' }
                }
              ]
            }
          }
        }
      },
      {
        type: 'PASSPORT',
        label: 'Passport',
        countries: {
          default: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Passport Issuing Country',
                  options: [
                    // All ISO 3166-1 alpha-3 countries, sorted alphabetically by label.
                    // Contains ~250 entries in the format { label: 'Country Name', value: 'ALPHA3_CODE' }.
                    // First few: { label: 'Afghanistan', value: 'AFG' }, { label: 'Albania', value: 'ALB' }, ...
                    // Last: { label: 'Zambia', value: 'ZMB' }, { label: 'Zimbabwe', value: 'ZWE' }
                  ],
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Passport Number', placeholder: 'e.g. A1234567890',
                  rules: { required: { value: true, message: 'Please enter your passport number' } }
                }
              ]
            }
          },
          AUS: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Passport Issuing Country',
                  options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Passport Number', placeholder: 'e.g. A1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your passport number' },
                    minLength: { value: 8, message: 'Passport number must be at least 8 characters' },
                    maxLength: { value: 9, message: 'Passport number must not exceed 9 characters' }
                  }
                }
              ]
            }
          },
          NZL: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Passport Issuing Country',
                  options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Passport Number', placeholder: 'e.g. A1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your passport number' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Date of Expiry',
                  rules: {
                    required: { value: true, message: "Please enter your passport's expiry date" }
                  },
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    day: { placeholder: 'Day' }, month: { placeholder: 'Month' }, year: { placeholder: 'Year' },
                    dateRange: {
                      min: { value: 'now' },
                      max: { value: '+10 years' }
                    },
                    message: "Please enter your passport's expiry date"
                  }
                }
              ]
            }
          },
          IND: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'country',
                  label: 'Passport Issuing Country',
                  options: [/* all ISO 3166-1 alpha-3 countries, sorted alphabetically */],
                  rules: { required: { value: true, message: 'Please select a country' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Passport Number', placeholder: 'e.g. A1234567890',
                  rules: {
                    required: { value: true, message: 'Please enter your passport number' }
                  }
                },
                {
                  fieldType: 'input', name: 'extraData.document_number', dataType: 'document_extra',
                  label: 'File Number', placeholder: 'e.g. ABCD12345678',
                  rules: {
                    required: { value: true, message: 'Please enter your File Number' }
                  }
                }
              ]
            }
          }
        }
      },
      {
        type: 'NATIONAL_HEALTH_ID',
        label: 'Medicare card',
        countries: {
          default: {
            default: {
              fields: [
                {
                  fieldType: 'select', dataType: 'text', name: 'idSubType',
                  label: 'Medicare Card Colour',
                  options: [
                    { label: 'Green', value: 'G' },
                    { label: 'Blue', value: 'B' },
                    { label: 'Yellow', value: 'Y' }
                  ],
                  placeholder: 'Select Medicare Card Colour',
                  rules: { required: { value: true, message: 'Please select your Medicare card colour' } }
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'idNumber',
                  label: 'Medicare Card Number',
                  rules: {
                    required: { value: true, message: 'Please enter your Medicare card number' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' },
                    minLength: { value: 10, message: 'Medicare card number must be at least 10 digits' },
                    maxLength: { value: 10, message: 'Medicare card number must be not exceed 10 digits' }
                  }
                },
                {
                  fieldType: 'input', dataType: 'document_extra', name: 'extraData.reference',
                  label: 'Position on Card',
                  rules: {
                    required: { value: true, message: 'Please enter your position on card' },
                    pattern: { value: '^[0-9]+$', message: 'Please enter numeric values only' },
                    maxLength: { value: 1, message: 'Position on card must not exceed 1 digit' }
                  }
                },
                {
                  fieldType: 'date', dataType: 'text', name: 'idExpiry',
                  label: 'Date of Expiry',
                  rules: { required: { value: true, message: 'Please enter your Medicare expiry date' } },
                  calendarConfig: {
                    type: 'gregory', locale: 'en',
                    message: 'Please enter valid Medicare expiry date'
                  }
                },
                {
                  fieldType: 'select', dataType: 'text', name: 'middleNameDisplayType',
                  label: 'How is middle name displayed on the card?',
                  options: [
                    { label: 'No Middle Name', value: 'No middle name' },
                    { label: 'Initial Only', value: 'Initial only' },
                    { label: 'Full Middle Name', value: 'Full middle name' }
                  ]
                },
                {
                  fieldType: 'input', dataType: 'text', name: 'extraData.display_name_line1',
                  label: 'Name displayed on card',
                  disabledVisually: true
                },
                {
                  fieldType: 'hidden', dataType: 'text', name: 'extraData.display_middle_name',
                  label: 'Middle name displayed on card'
                }
              ]
            }
          }
        }
      }
    ],
    cta: { label: 'Next' },
    additionInfo: {
      label: 'Additional ID',
      descriptions: [{ label: 'We need an additional ID verify your identity.' }]
    }
  }
  ```
</Accordion>

### Doc Upload

```javascript theme={null}
{
  name: 'DOC_UPLOAD',
  mode: 'business',
  type: 'manual',
  cta: { label: 'Next' }
}
```

### Required Document Upload

```javascript theme={null}
{
  name: 'REQUIRED_DOCUMENT_UPLOAD',
  mode: 'individual',
  type: 'manual',
  title: { label: 'Required Documents' },
  descriptions: [{ label: 'All documents in this section must be uploaded' }],
  cta: { label: 'Next' }
}
```

### Partial Document Upload

```javascript theme={null}
{
  name: 'PARTIAL_DOCUMENT_UPLOAD',
  mode: 'individual',
  type: 'manual',
  title: { label: 'Additional documents' },
  descriptions: [{ label: 'Upload <b>at least one</b> document from this list' }],
  cta: { label: 'Next' }
}
```

### Optional Document Upload

```javascript theme={null}
{
  name: 'OPTIONAL_DOCUMENT_UPLOAD',
  mode: 'individual',
  type: 'manual',
  title: { label: 'Optional documents' },
  descriptions: [{ label: 'These documents are optional but may help with your application' }],
  cta: { label: 'Next' }
}
```

***

## Custom Fields

You can add custom fields to the Personal Details and Review screens. Custom field values are stored in the `extraData` object of the individual entity.

### Naming Convention

Custom field names must use the `extraData.idv.` prefix followed by your desired field name:

```
extraData.idv.{fieldName}
```

For example, a field named `extraData.idv.personTitle` will store its value under the key `idv.personTitle` in the individual's `extraData` object.

### Adding a Custom Field

To add a custom field, include it in the `fields` array of your country configuration. When you only provide custom fields (without redefining existing fields), they appear at the **top** of the form, before the default fields.

```javascript theme={null}
const personal = sdk.component('form', {
  name: 'PERSONAL',
  type: 'manual',
  personal: {
    countries: {
      default: {
        default: {
          fields: [
            {
              name: 'extraData.idv.personTitle',
              fieldType: 'input',
              dataType: 'text',
              label: 'Title',
              rules: {
                required: {
                  value: true,
                  message: 'Please enter your title'
                }
              }
            }
          ]
        }
      }
    }
  }
});
```

<Warning>
  You must define custom fields for **all** your supported countries. Configuration overrides are merged, so if you only define a custom field under one country (e.g., `AUS`), other countries will use the built-in default without your custom field — producing inconsistent forms. If you use country-specific configurations (e.g., `AUS`, `NZL`), each country entry must include the custom field.
</Warning>

***

## Field Ordering

To control the order of fields on the Personal Details screen, redefine the `fields` array with entries in the desired order. Each entry needs at least the `name` property to reference an existing default field.

### How It Works

* Fields appear in the order they are listed in the `fields` array
* To reference an existing default field, include an entry with just `{ name: 'fieldName' }` — the default properties are preserved
* To add a custom field at a specific position, insert it at the desired index in the array
* Fields from the default configuration that are **not** included in your array will appear after your defined fields

### Reordering Default Fields

For example, if the default order is `givenName`, `middleName`, `familyName` and you want `familyName` first:

```javascript theme={null}
const personal = sdk.component('form', {
  name: 'PERSONAL',
  type: 'manual',
  personal: {
    countries: {
      default: {
        default: {
          fields: [
            { name: 'familyName' },
            { name: 'givenName' },
            { name: 'middleName' }
          ]
        }
      }
    }
  }
});
```

### Inserting a Custom Field at a Specific Position

To insert a custom field after `givenName`, redefine `givenName` (with just `name`) and place the custom field right after it:

```javascript theme={null}
const personal = sdk.component('form', {
  name: 'PERSONAL',
  type: 'manual',
  personal: {
    countries: {
      default: {
        default: {
          fields: [
            { name: 'givenName' },
            {
              name: 'extraData.idv.personTitle',
              fieldType: 'input',
              dataType: 'text',
              label: 'Title',
              rules: {
                required: {
                  value: true,
                  message: 'Please enter your title'
                }
              }
            }
          ]
        }
      }
    }
  }
});
```

This places `Title` directly after `Given Name`, with all remaining default fields (`middleName`, `familyName`, `dateOfBirth`, address) following after.

***

## Document Upload Configuration

Document upload is configured through the recipe's `docUpload` property:

```javascript theme={null}
const sdk = await OneSdk({
  session: { token: 'your-token' },
  recipe: {
    form: {
      provider: {
        name: 'react',
        googleApiKey: 'your-key'
      },
      docUpload: {
        requestedDocuments: [
          { documentType: 'PROOF_OF_ADDRESS' },
          { documentType: 'BANK_STATEMENT' }
        ],
        partialDocuments: [
          {
            title: 'Additional Identity Documents',
            minimumRequirement: 1,
            documents: [
              { documentType: 'BIRTH_CERTIFICATE' },
              { documentType: 'UTILITY_BILL' },
              { documentType: 'TAX_RETURN' }
            ]
          }
        ],
        optionalDocuments: [
          { documentType: 'EMPLOYMENT_LETTER' }
        ]
      }
    }
  }
});
```

### DocUploadRecipeOptions

| Property             | Type    | Description                                                                   |
| -------------------- | ------- | ----------------------------------------------------------------------------- |
| `requestedDocuments` | `array` | Documents that **must** be uploaded. Each item has a `documentType` property. |
| `partialDocuments`   | `array` | Groups of documents where a minimum number must be uploaded.                  |
| `optionalDocuments`  | `array` | Documents that **may** be uploaded but are not required.                      |

### Partial Documents

| Property             | Type     | Description                                           |
| -------------------- | -------- | ----------------------------------------------------- |
| `title`              | `string` | Title displayed for this document group               |
| `documents`          | `array`  | Available documents in this group                     |
| `minimumRequirement` | `number` | Minimum number of documents to upload from this group |

### Document Upload Validation

File uploads support validation rules:

```typescript theme={null}
type DocUploadRules = {
  min_size?: { value: number; message: string };
  max_size?: { value: number; message: string };
  mime?: {
    value: {
      'image/jpeg'?: boolean;
      'image/png'?: boolean;
      'image/gif'?: boolean;
      'image/webp'?: boolean;
      'image/tiff'?: boolean;
      'image/bmp'?: boolean;
      'application/pdf'?: boolean;
    };
    message: string;
  }
}
```

***

## Screen Configuration Examples

### Customizing the Welcome Screen

```javascript theme={null}
const welcome = sdk.component('form', {
  name: 'WELCOME',
  mode: 'individual',
  type: 'manual',
  // Welcome screen customization (as part of TPageConfig)
  welcome: {
    name: 'WELCOME',
    logo: { src: 'https://your-logo-url.com/logo.png' },
    title: {
      label: 'Verify Your Identity',
      style: {
        'ff-title': { color: '#1a1a1a', fontSize: '32px' }
      }
    },
    subtitle: {
      label: 'We need to verify your identity to continue.'
    },
    descriptions: [
      { label: 'This process takes about 2 minutes' },
      { label: 'Have your ID document ready' }
    ],
    cta: {
      label: 'Start Verification'
    },
    style: {
      'ff-wrapper': { maxWidth: '500px', margin: '0 auto' },
      font: { name: 'Inter', url: 'https://fonts.googleapis.com/css2?family=Inter' }
    }
  }
});
```

### Customizing the Result Screen

```javascript theme={null}
const result = sdk.component('form', {
  name: 'RESULT',
  type: 'manual',
  state: 'SUCCESS',
  title: { label: 'Verification Complete' },
  descriptions: [
    { label: 'Your identity has been verified.' }
  ],
  cta: {
    label: 'Continue to Dashboard',
    onClick: () => window.location.href = '/dashboard'
  }
});
```

***

## Country-Specific Field Configuration

In manual mode, form fields can be configured per country and state using the `CountryConfig` type. This is used in two places:

* **Document Selection screen** — inside each entry of the [`documents`](#idocuments) array, via the `countries` property
* **Personal Details screen** — via the `personal.countries` property

```typescript theme={null}
type CountryConfig = {
  [countryCode: string]: {     // e.g., 'AUS', 'NZL', 'default'
    [stateCode: string]: {     // e.g., 'NSW', 'VIC', 'default'
      image?: string;
      fields: FormField[];
    }
  }
}
```

Use `'default'` as a fallback key when no specific country or state match is found.

### Document-Type-Specific Configuration

On the Document Selection screen, the `countries` configuration is nested **within each document type** in the `documents` array. This means the full configuration hierarchy has three levels:

1. **Document type** — e.g., `DRIVERS_LICENCE`, `PASSPORT`, `NATIONAL_HEALTH_ID`
2. **Country** — e.g., `AUS`, `NZL`, `default`
3. **State** — e.g., `NSW`, `VIC`, `default`

Each document type carries its own independent `CountryConfig`, so different document types can require entirely different fields for the same country. For example, a driver's licence in Australia requires a licence number and card number, while a passport for the same country requires a passport number and expiry date.

```javascript theme={null}
const document = sdk.component('form', {
  name: 'DOCUMENT',
  mode: 'individual',
  type: 'manual',
  numberOfIDs: 2,
  documents: [
    {
      // Document type level
      type: 'DRIVERS_LICENCE',
      countries: {
        // Country level
        AUS: {
          // State level
          NSW: {
            fields: [
              { fieldType: 'input', name: 'licenceNumber', title: { label: 'Licence Number' } },
              { fieldType: 'input', name: 'cardNumber', title: { label: 'Card Number' } }
            ]
          },
          default: {
            fields: [
              { fieldType: 'input', name: 'licenceNumber', title: { label: 'Licence Number' } }
            ]
          }
        }
      }
    },
    {
      // Different document type — different fields for the same country
      type: 'PASSPORT',
      countries: {
        AUS: {
          default: {
            fields: [
              { fieldType: 'input', name: 'passportNumber', title: { label: 'Passport Number' } },
              { fieldType: 'date', name: 'expiryDate', title: { label: 'Expiry Date' } }
            ]
          }
        },
        default: {
          default: {
            fields: [
              { fieldType: 'input', name: 'passportNumber', title: { label: 'Passport Number' } }
            ]
          }
        }
      }
    }
  ]
});
```

The Personal Details screen does not have the document-type level — it uses `CountryConfig` directly under `personal.countries`.

**Document Selection example:**

Configures country and state-specific fields for each document type. When a user selects a country (e.g., Australia) and state (e.g., NSW), the matching field configuration is used. The `'default'` key acts as a fallback.

```javascript theme={null}
const document = sdk.component('form', {
  name: 'DOCUMENT',
  mode: 'individual',
  type: 'manual',
  numberOfIDs: 2,
  documents: [
    {
      type: 'DRIVERS_LICENCE',
      countries: {
        // Australia — with state-specific fields
        AUS: {
          NSW: {
            fields: [
              { fieldType: 'input', name: 'licenceNumber', title: { label: 'Licence Number' } },
              { fieldType: 'input', name: 'cardNumber', title: { label: 'Card Number' } },
              { fieldType: 'date', name: 'expiryDate', title: { label: 'Expiry Date' } }
            ]
          },
          VIC: {
            fields: [
              { fieldType: 'input', name: 'licenceNumber', title: { label: 'Licence Number' } },
              { fieldType: 'date', name: 'expiryDate', title: { label: 'Expiry Date' } }
            ]
          },
          // Fallback for other Australian states
          default: {
            fields: [
              { fieldType: 'input', name: 'licenceNumber', title: { label: 'Licence Number' } },
              { fieldType: 'date', name: 'expiryDate', title: { label: 'Expiry Date' } }
            ]
          }
        },
        // New Zealand — no state-level distinction
        NZL: {
          default: {
            fields: [
              { fieldType: 'input', name: 'licenceNumber', title: { label: 'Licence Number' } },
              { fieldType: 'input', name: 'version', title: { label: 'Version Number' } }
            ]
          }
        },
        // Fallback for all other countries
        default: {
          default: {
            fields: [
              {
                fieldType: 'select',
                name: 'country',
                options: [
                  { label: 'Australia', value: 'AUS' },
                  { label: 'New Zealand', value: 'NZL' }
                ]
              }
            ]
          }
        }
      }
    },
    {
      type: 'PASSPORT',
      countries: {
        default: {
          default: {
            fields: [
              {
                fieldType: 'select',
                name: 'country',
                options: [
                  { label: 'Australia', value: 'AUS' },
                  { label: 'New Zealand', value: 'NZL' }
                ]
              }
            ]
          }
        }
      }
    }
  ]
});
```

**Personal Details example:**

Configures country-specific personal detail fields. Different countries can require different fields or validation rules.

```javascript theme={null}
const personal = sdk.component('form', {
  name: 'PERSONAL',
  mode: 'individual',
  type: 'manual',
  personal: {
    countries: {
      // Australia — stricter age range
      AUS: {
        default: {
          fields: [
            {
              fieldType: 'date',
              dataType: 'text',
              name: 'dateOfBirth',
              hide: false,
              calendarConfig: {
                age: {
                  min: 18,
                  max: 65,
                  message: 'The age must be between 18 and 65'
                }
              }
            }
          ]
        }
      },
      // Fallback for all other countries
      default: {
        default: {
          fields: [
            {
              fieldType: 'date',
              dataType: 'text',
              name: 'dateOfBirth',
              hide: false,
              calendarConfig: {
                age: {
                  min: 16,
                  max: 80,
                  message: 'The age must be between 16 and 80'
                }
              }
            }
          ]
        }
      }
    }
  }
});
```

The lookup order is:

1. Exact country + exact state match (e.g., `AUS` → `NSW`)
2. Exact country + `default` state (e.g., `AUS` → `default`)
3. `default` country + `default` state

***

## Related

* [Form Module Overview](/docs/sdk-reference/form-module)
* [Form Screens](/docs/sdk-reference/form-module/screens)
* [Individual Module - Document Structure](/docs/sdk-reference/individual-module#document-structure)


# Form Screens
Source: https://docs.frankieone.com/docs/sdk-reference/form-module/screens

Complete reference for all form module screens and their events

## 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`](/docs/sdk-reference/form-module/configuration#page-configuration-types) only)      | review, result, doc\_upload             |
| `partial`  | CTA pressed on a PARTIAL-state result screen, or partial verification result (review with [`customResult`](/docs/sdk-reference/form-module/configuration#page-configuration-types) only) | review, result                          |
| `pending`  | CTA pressed on a PENDING-state result screen, or verification pending (review with [`customResult`](/docs/sdk-reference/form-module/configuration#page-configuration-types) 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:

```typescript theme={null}
{
  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

<Note>
  All examples below assume the SDK has been initialized:

  ```javascript theme={null}
  const sdk = await OneSdk({
    session: { token: 'your-token' },
    recipe: {
      form: {
        provider: {
          name: 'react',
          googleApiKey: 'your-google-api-key'
        }
      }
    }
  });
  ```
</Note>

### 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:**

```javascript theme={null}
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              |

***

### Consent

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:**

```javascript theme={null}
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.

<Note>
  In OCR mode, the Document Selection screen is a legacy feature tied to headless OCR flows. Modern integrations use the [IDV flow](/docs/sdk-reference/idv-module) for document capture and the form [Review screen](#review) to display extracted data.
</Note>

**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:**

```javascript theme={null}
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:**

```javascript theme={null}
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`](/docs/sdk-reference/form-module/configuration#page-configuration-types), submits the data for verification and navigates to the appropriate result screen automatically. When [`customResult: true`](/docs/sdk-reference/form-module/configuration#page-configuration-types) 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             |

<Warning>
  **`form:review:failed/success/partial/pending` require [`customResult: true`](/docs/sdk-reference/form-module/configuration#page-configuration-types) 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`](/docs/sdk-reference/form-module/configuration#page-configuration-types) and [`customResult`](/docs/sdk-reference/form-module/configuration#page-configuration-types) in the configuration reference.
</Warning>

**Example (with `customResult: true`):**

```javascript theme={null}
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:**

```javascript theme={null}
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:**

```javascript theme={null}
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.

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

**Retry Flow:**

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

**Example with retry limit:**

```javascript theme={null}
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:**

```javascript theme={null}
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

```javascript theme={null}
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');
```

***

## Related

* [Form Module Overview](/docs/sdk-reference/form-module)
* [Form Configuration](/docs/sdk-reference/form-module/configuration)
* [Event System](/docs/sdk-reference/events)


# IDV Module
Source: https://docs.frankieone.com/docs/sdk-reference/idv-module

Complete reference for the IDV (Identity Verification) module

## Overview

The IDV (Identity Verification) module provides an integrated document capture and biometric verification flow through third-party provider integrations. It manages the complete identity verification process with minimal configuration required.

## Consent Requirement

<Warning>
  **Consent must be collected before mounting the IDV flow.** Without consent, verification submission will fail. Use the [Form Module](/docs/sdk-reference/form-module) CONSENT screen to collect consent from the user before calling `idv.mount()`. See the [IDV Flow guide](/docs/embedded-flows/idv) for a complete example.
</Warning>

## Accessing the Module

The IDV module is accessed through the SDK's flow factory:

```javascript theme={null}
const sdk = await OneSdk({
  mode: 'production',
  session: { token: 'your-token' }
});

// Create IDV flow instance
const idvFlow = sdk.flow('idv', options);
```

## Supported Providers

The IDV module supports multiple identity verification providers:

| Provider | Value      | Learn More                       |
| -------- | ---------- | -------------------------------- |
| Onfido   | `'onfido'` | [onfido.com](https://onfido.com) |
| Sumsub   | `'sumsub'` | [sumsub.com](https://sumsub.com) |
| Incode   | `'incode'` | [incode.com](https://incode.com) |
| Truuth   | `'truuth'` | [truuth.id](https://truuth.id)   |
| Daon     | `'daon'`   | [daon.com](https://www.daon.com) |

<Note>
  Each provider has different capabilities, UI/UX, supported documents, and geographic coverage. Visit the provider's website to understand their specific features and limitations.
</Note>

***

## Configuration Options

### Basic Configuration

```javascript theme={null}
const idvFlow = sdk.flow('idv', {
  provider: {
    name: 'onfido'
  }
});
```

### Common Options

In addition to provider-specific settings, you can configure:

| Option                | Type     | Description                                                                |
| --------------------- | -------- | -------------------------------------------------------------------------- |
| `documents`           | `array`  | Array of document configurations specifying types and countries (optional) |
| `checkProcessingPool` | `object` | Configure check processing polling behavior (optional)                     |

**Documents Array:**

```javascript theme={null}
documents: [
  {
    type: 'DRIVERS_LICENCE',     // Document type
    countries: ['AUS', 'NZL']    // ISO country codes (optional)
  }
]
```

<Callout icon="bell">
  **Daon provider:** The `documents` parameter and document selection are not required when using the Daon provider — Daon provides its own document type selection screen. To use custom document selection instead of Daon's built-in screen, contact your FrankieOne account team.
</Callout>

**Check Processing Pool:**

```javascript theme={null}
checkProcessingPool: {
  enabled: true,      // Enable polling for check results
  wait_time: 5,       // Wait time between polls (seconds)
  max_attempts: 1     // Maximum polling attempts
}
```

### Provider-Specific Options

#### Onfido Provider

```javascript theme={null}
const idvFlow = sdk.flow('idv', {
  provider: {
    name: 'onfido',
    sdkVersion: '13.0.0',          // Onfido SDK version
    theme: 'light',                 // 'light' or 'dark'
    language: 'en_GB',              // UI language (optional)
    translations: {                 // Custom translation strings (optional)
      // See Onfido documentation for translation keys
    },
    maxDocumentCount: 3,            // Maximum documents to capture
    product: 'idv',                 // Product type
    biometricsVariant: 'standard',  // 'standard', 'video', or 'motion'
    useOneStep: false,              // Enable one-step capture
    showExitButton: true,           // Show exit button in UI
    fallback: 'standard',           // Fallback method: 'standard' or 'video'
    crossDevicePolicy: 'disable',   // Cross-device flow: 'force' or 'disable'
    customUI: {                     // Custom UI configuration
      // See Onfido documentation for customUI options
    }
  }
});
```

**Onfido Options:**

| Option              | Type                    | Description                                                                                                                                                                                                                                                                                                                     |
| ------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sdkVersion`        | `string`                | Version of the Onfido SDK to use. Default: `'12'`. Refer to the [Onfido documentation](https://documentation.onfido.com/sdk/changelog/) for available versions.                                                                                                                                                                 |
| `theme`             | `'light' \| 'dark'`     | UI theme                                                                                                                                                                                                                                                                                                                        |
| `language`          | `string`                | Language code for the Onfido UI. Requires `sdkVersion` 14 or later. When `useOneStep` is `false`, this is forwarded to both the OCR and Biometrics sub-components. See supported values below.                                                                                                                                  |
| `translations`      | `object`                | Custom translation strings to override default Onfido copy. Keys must match Onfido's translation key schema — see the [Onfido language customisation docs](https://documentation.onfido.com/sdk/web/#language-customisation). Requires `sdkVersion` 14 or later. Also forwarded to sub-components when `useOneStep` is `false`. |
| `maxDocumentCount`  | `number`                | Maximum number of documents to capture                                                                                                                                                                                                                                                                                          |
| `product`           | `'idv'`                 | Product type (always `'idv'` for IDV module)                                                                                                                                                                                                                                                                                    |
| `biometricsVariant` | `string`                | Biometric capture variant: `'standard'`, `'video'`, or `'motion'`                                                                                                                                                                                                                                                               |
| `useOneStep`        | `boolean`               | Enable one-step capture workflow                                                                                                                                                                                                                                                                                                |
| `showExitButton`    | `boolean`               | Display exit button in the UI                                                                                                                                                                                                                                                                                                   |
| `fallback`          | `'standard' \| 'video'` | Fallback biometric method                                                                                                                                                                                                                                                                                                       |
| `crossDevicePolicy` | `'force' \| 'disable'`  | Enable/disable cross-device flow                                                                                                                                                                                                                                                                                                |
| `customUI`          | `object`                | Custom UI configuration object                                                                                                                                                                                                                                                                                                  |

**Supported `language` values:**

`ar`, `bg`, `cs`, `da`, `de`, `el`, `en_GB`, `en_US`, `es`, `es_419`, `es_DO`, `et`, `fa`, `fi`, `fr`, `fr_CA`, `he`, `hi`, `hr`, `hu`, `hy`, `id`, `it`, `ja`, `ko`, `lt`, `lv`, `ms`, `nl`, `no`, `pl`, `pt`, `pt_BR`, `ro`, `ru`, `sk`, `sl`, `sr`, `sv`, `th`, `tr`, `uk`, `vi`, `zh_CN`, `zh_TW`

***

#### Incode Provider

```javascript theme={null}
const idvFlow = sdk.flow('idv', {
  provider: {
    name: 'incode',
    product: 'idv',
    lang: 'en'  // Language code
  }
});
```

**Incode Options:**

| Option    | Type     | Description                                                          |
| --------- | -------- | -------------------------------------------------------------------- |
| `product` | `'idv'`  | Product type (required)                                              |
| `lang`    | `string` | Language code (e.g., `'en'`, `'es'`, `'fr'`, `'de'`, `'pt'`, `'zh'`) |

**Supported Languages:**
`'bn'`, `'ca'`, `'zh'`, `'hr'`, `'nl'`, `'en'`, `'en-BZ'`, `'en-DG'`, `'fr'`, `'de'`, `'ht'`, `'hi'`, `'hmn'`, `'hu'`, `'id'`, `'it'`, `'ms'`, `'pl'`, `'pt'`, `'pt-BR'`, `'pt-PT'`, `'ro'`, `'sr'`, `'sr-LATN'`, `'so'`, `'es'`, `'es-ES'`, `'tl-PH'`, `'tr'`, `'vi'`

***

#### Sumsub Provider

```javascript theme={null}
const idvFlow = sdk.flow('idv', {
  provider: {
    name: 'sumsub',
    product: 'idv',  // or 'poa' for proof of address
    config: {
      theme: 'light',  // 'light' or 'dark'
      lang: 'en',      // Language code (optional)
      email: 'user@example.com',  // Pre-fill email (optional)
      phone: '+1234567890'        // Pre-fill phone (optional)
    },
    options: {
      addViewportTag: true,      // Add viewport meta tag
      adaptIframeHeight: true    // Auto-adjust iframe height
    }
  }
});
```

**Sumsub Options:**

| Option    | Type             | Description                                                                     |
| --------- | ---------------- | ------------------------------------------------------------------------------- |
| `product` | `'idv' \| 'poa'` | Product type: `'idv'` for identity verification or `'poa'` for proof of address |
| `config`  | `object`         | Sumsub configuration object (see Config table below)                            |
| `options` | `object`         | Sumsub SDK options (see Options table below)                                    |

**Sumsub Config Object:**

| Property | Type                | Required | Description                                  |
| -------- | ------------------- | -------- | -------------------------------------------- |
| `theme`  | `'dark' \| 'light'` | Yes      | UI theme                                     |
| `lang`   | `string`            | No       | Language code (e.g., `'en'`, `'es'`, `'fr'`) |
| `email`  | `string`            | No       | Pre-fill user's email address                |
| `phone`  | `string`            | No       | Pre-fill user's phone number                 |

**Sumsub Options Object:**

| Property            | Type      | Required | Description                                   |
| ------------------- | --------- | -------- | --------------------------------------------- |
| `addViewportTag`    | `boolean` | Yes      | Whether to add viewport meta tag to page      |
| `adaptIframeHeight` | `boolean` | Yes      | Whether to automatically adjust iframe height |

***

#### Truuth Provider

```javascript theme={null}
const idvFlow = sdk.flow('idv', {
  provider: {
    name: 'truuth',
    sdkVersion: '1.0.0'  // Optional SDK version
  }
});
```

**Truuth Options:**

| Option       | Type     | Description                                                                                               |
| ------------ | -------- | --------------------------------------------------------------------------------------------------------- |
| `sdkVersion` | `string` | Version of the Truuth SDK to use. Default: `'1.0'`. Refer to Truuth documentation for available versions. |

***

#### Daon Provider

```javascript theme={null}
const idvFlow = sdk.flow('idv', {
  provider: {
    name: 'daon',
    products: ['IdentityX', 'VeriFLY'],  // Daon products to use
    processInstanceParameters: [
      {
        name: 'param1',
        mandatory: true,
        default: 'value'
      }
    ]
  }
});
```

***

## Methods

### `mount()`

Mounts the IDV component to a DOM element and starts the verification flow.

**Signature:**

```typescript theme={null}
mount(domElementOrSelector: string | HTMLElement): void
```

**Parameters:**

| Parameter              | Type                    | Required | Description                                                                                              |
| ---------------------- | ----------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `domElementOrSelector` | `string \| HTMLElement` | Yes      | CSS selector string (e.g., `'#idv-container'`) or HTMLElement object where the component will be mounted |

**Description:**
Mounts the IDV Smart UI to the specified DOM element and initiates the identity verification flow. The provider's interface will be displayed within this element.

**Example:**

```javascript theme={null}
// Mount to element by ID
idvFlow.mount('#idv-container');

// Mount to element reference
const container = document.getElementById('idv-container');
idvFlow.mount(container);
```

***

### `unmount()`

Unmounts the IDV component from the DOM.

**Signature:**

```typescript theme={null}
unmount(): void
```

**Description:**
Removes the IDV component from the DOM and cleans up resources. Call this when the user navigates away or the verification flow is complete.

**Example:**

```javascript theme={null}
idvFlow.unmount();
```

***

### `isPreloaded()`

Checks if IDV data has been previously captured for this entity.

**Signature:**

```typescript theme={null}
isPreloaded(): boolean
```

**Returns:** `boolean` - `true` if IDV verification data exists for this entity, `false` otherwise

**Description:**
Returns `true` if the entity has existing IDV verification data (indicated by an attestation document). This allows you to skip the verification flow for returning users who have already completed identity verification.

The method checks:

1. Whether the individual module has preloaded data
2. Whether the entity has an attestation document (indicating completed IDV verification)

**Example:**

```javascript theme={null}
const idvFlow = sdk.flow('idv', {
  provider: { name: 'onfido' }
});

if (idvFlow.isPreloaded()) {
  console.log('User has completed IDV verification');
  // Skip verification, proceed to next step
  proceedToNextStep();
} else {
  console.log('User needs to complete IDV verification');
  // Mount and start verification
  idvFlow.mount('#idv-container');
}
```

**Use Cases:**

* Skip verification UI for returning users with completed IDV
* Show different messaging for users with existing verification
* Conditionally render verification components based on verification status

<Warning>
  This method checks for the presence of verification data, not the verification result. A user may have completed verification but failed checks. Always verify the actual verification status through your backend before granting access.
</Warning>

***

### `access()`

Accesses reactive data accessors for the IDV component state.

**Signature:**

```typescript theme={null}
access(fieldName: string): Accessor
```

**Returns:** Currently returns `void` (not implemented)

**Note:** This method is present for API consistency but is not yet implemented for the IDV module.

***

### `statuses`

Object containing all possible IDV status constants.

**Type:** `Readonly<typeof IDVStatus>`

**Description:**
Provides access to IDV status enum values for comparison in event handlers and status checks.

**Available Statuses:**

<Note>
  **Provider-Specific:** Not all statuses are used by all providers. The specific statuses emitted depend on your chosen verification provider's workflow and capabilities.
</Note>

| Status                  | Value                                     | Description                                           |
| ----------------------- | ----------------------------------------- | ----------------------------------------------------- |
| `CHECK_NOT_STARTED`     | `'CHECK_NOT_STARTED'`                     | Verification check has not been initiated             |
| `CHECK_PROCESSING`      | `'CHECK_PROCESSING'`                      | Verification check is currently processing            |
| `COMPLETE`              | `'COMPLETE'`                              | Verification completed successfully                   |
| `FAILED`                | `'FAILED'`                                | Verification failed                                   |
| `INCOMPLETE`            | `'INCOMPLETE'`                            | Verification incomplete (missing data or steps)       |
| `DOCUMENTS_INVALID`     | `'AWAITING_DOCUMENT_UPLOAD_INVALID_TYPE'` | Provided documents are invalid                        |
| `PROVIDER_OFFLINE`      | `'PROVIDER_OFFLINE'`                      | Verification provider is offline/unavailable          |
| `AWAITING_CONSENT`      | `'AWAITING_CONSENT'`                      | Waiting for user consent                              |
| `WAITING_SELFIE_UPLOAD` | `'WAITING_SELFIE_UPLOAD'`                 | Waiting for selfie/biometric upload                   |
| `WAITING_DOC_UPLOAD`    | `'WAITING_DOC_UPLOAD'`                    | Waiting for document upload                           |
| `INTERRUPTED`           | `'INTERRUPTED'`                           | Verification flow was interrupted (provider-specific) |

**Status-to-Event Mapping:**

The `results` event only fires for terminal statuses. Non-terminal statuses surface through other events. The exact mapping varies by provider.

<Tabs>
  <Tab title="Default">
    Used by **Sumsub**, **Incode**, **Daon**, **Mastercard**, and **OcrLabs**. These providers call the backend `initProcess` endpoint after the vendor flow completes and map the returned status to events using the common mapping.

    | Status                  | Event            |
    | ----------------------- | ---------------- |
    | `COMPLETE`              | `results`        |
    | `FAILED`                | `results`        |
    | `INCOMPLETE`            | `input_required` |
    | `DOCUMENTS_INVALID`     | `input_required` |
    | `WAITING_SELFIE_UPLOAD` | `input_required` |
    | `WAITING_DOC_UPLOAD`    | `input_required` |
    | `INTERRUPTED`           | `input_required` |
    | `PROVIDER_OFFLINE`      | `error`          |
    | `AWAITING_CONSENT`      | `error`          |
    | `CHECK_PROCESSING`      | `processing`     |

    <Note>
      **Daon** enables check processing polling by default. If the initial status is not `COMPLETE` or `FAILED`, the SDK polls the backend until a terminal status is reached, then emits `results`.
    </Note>
  </Tab>

  <Tab title="Onfido">
    Onfido does **not** use the common status mapping. Instead, it delegates to internal OCR and Biometrics sub-modules, which emit events directly.

    **Two-step mode (default):** The IDV module creates separate OCR and Biometrics components. Events from each sub-component (`results`, `input_required`, `error`, `detection_complete`, `detection_failed`) are forwarded to the IDV event hub. The status values in these events come from the sub-modules' own processing.

    **One-step mode** (`useOneStep: true`)**:** The Onfido SDK handles both document and face capture in a single flow. On completion, the biometrics `initProcess` is called. Its mapping differs from the default:

    | Status                  | Event        |
    | ----------------------- | ------------ |
    | `COMPLETE`              | `results`    |
    | `FAILED`                | `results`    |
    | `DOCUMENTS_INVALID`     | `error`      |
    | `WAITING_DOC_UPLOAD`    | `error`      |
    | `WAITING_SELFIE_UPLOAD` | `error`      |
    | `PROVIDER_OFFLINE`      | `error`      |
    | `AWAITING_CONSENT`      | `error`      |
    | `CHECK_PROCESSING`      | `processing` |

    In one-step mode, if the user exits, `input_required` is emitted with `INTERRUPTED` status, along with `detection_failed` and `session_interrupted`.

    <Note>
      **Secondary error on SDK failure (one-step mode):** If the Onfido SDK itself reports an error (its `onError` callback), OneSDK emits an `error` event for that SDK failure, then automatically re-triggers the biometrics `initProcess` call to attempt to resolve the check. If that retry also fails, a **second** `error` event is emitted for the `initProcess` failure. Listeners should not assume a single `error` event per failed attempt in one-step mode — up to two `error` events can fire in sequence for the same user action.
    </Note>
  </Tab>

  <Tab title="Truuth">
    Truuth has its own status interpretation based on the provider's `userBehaviourChecks` response. It emits `input_required` directly for non-complete statuses **before** calling the backend, treating them as recoverable conditions.

    | Status                  | Event                                              |
    | ----------------------- | -------------------------------------------------- |
    | `COMPLETE`              | `results` (via common mapping after `initProcess`) |
    | `FAILED`                | `results` (via common mapping after `initProcess`) |
    | `INCOMPLETE`            | `input_required`                                   |
    | `AWAITING_CONSENT`      | `input_required`                                   |
    | `WAITING_DOC_UPLOAD`    | `input_required`                                   |
    | `WAITING_SELFIE_UPLOAD` | `input_required`                                   |
    | `INTERRUPTED`           | `input_required`                                   |
    | `CHECK_PROCESSING`      | `processing` (via polling)                         |

    <Note>
      Unlike other providers, Truuth maps `AWAITING_CONSENT` to `input_required` rather than `error`, treating consent rejection as a recoverable user action. Truuth also enables check processing polling when the vendor reports processing has started.
    </Note>
  </Tab>
</Tabs>

**Example:**

```javascript theme={null}
const idvFlow = sdk.flow('idv', { provider: { name: 'onfido' } });

idvFlow.on('input_required', (info, status) => {
  if (status === idvFlow.statuses.WAITING_DOC_UPLOAD) {
    console.log('Waiting for document upload');
  } else if (status === idvFlow.statuses.WAITING_SELFIE_UPLOAD) {
    console.log('Waiting for selfie upload');
  }
});

idvFlow.on('results', (results) => {
  if (results.checkStatus === idvFlow.statuses.COMPLETE) {
    console.log('Verification completed successfully');
  } else if (results.checkStatus === idvFlow.statuses.FAILED) {
    console.log('Verification failed');
  }
});
```

***

## Events

The IDV module emits events throughout the verification lifecycle.

<Warning>
  **Provider-Specific Behavior:** Events and statuses vary by provider. Not all providers emit all events, and some events are provider-specific. Always test with your chosen provider to understand which events are emitted and when.
</Warning>

### `session_data_generated`

Emitted when session data for the vendor is generated.

**Arguments:**

```typescript theme={null}
{
  session: {
    entityId: string | null;
    vendorParameters: object;
  }
}
```

**Example:**

```javascript theme={null}
idvFlow.on('session_data_generated', ({ session }) => {
  console.log('Session created for entity:', session.entityId);
  console.log('Vendor parameters:', session.vendorParameters);
});
```

***

### `detection_complete`

Emitted when initial detection/capture is complete.

**Arguments:** None

**Example:**

```javascript theme={null}
idvFlow.on('detection_complete', () => {
  console.log('Document and biometric capture complete');
  showProcessingMessage();
});
```

***

### `detection_failed`

Emitted when detection/capture fails.

**Arguments:**

```typescript theme={null}
{
  message: string;
  payload?: Record<string, unknown>;
}
```

**Example:**

```javascript theme={null}
idvFlow.on('detection_failed', ({ message, payload }) => {
  console.error('Detection failed:', message);
  console.error('Details:', payload);
  showErrorMessage(message);
});
```

***

### `input_required`

Emitted when a non-positive flow has occurred but is likely recoverable by retrying.

**Arguments:**

```typescript theme={null}
(
  info: { entityId: string | null },
  status: IDVStatus
)
```

**Description:**
Emitted when the check could not be completed due to user input — not because of a system failure. For example, the user uploaded the wrong document type, or the user closed the session before completing it. Retrying the step will always help resolve `input_required`.

Common scenarios:

* Waiting for document or selfie upload
* Awaiting user consent
* User closed or interrupted the verification session (remounting the module allows them to resume)

<Note>
  There is no way to differentiate between user abandonment and session timeout within the SDK. Both surface as `input_required` with `INTERRUPTED` status. Whether to limit retry attempts depends on your business process.
</Note>

**Example:**

```javascript theme={null}
idvFlow.on('input_required', ({ entityId }, status) => {
  console.log('Input required. Status:', status);
  console.log('User can retry to continue verification');

  if (status === idvFlow.statuses.WAITING_DOC_UPLOAD) {
    showMessage('Please upload your document to continue');
    enableRetry();
  } else if (status === idvFlow.statuses.WAITING_SELFIE_UPLOAD) {
    showMessage('Please capture your selfie to continue');
    enableRetry();
  } else if (status === idvFlow.statuses.AWAITING_CONSENT) {
    showMessage('Please provide consent to continue');
    enableRetry();
  }
});
```

***

### `processing`

Emitted when verification checks are processing.

**Arguments:**

```typescript theme={null}
{
  checkStatus: IDVStatus;
  entityId: string | null;
  [key: string]: any;
}
```

**Example:**

```javascript theme={null}
idvFlow.on('processing', (status) => {
  console.log('Processing verification. Status:', status.checkStatus);
  showLoadingSpinner();
});
```

***

### `results`

Emitted when verification reaches a terminal state. Only fires with `COMPLETE` or `FAILED` status. Other statuses surface through `input_required`, `error`, or `processing` events.

**Arguments:**

```typescript theme={null}
{
  checkStatus: IDVStatus;
  entityId: string | null;
  [key: string]: any;
}
```

**Example:**

```javascript theme={null}
idvFlow.on('results', (results) => {
  console.log('Verification results received');
  console.log('Status:', results.checkStatus);
  console.log('Entity ID:', results.entityId);

  if (results.checkStatus === idvFlow.statuses.COMPLETE) {
    navigateToSuccess();
  } else if (results.checkStatus === idvFlow.statuses.FAILED) {
    showFailureScreen(results);
  }
});
```

***

### `session_interrupted`

Emitted when the user interrupts the verification session.

**Arguments:** None

<Note>
  **Provider-Specific:**

  * **Onfido:** Emits this when the verification modal is closed.
</Note>

**Example:**

```javascript theme={null}
// Onfido-specific event
idvFlow.on('session_interrupted', () => {
  console.log('User interrupted the verification (Onfido)');
  saveProgress();
});
```

***

### `session_closed`

Emitted when the verification session is closed.

**Arguments:** None

**Example:**

```javascript theme={null}
idvFlow.on('session_closed', () => {
  console.log('Verification session closed');
  idvFlow.unmount();
});
```

***

### `session_data_failed_loading`

Emitted when session data fails to load.

**Arguments:** None

**Example:**

```javascript theme={null}
idvFlow.on('session_data_failed_loading', () => {
  console.error('Failed to load session data');
  showErrorMessage('Unable to start verification. Please try again.');
});
```

***

### `vendor_event`

Emitted for provider-specific events.

**Arguments:**

```typescript theme={null}
{
  [key: string]: any;  // Provider-specific event data
}
```

**Example:**

```javascript theme={null}
idvFlow.on('vendor_event', (event) => {
  console.log('Provider event:', event);
  // Handle provider-specific events
});
```

<Note>
  **Truuth:** `vendor_event` payloads are `{ provider: 'truuth', vendorEventType }` — the raw event `payload` (which could contain PII from the vendor SDK) is intentionally not included. If your integration previously relied on fields from the Truuth event payload, read them from the `results` event or your backend API instead.
</Note>

***

### Common Events

The IDV module also emits common events inherited from the event system:

* `error` - When an error occurs
* `warning` - For non-critical warnings
* `info` - Informational messages
* `loading` - Loading state changes

See [Event System Reference](/docs/sdk-reference/events) for details.

***

## Complete Example

```javascript theme={null}
import OneSdk from '@frankieone/one-sdk';

async function performIDV() {
  try {
    // Initialize SDK
    const sdk = await OneSdk({
      mode: 'production',
      session: { token: await getSessionToken() }
    });

    // Create IDV component with Onfido provider
    const idvFlow = sdk.flow('idv', {
      provider: {
        name: 'onfido',
        theme: 'light',
        product: 'idv',
        biometricsVariant: 'standard',
        showExitButton: true
      }
    });

    // Check if user has already completed IDV
    if (idvFlow.isPreloaded()) {
      console.log('User has existing IDV verification data');
      // Skip verification for returning user
      return navigateToNextStep();
    }

    // Set up event listeners
    idvFlow.on('session_data_generated', ({ session }) => {
      console.log('IDV session started for:', session.entityId);
    });

    idvFlow.on('detection_complete', () => {
      console.log('Capture complete, processing...');
      showMessage('Processing your verification...');
    });

    idvFlow.on('detection_failed', ({ message }) => {
      console.error('Capture failed:', message);
      showError(message);
    });

    idvFlow.on('processing', (status) => {
      console.log('Verification processing:', status.checkStatus);
    });

    idvFlow.on('results', (results) => {
      console.log('Verification complete');

      if (results.checkStatus === idvFlow.statuses.COMPLETE) {
        console.log('✓ Verification passed');
        navigateToSuccess();
      } else if (results.checkStatus === idvFlow.statuses.FAILED) {
        console.log('✗ Verification failed');
        showFailureScreen();
      } else {
        console.log('Status:', results.checkStatus);
        handleOtherStatus(results);
      }
    });

    idvFlow.on('session_interrupted', () => {
      console.log('User closed verification');
      saveProgress();
    });

    idvFlow.on('error', (error) => {
      console.error('IDV error:', error);
      showError('Verification error. Please try again.');
    });

    // Mount and start verification
    idvFlow.mount('#idv-container');

  } catch (error) {
    console.error('IDV initialization failed:', error);
    throw error;
  }
}
```

***

## Best Practices

1. **Handle all events, not just `results`** - The `results` event only fires with `COMPLETE` or `FAILED`. Also listen to `input_required` (for recoverable states like INCOMPLETE or INTERRUPTED), `error` (for system failures such as PROVIDER\_OFFLINE), and `processing` (for intermediate states).

2. **Set up event listeners before mounting** - Register all event handlers before calling `mount()` to avoid missing events.

3. **Unmount on navigation** - Always call `unmount()` when the user leaves the page to clean up resources.

4. **Provider-specific configuration** - Review each provider's documentation for optimal configuration.

5. **Error handling** - Always listen to the `error` event and provide user-friendly error messages.

***

## Common Issues

### Component not displaying

Ensure the mount element exists in the DOM and has sufficient size:

```css theme={null}
#idv-container {
  width: 100%;
  min-height: 600px;
}
```

### Session data failed to load

This usually means the backend session setup failed. Ensure your backend is correctly generating IDV tokens.

### Provider-specific errors

Check the `vendor_event` emissions for provider-specific error details and consult the provider's documentation.

***

## Related

* [SDK Initialization](/docs/sdk-reference/sdk-initialization)
* [Individual Module](/docs/sdk-reference/individual-module)
* [Event System](/docs/sdk-reference/events)
* [Component System](/docs/sdk-reference/components)


# Individual Module
Source: https://docs.frankieone.com/docs/sdk-reference/individual-module

Complete reference for the Individual (KYC) module

## Overview

The Individual module manages individual identity verification (KYC). It provides methods to collect, update, and submit personal information for verification including name, date of birth, documents, addresses, and consents.

## Accessing the Module

The Individual module is accessed through the SDK context after initialization:

```javascript theme={null}
const oneSDKInstance = await OneSdk({
  mode: 'production',
  session: { token: 'your-token' }
});

// Access the Individual module
const individual = oneSDKInstance.individual();
```

## Module Options

When initializing the SDK, you can configure how much detail the Individual module retrieves from the API:

```javascript theme={null}
const oneSDKInstance = await OneSdk({
  mode: 'production',
  session: { token: 'your-token' },
  individualLevel: 'base64'  // or 'meta'
});
```

### IndividualLevel

Controls the level of detail retrieved for entity data, particularly document scans:

| Value      | Description                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `'base64'` | Retrieves full entity data including document scan images as base64-encoded strings. Use when you need to display or process document images. |
| `'meta'`   | Retrieves only metadata without document scan images. More efficient when you don't need the actual images.                                   |

**Default:** If not specified, uses the default level configured by FrankieOne.

***

## State Management Methods

### `isLoading()`

Returns whether the module is currently performing an async operation (search, submit, etc.).

**Signature:**

```typescript theme={null}
isLoading(): boolean
```

**Returns:** `boolean` - `true` if loading, `false` otherwise

**Description:**
Indicates if the module is actively fetching or submitting data. Set to `true` at the start of `search()` or `submit()` calls, and `false` when completed.

**Example:**

```javascript theme={null}
console.log('Loading:', individual.isLoading());

// Listen for loading state changes
individual.on('loading', (isLoading, context) => {
  if (isLoading) {
    showSpinner(context.message);
  } else {
    hideSpinner();
  }
});
```

***

### `isPreloaded()`

Returns whether existing entity data was found and loaded.

**Signature:**

```typescript theme={null}
isPreloaded(): boolean
```

**Returns:** `boolean` - `true` if existing data was loaded, `false` if starting fresh

**Description:**
After calling `search()`, this indicates whether the entity already exists in the system with existing verification data. `true` means you're continuing an existing verification; `false` means this is a new entity.

**Example:**

```javascript theme={null}
await individual.search();

if (individual.isPreloaded()) {
  console.log('Continuing existing verification');
  // Pre-fill form with existing data
  const name = individual.access('name').getValue();
  prefillForm(name);
} else {
  console.log('Starting new verification');
  // Show empty form
}
```

***

### `isPersisted()`

Returns whether all changes have been submitted to the server.

**Signature:**

```typescript theme={null}
isPersisted(): boolean
```

**Returns:** `boolean` - `true` if all data is saved, `false` if there are unsaved changes

**Description:**
Whenever you make changes to the individual's data (name, documents, addresses, etc.), this flag is set to `false`. After successfully calling `submit()`, it's set back to `true`. Use this to track whether there are pending changes.

**Example:**

```javascript theme={null}
console.log('Has unsaved changes:', !individual.isPersisted());

// Warn user before navigating away
window.addEventListener('beforeunload', (e) => {
  if (!individual.isPersisted()) {
    e.preventDefault();
    e.returnValue = 'You have unsaved changes. Are you sure you want to leave?';
  }
});
```

***

## Data Fetching Methods

### `search()`

Searches for and loads existing entity data from the server.

**Signature:**

```typescript theme={null}
search(): Promise<void>
```

**Returns:** `Promise<void>` - Resolves when search completes

**Description:**
Queries the server for any existing data associated with the current session's entity. If data exists, it's loaded into the module and can be accessed via the `access()` method. Sets `isPreloaded()` to `true` if data is found.

**Warning:** Calling `search()` will overwrite any unpersisted local changes with server data.

**Events Emitted:**

* `data_loaded` - When search completes (whether data was found or not)
* `loading` - Loading state changes

**Example:**

```javascript theme={null}
try {
  await individual.search();

  individual.on('data_loaded', ({ entityId, reference, isPreloaded }) => {
    console.log('Data loaded:', { entityId, reference, isPreloaded });

    if (isPreloaded) {
      // Display existing data
      const name = individual.access('name').getValue();
      const dob = individual.access('dateOfBirth').getValue();
      console.log(`Found existing profile: ${name.givenName} ${name.familyName}`);
    }
  });
} catch (error) {
  console.error('Search failed:', error);
}
```

***

### `syncEntityId()`

Synchronizes the entity ID from the session into the individual module.

**Signature:**

```typescript theme={null}
syncEntityId(): void
```

**Returns:** `void`

**Description:**
Updates the individual's entity ID to match the current session's entity ID. Useful if the session entity ID changes after module initialization.

**Example:**

```javascript theme={null}
individual.syncEntityId();
const entityId = individual.access('entityId').getValue();
console.log('Synced entity ID:', entityId);
```

***

## Data Submission Methods

### `submit()`

Persists all entity data to the server.

**Signature:**

```typescript theme={null}
submit<T extends boolean>(
  options?: {
    verify?: T;
  },
  retryOptions?: {
    maxRetries?: number;
    backoffDelayMs?: number;
  }
): Promise<T extends true ? CheckSummary : void>
```

**Parameters:**

| Parameter                     | Type      | Required | Default | Description                                                                                                    |
| ----------------------------- | --------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| `options.verify`              | `boolean` | No       | `false` | If `true`, triggers verification checks and returns results. If `false`, only saves data without verification. |
| `retryOptions.maxRetries`     | `number`  | No       | -       | Maximum number of retry attempts on failure                                                                    |
| `retryOptions.backoffDelayMs` | `number`  | No       | -       | Delay in milliseconds between retry attempts                                                                   |

**Returns:**

* `Promise<void>` if `verify` is `false` (default) - Data saved, no verification run
* `Promise<CheckSummary>` if `verify` is `true` - Returns verification results (see [CheckSummary Structure](#checksummary-structure) below)

**Description:**
Submits all individual data (name, DOB, documents, addresses, consents) to the server. When `verify: true` is passed, it also triggers verification checks and returns a summary of results.

Retry behavior is **not enabled by default**. Pass `retryOptions` explicitly to enable automatic retries with exponential backoff.

**Events Emitted:**

* `results` - When verification completes (only if `verify: true`)
* `loading` - Loading state changes

**Examples:**

```javascript theme={null}
// Save data without verification
try {
  await individual.submit();
  console.log('Data saved successfully');
} catch (error) {
  console.error('Submit failed:', error);
}
```

```javascript theme={null}
// Save data AND run verification
try {
  const results = await individual.submit({ verify: true });

  console.log('Verification results:', {
    status: results.status,
    checkDate: results.checkDate,
    checks: results.checkResults,
    risk: results.risk
  });

  if (results.status.type === 'passed') {
    navigateToSuccess();
  } else {
    showVerificationErrors(results);
  }
} catch (error) {
  console.error('Verification failed:', error);
}
```

```javascript theme={null}
// Submit with retry logic
try {
  await individual.submit(
    { verify: false },
    {
      maxRetries: 3,
      backoffDelayMs: 1000
    }
  );
} catch (error) {
  console.error('Submit failed after retries:', error);
}
```

***

### `runChecks()`

Runs verification checks without submitting data.

**Signature:**

```typescript theme={null}
runChecks(): Promise<CheckSummary>
```

**Returns:** `Promise<CheckSummary>` - Verification results

**Description:**
Triggers verification checks on the current entity data without performing a data submission. Use this to re-run checks on already-submitted data or to check verification status.

**Events Emitted:**

* `results` - When checks complete
* `loading` - Loading state changes

**Example:**

```javascript theme={null}
try {
  const results = await individual.runChecks();

  console.log('Status:', results.status.type, results.status.label);
  console.log('Risk level:', results.risk.level, results.risk.class);

  // Iterate through individual check results
  if (results.checkResults) {
    results.checkResults.forEach(check => {
      console.log(`${check.type}: ${check.result.label}`);
    });
  }
} catch (error) {
  console.error('Checks failed:', error);
}
```

***

## CheckSummary Structure

Both `submit({ verify: true })` and `runChecks()` return a `CheckSummary` object containing verification results.

### Properties

| Property                    | Type               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| --------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`                    | `object`           | **Overall verification status object:**<br />• `type`: `"passed" \| "failed" \| "fail_manual" \| "pass_manual" \| "refer" \| "wait" \| "unchecked" \| "archived" \| "inactive" \| null` - The verification result type<br />• `label`: `string` - Human-readable status label (e.g., "Verified", "Failed", "Needs Review")<br />• `key`: `string` - Status key identifier (e.g., "VERIFIED", "FAILED")<br />• `action?`: `string` - Optional action required                                                                                                                                                  |
| `checkDate`                 | `string`           | ISO 8601 timestamp indicating when verification checks were performed (e.g., `"2024-01-15T10:30:00.000Z"`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `checkTypes`                | `string[]`         | Array of check type names that were executed during verification. Common values: `"name"`, `"dob"`, `"document"`, `"address"`, `"watchlist"`, `"pep"`, `"sanctions"`                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `personalChecks`            | `object`           | **Validation results for personal information fields:**<br />• `name`: `boolean \| null` - Name validation result<br />• `dateOfBirth`: `boolean \| null` - DOB validation result<br />• `phoneNumber`: `boolean \| null` - Phone validation result<br />• `email`: `boolean \| null` - Email validation result<br />• `chineseName`: `string \| null` - Chinese name if provided<br />• `addresses`: `{ [addressId: string]: boolean \| null }` - Address validation results by address ID<br /><br />For boolean fields: `true` = validated successfully, `false` = validation failed, `null` = not checked |
| `risk`                      | `object`           | **Risk assessment:**<br />• `level`: `number \| null` - Numeric risk level (lower numbers indicate lower risk)<br />• `class`: `"low" \| "medium" \| "high" \| "unacceptable" \| null` - Risk classification                                                                                                                                                                                                                                                                                                                                                                                                  |
| `checkResults`              | `array` (optional) | **Array of detailed check results:**<br />Each item contains:<br />• `type`: `string \| null` - Check type identifier (e.g., `"document_verification"`, `"watchlist_aml"`)<br />• `result`: Status object with `type`, `label`, `key` (same structure as main `status`)<br />• `issues`: `Array<{ code: string \| null, description: string \| null }>` - Issues found in this specific check                                                                                                                                                                                                                 |
| `checkCounts`               | `object`           | **Count of data sources used for verification:**<br />• `name`: `string[] \| null` - Data sources that verified name<br />• `dob`: `string[] \| null` - Data sources that verified date of birth<br />• `address`: `{ [addressId: string]: string[] \| null }` - Data sources per address<br />• `document`: `{ [documentId: string]: string[] \| null }` - Data sources per document                                                                                                                                                                                                                         |
| `kycMethod`                 | `string`           | KYC method used: `"electronic"` (automated) or `"manual"` (human review)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `issues`                    | `object`           | Dictionary of issues found during verification. Key-value pairs where keys are issue identifiers and values contain issue details.<br /><br />**`issues.creditHeader`** (`boolean \| string`): Indicates a credit header issue was detected. Value is `true`/`false`, or a `string` containing a specific issue message when one is available — some accounts only ever produce the boolean form. Also exposed directly via `individual.access('creditHeaderIssue')` (always coerced to a `boolean` there).                                                                                                   |
| `alertList`                 | `array`            | **Array of alerts or actions required:**<br />Each item can be an `IIssue` or `IIssueAction`:<br />• `term`: `string` - Issue identifier (e.g., `"document_expired"`, `"additional_document_required"`)<br />• `type`: `"warning" \| "action" \| "alert" \| "success"` - Alert severity<br />• `extra?`: `{ action: string, label?: string }` - Additional action details (only for `type: "action"`)                                                                                                                                                                                                         |
| `blocklistPotentialMatches` | `array`            | **Array of potential blocklist matches:**<br />Each item contains:<br />• `entityId`: `string` - ID of the matched entity<br />• `matchStrength`: `number \| null` - Match confidence (0-1)<br />• `matches`: Object with `personal` (string array of matched fields) and `documents` (matched document details)                                                                                                                                                                                                                                                                                              |
| `duplicatePotentialMatches` | `array`            | **Array of potential duplicate entities found:**<br />Same structure as `blocklistPotentialMatches`. Indicates this entity may be a duplicate of an existing entity in the system                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `duplicateBlocklistMatches` | `array`            | **Array of entities found in both duplicate and blocklist checks:**<br />Same structure as `blocklistPotentialMatches`. These are high-priority matches requiring attention                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `rulesetsMatches`           | `array`            | **Array of ruleset matching results:**<br />Each item contains:<br />• `name`: `string \| null` - Ruleset name<br />• `order`: `number \| null` - Ruleset execution order<br />• `result`: `string \| null` - Ruleset result (e.g., `"passed"`, `"failed"`)<br />• `rulesetMatchFields`: Object with match counts for `name`, `dob`, `address`, `govId` - each containing `{ required: number \| null, actual: number \| null }`                                                                                                                                                                              |
| `retryPages`                | `array`            | **Array of pages that can be retried if verification failed:**<br />Each item contains:<br />• `name`: `string` - Screen/page identifier that can be retried                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

### Status Types

The `status.type` property indicates the overall verification result:

| Status        | Description                          |
| ------------- | ------------------------------------ |
| `passed`      | Verification passed all checks       |
| `failed`      | Verification failed automated checks |
| `pass_manual` | Manually approved after review       |
| `fail_manual` | Manually rejected after review       |
| `refer`       | Requires manual review               |
| `wait`        | Waiting for additional information   |
| `unchecked`   | No checks have been run              |
| `archived`    | Entity has been archived             |
| `inactive`    | Entity is inactive                   |

### Example Structure

```javascript theme={null}
{
  // Overall verification status
  status: {
    type: "passed",        // "passed" | "failed" | "refer" | "wait" | etc.
    label: "Verified",     // Human-readable status label
    key: "VERIFIED"        // Status key identifier
  },

  // When checks were performed
  checkDate: "2024-01-15T10:30:00.000Z",

  // Types of checks that were executed
  checkTypes: ["name", "dob", "document", "address"],

  // Validation results for personal information
  personalChecks: {
    name: true,           // true = validated, false = failed, null = not checked
    dateOfBirth: true,
    phoneNumber: null,    // Not checked
    email: true,
    chineseName: null,    // Optional field
    addresses: {
      "address-123": true // Address ID as key, validation result as value
    }
  },

  // Risk assessment
  risk: {
    level: 1,             // Risk level number (lower is better)
    class: "low"          // "low" | "medium" | "high" | "unacceptable" | null
  },

  // Detailed results from individual checks
  checkResults: [
    {
      type: "document_verification",
      result: {
        type: "passed",
        label: "Passed",
        key: "DOCUMENT_VERIFIED"
      },
      issues: []          // Array of { code: string | null, description: string | null }
    },
    {
      type: "watchlist_aml",
      result: {
        type: "passed",
        label: "No Matches",
        key: "AML_CLEAR"
      },
      issues: []
    }
  ],

  // Count of data sources used for each check type
  checkCounts: {
    name: ["data_source_1", "data_source_2"],    // Sources that verified name
    dob: ["data_source_1"],                       // Sources that verified DOB
    address: {
      "address-123": ["address_verification_service"]
    },
    document: {
      "passport-456": ["document_ocr_provider"]
    }
  },

  // KYC method used
  kycMethod: "electronic",  // "electronic" | "manual"

  // Issues found during verification (if any)
  issues: {
    // Example: boolean form (no specific message available)
    // creditHeader: true,
    // Example: string form (a specific message is available)
    // creditHeader: "Credit header could not be located for this applicant"
  },

  // Alerts requiring attention
  alertList: [
    // Example issue:
    // {
    //   term: "document_expired",
    //   type: "warning"  // "warning" | "action" | "alert" | "success"
    // }
    // Example action required:
    // {
    //   term: "additional_document_required",
    //   type: "action",
    //   extra: {
    //     action: "upload_proof_of_address",
    //     label: "Please upload proof of address"
    //   }
    // }
  ],

  // Duplicate and blocklist matching results
  blocklistPotentialMatches: [],
  duplicatePotentialMatches: [
    // Example duplicate match:
    // {
    //   entityId: "entity-789",
    //   matchStrength: 0.85,
    //   matches: {
    //     personal: ["name", "dob"],
    //     documents: {
    //       documentId: "doc-456",
    //       field: ["documentNumber", "dateOfBirth"]
    //     }
    //   }
    // }
  ],
  duplicateBlocklistMatches: [],

  // Ruleset matching results
  rulesetsMatches: [
    // Example ruleset match:
    // {
    //   name: "standard_kyc_ruleset",
    //   order: 1,
    //   result: "passed",
    //   rulesetMatchFields: {
    //     name: { required: 2, actual: 2 },
    //     dob: { required: 1, actual: 1 },
    //     address: { required: 1, actual: 1 },
    //     govId: { required: 1, actual: 1 }
    //   }
    // }
  ],

  // Pages that can be retried if verification failed
  retryPages: []
}
```

***

## Data Access Methods

### `access(fieldName)`

Accesses reactive data accessors for reading and updating entity fields.

**Signature:**

```typescript theme={null}
access<K extends keyof PublicAccessors>(
  fieldName: K
): PublicAccessors[K]
```

**Parameters:**

| Parameter   | Type     | Required | Description                                                    |
| ----------- | -------- | -------- | -------------------------------------------------------------- |
| `fieldName` | `string` | Yes      | Name of the field to access. See Available Fields table below. |

**Returns:** `Accessor` object

**Accessor Interface:**

```typescript theme={null}
{
  getValue(): T;              // Read current value
  setValue(value: T): void;  // Write new value
  observable: Observable<T>; // Subscribe to reactive changes
}
```

**`access()` vs `search()`:**

* Use `access()` to read or write entity data within the module. You don't have direct access to the full raw entity object — `access()` is the interface for it.
* Use `search()` to refresh entity data by fetching the latest state from FrankieOne's backend.

**Available Fields:**

| Field               | Type                                                 | Description                                                                                                                                                                                                                               |
| ------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entityId`          | `string \| null`                                     | Entity identifier (read-only)                                                                                                                                                                                                             |
| `name`              | `{ givenName, middleName, familyName, displayName }` | Individual's name                                                                                                                                                                                                                         |
| `dateOfBirth`       | `string \| null`                                     | Date of birth (ISO 8601 format: YYYY-MM-DD)                                                                                                                                                                                               |
| `consentsGiven`     | `string[]`                                           | Array of consent strings                                                                                                                                                                                                                  |
| `documents`         | `object[]`                                           | Array of identity documents. See [Document Structure](#document-structure).                                                                                                                                                               |
| `addresses`         | `object[]`                                           | Array of addresses. See [Address Structure](#address-structure).                                                                                                                                                                          |
| `profile`           | `object \| null`                                     | Verification profile configuration                                                                                                                                                                                                        |
| `phoneNumber`       | `{ documentId, idNumber }`                           | Phone number details                                                                                                                                                                                                                      |
| `email`             | `{ documentId, idNumber }`                           | Email details                                                                                                                                                                                                                             |
| `extraData`         | `object`                                             | Custom additional data                                                                                                                                                                                                                    |
| `device`            | `object`                                             | Device fingerprinting details                                                                                                                                                                                                             |
| `isLoading`         | `boolean`                                            | Current loading state (read-only)                                                                                                                                                                                                         |
| `isPersisted`       | `boolean`                                            | Current persistence state (read-only)                                                                                                                                                                                                     |
| `creditHeaderIssue` | `boolean`                                            | Read-only flag indicating whether the last verification run detected a credit header issue. `false` until `submit({ verify: true })` or `runChecks()` completes, then set from `checkSummary.issues.creditHeader` (coerced to a boolean). |

**Examples:**

```javascript theme={null}
// Read values
const name = individual.access('name').getValue();
console.log(`Name: ${name.givenName} ${name.familyName}`);

const dob = individual.access('dateOfBirth').getValue();
console.log('Date of birth:', dob);

const documents = individual.access('documents').getValue();
console.log('Number of documents:', documents.length);
```

```javascript theme={null}
// Update values
individual.access('name').setValue({
  givenName: 'John',
  familyName: 'Doe',
  middleName: null,
  displayName: 'John Doe'
});

individual.access('dateOfBirth').setValue('1990-01-15');
```

```javascript theme={null}
// Subscribe to changes
individual.access('name').observable.subscribe((newName) => {
  console.log('Name changed:', newName);
  updateUI(newName);
});
```

***

## Name Methods

### `setEmail()`

Sets the individual's email address.

**Signature:**

```typescript theme={null}
setEmail(email: string | null): void
```

**Parameters:**

| Parameter | Type             | Required | Description                             |
| --------- | ---------------- | -------- | --------------------------------------- |
| `email`   | `string \| null` | Yes      | Email address string or `null` to clear |

**Example:**

```javascript theme={null}
individual.setEmail('john.doe@example.com');
```

***

### `getEmail()`

Gets the individual's email address.

**Signature:**

```typescript theme={null}
getEmail(): string | null
```

**Returns:** `string | null` - Email address or `null` if not set

**Example:**

```javascript theme={null}
const email = individual.getEmail();
console.log('Email:', email);
```

***

### `setPhoneNumber()`

Sets the individual's phone number.

**Signature:**

```typescript theme={null}
setPhoneNumber(phone: string | null): void
```

**Parameters:**

| Parameter | Type             | Required | Description                            |
| --------- | ---------------- | -------- | -------------------------------------- |
| `phone`   | `string \| null` | Yes      | Phone number string or `null` to clear |

**Example:**

```javascript theme={null}
individual.setPhoneNumber('+61412345678');
```

***

### `getPhoneNumber()`

Gets the individual's phone number.

**Signature:**

```typescript theme={null}
getPhoneNumber(): string | null
```

**Returns:** `string | null` - Phone number or `null` if not set

**Example:**

```javascript theme={null}
const phone = individual.getPhoneNumber();
console.log('Phone:', phone);
```

***

## Profile Methods

### `setProfileType()`

Sets the verification profile type.

**Signature:**

```typescript theme={null}
setProfileType(profileType: string): void
```

**Parameters:**

| Parameter     | Type     | Required | Description                                                               |
| ------------- | -------- | -------- | ------------------------------------------------------------------------- |
| `profileType` | `string` | Yes      | Profile type name that determines which verification checks are performed |

**Description:**
Sets the verification profile which determines what checks are performed during verification. The profile type corresponds to predefined verification workflows.

**Common Profile Types:**

| Profile Type              | Description                                                       |
| ------------------------- | ----------------------------------------------------------------- |
| `auto`                    | Automatically selects appropriate profile based on available data |
| `gov_id`                  | Government ID verification                                        |
| `safe_harbour`            | Safe harbour compliance checks                                    |
| `safe_harbour_id`         | Safe harbour with ID verification                                 |
| `safe_harbour_plus`       | Enhanced safe harbour checks                                      |
| `international`           | International verification profile                                |
| `gov_id_media`            | Government ID with media/AML checks                               |
| `safe_harbour_media`      | Safe harbour with media/AML checks                                |
| `safe_harbour_id_media`   | Safe harbour ID with media/AML checks                             |
| `safe_harbour_plus_media` | Safe harbour plus with media/AML checks                           |
| `international_media`     | International with media/AML checks                               |
| `aml_only`                | AML checks only                                                   |
| `aml_media_only`          | AML media checks only                                             |

**Note:** Profile types may be customized in your FrankieOne account configuration. Contact your account manager for custom profile options.

**Examples:**

```javascript theme={null}
// Common profile types
individual.setProfileType('auto');
individual.setProfileType('safe_harbour_plus');
individual.setProfileType('gov_id_media');

// AML-focused profiles
individual.setProfileType('aml_only');
```

***

### `getProfileType()`

Gets the current verification profile type.

**Signature:**

```typescript theme={null}
getProfileType(): void
```

**Returns:** `void`

***

## Consent Methods

### `addConsent()`

Adds a consent string to the entity's list of consents.

**Signature:**

```typescript theme={null}
addConsent(type: string): void
```

**Parameters:**

| Parameter | Type     | Required | Description                             |
| --------- | -------- | -------- | --------------------------------------- |
| `type`    | `string` | Yes      | Consent type identifier or consent text |

**Description:**
Records that the individual has provided a specific consent. Consent strings are stored and can be retrieved via `access('consentsGiven')`.

**Example:**

```javascript theme={null}
individual.addConsent('terms_and_conditions_v1.2');
individual.addConsent('privacy_policy_2024');

// View all consents
const consents = individual.access('consentsGiven').getValue();
console.log('Consents given:', consents);
```

***

## Document Methods

### `addDocument()`

Adds a new identity document to the entity.

**Signature:**

```typescript theme={null}
addDocument(details: Document): void
```

**Parameters:**

| Parameter | Type     | Required | Description                                                                                          |
| --------- | -------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `details` | `object` | Yes      | Document object with identity document details. See [Document Structure](#document-structure) below. |

**Example:**

```javascript theme={null}
// Pass a plain object - it will be converted internally
const passport = {
  idType: 'PASSPORT',
  country: 'AUS',
  idNumber: 'N1234567',
  idExpiry: '2030-12-31',
  dateOfBirth: '1990-01-15'
};

individual.addDocument(passport);
```

***

### `updateDocument()`

Updates an existing document by its ID.

**Signature:**

```typescript theme={null}
updateDocument(id: string | null, details: Document): void
```

**Parameters:**

| Parameter | Type             | Required | Description                                                             |
| --------- | ---------------- | -------- | ----------------------------------------------------------------------- |
| `id`      | `string \| null` | Yes      | Document ID to update                                                   |
| `details` | `object`         | Yes      | Updated document object. See [Document Structure](#document-structure). |

**Example:**

```javascript theme={null}
const documents = individual.access('documents').getValue();
const docToUpdate = documents[0];

// Update expiry date
docToUpdate.idExpiry = '2031-12-31';
individual.updateDocument(docToUpdate.documentId, docToUpdate);

// Or create a new object with updates
const updatedDoc = {
  ...docToUpdate,
  idExpiry: '2031-12-31',
  extraData: { verified: true }
};
individual.updateDocument(docToUpdate.documentId, updatedDoc);
```

***

### `deleteDocument()`

Deletes a document by its ID.

**Signature:**

```typescript theme={null}
deleteDocument(id: string): void
```

**Parameters:**

| Parameter | Type     | Required | Description           |
| --------- | -------- | -------- | --------------------- |
| `id`      | `string` | Yes      | Document ID to delete |

**Example:**

```javascript theme={null}
const documentId = 'doc-12345';
individual.deleteDocument(documentId);
```

***

## Address Methods

### `addAddress()`

Adds a new address to the entity.

**Signature:**

```typescript theme={null}
addAddress(details: Address): void
```

**Parameters:**

| Parameter | Type     | Required | Description                                                        |
| --------- | -------- | -------- | ------------------------------------------------------------------ |
| `details` | `object` | Yes      | Address object. See [Address Structure](#address-structure) below. |

**Example:**

```javascript theme={null}
// Pass a plain object - it will be converted internally
const residentialAddress = {
  addressType: 'RESIDENTIAL',
  unitNumber: '5',
  streetNumber: '123',
  streetName: 'Main',
  streetType: 'Street',
  suburb: 'Sydney',
  state: 'NSW',
  postalCode: '2000',
  country: 'AUS'
};

individual.addAddress(residentialAddress);
```

***

### `updateAddress()`

Updates an existing address by its ID.

**Signature:**

```typescript theme={null}
updateAddress(id: string | null, details: Address): void
```

**Parameters:**

| Parameter | Type             | Required | Description                                                          |
| --------- | ---------------- | -------- | -------------------------------------------------------------------- |
| `id`      | `string \| null` | Yes      | Address ID to update                                                 |
| `details` | `object`         | Yes      | Updated address object. See [Address Structure](#address-structure). |

**Example:**

```javascript theme={null}
const addresses = individual.access('addresses').getValue();
const addressToUpdate = addresses[0];

// Update postal code
addressToUpdate.postalCode = '2001';
individual.updateAddress(addressToUpdate.addressId, addressToUpdate);

// Or create a new object with updates
const updatedAddress = {
  ...addressToUpdate,
  postalCode: '2001',
  suburb: 'North Sydney'
};
individual.updateAddress(addressToUpdate.addressId, updatedAddress);
```

***

## Reference Methods

### `addReference()`

Attaches indexable references to the entity.

**Signature:**

```typescript theme={null}
addReference(customerReference: string): void
addReference(key: string, value: string): void
```

**Overloads:**

1. **Single parameter** - Sets the customer reference (won't override if already set)
2. **Two parameters** - Sets a custom key-value reference pair

**Parameters:**

| Parameter           | Type     | Required         | Description                        |
| ------------------- | -------- | ---------------- | ---------------------------------- |
| `customerReference` | `string` | Yes (overload 1) | Your customer reference identifier |
| `key`               | `string` | Yes (overload 2) | Reference key name                 |
| `value`             | `string` | Yes (overload 2) | Reference value                    |

**Description:**
References are custom identifiers you can attach to entities for indexing and searching in your system. The customer reference is a special primary reference; additional key-value pairs can also be added.

**Examples:**

```javascript theme={null}
// Set customer reference
individual.addReference('CUST-12345');

// Add custom key-value references
individual.addReference('application_id', 'APP-789');
individual.addReference('campaign', 'summer-2024');
```

***

## Extra Data Methods

### `setExtraData()`

Sets custom extra data on the entity.

**Signature:**

```typescript theme={null}
setExtraData(data: object): void
```

**Parameters:**

| Parameter | Type     | Required | Description                                |
| --------- | -------- | -------- | ------------------------------------------ |
| `data`    | `object` | Yes      | Custom data object to attach to the entity |

**Description:**
Allows you to store arbitrary custom data with the entity. This can be used to pass application-specific information through the verification flow.

**Example:**

```javascript theme={null}
individual.setExtraData({
  applicationSource: 'mobile_app',
  campaignId: 'PROMO2024',
  internalNotes: 'VIP customer'
});

// Retrieve extra data
const extraData = individual.access('extraData').getValue();
console.log('Extra data:', extraData);
```

***

## Data Structures

### Document Structure

When adding or updating documents, pass a plain object with these properties. The SDK will convert it internally.

| Property      | Type             | Required | Description                                                                                                       |
| ------------- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `documentId`  | `string \| null` | No       | Unique document identifier. Leave `null` for new documents (auto-generated).                                      |
| `idType`      | `string \| null` | Yes      | Document type: `'DRIVERS_LICENCE'`, `'PASSPORT'`, `'NATIONAL_ID'`, `'BIRTH_CERTIFICATE'`, `'MEDICARE_CARD'`, etc. |
| `idSubType`   | `string \| null` | No       | Document subtype if applicable (provider-specific).                                                               |
| `country`     | `string \| null` | Yes      | ISO 3166-1 alpha-3 country code (e.g., `'AUS'`, `'USA'`, `'GBR'`).                                                |
| `region`      | `string \| null` | No       | State or region code (e.g., `'NSW'`, `'CA'`, `'QLD'`).                                                            |
| `idNumber`    | `string \| null` | Yes      | Document number or identifier.                                                                                    |
| `idExpiry`    | `string \| null` | No       | Expiry date in ISO 8601 format: `YYYY-MM-DD`.                                                                     |
| `dateOfBirth` | `string \| null` | No       | Date of birth as shown on document in ISO 8601 format: `YYYY-MM-DD`.                                              |
| `gender`      | `string \| null` | No       | Gender as shown on document.                                                                                      |
| `extraData`   | `object`         | No       | Additional document-specific data (key-value pairs).                                                              |

**Example:**

```javascript theme={null}
const driverLicense = {
  idType: 'DRIVERS_LICENCE',
  country: 'AUS',
  region: 'NSW',
  idNumber: '12345678',
  idExpiry: '2028-06-30',
  dateOfBirth: '1990-01-15',
  extraData: {
    cardNumber: 'ABC123',
    licenseClass: 'C'
  }
};

individual.addDocument(driverLicense);
```

***

### Address Structure

When adding or updating addresses, pass a plain object with these properties. The SDK will convert it internally.

| Property       | Type             | Required | Description                                                                 |
| -------------- | ---------------- | -------- | --------------------------------------------------------------------------- |
| `addressId`    | `string \| null` | No       | Unique address identifier. Leave `null` for new addresses (auto-generated). |
| `addressType`  | `string \| null` | Yes      | Address type: `'RESIDENTIAL'`, `'MAILING'`, `'BUSINESS'`, etc.              |
| `unitNumber`   | `string \| null` | No       | Unit or apartment number.                                                   |
| `streetNumber` | `string \| null` | Yes      | Street number.                                                              |
| `streetName`   | `string \| null` | Yes      | Street name.                                                                |
| `streetType`   | `string \| null` | No       | Street type (e.g., `'Street'`, `'Road'`, `'Avenue'`, `'Lane'`).             |
| `suburb`       | `string \| null` | No       | Suburb or city district.                                                    |
| `town`         | `string \| null` | Yes      | Town or city name.                                                          |
| `state`        | `string \| null` | No       | State or province code.                                                     |
| `postalCode`   | `string \| null` | Yes      | Postal or ZIP code.                                                         |
| `country`      | `string \| null` | Yes      | ISO 3166-1 alpha-3 country code (e.g., `'AUS'`, `'USA'`).                   |
| `buildingName` | `string \| null` | No       | Building name if applicable.                                                |
| `longForm`     | `string \| null` | No       | Complete address as a single string.                                        |

**Example:**

```javascript theme={null}
const homeAddress = {
  addressType: 'RESIDENTIAL',
  unitNumber: '12',
  streetNumber: '456',
  streetName: 'Elizabeth',
  streetType: 'Street',
  suburb: 'Surry Hills',
  town: 'Sydney',
  state: 'NSW',
  postalCode: '2010',
  country: 'AUS'
};

individual.addAddress(homeAddress);
```

***

## Events

The Individual module emits the following events:

### `data_loaded`

Emitted when entity data has been loaded from the server.

**Arguments:**

```typescript theme={null}
{
  entityId: string | null;
  reference: string | null;
  isPreloaded: boolean;
}
```

**Example:**

```javascript theme={null}
individual.on('data_loaded', ({ entityId, reference, isPreloaded }) => {
  console.log('Data loaded:', { entityId, reference, isPreloaded });

  if (isPreloaded) {
    console.log('Found existing entity data');
  } else {
    console.log('No existing data, starting fresh');
  }
});
```

***

### `data_updated`

Emitted when any data field changes.

**Arguments:**

```typescript theme={null}
(fieldName: string, newValue: unknown)
```

**Example:**

```javascript theme={null}
individual.on('data_updated', (fieldName, newValue) => {
  console.log(`Field "${fieldName}" updated:`, newValue);
});
```

***

### Common Events

The Individual module also emits common events inherited from the event system:

* `error` - When an error occurs
* `warning` - For non-critical warnings
* `info` - Informational messages
* `loading` - Loading state changes

See [Event System Reference](/docs/sdk-reference/events) for details.

***

## Complete Example

```javascript theme={null}
import OneSdk from '@frankieone/one-sdk';

async function performKYC() {
  try {
    // Initialize SDK
    const sdk = await OneSdk({
      mode: 'production',
      session: { token: await getSessionToken() },
      individualLevel: 'base64' // Include document images
    });

    // Get Individual module
    const individual = sdk.individual();

    // Set up event listeners
    individual.on('data_loaded', ({ isPreloaded }) => {
      if (isPreloaded) {
        console.log('Continuing existing verification');
      }
    });

    individual.on('error', (error) => {
      console.error('Individual module error:', error);
    });

    // Search for existing data
    await individual.search();

    // Set personal information
    individual.access('name').setValue({
      givenName: 'John',
      familyName: 'Doe',
      middleName: null,
      displayName: 'John Doe'
    });

    individual.access('dateOfBirth').setValue('1990-01-15');
    individual.setEmail('john.doe@example.com');
    individual.setPhoneNumber('+61412345678');

    // Add consent
    individual.addConsent('terms_and_conditions_v1.0');

    // Add document (plain object - converted internally)
    const license = {
      idType: 'DRIVERS_LICENCE',
      country: 'AUS',
      region: 'NSW',
      idNumber: '12345678',
      idExpiry: '2028-12-31'
    };
    individual.addDocument(license);

    // Add address (plain object - converted internally)
    const address = {
      addressType: 'RESIDENTIAL',
      streetNumber: '123',
      streetName: 'Main',
      streetType: 'Street',
      suburb: 'Sydney',
      state: 'NSW',
      postalCode: '2000',
      country: 'AUS'
    };
    individual.addAddress(address);

    // Submit and verify (includes automatic retry logic)
    const results = await individual.submit({ verify: true });

    if (results.status.type === 'passed') {
      console.log('✓ Verification passed');
      return { success: true, entityId: individual.access('entityId').getValue() };
    } else {
      console.log('✗ Verification failed');
      return { success: false, status: results.status, issues: results.issues };
    }

  } catch (error) {
    console.error('KYC process failed:', error);
    throw error;
  }
}
```

***

## Best Practices

1. **Always call `search()` first** - Load existing data before making changes to avoid overwriting user progress.

2. **Check `isPersisted()` before navigation** - Warn users if they have unsaved changes.

3. **Use `access()` for reactive data** - Subscribe to field changes for real-time UI updates.

4. **Handle verification results** - Always check `checkStatus` after `submit({ verify: true })`.

5. **Validate data before submit** - Check that required fields are populated before calling `submit()`.

6. **Add proper error handling** - Listen to `error` events and wrap async calls in try-catch blocks.

7. **Set consents explicitly** - Always record user consent with `addConsent()` before verification.

***

## Related

* [SDK Initialization](/docs/sdk-reference/sdk-initialization)
* [Session Management](/docs/sdk-reference/session-management)
* [Event System](/docs/sdk-reference/events)
* [Form Module](/docs/sdk-reference/form-module)
* [IDV Module](/docs/sdk-reference/idv-module)


# OCR Module
Source: https://docs.frankieone.com/docs/sdk-reference/ocr-module

Complete reference for the OCR (Document Capture) module

## Overview

The OCR (Optical Character Recognition) module handles document capture and extraction of identity information from government-issued documents. It integrates with third-party OCR providers to capture document images and extract data such as name, date of birth, document number, and expiry date.

## Accessing the Module

The OCR module is accessed through the SDK's component factory:

```javascript theme={null}
const sdk = await OneSdk({
  mode: 'production',
  session: { token: 'your-token' }
});

// Create OCR component instance
const ocrComponent = sdk.component('ocr', options);
```

## Supported Providers

The OCR module supports multiple document capture providers:

| Provider | Value       | Learn More                             |
| -------- | ----------- | -------------------------------------- |
| Onfido   | `'onfido'`  | [onfido.com](https://onfido.com)       |
| Sumsub   | `'sumsub'`  | [sumsub.com](https://sumsub.com)       |
| Incode   | `'incode'`  | [incode.com](https://incode.com)       |
| IDVerse  | `'idverse'` | [idverse.com](https://www.idverse.com) |
| Daon     | `'daon'`    | [daon.com](https://www.daon.com)       |

<Note>
  Each provider has different capabilities, supported document types, and geographic coverage. Visit the provider's website to understand their specific features and limitations.
</Note>

***

## Configuration Options

### Basic Configuration

```javascript theme={null}
const ocrComponent = sdk.component('ocr', {
  provider: {
    name: 'onfido'
  }
});
```

### Common Options

| Option             | Type      | Description                                                     |
| ------------------ | --------- | --------------------------------------------------------------- |
| `maxDocumentCount` | `number`  | Maximum number of documents to capture                          |
| `documents`        | `array`   | Array of document configurations specifying types and countries |
| `skipInitProcess`  | `boolean` | Skip initialization process (advanced use)                      |

**Documents Array Structure:**

```javascript theme={null}
documents: [
  {
    type: 'DRIVERS_LICENCE',     // Document type
    countries: ['AUS', 'NZL']    // ISO country codes (optional)
  }
]
```

<Callout icon="bell">
  **Daon provider:** The `documents` parameter and document selection are not required when using the Daon provider — Daon provides its own document type selection screen. To use custom document selection instead of Daon's built-in screen, contact your FrankieOne account team.
</Callout>

***

### Provider-Specific Options

#### Onfido Provider

```javascript theme={null}
const ocrComponent = sdk.component('ocr', {
  provider: {
    name: 'onfido',
    sdkVersion: '13.0.0',           // Onfido SDK version
    theme: 'light',                  // 'light' or 'dark'
    language: 'en_GB',               // UI language (optional)
    translations: {                  // Custom translation strings (optional)
      // See Onfido documentation for translation keys
    },
    showExitButton: true,            // Show exit button in UI
    crossDevicePolicy: 'disable',    // Cross-device flow: 'force' or 'disable'
    onUserExit: () => {              // Callback when user exits
      console.log('User exited');
    },
    customUI: {                      // Custom UI configuration
      // See Onfido documentation for customUI options
    }
  },
  documents: [
    { type: 'PASSPORT', countries: ['AUS'] }
  ]
});
```

**Onfido Options:**

| Option                    | Type                                       | Description                                                                                                                                                                                                                                                      |
| ------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sdkVersion`              | `string`                                   | Version of the Onfido SDK to use. Default: `'12'`. Refer to the [Onfido documentation](https://documentation.onfido.com/sdk/changelog/) for available versions.                                                                                                  |
| `theme`                   | `'light' \| 'dark'`                        | UI theme                                                                                                                                                                                                                                                         |
| `language`                | `string`                                   | Language code for the Onfido UI. Requires `sdkVersion` 14 or later. See supported values below.                                                                                                                                                                  |
| `translations`            | `object`                                   | Custom translation strings to override default Onfido copy. Keys must match Onfido's translation key schema — see the [Onfido language customisation docs](https://documentation.onfido.com/sdk/web/#language-customisation). Requires `sdkVersion` 14 or later. |
| `showExitButton`          | `boolean`                                  | Display exit button in the UI                                                                                                                                                                                                                                    |
| `crossDevicePolicy`       | `'force' \| 'disable'`                     | Enable/disable cross-device flow                                                                                                                                                                                                                                 |
| `onUserExit`              | `() => void`                               | Callback function when user exits                                                                                                                                                                                                                                |
| `customUI`                | `object`                                   | Custom UI styling configuration (see Custom UI section below)                                                                                                                                                                                                    |
| `_crossDeviceLinkMethods` | `Array<'qr_code' \| 'copy_link' \| 'sms'>` | Cross-device sharing methods (internal)                                                                                                                                                                                                                          |

**Supported `language` values:**

`ar`, `bg`, `cs`, `da`, `de`, `el`, `en_GB`, `en_US`, `es`, `es_419`, `es_DO`, `et`, `fa`, `fi`, `fr`, `fr_CA`, `he`, `hi`, `hr`, `hu`, `hy`, `id`, `it`, `ja`, `ko`, `lt`, `lv`, `ms`, `nl`, `no`, `pl`, `pt`, `pt_BR`, `ro`, `ru`, `sk`, `sl`, `sr`, `sv`, `th`, `tr`, `uk`, `vi`, `zh_CN`, `zh_TW`

**Onfido Custom UI Properties:**

The `customUI` object allows extensive styling customization:

```javascript theme={null}
customUI: {
  // Typography
  fontWeightBody: 400,
  fontSizeBody: '16px',
  fontSizeSubtitle: '18px',
  fontSizeTitle: '24px',

  // Colors - Background
  colorBackgroundSurfaceModal: '#FFFFFF',
  colorBackgroundIcon: '#353FF4',
  colorBackgroundInput: '#FFFFFF',

  // Colors - Content/Text
  colorContentBody: '#475467',
  colorContentTitle: '#101828',
  colorContentSubtitle: '#344054',
  colorContentInput: '#101828',

  // Colors - Buttons (Primary)
  colorContentButtonPrimaryText: '#FFFFFF',
  colorBackgroundButtonPrimary: '#353FF4',
  colorBackgroundButtonPrimaryHover: '#2835E5',
  colorBackgroundButtonPrimaryActive: '#1F2AD1',

  // Colors - Buttons (Secondary)
  colorContentButtonSecondaryText: '#344054',
  colorBackgroundButtonSecondary: '#FFFFFF',
  colorBackgroundButtonSecondaryHover: '#F9FAFB',
  colorBackgroundButtonSecondaryActive: '#F2F4F7',

  // Colors - Buttons (Tertiary)
  colorContentButtonTertiaryText: '#344054',

  // Borders
  borderRadiusButton: '8px',
  borderStyleSurfaceModal: '1px solid #E4E7EC',
  colorBorderInput: '#D0D5DD',
  colorInputOutline: '#353FF4',

  // Additional UI elements
  colorIcon: '#667085',
  colorBackgroundInfoPill: '#F2F4F7',
  colorContentInfoPill: '#344054',
  // ... see Onfido documentation for full list
}
```

***

#### Incode Provider

```javascript theme={null}
const ocrComponent = sdk.component('ocr', {
  provider: {
    name: 'incode',
    sdkVersion: '1.0.0',         // SDK version
    lang: 'es',                  // UI language (optional)
    translations: {              // Custom translation strings (optional)
      // See Incode documentation for translation keys
    },
    numberOfTries: 3,            // Max capture attempts
    consentId: 'consent_123',    // Consent identifier
    renderCamera: {
      showDocSelector: true,     // Show document selector
      showTutorial: true         // Show tutorial screens
    },
    renderCameraProps: {          // Raw options passed to the Incode SDK's renderCamera() call (optional)
      // See Incode Web SDK documentation for available renderCamera options
    },
    products: ['ID_CHECK']       // Incode products to run for this session (required)
  },
  documents: [
    { type: 'DRIVERS_LICENCE' }
  ]
});
```

**Incode Options:**

| Option              | Type             | Description                                                                                                                                                                                                      |
| ------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sdkVersion`        | `string`         | Version of the Incode SDK to use. Default: `'1.75.2'`. Refer to the [Incode documentation](https://docs.incode.com/docs/omni-web-sdk/release-notes) for available versions.                                      |
| `lang`              | `string`         | Language code for the Incode UI. See supported values below.                                                                                                                                                     |
| `translations`      | `object`         | Custom translation strings to override default Incode copy. See the [Incode language keys docs](https://documentation.identity.entrust.com/sdk/web/#identifying-language-keys) for available translation keys.   |
| `numberOfTries`     | `number`         | Maximum number of capture attempts                                                                                                                                                                               |
| `consentId`         | `string \| null` | Consent identifier for the session                                                                                                                                                                               |
| `renderCamera`      | `object`         | Camera rendering options (see below)                                                                                                                                                                             |
| `renderCameraProps` | `object`         | Advanced/raw options forwarded directly to the Incode SDK's `renderCamera()` call (optional). See [renderCameraProps vs renderCamera](#rendercameraprops-vs-rendercamera) below.                                 |
| `products`          | `string[]`       | **Required.** Array of Incode product names to run for this OCR session, sent to the backend when the session is created. Refer to your Incode account team for the product identifiers enabled for your tenant. |

**Supported `lang` values:**

`bn`, `ca`, `zh`, `hr`, `nl`, `en`, `en-BZ`, `en-DG`, `fr`, `de`, `ht`, `hi`, `hmn`, `hu`, `id`, `it`, `ms`, `pl`, `pt`, `pt-BR`, `pt-PT`, `ro`, `sr`, `sr-LATN`, `so`, `es`, `es-ES`, `tl-PH`, `tr`, `vi`

**renderCamera Options:**

| Option            | Type      | Description                    |
| ----------------- | --------- | ------------------------------ |
| `showDocSelector` | `boolean` | Display document type selector |
| `showTutorial`    | `boolean` | Display tutorial/instructions  |

#### `renderCameraProps` vs `renderCamera`

<Note>
  `renderCamera` and `renderCameraProps` are separate, additive options:

  * **`renderCamera`** (`{ showDocSelector, showTutorial }`) is a OneSDK-defined object. OneSDK reads these two flags itself to decide whether to show the document selector/tutorial screens before capture.
  * **`renderCameraProps`** is an arbitrary `Record<string, unknown>` that OneSDK spreads directly into the underlying Incode SDK's `renderCamera(type, mountElement, options)` call, ahead of OneSDK's own `onSuccess`/`onError`/`onLog`/`token`/`numberOfTries` handlers. Use it to pass Incode SDK-native camera options that OneSDK doesn't otherwise expose. It applies to the front/back document capture calls only, not the consent screen (`renderCombinedConsent`).

  Both options can be set at the same time — they don't conflict, since `renderCamera` only controls OneSDK's own pre-capture screens.
</Note>

***

#### Sumsub Provider

```javascript theme={null}
const ocrComponent = sdk.component('ocr', {
  provider: {
    name: 'sumsub',
    config: {
      theme: 'light',              // 'light' or 'dark'
      lang: 'en',                  // Language code
      email: 'user@example.com',   // Pre-fill email
      phone: '+1234567890'         // Pre-fill phone
    },
    options: {
      addViewportTag: true,        // Add viewport meta tag
      adaptIframeHeight: true      // Auto-adjust iframe height
    }
  }
});
```

**Sumsub Options:**

| Option    | Type     | Description                                                                                                                                    |
| --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `config`  | `object` | Sumsub configuration (theme, lang, email, phone). See [IDV Module - Sumsub](/docs/sdk-reference/idv-module#sumsub-provider) for details.       |
| `options` | `object` | Sumsub SDK options (addViewportTag, adaptIframeHeight). See [IDV Module - Sumsub](/docs/sdk-reference/idv-module#sumsub-provider) for details. |

***

#### IDVerse Provider

```javascript theme={null}
const ocrComponent = sdk.component('ocr', {
  provider: {
    name: 'idverse',
    translations: {              // Custom translations (optional)
      // Language-specific strings
    },
    retryCount: 3,              // Max retry attempts
    skipLoad: false,            // Skip loading vendor SDK
    workerPathString: '/path',  // Worker script path
    assetPathString: '/assets'  // Asset files path
  }
});
```

**IDVerse Options:**

| Option             | Type      | Description                        |
| ------------------ | --------- | ---------------------------------- |
| `translations`     | `object`  | Custom translation strings         |
| `retryCount`       | `number`  | Maximum retry attempts             |
| `skipLoad`         | `boolean` | Skip loading vendor SDK (advanced) |
| `workerPathString` | `string`  | Path to worker script files        |
| `assetPathString`  | `string`  | Path to asset files                |

***

#### Daon Provider

```javascript theme={null}
const ocrComponent = sdk.component('ocr', {
  provider: {
    name: 'daon',
    products: ['IdentityX', 'VeriFLY'],  // Daon products to use
    processInstanceParameters: [
      {
        name: 'param1',
        mandatory: true,
        minimumLength: 1,
        maximumLength: 50,
        default: 'value'
      }
    ]
  }
});
```

**Daon Options:**

| Option                      | Type       | Description                                       |
| --------------------------- | ---------- | ------------------------------------------------- |
| `products`                  | `string[]` | Array of Daon product names to use                |
| `processInstanceParameters` | `array`    | Process instance parameters (see structure below) |

**Process Instance Parameters:**

| Property        | Type               | Description                     |
| --------------- | ------------------ | ------------------------------- |
| `name`          | `string`           | Parameter name                  |
| `mandatory`     | `boolean`          | Whether parameter is required   |
| `minimumLength` | `number`           | Minimum value length (optional) |
| `maximumLength` | `number`           | Maximum value length (optional) |
| `default`       | `string \| number` | Default value                   |

***

## Methods

### `mount()`

Mounts the OCR component to a DOM element.

**Signature:**

```typescript theme={null}
mount(domElementOrSelector: string | HTMLElement): void
```

**Parameters:**

| Parameter              | Type                    | Required | Description                                                                                              |
| ---------------------- | ----------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `domElementOrSelector` | `string \| HTMLElement` | Yes      | CSS selector string (e.g., `'#ocr-container'`) or HTMLElement object where the component will be mounted |

**Description:**
Mounts the OCR component to the specified DOM element. After mounting, call `start()` to begin the document capture process.

**Example:**

```javascript theme={null}
// Mount to element by ID - capture begins automatically
ocrComponent.mount('#ocr-container');

// Mount to element reference
const container = document.getElementById('ocr-container');
ocrComponent.mount(container);
```

***

### `start()`

<Warning>
  **Legacy Method:** This method is for headless OCR integration and is not recommended for standard use. Modern provider integrations handle the capture flow automatically after mounting. Avoid using this method unless you have a specific headless integration requirement.
</Warning>

Starts the document capture process in headless mode.

**Signature:**

```typescript theme={null}
start(): void
```

**Description:**
Initiates the document capture flow for headless OCR implementations. For standard provider integrations, the capture flow begins automatically when mounting.

***

### `unmount()`

Unmounts the OCR component from the DOM.

**Signature:**

```typescript theme={null}
unmount(): void
```

**Description:**
Removes the OCR component from the DOM and cleans up resources. Call this when the user navigates away or document capture is complete.

**Example:**

```javascript theme={null}
ocrComponent.unmount();
```

***

### `isPreloaded()`

<Warning>
  **Not typically used:** `isPreloaded()` is not used in standard OCR integrations and can be safely ignored. Use events (`detection_complete`, `results`) to track document capture progress instead. This method was designed for legacy headless OCR flows.
</Warning>

Checks if OCR data has been previously captured for this entity.

**Signature:**

```typescript theme={null}
isPreloaded(): boolean | null
```

**Returns:** `boolean | null` - `true` if OCR data exists for this entity, `false` if not, `null` if unable to determine

**Description:**
Returns `true` if the entity has existing OCR/document data in local state. This method was designed for headless integrations where you need to check local state before rendering capture UI.

**For standard provider integrations**, document capture status should be determined by:

* Using the `results` event to receive capture completion status
* Querying your backend API for document verification results
* Checking entity status through the FrankieOne API

**Example:**

```javascript theme={null}
// ✅ Use events to track capture progress
ocrComponent.on('results', ({ document }) => {
  console.log('Document captured:', document);
  proceedToNextStep();
});

ocrComponent.mount('#ocr-container');
// Capture begins automatically
```

<Warning>
  This method only checks for the presence of document data in local state, not the actual verification result. Always verify document status through your backend API before proceeding with verification workflows.
</Warning>

***

### `access()`

<Warning>
  **Legacy Method:** This method is for headless OCR integration and is not recommended for standard use. For standard provider integrations, use events to track document capture progress instead of polling status. Avoid using this method unless you have a specific headless integration requirement.
</Warning>

Accesses reactive data accessors for the OCR component state.

**Signature:**

```typescript theme={null}
access(fieldName: 'status'): Accessor
```

**Description:**
Provides access to internal OCR status for headless implementations. For standard provider integrations, listen to events (`detection_complete`, `results`, etc.) instead of polling status.

***

### `statuses`

Object containing all possible OCR status constants.

**Type:** `Readonly<typeof OCRStatus>`

**Description:**
Provides access to OCR status enum values for comparison in event handlers and status checks.

**Available Statuses:**

<Note>
  **Provider-Specific:** Not all statuses are used by all providers. The specific statuses emitted depend on your chosen provider's workflow and capabilities.
</Note>

| Status                    | Value                                      | Description                                      |
| ------------------------- | ------------------------------------------ | ------------------------------------------------ |
| `WAITING_OCR_RUN`         | `'AWAITING_DOCUMENT_OCR'`                  | Waiting for OCR processing to run                |
| `WAITING_BACK`            | `'AWAITING_DOCUMENT_UPLOAD_BACK'`          | Waiting for back side of document                |
| `WAITING_FRONT`           | `'AWAITING_DOCUMENT_UPLOAD_FRONT'`         | Waiting for front side of document               |
| `COMPLETE`                | `'COMPLETE_OCR'`                           | OCR capture and processing complete              |
| `DOCUMENTS_INVALID`       | `'AWAITING_DOCUMENT_UPLOAD_INVALID_TYPE'`  | Invalid document type provided                   |
| `DOCUMENTS_UPLOAD_FAILED` | `'AWAITING_DOCUMENT_UPLOAD_FAILED_OCR'`    | Document upload failed                           |
| `PROVIDER_OFFLINE`        | `'AWAITING_OCR_RESULTS_PROVIDER_OFFLINE'`  | OCR provider is offline/unavailable              |
| `FAILED_FILE_SIZE`        | `'DOCUMENT_INVALID_EXCEEDED_SIZE_LIMIT'`   | File size exceeds limit                          |
| `FAILED_FILE_FORMAT`      | `'DOCUMENT_INVALID_INCORRECT_FILE_FORMAT'` | Incorrect file format                            |
| `INTERRUPTED`             | `'INTERRUPTED'`                            | Capture flow was interrupted (provider-specific) |

**Example:**

```javascript theme={null}
const ocrComponent = sdk.component('ocr', { provider: { name: 'onfido' } });

ocrComponent.on('input_required', (info, status) => {
  if (status === ocrComponent.statuses.WAITING_FRONT) {
    console.log('Please capture front of document');
  } else if (status === ocrComponent.statuses.WAITING_BACK) {
    console.log('Please capture back of document');
  }
});

ocrComponent.on('results', ({ document }) => {
  const status = ocrComponent.access('status').getValue();

  if (status === ocrComponent.statuses.COMPLETE) {
    console.log('OCR completed successfully');
    console.log('Extracted data:', document);
  }
});
```

***

## Events

The OCR module emits events throughout the document capture lifecycle.

<Warning>
  **Provider-Specific Behavior:** Events and statuses vary by provider. Not all providers emit all events, and some events are provider-specific. Always test with your chosen provider to understand which events are emitted and when.
</Warning>

### `session_data_generated`

Emitted when session data for the vendor is generated.

**Arguments:**

```typescript theme={null}
{
  session: {
    entityId: string;
    vendorParameters: unknown;
  }
}
```

**Example:**

```javascript theme={null}
ocrComponent.on('session_data_generated', ({ session }) => {
  console.log('OCR session created for entity:', session.entityId);
});
```

***

### `ready`

Emitted when the OCR component is ready and mounted.

**Arguments:**

```typescript theme={null}
{
  domElement: HTMLElement;
}
```

**Example:**

```javascript theme={null}
ocrComponent.on('ready', ({ domElement }) => {
  console.log('OCR component ready in element:', domElement);
});
```

***

### `detection_complete`

Emitted when document capture is complete.

**Arguments:**

```typescript theme={null}
{
  provider: string;
} | []
```

**Example:**

```javascript theme={null}
ocrComponent.on('detection_complete', (data) => {
  if (data && data.provider) {
    console.log(`Document captured with ${data.provider}`);
  } else {
    console.log('Document capture complete');
  }
  showProcessingMessage();
});
```

***

### `detection_failed`

Emitted when document capture fails.

**Arguments:**

```typescript theme={null}
{
  message?: string;
}
```

**Example:**

```javascript theme={null}
ocrComponent.on('detection_failed', ({ message }) => {
  console.error('Capture failed:', message);
  showErrorMessage(message || 'Failed to capture document. Please try again.');
});
```

***

### `input_required`

Emitted when a non-positive flow has occurred but is likely recoverable by retrying.

**Arguments:**

```typescript theme={null}
(
  info: {
    documentType: string | null;
    side: 'front' | 'back' | null;
  },
  status: OCRStatus,
  provideFile: (blob: File) => void
)
```

**Description:**
This event indicates that document capture cannot proceed in its current state, but the issue is typically recoverable. Common scenarios include:

* Waiting for front or back side of document
* User needs to retry capture
* Document type mismatch

<Warning>
  **Legacy Parameter:** The `provideFile` callback is for headless OCR integration and is not recommended for standard use. For standard provider integrations, the provider handles file capture automatically. Avoid using this parameter unless you have a specific headless integration requirement.
</Warning>

**Example:**

```javascript theme={null}
ocrComponent.on('input_required', (info, status) => {
  console.log('Input required:', {
    documentType: info.documentType,
    side: info.side,
    status: status
  });

  if (status === ocrComponent.statuses.WAITING_FRONT) {
    showMessage('Please capture the front of your document');
  } else if (status === ocrComponent.statuses.WAITING_BACK) {
    showMessage('Please capture the back of your document');
  }
});
```

***

### `results`

Emitted when OCR processing is complete and document data is available.

**Arguments:**

```typescript theme={null}
{
  document: Document | null;
  entityId: string | null;
}
```

**Description:**
Contains the extracted document information including ID number, expiry date, date of birth, and other fields depending on document type. The document structure matches the [Document Structure](/docs/sdk-reference/individual-module#document-structure) used in the Individual module.

**Example:**

```javascript theme={null}
ocrComponent.on('results', ({ document, entityId }) => {
  if (document) {
    console.log('Document extracted:', {
      type: document.idType,
      number: document.idNumber,
      expiry: document.idExpiry,
      dateOfBirth: document.dateOfBirth,
      country: document.country
    });

    // Document is automatically added to Individual module
    navigateToNextStep();
  } else {
    console.log('No document data extracted');
    showRetryOption();
  }
});
```

***

### `file_uploaded`

Emitted when a file is successfully uploaded.

<Note>
  **Legacy Headless OCR:** This event is primarily used in legacy headless OCR implementations. For standard provider integrations, use the `results` event instead.
</Note>

**Arguments:**

```typescript theme={null}
{
  fileName: string | null;
  mimeType: string | null;
  scanId: string | null;
  statusAfterUpload: OCRStatus;
  statusBeforeUpload: OCRStatus | null;
}
```

**Example:**

```javascript theme={null}
ocrComponent.on('file_uploaded', (meta) => {
  console.log('File uploaded:', meta.fileName);
  console.log('Status changed:', meta.statusBeforeUpload, '→', meta.statusAfterUpload);
});
```

***

### `session_closed`

Emitted when the OCR session is closed.

**Arguments:** None

**Example:**

```javascript theme={null}
ocrComponent.on('session_closed', () => {
  console.log('OCR session closed');
  ocrComponent.unmount();
});
```

***

### `session_interrupted`

Emitted when the user interrupts the capture session.

**Arguments:**

```typescript theme={null}
{
  eventName: string;
  reason: string;
  module: 'OCR' | 'BIOMETRICS';
}
```

<Note>
  **Provider-Specific:**

  * **Onfido:** Emits this when the verification modal is closed.
</Note>

**Example:**

```javascript theme={null}
ocrComponent.on('session_interrupted', ({ reason, eventName }) => {
  console.log(`Session interrupted: ${reason}`);
  console.log('Event:', eventName);
  saveProgress();
});
```

***

### `session_data_failed_loading`

Emitted when session data fails to load.

**Arguments:**

```typescript theme={null}
{
  code?: unknown;
  message: string;
}
```

**Example:**

```javascript theme={null}
ocrComponent.on('session_data_failed_loading', ({ message, code }) => {
  console.error('Failed to load session:', message);
  console.error('Error code:', code);
  showError('Unable to start document capture. Please try again.');
});
```

***

### `vendor_event`

Emitted for provider-specific events.

**Arguments:**

```typescript theme={null}
Record<string, unknown>  // Provider-specific event data
```

**Example:**

```javascript theme={null}
ocrComponent.on('vendor_event', (event) => {
  console.log('Provider event:', event);
  // Handle provider-specific events
});
```

***

### Common Events

The OCR module also emits common events inherited from the event system:

* `error` - When an error occurs
* `warning` - For non-critical warnings
* `info` - Informational messages
* `loading` - Loading state changes

See [Event System Reference](/docs/sdk-reference/events) for details.

***

## Complete Example

```javascript theme={null}
import OneSdk from '@frankieone/one-sdk';

async function captureDocument() {
  try {
    // Initialize SDK
    const sdk = await OneSdk({
      mode: 'production',
      session: { token: await getSessionToken() }
    });

    // Create OCR component with Onfido provider
    const ocrComponent = sdk.component('ocr', {
      provider: {
        name: 'onfido',
        theme: 'light',
        showExitButton: true
      },
      documents: [
        { type: 'DRIVERS_LICENCE', countries: ['AUS'] },
        { type: 'PASSPORT' }
      ]
    });

    // Set up event listeners before mounting
    ocrComponent.on('session_data_generated', ({ session }) => {
      console.log('OCR session started for:', session.entityId);
    });

    ocrComponent.on('ready', () => {
      console.log('OCR component ready');
      // Capture begins automatically - no need to call start()
    });

    ocrComponent.on('detection_complete', () => {
      console.log('Document captured, processing...');
      showMessage('Processing your document...');
    });

    ocrComponent.on('detection_failed', ({ message }) => {
      console.error('Capture failed:', message);
      showError(message);
      enableRetry();
    });

    ocrComponent.on('input_required', (info, status) => {
      console.log('Input required:', info.documentType, info.side);

      if (status === ocrComponent.statuses.WAITING_FRONT) {
        showInstruction('Please capture the front of your document');
      } else if (status === ocrComponent.statuses.WAITING_BACK) {
        showInstruction('Please capture the back of your document');
      }
    });

    ocrComponent.on('file_uploaded', (meta) => {
      console.log('File uploaded:', meta.fileName);
      updateProgress();
    });

    ocrComponent.on('results', ({ document, entityId }) => {
      console.log('OCR complete for entity:', entityId);

      if (document) {
        console.log('Extracted document data:', {
          type: document.idType,
          number: document.idNumber,
          expiry: document.idExpiry,
          dateOfBirth: document.dateOfBirth
        });

        // Document automatically added to Individual module
        ocrComponent.unmount();
        navigateToNextStep();
      } else {
        console.log('No document data extracted');
        showRetryOption();
      }
    });

    ocrComponent.on('session_closed', () => {
      console.log('User closed OCR session');
      ocrComponent.unmount();
    });

    ocrComponent.on('error', (error) => {
      console.error('OCR error:', error);
      showError('Document capture error. Please try again.');
    });

    // Mount the component - capture begins automatically
    ocrComponent.mount('#ocr-container');

  } catch (error) {
    console.error('OCR initialization failed:', error);
    throw error;
  }
}
```

***

## Best Practices

1. **Handle all events, not just `results`** - Also listen to `input_required` (for recoverable states like WAITING\_FRONT, WAITING\_BACK, DOCUMENTS\_INVALID), `detection_failed` (for capture failures), and `error` (for system failures).

2. **Set up event listeners before mounting** - Register all event handlers before calling `mount()` to avoid missing events.

3. **Unmount on navigation** - Always call `unmount()` when the user leaves the page to clean up resources.

4. **Provider-specific configuration** - Review each provider's documentation for optimal configuration.

5. **Error handling** - Always listen to the `error` event and provide user-friendly error messages.

***

## Common Issues

### Component not displaying

Ensure the mount element exists in the DOM and has sufficient size:

```css theme={null}
#ocr-container {
  width: 100%;
  min-height: 600px;
}
```

### Session data failed to load

This usually means the backend session setup failed. Ensure your backend is correctly generating IDV tokens.

### Provider-specific errors

Check the `vendor_event` emissions for provider-specific error details and consult the provider's documentation.

***

## Related

* [SDK Initialization](/docs/sdk-reference/sdk-initialization)
* [Individual Module](/docs/sdk-reference/individual-module)
* [IDV Module](/docs/sdk-reference/idv-module)
* [Event System](/docs/sdk-reference/events)
* [Document Structure](/docs/sdk-reference/individual-module#document-structure)


# SDK Initialization
Source: https://docs.frankieone.com/docs/sdk-reference/sdk-initialization

Complete reference for initializing the OneSDK

## Overview

The OneSDK must be initialized before any modules can be used. The initialization process configures the SDK with your session token, sets the environment mode, and prepares all modules for use.

## Import

```javascript theme={null}
import OneSdk from '@frankieone/one-sdk';
```

## Method

### `OneSdk(parameters)`

Initializes the OneSDK and returns a Promise that resolves to the SDK context object. `OneSdk` is the default export of the package and is itself the initialization function.

**Signature:**

```typescript theme={null}
OneSdk(parameters: OneSdkRootParameters): Promise<OneSdkContext>
```

**Parameters:**

| Parameter         | Type                      | Required    | Default        | Description                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ----------------- | ------------------------- | ----------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode`            | `string \| ModeOption`    | No          | `"production"` | SDK operational mode. Use `"production"` for live deployments, `"development"` when building and testing your integration, or `"dummy"` to explore the SDK with locally mocked responses (no backend required). The target environment (sandbox vs production) is determined by the customer credentials used to generate your session token. See [SDK Modes](#sdk-modes) for details. Can also be an object for advanced configuration. |
| `session`         | `SessionOptions`          | Conditional | -              | Session configuration containing authentication token and persistence settings. Required when `mode` is `"production"` or `"development"`. Optional when `mode` is `"dummy"`.                                                                                                                                                                                                                                                            |
| `recipe`          | `string \| PartialRecipe` | No          | `"auto"`       | Verification recipe configuration. Pass a string recipe name (e.g., `"kyc-basic"`) to use a predefined recipe, or pass a partial recipe object to customize configuration. When omitted, defaults to automatic recipe selection.                                                                                                                                                                                                         |
| `telemetry`       | `boolean`                 | No          | `true`         | Enable or disable telemetry. When `true` (default), the SDK sends diagnostic data to FrankieOne to help troubleshoot issues. It's recommended to leave this enabled for easier support. Set to `false` to disable.                                                                                                                                                                                                                       |
| `devtools`        | `boolean`                 | No          | `false`        | Enable developer tools overlay for debugging. When `true`, attaches debugging utilities to help inspect SDK state and behavior during development. Should only be enabled in development environments.                                                                                                                                                                                                                                   |
| `individualLevel` | `string`                  | No          | -              | Controls the level of detail retrieved for entity data from the API. Use `'base64'` to include document scan images as base64-encoded strings, or `'meta'` to retrieve only metadata without images. See [Individual Module](/docs/sdk-reference/individual-module#module-options) for details.                                                                                                                                          |

<Note>
  When `telemetry` is enabled, the SDK automatically redacts sensitive values (e.g. tokens, API keys, secrets, `clientID`) from component options and recipe data before including them in telemetry events.
</Note>

### SessionOptions

Session configuration object. Required when `mode` is not `"dummy"`.

| Property       | Type             | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------- | ---------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token`        | `string \| null` | Yes      | -       | Session authentication token. Your backend server obtains this token by calling the [FrankieOne session API](/docs/sdk-reference/sdk-initialization#generating-session-tokens), then passes it to your frontend to initialize the SDK. This token authorizes the SDK to perform verification operations for a specific entity. Must be a valid JWT token string. Pass `null` only in special cases where the token will be set later. |
| `persist`      | `boolean`        | No       | `false` | Enable session persistence across browser refreshes and page navigation. When `true`, the session token is stored in browser storage and automatically reused on next initialization. When `false`, a new session must be created each time. See [Session Management](/docs/sdk-reference/session-management) for persistence details.                                                                                                |
| `appReference` | `string`         | No       | -       | A reference string identifying the application integrating with OneSDK. This value is included in telemetry data sent to FrankieOne, allowing FrankieOne to distinguish which application under your account generated a given event. Useful when you have multiple applications using OneSDK on the same customer account. Recommended format: `"app-name-vX.Y.Z"` (e.g., `"my-kyc-app-v1.2.0"`).                                    |

### Recipe Configuration

The `recipe` parameter controls how the SDK performs verification. You can pass either a string (recipe name) or an object (recipe configuration).

#### String Recipe Name

Pass a predefined recipe name to use standard verification workflows:

```javascript theme={null}
OneSdk({
  session: { token: 'your-token' },
  recipe: 'standard_kyc'
});
```

**Common Recipe Names:**

* `"auto"` - Automatically selects appropriate recipe (default)
* `"default"` - Standard verification flow
* `"standard_kyc"` - Standard KYC verification
* `"full"` - Full verification with all checks
* `"safe_harbour"` - Safe harbour compliance checks
* `"safe_harbour_plus"` - Enhanced safe harbour checks
* `"international"` - International verification flow
* `"gov_id"` - Government ID verification
* `"aml_only"` - AML checks only
* Custom recipe names configured by FrankieOne

#### Recipe Configuration Object

Pass a partial configuration object to customize the verification flow:

```javascript theme={null}
OneSdk({
  session: { token: 'your-token' },
  recipe: {
    name: 'standard_kyc',
    // Module-specific configurations can be added here
    // See individual module documentation for available options
  }
});
```

**Recipe Object Structure:**

| Property              | Type     | Description                                                                                                                                                                                                                                                                                                                                         |
| --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                | `string` | Recipe name (required when using object form)                                                                                                                                                                                                                                                                                                       |
| Module configurations | `object` | Each module can add its own configuration properties. See [Form Module Configuration](/docs/sdk-reference/form-module/configuration), [IDV Module](/docs/sdk-reference/idv-module), [OCR Module](/docs/sdk-reference/ocr-module), [Biometrics Module](/docs/sdk-reference/biometrics-module), and other module documentation for available options. |

**Examples:**

```javascript theme={null}
// Basic recipe by name
recipe: 'standard_kyc'

// Recipe object with name only
recipe: {
  name: 'standard_kyc'
}

// Custom recipe configuration (module-specific options depend on your recipe)
recipe: {
  name: 'custom_kyc',
  // Module-specific configurations added by recipe
}
```

<Note>
  Recipe configuration is typically managed by FrankieOne. The SDK will fetch and merge the recipe configuration from the server with any recipe options you pass during initialization.
</Note>

***

### SDK Modes

The SDK supports three operational modes:

| Mode        | Value           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Production  | `"production"`  | For live, production deployments. Makes real API calls to FrankieOne. Requires a session token. Use this with your production customer credentials.                                                                                                                                                                                                                                                                                                   |
| Development | `"development"` | For use during integration and testing. Makes real API calls to FrankieOne, just like production. Requires a session token. Use this mode while building and testing your integration before going live. Note that the target environment (sandbox vs production) is determined by the customer credentials used to generate your session token, not by this mode setting — ensure your credentials match the environment you intend to test against. |
| Dummy       | `"dummy"`       | Runs the SDK entirely with locally mocked responses — no API calls are made and no session token is required. Use this mode to explore OneSDK's UI components and flows in complete isolation, without needing any backend integration or FrankieOne account. Ideal for prototyping and getting familiar with the SDK before connecting to a real environment.                                                                                        |

**Type Definition:**

```typescript theme={null}
enum SdkModes {
  DEV = 'development',
  PROD = 'production',
  DUMMY = 'dummy',
}
```

## Return Value

Returns a `Promise<OneSdkContext>` that resolves to the SDK context object.

### OneSdkContext

The SDK context provides access to all modules and SDK functionality:

| Property                   | Type                                   | Description                                                                                                                                                                                                                                                                                                                                                                     |
| -------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `individual()`             | `() => IndividualModuleContext`        | Factory function that returns the Individual (KYC) module context for managing individual identity verification. Provides methods for collecting and submitting personal information, documents, addresses, and consents. See [Individual Module Reference](/docs/sdk-reference/individual-module).                                                                             |
| `component()`              | `ComponentFactory`                     | Dynamic component loader that creates instances of verification components. Accepts component name and options, returns component instance. Available components: [OCR Module](/docs/sdk-reference/ocr-module), [Biometrics Module](/docs/sdk-reference/biometrics-module), [Device Module](/docs/sdk-reference/device-module), [Form Module](/docs/sdk-reference/form-module). |
| `flow()`                   | `FlowFactory`                          | Dynamic flow loader that creates instances of verification flows (pre-built multi-step processes). Accepts flow name and options, returns flow instance. Use this to access the [IDV Module](/docs/sdk-reference/idv-module).                                                                                                                                                   |
| `session`                  | `SessionFacade`                        | Session management interface providing methods to query session state, entity information, and session metadata. See [Session Management Reference](/docs/sdk-reference/session-management).                                                                                                                                                                                    |
| `emit()`                   | `(eventName, ...args) => void`         | Emit custom global events. See [Event System Reference](/docs/sdk-reference/events).                                                                                                                                                                                                                                                                                            |
| `on()`                     | `(eventName, callback) => void`        | Register event listener for global SDK events (error, warning, loading, network events, etc.). Events are not fully typed. See [Event System Reference](/docs/sdk-reference/events).                                                                                                                                                                                            |
| `off()`                    | `(eventName, callback) => void`        | Remove previously registered event listener. Pass the exact same callback function reference used with `on()`. See [Event System Reference](/docs/sdk-reference/events).                                                                                                                                                                                                        |
| `utils.getVendorConsent()` | `() => Promise<VendorConsentResponse>` | Discovers any dynamic vendor consent requirements for the configured provider. Currently only Incode has a combined-consent concept; returns `{ vendor: null }` for every other provider. Added in v1.9.36.                                                                                                                                                                     |

### `utils.getVendorConsent()`

Some vendors gate access to their SDK behind a dynamic set of consent checkboxes configured per customer, rather than a fixed list of consent types. `getVendorConsent()` lets you discover what's currently required before mounting a component, so you can render the checkboxes and collect consent up front instead of hitting an error at mount time.

**Signature:**

```typescript theme={null}
getVendorConsent(): Promise<VendorConsentResponse>
```

**Returns:** `Promise<VendorConsentResponse>`, one of:

| Shape                                                                                     | Description                                                                                                                                                                                                     |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{ vendor: null }`                                                                        | No dynamic consent is required. Returned for every provider except Incode, and even for Incode if neither the `ocr` nor `biometrics` recipe config is set to the `incode` provider.                             |
| `{ vendor: 'incode', title: string, terms: string, consents: IncodeVendorConsentItem[] }` | Incode is configured and has one or more consent items to collect. Each `IncodeVendorConsentItem` has `checkboxId: string`, `consentText: string`, `optional: boolean`, and an optional `consentType?: string`. |

**Description:**
Only calls the backend when `ocr` or `biometrics` is configured for the `incode` provider in the active recipe; otherwise short-circuits to `{ vendor: null }` without a network request. Grant a returned consent item via `individual().addConsent('incode.<checkboxId>')` before mounting OCR or biometrics with Incode — see [`addConsent()`](/docs/sdk-reference/individual-module#addconsent) for details.

**Example:**

```javascript theme={null}
const { vendor, ...consentData } = await oneSdk.utils.getVendorConsent();

if (vendor === 'incode') {
  // Render consentData.title / consentData.terms / consentData.consents to the user,
  // then record acceptance for each required checkbox before mounting Incode:
  consentData.consents
    .filter((item) => !item.optional)
    .forEach((item) => {
      individual().addConsent(`incode.${item.checkboxId}`);
    });
}
```

***

## Usage Examples

### Basic Initialization (Production)

```javascript theme={null}
import OneSdk from '@frankieone/one-sdk';

const oneSDKInstance = await OneSdk({
  mode: 'production',
  session: {
    token: 'your-session-token-here'
  }
});
```

### Development Mode with DevTools

```javascript theme={null}
const oneSDKInstance = await OneSdk({
  mode: 'development',
  session: {
    token: 'your-dev-token',
    appReference: 'my-app-v1.2.3'
  },
  devtools: true
});
```

### Dummy Mode (No Backend Required)

```javascript theme={null}
const oneSDKInstance = await OneSdk({
  mode: 'dummy'
});
```

### With Recipe (String Name)

```javascript theme={null}
const oneSDKInstance = await OneSdk({
  mode: 'production',
  session: {
    token: 'your-session-token'
  },
  recipe: 'standard_kyc'
});
```

### With Recipe (Object Configuration)

```javascript theme={null}
const oneSDKInstance = await OneSdk({
  mode: 'production',
  session: {
    token: 'your-session-token'
  },
  recipe: {
    name: 'standard_kyc',
    // Example: OCR module configuration
    ocr: {
      provider: {
        name: 'incode'
      },
      modes: ['auto']
    }
  }
});
```

### With Token Persistence

```javascript theme={null}
const oneSDKInstance = await OneSdk({
  mode: 'production',
  session: {
    token: 'your-session-token',
    persist: true  // Token will be stored and reused
  }
});
```

### Generating Session Tokens

Session tokens must be generated on your backend server by calling the FrankieOne API. **Never expose your API credentials in client-side code.**

<Tabs>
  <Tab title="Backend (Node.js/Express)">
    ```javascript theme={null}
    const express = require('express');
    const app = express();

    const CUSTOMER_ID = process.env.FRANKIE_CUSTOMER_ID;
    const CUSTOMER_CHILD_ID = process.env.FRANKIE_CUSTOMER_CHILD_ID; // Optional
    const API_KEY = process.env.FRANKIE_API_KEY;
    const FRANKIE_BASE_URL = process.env.FRANKIE_BASE_URL || 'https://backend.kycaml.uat.frankiefinancial.io';

    app.use(express.json());

    /**
     * Generates a base64-encoded authorization token.
     * Format: base64(customerID:apiKey) or base64(customerID:customerChildID:apiKey)
     */
    function getAuthToken() {
      const elements = [CUSTOMER_ID, CUSTOMER_CHILD_ID, API_KEY].filter(Boolean);
      return Buffer.from(elements.join(':')).toString('base64');
    }

    /**
     * Generates a OneSDK session token
     */
    async function generateSessionToken(reference) {
      try {
        const response = await fetch(
          `${FRANKIE_BASE_URL}/auth/v2/machine-session`,
          {
            method: 'POST',
            headers: {
              'authorization': `machine ${getAuthToken()}`,
              'Content-Type': 'application/json',
            },
            body: JSON.stringify({
              permissions: {
                preset: 'one-sdk',
                reference: reference || `session-${Date.now()}`,
              },
            }),
          }
        );

        if (!response.ok) {
          throw new Error(`Failed to generate token: ${response.statusText}`);
        }

        return await response.json();
      } catch (error) {
        console.error('Token generation error:', error);
        throw error;
      }
    }

    /**
     * Endpoint to create a verification session
     */
    app.post('/api/create-session', async (req, res) => {
      try {
        const { reference } = req.body;
        const session = await generateSessionToken(reference);

        res.json({
          token: session.token,
          sessionId: session.session_id
        });
      } catch (error) {
        res.status(500).json({
          error: 'Failed to generate session token',
          message: error.message
        });
      }
    });

    app.listen(3001, () => {
      console.log('Server running on http://localhost:3001');
    });
    ```
  </Tab>

  <Tab title="Frontend">
    ```javascript theme={null}
    /**
     * Fetches a session token from your backend
     */
    async function createVerificationSession(reference) {
      try {
        const response = await fetch('/api/create-session', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            reference: reference || `user-${Date.now()}`
          })
        });

        if (!response.ok) {
          throw new Error('Failed to create session');
        }

        return await response.json();
      } catch (error) {
        console.error('Session creation error:', error);
        throw error;
      }
    }

    /**
     * Initialize OneSDK with the session token
     */
    async function initializeSDK() {
      try {
        // Get session token from your backend
        const { token } = await createVerificationSession('user-123');

        // Initialize the SDK
        const sdk = await OneSdk({
          mode: 'production',
          session: { token }
        });

        console.log('SDK initialized successfully');
        return sdk;
      } catch (error) {
        console.error('SDK initialization failed:', error);
      }
    }

    // Usage
    initializeSDK();
    ```
  </Tab>
</Tabs>

<Note>
  For the complete implementation with React hooks and error handling, see the [Embedded OneSDK Quick Start](/docs/embedded-flows/quick-start).
</Note>

## Error Handling

`OneSdk()` returns a Promise that will reject if initialization fails. Always wrap it in a try-catch block:

```javascript theme={null}
try {
  const oneSDKInstance = await OneSdk({
    mode: 'production',
    session: { token: 'your-token' }
  });

  console.log('SDK initialized successfully');
} catch (error) {
  console.error('Failed to initialize SDK:', error);
  // Handle initialization error
}
```

## Events

The SDK emits several events during and after initialization:

### `resolved_root_config`

Emitted when the root configuration is resolved.

```javascript theme={null}
oneSDKInstance.on('resolved_root_config', (config) => {
  console.log('Configuration resolved:', config);
});
```

### `telemetry`

Emitted for internal diagnostic data. Used by FrankieOne for troubleshooting and support.

<Note>
  Telemetry events are primarily for internal use by FrankieOne support. Event structure is not fully typed and may change.
</Note>

```javascript theme={null}
oneSDKInstance.on('telemetry', (event) => {
  // For debugging purposes only
  console.log('Telemetry event:', event);
});
```

### `error`

Emitted when an error occurs.

```javascript theme={null}
oneSDKInstance.on('error', (error) => {
  console.error('SDK error:', error);
});
```

### `warning`

Emitted for configuration warnings.

```javascript theme={null}
oneSDKInstance.on('warning', (warning) => {
  console.warn('SDK warning:', warning.message);
});
```

### Network Events

The SDK monitors network connectivity:

```javascript theme={null}
oneSDKInstance.on('network_offline', () => {
  console.log('Network connection lost');
});

oneSDKInstance.on('network_online', () => {
  console.log('Network connection restored');
});
```

## Session Management

After initialization, you can access session information through the `session` property:

```javascript theme={null}
const sessionId = oneSDKInstance.session.getSessionId();
const entityId = oneSDKInstance.session.getEntityId();
const reference = oneSDKInstance.session.getReference();
const isPersisted = oneSDKInstance.session.isPersisted();

// Get extra session data
const extraData = oneSDKInstance.session.getExtraData();
console.log('Requested documents:', extraData.requestedDocuments);

// Get session expiration
const expirationEpoch = oneSDKInstance.session.getExpirationEpoch();

// Unpersist the session (remove from storage)
oneSDKInstance.session.unpersist();
```

## JavaScript/TypeScript Usage

OneSDK provides type definitions for TypeScript projects, but full TypeScript support is not available for all APIs:

```javascript theme={null}
import OneSdk from '@frankieone/one-sdk';

// Initialize the SDK
const sdk = await OneSdk({
  mode: 'production',
  session: {
    token: 'your-token'
  }
});

// Access modules
const individualModule = sdk.individual();
const formComponent = sdk.component('form', options);
const idvFlow = sdk.flow('idv', options);

// Listen to events
sdk.on('error', (error) => {
  console.error('SDK error:', error);
});

// Access session information
const sessionId = sdk.session.getSessionId();
const entityId = sdk.session.getEntityId();
```

## Best Practices

1. **Always handle errors**: Wrap initialization in try-catch blocks to handle failures gracefully.

2. **Use environment variables**: Store tokens in environment variables, never hardcode them.

3. **Enable devtools in development**: Use `devtools: true` during development for better debugging.

4. **Set appReference**: Always provide an `appReference` to help track issues in logs.

5. **Listen to network events**: Monitor network connectivity to improve user experience.

6. **Use token persistence wisely**: Only enable `persist: true` when appropriate for your use case.

## Common Issues

### Token expired or invalid

If the session token is expired or invalid, initialization will fail. Generate a fresh token from your backend and reinitialize the SDK. See the [Generating Session Tokens](#generating-session-tokens) example above.

### CSP (Content Security Policy) errors

If you see CSP errors in the browser console, ensure your CSP headers allow the OneSDK resources:

```
Content-Security-Policy:
  script-src 'self' https://assets.frankiefinancial.io;
  style-src 'self' https://*.frankiefinancial.io;
  connect-src 'self' https://*.frankiefinancial.io https://*.frankieone.com;
  img-src 'self' https://*.frankiefinancial.io data:;
  font-src 'self' https://*.frankiefinancial.io data:;
  frame-src 'self' https://*.frankiefinancial.io https://*.frankie.one;
```

If you are using a third-party vendor (Onfido, Incode, Sumsub, etc.), additional vendor-specific domains are required. See [Vendor CSP Settings](/docs/sdk-reference/vendor-customizations#content-security-policy-csp-settings) for the full list.

## Related

* [Individual Module](/docs/sdk-reference/individual-module)
* [Session Management](/docs/sdk-reference/session-management)
* [Event System](/docs/sdk-reference/events)
* [Form Module](/docs/sdk-reference/form-module)
* [IDV Module](/docs/sdk-reference/idv-module)


# Session Management
Source: https://docs.frankieone.com/docs/sdk-reference/session-management

Reference for managing OneSDK sessions

## Overview

The Session API provides methods to access and manage session information after SDK initialization. Session data includes entity identifiers, session tokens, and metadata that persists throughout the verification flow.

## Accessing the Session

The session is available through the SDK context after initialization:

```javascript theme={null}
const oneSDKInstance = await OneSdk({
  mode: 'production',
  session: { token: 'your-token' }
});

// Access session methods
const sessionId = oneSDKInstance.session.getSessionId();
```

## Methods

### `getSessionId()`

Returns the current session identifier.

**Signature:**

```typescript theme={null}
getSessionId(): string
```

**Returns:** `string` - The unique session ID generated when the session was created.

**Description:**
The session ID is a unique identifier for this verification session. It's used internally by the SDK to maintain state and can be included in support requests or logs to help trace issues. This ID remains constant throughout the session lifecycle.

**Example:**

```javascript theme={null}
const sessionId = oneSDKInstance.session.getSessionId();
console.log('Session ID:', sessionId);

// Use in support requests or logs
console.log('Support ID:', sessionId);
```

***

### `getEntityId()`

Returns the entity ID associated with this session, if available.

**Signature:**

```typescript theme={null}
getEntityId(): string | null
```

**Returns:** `string | null` - The entity ID representing the individual or business being verified, or `null` if not yet assigned.

**Description:**
The entity ID uniquely identifies the person or business undergoing verification in your system. It's typically set when the session is created on your backend and links the SDK session to a profile in the Frankie platform. Returns `null` if the session hasn't been associated with an entity yet (e.g., during initial setup or before verification begins).

**Use Cases:**

* Reference the entity when calling backend APIs
* Track entity across multiple verification sessions

**Example:**

```javascript theme={null}
const entityId = oneSDKInstance.session.getEntityId();
if (entityId) {
  console.log('Entity ID:', entityId);
  // Fetch data from your backend API using entityId
  const userData = await fetch(`/api/users/${entityId}`).then(r => r.json());
} else {
  console.log('No entity associated yet');
}
```

***

### `getReference()`

Returns the reference identifier for this session.

**Signature:**

```typescript theme={null}
getReference(): string | null
```

**Returns:** `string | null` - A custom reference string you provided when creating the session, or `null` if no reference was set.

**Description:**
The reference is an optional custom identifier you can set when generating the session token on your backend. It allows you to link the OneSDK session to your own internal reference system (e.g., application ID, customer ID, transaction ID). This is particularly useful for correlating verification sessions with records in your own database.

**Example:**

```javascript theme={null}
const reference = oneSDKInstance.session.getReference();
if (reference) {
  console.log('Application Reference:', reference);
  // Look up application in your system
  const application = await getApplicationByReference(reference);
} else {
  console.log('No reference set');
}
```

***

### `isPersisted()`

Checks whether the session token was loaded from storage (persisted from a previous initialization).

**Signature:**

```typescript theme={null}
isPersisted(): boolean
```

**Returns:** `boolean` - `true` if the session was restored from browser storage, `false` if it's a newly created session.

**Description:**
When you initialize the SDK with `persist: true`, the session token is stored in browser storage (localStorage or sessionStorage). On subsequent page loads or SDK initializations, the SDK automatically checks for and restores the stored token. This method tells you whether the current session is a restored one or a freshly created one.

**Use Cases:**

* Determine if a user is resuming a previous verification session
* Show different UI for new vs. returning users
* Track session continuity for analytics
* Decide whether to show onboarding instructions

**Example:**

```javascript theme={null}
if (oneSDKInstance.session.isPersisted()) {
  console.log('Welcome back! Resuming your verification...');
  // Skip onboarding, go directly to where they left off
  resumeVerification();
} else {
  console.log('Starting new verification session');
  // Show onboarding/instructions
  showWelcomeScreen();
}
```

***

### `unpersist()`

Removes the session token from storage. After calling this, the next SDK initialization will not reuse the stored token.

**Signature:**

```typescript theme={null}
unpersist(): void
```

**Returns:** `void` - No return value.

**Description:**
Removes the currently persisted session token from browser storage. This is important for security and user privacy - always call this method when:

* User logs out
* User explicitly ends their verification session
* Session expires or becomes invalid
* User switches accounts

After calling `unpersist()`, the next SDK initialization will require a fresh token (it won't automatically restore the old one).

**Important:** This only removes the token from storage; it doesn't invalidate the session on the server. The session remains valid until it expires or is explicitly invalidated via your backend.

**Example:**

```javascript theme={null}
function handleLogout() {
  // Clear persisted session from browser storage
  oneSDKInstance.session.unpersist();
  console.log('Session cleared from storage');

  // Also invalidate on backend (optional but recommended)
  await revokeSessionOnBackend(sessionId);

  // Redirect to login
  window.location.href = '/login';
}
```

***

### `getFrankie2customer()`

Returns the frankie2customer flag value.

**Signature:**

```typescript theme={null}
getFrankie2customer(): boolean | undefined
```

**Returns:** `boolean | undefined` - The frankie2customer flag value, or `undefined` if not set.

**Description:**
Internal flag that indicates whether this session uses the Frankie v2 API. This is used in specific integration scenarios for customers using the v2 API.

**Note:** This is primarily for internal use and specific partnership integrations. Standard SDK implementations typically don't need to check this value.

**Example:**

```javascript theme={null}
const isFrankie2customer = oneSDKInstance.session.getFrankie2customer();
if (isFrankie2customer) {
  console.log('Using Frankie v2 API');
} else {
  console.log('Standard API integration');
}
```

***

### `getExtraData()`

Returns additional session metadata that may include document requirements and configuration.

**Signature:**

```typescript theme={null}
getExtraData(): {
  linkExpiry?: string;
  [key: string]: any;
}
```

**Returns:** Object with optional properties containing session metadata. All properties are optional and may be `undefined`.

**Description:**
Extra data contains session-specific metadata that can be set when generating the session token on your backend. This is particularly useful for scenarios where you need to pass custom configuration or context to the SDK.

**Properties:**

| Property      | Type                  | Description                                                                                                                                |
| ------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `linkExpiry`  | `string \| undefined` | Session link expiration timestamp or date string. Format depends on your backend implementation (could be ISO 8601, Unix timestamp, etc.). |
| Custom fields | `any`                 | Additional custom metadata fields that you set when generating the session token on your backend.                                          |

**Example:**

```javascript theme={null}
const extraData = oneSDKInstance.session.getExtraData();

if (extraData.linkExpiry) {
  console.log('Session expires:', extraData.linkExpiry);
  // Parse and show expiration warning
  const expiryDate = new Date(extraData.linkExpiry);
  if (expiryDate < new Date()) {
    showExpiryWarning();
  }
}

// Access custom metadata if you set any
if (extraData.customField) {
  console.log('Custom data:', extraData.customField);
}
```

***

### `getExpirationEpoch()`

Returns the session expiration time as a Unix epoch timestamp.

**Signature:**

```typescript theme={null}
getExpirationEpoch(): number
```

**Returns:** `number` - Unix timestamp in **seconds** since epoch (January 1, 1970 00:00:00 UTC).

**Description:**
Every session has an expiration time after which it becomes invalid. This method returns the exact timestamp when the session expires. You should monitor this value to warn users before expiration or to refresh sessions proactively.

**Important:** The returned value is in **seconds**, not milliseconds. When using with JavaScript `Date`, multiply by 1000: `new Date(epoch * 1000)`.

**Use Cases:**

* Display countdown timer to users
* Warn users before session expires
* Automatically refresh/extend sessions
* Determine if session is still valid

**Example:**

```javascript theme={null}
const expirationEpoch = oneSDKInstance.session.getExpirationEpoch();

// Convert to JavaScript Date (note: multiply by 1000)
const expirationDate = new Date(expirationEpoch * 1000);
console.log('Session expires at:', expirationDate.toLocaleString());

// Check if session is expired
const now = Date.now();
const isExpired = now > (expirationEpoch * 1000);

if (isExpired) {
  console.warn('Session has expired!');
  handleExpiredSession();
} else {
  // Calculate time remaining
  const timeRemaining = (expirationEpoch * 1000) - now;
  const minutesRemaining = Math.floor(timeRemaining / 60000);

  console.log(`Session expires in ${minutesRemaining} minutes`);

  // Warn if less than 5 minutes remaining
  if (minutesRemaining < 5) {
    showExpirationWarning(`Your session will expire in ${minutesRemaining} minutes`);
  }
}
```

## Session Persistence

When initializing the SDK with `persist: true`, the session token is stored in browser storage. On subsequent initializations, the stored token takes priority if valid.

**Important:** Even with `persist: true`, you must still provide a token in the `session.token` parameter. The SDK will:

1. Check if a valid stored token exists
2. If yes and the stored token is valid, **use the stored token** (it takes priority over the provided token)
3. If no stored token or stored token is invalid, use the provided token and store it

A stored token is considered **invalid** if it has a different entity ID, a different customer reference, or has expired. Invalid tokens are rejected gracefully — a `warning` event is emitted, and the SDK falls back to the provided token. No error is thrown.

<Warning>
  **No token refresh mechanism.** If a session expires mid-flow, there is no way to refresh it. The user must restart the verification flow with a new token obtained from your backend. To avoid this, monitor `getExpirationEpoch()` and warn users before their session expires.
</Warning>

### Enable Persistence

```javascript theme={null}
// First initialization - token is stored
const oneSDKInstance = await OneSdk({
  mode: 'production',
  session: {
    token: 'your-token',  // Required - will be stored
    persist: true
  }
});

// Subsequent initialization - stored token is used if valid
const oneSDKInstance = await OneSdk({
  mode: 'production',
  session: {
    token: 'new-token',  // Required but may not be used if stored token is valid
    persist: true
  }
});
```

### Check and Clear Persistence

```javascript theme={null}
// Check if current session is persisted
if (oneSDKInstance.session.isPersisted()) {
  console.log('This session was restored from storage');

  // Clear it when done (e.g., on logout)
  oneSDKInstance.session.unpersist();
}
```

### Use Cases for Persistence

**When to enable:**

* Multi-page flows where users navigate between pages
* Resumable verification processes
* Saving progress across browser refreshes

**When to disable:**

* One-time verification flows
* Public/shared device scenarios
* When security requires fresh sessions each time

## Complete Example

Here's a comprehensive example showing session management in a verification flow:

```javascript theme={null}
import OneSdk from '@frankieone/one-sdk';

async function initializeVerification() {
  try {
    // Initialize SDK
    const sdk = await OneSdk({
      mode: 'production',
      session: {
        token: await fetchTokenFromBackend(),
        persist: true,
        appReference: 'my-app-v1.0.0'
      }
    });

    // Log session information
    console.log('Session initialized:', {
      sessionId: sdk.session.getSessionId(),
      entityId: sdk.session.getEntityId(),
      reference: sdk.session.getReference(),
      isPersisted: sdk.session.isPersisted(),
      expiresAt: new Date(sdk.session.getExpirationEpoch() * 1000)
    });

    // Check extra data for custom metadata
    const extraData = sdk.session.getExtraData();
    if (extraData.linkExpiry) {
      console.log('Session link expires:', extraData.linkExpiry);
    }

    // Monitor session expiration
    const expirationEpoch = sdk.session.getExpirationEpoch();
    const timeUntilExpiry = (expirationEpoch * 1000) - Date.now();

    if (timeUntilExpiry < 5 * 60 * 1000) {
      console.warn('Session expires in less than 5 minutes');
    }

    // Set up expiration warning
    setTimeout(() => {
      alert('Your session is about to expire. Please complete verification soon.');
    }, timeUntilExpiry - (2 * 60 * 1000)); // Warn 2 minutes before expiry

    return sdk;

  } catch (error) {
    console.error('Failed to initialize:', error);
    throw error;
  }
}

function logout(sdk) {
  // Clear persisted session on logout
  sdk.session.unpersist();
  console.log('Session cleared');
}

// Initialize
const sdk = await initializeVerification();

// Later, on logout
logout(sdk);
```

## Session Lifecycle

```mermaid theme={null}
sequenceDiagram
    participant Backend
    participant App
    participant SDK
    participant Storage

    App->>Backend: Request session token
    Backend->>App: Return token
    App->>SDK: Initialize with token (persist: true)
    SDK->>Storage: Store token
    SDK->>App: Return SDK context

    Note over App,SDK: User navigates away / refreshes page

    App->>SDK: Initialize (with token, persist: true)
    SDK->>Storage: Check for stored token
    Storage->>SDK: Return stored token
    SDK->>SDK: Validate stored token (expiry, entityId, reference)
    alt Stored token valid
        SDK->>App: Return SDK context (isPersisted: true, uses stored token)
    else Stored token invalid
        SDK->>Storage: Store new token
        SDK->>App: Return SDK context (isPersisted: false, uses provided token)
    end

    App->>SDK: session.unpersist()
    SDK->>Storage: Remove token
```

## Best Practices

1. **Always check expiration**: Monitor `getExpirationEpoch()` and warn users before their session expires. There is no refresh mechanism — expired sessions require a new token and the user must restart the flow.

2. **Clear sessions on logout**: Call `unpersist()` when users log out to prevent session reuse.

3. **Log session IDs for debugging**: Include `getSessionId()` in error reports to help support teams.

4. **Use appReference**: Set a meaningful `appReference` during initialization for better tracking.

5. **Handle missing entity IDs**: `getEntityId()` may return null before verification completes.

6. **Validate extra data**: Always check if extra data properties exist before using them.

## Common Issues

### Session expires during verification

There is no token refresh mechanism. If the session expires mid-flow, the user must restart with a new token. Proactively warn users before their session expires to avoid losing progress:

```javascript theme={null}
const expirationEpoch = sdk.session.getExpirationEpoch();
const timeLeft = (expirationEpoch * 1000) - Date.now();
const fiveMinutes = 5 * 60 * 1000;

if (timeLeft < 0) {
  // Already expired — the user must start over
  showMessage('Your session has expired. Please start the verification process again.');
  redirectToStart();
} else if (timeLeft < fiveMinutes) {
  // Expiring soon — warn the user
  showWarning(`Your session will expire in ${Math.floor(timeLeft / 60000)} minutes.`);
}
```

### Persisted session not working

Ensure your app has the necessary storage permissions and isn't running in private/incognito mode:

```javascript theme={null}
try {
  const sdk = await OneSdk({
    session: { token: 'token', persist: true }
  });
} catch (error) {
  if (error.message.includes('storage')) {
    console.warn('Session persistence not available');
    // Fall back to non-persistent mode
  }
}
```

## Related

* [SDK Initialization](/docs/sdk-reference/sdk-initialization)
* [Event System](/docs/sdk-reference/events)
* [Error Handling](/docs/sdk-reference/error-handling)


# Vendor Customizations
Source: https://docs.frankieone.com/docs/sdk-reference/vendor-customizations

Advanced vendor-specific customization options for styling, theming, and configuration across identity verification providers

## Overview

This page covers advanced vendor-specific customization options for styling, theming, and configuration that go beyond the basic provider options documented on each module's page.

For basic provider options such as `sdkVersion`, `showExitButton`, `crossDevicePolicy`, `fallback`, and `biometricsVariant`, refer to the individual module pages:

* [IDV Module](/docs/sdk-reference/idv-module#provider-specific-options)
* [OCR Module](/docs/sdk-reference/ocr-module#provider-specific-options)
* [Biometrics Module](/docs/sdk-reference/biometrics-module#provider-specific-options)

***

## Content Security Policy (CSP) Settings

If your application enforces a Content Security Policy, you will need to allowlist domains for both OneSDK itself and the third-party vendor SDK it loads at runtime. Without the correct CSP rules, the browser will block scripts, API calls, or media resources and the verification flow will fail silently or show errors.

### OneSDK Base Domains

All integrations require these FrankieOne domains regardless of which vendor you use:

```
script-src  https://assets.frankiefinancial.io;
style-src   https://*.frankiefinancial.io;
connect-src https://*.frankiefinancial.io https://*.frankieone.com;
img-src     https://*.frankiefinancial.io data:;
font-src    https://*.frankiefinancial.io data:;
frame-src   https://*.frankiefinancial.io https://*.frankie.one;
```

### Vendor-Specific Domains

Add the rules below for the vendor(s) you are integrating with. These are **in addition to** the base domains above and your existing `'self'` policy.

<Tabs>
  <Tab title="Onfido">
    Onfido maintains their own CSP guide. Refer to [Onfido CSP Guide](https://documentation.onfido.com/sdk/sdk-csp-guide/#content-security-policy) for the latest required domains.

    <Warning>
      CSP requirements change between Onfido SDK versions. If you set a specific `sdkVersion` in your recipe, check the Onfido CSP guide for that version.
    </Warning>
  </Tab>

  <Tab title="Incode">
    ```plaintext title="Additional CSP rules for Incode" theme={null}
    script-src  'unsafe-inline' 'unsafe-eval'
                https://d3vv997wtl2myz.cloudfront.net
                https://*.incodesmile.com
                https://*.incode.com
                https://*.opentok.com;
    style-src   'unsafe-inline' https://fonts.googleapis.com;
    connect-src https://*.incodesmile.com
                https://*.i18nexus.com
                https://d3vv997wtl2myz.cloudfront.net
                https://featureassets.org
                https://prodregistryv2.org
                https://*.opentok.com
                https://*.ipify.org;
    font-src    https://fonts.gstatic.com;
    frame-src   https://incode.com
                https://*.incode.com
                https://*.incodesmile.com;
    img-src     blob:;
    worker-src  blob:;
    ```

    <Note>
      Incode requires `'unsafe-inline'` and `'unsafe-eval'` in `script-src`. These are necessary for the Incode SDK to function but relax the default script execution policy. Ensure you understand the security implications for your application.
    </Note>
  </Tab>

  <Tab title="Truuth">
    ```plaintext title="Additional CSP rules for Truuth" theme={null}
    script-src  'unsafe-inline' 'unsafe-eval'
                https://cdn.truuth.id;
    connect-src https://static.au.truuth.id
                https://portal.api.au.truuth.id;
    img-src     https://static.au.truuth.id blob:;
    ```

    <Note>
      The domains above use Truuth's Australian region (`au`). If you are using a different Truuth region, replace `au` with your region identifier, or contact the support team for the correct domains.
    </Note>
  </Tab>

  <Tab title="Sumsub">
    Refer to the [Sumsub CSP documentation](https://docs.sumsub.com/docs/csp) for the latest required domains.

    At a minimum, Sumsub typically requires:

    ```plaintext title="Additional CSP rules for Sumsub" theme={null}
    script-src  https://static.sumsub.com;
    connect-src https://*.sumsub.com;
    frame-src   https://*.sumsub.com;
    img-src     https://*.sumsub.com blob:;
    style-src   https://static.sumsub.com;
    ```

    <Warning>
      Verify these domains against Sumsub's official documentation, as they may change between SDK versions.
    </Warning>
  </Tab>

  <Tab title="Daon">
    Contact the support team for Daon-specific CSP domains, as they vary depending on the Daon deployment configured for your account.
  </Tab>
</Tabs>

<Info>
  If you encounter CSP errors at runtime, check the browser console for the blocked URL and directive. Add the domain to the appropriate directive. See [CSP Error Troubleshooting](/docs/sdk-reference/error-scenarios#csp-content-security-policy-errors) for details.
</Info>

***

## Onfido

### SDK Version Selection

The `sdkVersion` property on the Onfido provider object controls which Onfido SDK version is loaded at runtime. By default, OneSdk uses Onfido v12 for backward compatibility. You can switch to a newer version by setting `sdkVersion` in the provider configuration for any module that uses Onfido (IDV, OCR, or Biometrics).

```javascript theme={null}
const sdk = await OneSdk({
  session: sessionObjectFromBackend,
  mode: 'production',
  recipe: {
    idv: {
      provider: {
        name: 'onfido',
        sdkVersion: '14'
      }
    },
    ocr: {
      provider: {
        name: 'onfido',
        sdkVersion: '14'
      }
    },
    biometrics: {
      provider: {
        name: 'onfido',
        sdkVersion: '14'
      }
    }
  }
});
```

<Note>
  Refer to the [Onfido SDK changelog](https://documentation.onfido.com/sdk/changelog/) for the latest available version.
</Note>

***

### Custom UI Styling (`customUI`)

Onfido provides extensive styling capabilities to customize the verification UI to match your application's design. Apply custom styling by setting the `customUI` property on the Onfido provider object for any module (IDV, OCR, or Biometrics).

#### All Available Properties

```typescript theme={null}
type OnfidoCustomUIProps = {
  // Borders & Shapes
  borderRadiusButton?: string;
  borderStyleSurfaceModal?: string;

  // Typography
  fontWeightBody?: number;
  fontSizeBody?: string;
  fontSizeSubtitle?: string;
  fontSizeTitle?: string;

  // Background Colors
  colorBackgroundSurfaceModal?: string;
  colorBackgroundIcon?: string;
  colorBackgroundDocTypeButton?: string;
  colorBackgroundDocTypeButtonHover?: string;
  colorBackgroundDocTypeButtonActive?: string;
  colorBackgroundSelector?: string;
  colorBackgroundInfoPill?: string;
  colorBackgroundInput?: string;

  // Button Colors - Primary
  colorBackgroundButtonPrimary?: string;
  colorBackgroundButtonPrimaryHover?: string;
  colorBackgroundButtonPrimaryActive?: string;
  colorContentButtonPrimaryText?: string;

  // Button Colors - Secondary
  colorBackgroundButtonSecondary?: string;
  colorBackgroundButtonSecondaryHover?: string;
  colorBackgroundButtonSecondaryActive?: string;
  colorContentButtonSecondaryText?: string;

  // Button Colors - Tertiary
  colorContentButtonTertiaryText?: string;

  // Content / Text Colors
  colorContentBody?: string;
  colorContentTitle?: string;
  colorContentSubtitle?: string;
  colorContentDocTypeButton?: string;
  colorContentInfoPill?: string;
  colorContentInput?: string;

  // Link Colors
  colorBorderLinkUnderline?: string;
  colorBackgroundLinkActive?: string;
  colorBackgroundLinkHover?: string;
  colorContentLinkTextHover?: string;

  // Border Colors
  colorBorderDocTypeButton?: string;
  colorBorderInput?: string;
  colorInputOutline?: string;

  // Icons
  colorIcon?: string;
}
```

#### Full Property Reference

| Property                               | Type     | Category            | Description                                                      |
| -------------------------------------- | -------- | ------------------- | ---------------------------------------------------------------- |
| `borderRadiusButton`                   | `string` | Borders             | Border radius for buttons (e.g., `'8px'`)                        |
| `borderStyleSurfaceModal`              | `string` | Borders             | Border style for the modal surface (e.g., `'1px solid #E4E7EC'`) |
| `fontWeightBody`                       | `number` | Typography          | Font weight for body text (e.g., `400`)                          |
| `fontSizeBody`                         | `string` | Typography          | Font size for body text (e.g., `'16px'`)                         |
| `fontSizeSubtitle`                     | `string` | Typography          | Font size for subtitles (e.g., `'18px'`)                         |
| `fontSizeTitle`                        | `string` | Typography          | Font size for titles (e.g., `'24px'`)                            |
| `colorBackgroundSurfaceModal`          | `string` | Background          | Background color of the modal surface                            |
| `colorBackgroundIcon`                  | `string` | Background          | Background color of icons                                        |
| `colorBackgroundDocTypeButton`         | `string` | Background          | Background color of document type buttons                        |
| `colorBackgroundDocTypeButtonHover`    | `string` | Background          | Background color of document type buttons on hover               |
| `colorBackgroundDocTypeButtonActive`   | `string` | Background          | Background color of document type buttons when active            |
| `colorBackgroundSelector`              | `string` | Background          | Background color of selector elements                            |
| `colorBackgroundInfoPill`              | `string` | Background          | Background color of info pill elements                           |
| `colorBackgroundInput`                 | `string` | Background          | Background color of input fields                                 |
| `colorBackgroundButtonPrimary`         | `string` | Buttons (Primary)   | Background color of primary buttons                              |
| `colorBackgroundButtonPrimaryHover`    | `string` | Buttons (Primary)   | Background color of primary buttons on hover                     |
| `colorBackgroundButtonPrimaryActive`   | `string` | Buttons (Primary)   | Background color of primary buttons when active                  |
| `colorContentButtonPrimaryText`        | `string` | Buttons (Primary)   | Text color of primary buttons                                    |
| `colorBackgroundButtonSecondary`       | `string` | Buttons (Secondary) | Background color of secondary buttons                            |
| `colorBackgroundButtonSecondaryHover`  | `string` | Buttons (Secondary) | Background color of secondary buttons on hover                   |
| `colorBackgroundButtonSecondaryActive` | `string` | Buttons (Secondary) | Background color of secondary buttons when active                |
| `colorContentButtonSecondaryText`      | `string` | Buttons (Secondary) | Text color of secondary buttons                                  |
| `colorContentButtonTertiaryText`       | `string` | Buttons (Tertiary)  | Text color of tertiary buttons                                   |
| `colorContentBody`                     | `string` | Content             | Text color for body content                                      |
| `colorContentTitle`                    | `string` | Content             | Text color for titles                                            |
| `colorContentSubtitle`                 | `string` | Content             | Text color for subtitles                                         |
| `colorContentDocTypeButton`            | `string` | Content             | Text color for document type buttons                             |
| `colorContentInfoPill`                 | `string` | Content             | Text color for info pill elements                                |
| `colorContentInput`                    | `string` | Content             | Text color for input fields                                      |
| `colorBorderLinkUnderline`             | `string` | Links               | Border color for link underlines                                 |
| `colorBackgroundLinkActive`            | `string` | Links               | Background color of active links                                 |
| `colorBackgroundLinkHover`             | `string` | Links               | Background color of hovered links                                |
| `colorContentLinkTextHover`            | `string` | Links               | Text color of hovered links                                      |
| `colorBorderDocTypeButton`             | `string` | Borders             | Border color of document type buttons                            |
| `colorBorderInput`                     | `string` | Borders             | Border color of input fields                                     |
| `colorInputOutline`                    | `string` | Borders             | Outline color of focused input fields                            |
| `colorIcon`                            | `string` | Icons               | Color of icons                                                   |

#### Code Example

```javascript theme={null}
const sdk = await OneSdk({
  session: sessionObjectFromBackend,
  mode: 'production',
  recipe: {
    ocr: {
      provider: {
        name: 'onfido',
        sdkVersion: '14',
        theme: 'dark',
        customUI: {
          // Typography
          fontWeightBody: 400,
          fontSizeBody: '16px',
          fontSizeSubtitle: '18px',
          fontSizeTitle: '24px',

          // Background
          colorBackgroundSurfaceModal: '#1A1A2E',
          colorBackgroundButtonPrimary: '#E94560',
          colorBackgroundButtonPrimaryHover: '#D63B56',
          colorBackgroundButtonPrimaryActive: '#C3314C',

          // Text
          colorContentBody: '#EAEAEA',
          colorContentTitle: '#FFFFFF',
          colorContentSubtitle: '#CCCCCC',
          colorContentButtonPrimaryText: '#FFFFFF',

          // Borders
          borderRadiusButton: '8px',
          colorBorderInput: '#333366',
          colorInputOutline: '#E94560',
        }
      }
    },
    biometrics: {
      provider: {
        name: 'onfido',
        sdkVersion: '14',
        theme: 'dark',
        customUI: {
          colorBackgroundButtonPrimary: '#E94560',
          colorContentButtonPrimaryText: '#FFFFFF',
          borderRadiusButton: '8px',
        }
      }
    }
  }
});
```

#### Theme Option

Onfido v14 introduces a `theme` option that can be set on the provider object. The available values are `'light'` (default) and `'dark'`.

```javascript theme={null}
provider: {
  name: 'onfido',
  sdkVersion: '14',
  theme: 'dark'
}
```

The `theme` option provides a base light or dark appearance. You can further customize individual elements using `customUI` properties on top of the chosen theme.

<Info>
  Refer to [Onfido's customUI styling documentation](https://documentation.onfido.com/sdk/web/#styling-customization) for the full list of supported styling keys and visual examples.
</Info>

***

### Document and Country Configuration

You can configure which document types and countries are accepted during document capture by providing a `documents` array in the recipe configuration. This applies to both the IDV and OCR modules when using Onfido.

By default, if no `documents` configuration is provided, the Onfido selection screen is shown with all supported document types and an empty country selection.

Depending on the configuration:

* The country selection screen will not be shown if only one country is specified or if only passports are allowed
* The document selection screen will not be shown if only one document type is specified

<Tabs>
  <Tab title="Code Example">
    ```javascript theme={null}
    const sdk = await OneSdk({
      session: sessionObjectFromBackend,
      mode: 'production',
      recipe: {
        idv: {
          documents: [
            {
              type: 'PASSPORT',
              countries: ['NZL'],
            },
            {
              type: 'DRIVERS_LICENCE',
              countries: ['NZL'],
            },
          ],
          provider: {
            name: 'onfido'
          }
        }
      }
    });

    const idv = sdk.flow('idv');
    idv.mount('#idv-container');
    ```
  </Tab>

  <Tab title="Type Definition">
    ```typescript theme={null}
    type DocumentConfig = {
      documents?: Array<{
        type: DocumentType;
        countries?: Array<string>;  // ISO 3166-1 alpha-3 country codes
      }>;
      provider: {
        name: 'onfido';
      }
    }

    enum DocumentType {
      PASSPORT = 'PASSPORT',
      NATIONAL_HEALTH_ID = 'NATIONAL_HEALTH_ID',
      NATIONAL_ID = 'NATIONAL_ID',
      DRIVERS_LICENCE = 'DRIVERS_LICENCE'
    }
    ```
  </Tab>
</Tabs>

<Warning>
  If you specify different countries for different document types (for example, `'NZL'` for passports and `'SGP'` for driver's licences), Onfido will fall back to displaying the full selection screen with all supported documents. Ensure all document types share the same country list to control the selection screens as expected.
</Warning>

***

### Exit Button and User Exit Handling

The `showExitButton` property (defaults to `false`) displays an exit button in the Onfido verification UI.

When the user clicks the exit button, a `vendor_event` event is emitted with the event name `OCR:ONFIDO:ON_USER_EXIT`.

```javascript theme={null}
const idv = sdk.flow('idv', {
  provider: {
    name: 'onfido',
    showExitButton: true
  }
});

// Listen for exit events
idv.on('vendor_event', (obj) => {
  if (obj.eventName === 'OCR:ONFIDO:ON_USER_EXIT') {
    console.log('User clicked exit button');
    // Handle exit (e.g., save progress, show confirmation)
  }
});

idv.mount('#idv-container');
```

***

### Error Codes

OneSdk surfaces Onfido-specific errors through the `onError` callback. The following table lists Onfido error codes, their meaning, and recommended recovery actions.

| Error Code                | Description                                                      | Recommended Recovery                                                                                                        |
| ------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `invalid_token`           | The Onfido IDV token is invalid.                                 | Re-generate the IDV token by remounting the component.                                                                      |
| `expired_token`           | The Onfido IDV token has expired.                                | Re-generate the IDV token by remounting the component.                                                                      |
| `expired_trial`           | The Onfido trial period has expired.                             | This is an unexpected error. Contact support if you encounter this.                                                         |
| `geoblocked_request`      | The request is not allowed from this geographic location.        | The end user may be in a restricted region. Disable any active VPN and retry, or contact support for details.               |
| `permissions_unavailable` | Unable to retrieve or access required user permissions.          | This may occur when the SDK is loaded in a WebView or custom browser. Try using a standard browser.                         |
| `unsupported`             | A module is not supported in the current environment.            | Check the documentation for supported environments and features, or contact support.                                        |
| `unsupported_feature`     | The requested feature is no longer supported.                    | Check the documentation for current supported features, or contact support.                                                 |
| `invalid_sdk_parameter`   | The SDK was initialized with invalid parameters.                 | Review the initialization parameters for correctness.                                                                       |
| `unsupported_sdk_version` | The workflow is not supported by the current SDK version.        | Update the `sdkVersion` parameter to a supported version.                                                                   |
| `no_camera`               | No camera is available and no other capture method is available. | The user has not granted camera access or their device does not have a camera. Prompt the user to grant camera permissions. |
| `user_consent_denied`     | The user declined consent.                                       | The user must provide consent to proceed. Display a message explaining why consent is required and allow them to retry.     |

***

## Incode

### Style Customization

OneSdk uses Incode's low-code approach for rendering the verification UI. To customize the appearance of the Incode integration, define custom CSS and work with the support team to apply it through the Incode portal.

<Info>
  Refer to [Incode's theming documentation](https://developer.incode.com/docs/styling) for details on customizing the appearance.
</Info>

### SDK Version

The Incode SDK version can be set via the `sdkVersion` property on the provider object.

```javascript theme={null}
provider: {
  name: 'incode',
  sdkVersion: '1.0.0'
}
```

<Note>
  Check with Incode or the support team for the latest available SDK version.
</Note>

***

## Daon

Daon provides extensive visual customization options that are configured through the support team. Below are the customizable areas available.

### Custom Colors

| Area                   | Description                                                    |
| ---------------------- | -------------------------------------------------------------- |
| **General**            | Overarching theme colors that set the primary look and feel.   |
| **Buttons**            | Colors for all button elements in the verification flow.       |
| **Text**               | Colors for all text displayed on the pages.                    |
| **Input**              | Colors for interactive input elements such as search boxes.    |
| **Country Selection**  | Color scheme for the country selection screen.                 |
| **Document Selection** | Color scheme for the document selection screen.                |
| **Document Capture**   | Color scheme for the document capture screen.                  |
| **Face Capture**       | Color scheme for the face capture screen.                      |
| **Header**             | Color scheme for page headers.                                 |
| **Stepper**            | Color scheme for the left-side step list displayed on desktop. |
| **Progress Bar**       | Color of the progress bar.                                     |
| **Other**              | Color of icons on the intro screen and preview borders.        |

### Icons

| Icon                          | Description                                               |
| ----------------------------- | --------------------------------------------------------- |
| **Logo**                      | The main logo displayed at the top of the app page.       |
| **Mobile Switch Icon**        | The icon shown on the "Switch to your phone" step.        |
| **Consent Icon**              | The icon shown on the "Consent" step.                     |
| **Face Capture Icon**         | The icon shown on the "Selfie" step.                      |
| **Document Capture Icon**     | The icon shown on the document capture screen.            |
| **Additional Documents Icon** | The icon shown on the additional document capture screen. |
| **Custom Form Icon**          | The icon shown on the custom form screen.                 |

### Fonts

| Font Style       | Description                                           |
| ---------------- | ----------------------------------------------------- |
| **Regular Font** | Used for general body text displayed to the end user. |
| **Medium Font**  | Used for medium-weight text such as sub-titles.       |
| **Bold Font**    | Used for bold text such as headings.                  |

### Media

Daon themes support uploading custom images for capture instruction and processing screens. Supported file types: `.jpg`, `.png`, `.jpeg`, `.svg`, `.gif`, `.mp4`, `.webm`. Maximum file size is 5MB per asset.

| Media Asset                             | Description                                                             |
| --------------------------------------- | ----------------------------------------------------------------------- |
| **Document Capture Instructions Front** | Image shown on the front document capture instructions screen.          |
| **Document Capture Instructions Back**  | Image shown on the back document capture instructions screen.           |
| **Face Capture Instructions**           | Image shown on the face capture instructions screen.                    |
| **Manual Capture Instructions Front**   | Image shown on the front manual capture instructions screen.            |
| **Manual Capture Instructions Back**    | Image shown on the back manual capture instructions screen.             |
| **Switch To Mobile Waiting**            | Image shown on the desktop while the user completes the flow on mobile. |
| **Processing Screen Image Front**       | Image shown during the front-facing processing capture screen.          |
| **Processing Screen Image Back**        | Image shown during the back-facing processing capture screen.           |

<Note>
  To apply Daon visual customizations, contact the support team with your desired assets, colors, fonts, and icons.
</Note>

***

## Sumsub

Sumsub provides customization options through its SDK configuration, including theme selection (`'light'` or `'dark'`), language settings, and iframe behavior options. These basic options are documented on the [IDV Module](/docs/sdk-reference/idv-module#sumsub-provider), [OCR Module](/docs/sdk-reference/ocr-module#sumsub-provider), and [Biometrics Module](/docs/sdk-reference/biometrics-module#sumsub-provider) pages.

For advanced visual customization (colors, fonts, branding), refer to the [Sumsub Web SDK customization documentation](https://docs.sumsub.com/docs/web-sdk-customization).

***

## Truuth

Truuth provides customization options through its provider configuration. For details on available customization options such as theming and branding, refer to the [Truuth documentation](https://truuth.id/docs) or contact the support team.

***

## Related

* [IDV Module](/docs/sdk-reference/idv-module)
* [OCR Module](/docs/sdk-reference/ocr-module)
* [Biometrics Module](/docs/sdk-reference/biometrics-module)
* [SDK Initialization](/docs/sdk-reference/sdk-initialization)


# Review & manage Supporting Documents
Source: https://docs.frankieone.com/docs/supporting-documents-review-portal



### Video Guide

<iframe title="Supporting Documents Review - Video Guide" />

## 1. Overview

The **Documents** tab in the FrankieOne Portal allows you to manage non-IDENTITY documents as part of your customer due diligence process. This feature is designed to handle evidence that falls outside of standard automated eKYC checks, such as utility bills, bank statements, or other supporting evidence.

Using this tab, you can:

* **Upload** new documents to an entity's profile.
* **Review** supporting documents and manually **Approve** or **Reject** them.
* **View** and **Download** all document classes, including Identity, Reports, and Supporting documents.
* **Delete** documents (with the correct permissions).
* **Track** all review actions and comments in a dedicated audit trail.

***

## 2. Accessing and Viewing Documents

You can find the document management feature within the new **"Documents"** tab on the entity profile view.

### Document List

When you open the tab, you will see a table of all documents associated with the entity.

* **Default View:** The list defaults to showing documents with the class `SUPPORTING`.
* **Document Class Switcher:** You can use the filter controls to switch between document classes:
  * **Supporting:** Documents uploaded for manual review (e.g., UTILITY\_BILL, BANK\_STATEMENT).
  * **Identity:** Documents used for eKYC/IDV checks (e.g., PASSPORT, DRIVERS\_LICENCE).
  * **Reports:** System-generated reports.

The document table provides the following information:

* **Document Type:** The specific type, such as `UTILITY_BILL`.
* **Status:**
  * For `SUPPORTING` documents, this shows the manual review status: **Approved**, **Rejected**, or **Needs Attention**.
  * For `IDENTITY` and `REPORT` documents, this will show **"N/A"** as they are not manually reviewed via this process.
* **Added On:** The timestamp when the document was created.
* **Added By:** The user or source that added the document.
* **Actions:** An ellipsis (...) menu with actions you can take, based on your permissions (View, Download, Delete, Review).

***

## 3. How to Review a Supporting Document

The primary function of this feature is to allow operators to manually review and verify `SUPPORTING` class documents.

1. Navigate to the **Documents** tab and ensure you are viewing `SUPPORTING` documents.
2. Find the document with the status **"Needs Attention"** that you wish to review.
3. Click the **Actions** (...) menu for that document and select **"Review"**.
4. A **"Review Document"** modal will appear.
5. In the modal, select either **"Approve"** or **"Reject"** using the radio buttons.
6. You can (and should) add an **optional comment** to provide context for your decision. This comment is saved to the audit log.
7. Click **Submit** to save the review. The document's status will update in the list.

This manual review status (`APPROVED` or `REJECTED`) is then used by the "Support Documents Step" in your KYC workflows to automatically determine if an entity passes this requirement.

***

## 4. How to Upload a Document

You can also upload new supporting documents directly through the portal.

1. From the main **Documents** tab, click the **"Upload Document"** button.
2. An **"Upload Document"** modal will appear.
3. Use the file selector to choose the document from your computer.
4. Select the correct **`document.type`** (e.g., UTILITY\_BILL) from the dropdown menu.
5. You can add an **optional comment** to be saved with the upload's audit event.
6. Click **Upload**.

Once uploaded, the new `SUPPORTING` document will appear in the list with the default status **"NEEDS\_ATTENTION"**, ready for review.

***

## 5. Other Document Actions

### View Details and Comment History

From the **Actions** menu, selecting **"View"** opens the Document Detail View. This interface has two panels:

* **Left Panel:** A list of all attachments for the selected document.
* **Right Panel:** A preview of the selected attachment, with controls for **zooming**, **rotating**, and **downloading**.

This view also contains a **"Comment History"** section, which displays all comments associated with the document from its audit trail in chronological order.

### Download a Document

You can download a document attachment in two ways:

1. From the **Actions** (...) menu in the document list.
2. From the previewer controls in the Document Detail View.

Downloading a document triggers a `PORTAL_ACTION` audit event.

### Delete a Document

1. From the **Actions** (...) menu, select **"Delete"**.
2. A confirmation modal will appear to prevent accidental deletion.
3. Confirming the deletion will remove the document.

<Callout icon="bell">
  **Important:** Deleting a `SUPPORTING` document or its attachments will also invalidate its associated review. The `systemStatus` of the review process object (PRO) will be set to `MARKED_INVALID`.
</Callout>

***

## 6. Permissions

Access to document functions is controlled by your user role.

* **Read Access (All Users):** All authenticated Portal users can **view** and **download** all documents for an entity. This is a baseline permission and is not configurable.
* **Write Access (Managed Roles):** The **"Manage Documents"** permission toggle in the Portal's Role Management settings controls all write actions. A user with this permission can:
  * **Upload** new documents.
  * **Review** (Approve/Reject) `SUPPORTING` documents.
  * **Delete** documents.

If you do not see the options to Upload, Review, or Delete, you do not have the "Manage Documents" permission. Please contact your system administrator.


# UAT Test Data
Source: https://docs.frankieone.com/docs/uat-test-data

The UAT sandbox environment provides a controlled testing ground with predefined test data to help you validate your integration. While it closely mirrors the production environment, there are some key differences you should be aware of.

## Test Data

The latest test data spreadsheets can be found here:

[KYC Test Data Records <Icon icon="arrow-up-right-from-square" />](https://docs.google.com/spreadsheets/d/1QDrjffj9VyL_ZthHNIMHJvrwAgQphKS_/edit?usp=sharing\&ouid=114443097573560405171\&rtpof=true\&sd=true)

[DVS Test Data <Icon icon="arrow-up-right-from-square" />](https://docs.google.com/spreadsheets/d/1Q1-md4KWLwfNvl3nZYWzuYQcbjuz91dt/edit?usp=drive_link\&ouid=100040548032051883372\&rtpof=true\&sd=true) Note: Contracted customers need to request view access to this file.

[KYB Test Data Records (Australia) <Icon icon="arrow-up-right-from-square" />](https://docs.google.com/spreadsheets/d/1CFXluVn9ZDetelrrEsvpbWIn0y5Njho3il1SRtsbzhM/edit?usp=sharing)

<Info>
  **Data Disclaimer**

  While effort has been taken to provide realistic data sets, please don't infer the structure of data based on this (e.g. don't design your UI validation based on information available in the spreadsheet).

  No individual information contained within this spreadsheet and any resemblance to real persons, living or dead, is purely coincidental.
</Info>

## Key Testing Guidelines

<AccordionGroup>
  <Accordion title="Name Matching Rules">
    * Family name matching is the primary identifier in sandbox mode
    * Matching is case-insensitive
    * Example: "Smith", "SMITH", and "smith" are treated as equivalent
  </Accordion>

  <Accordion title="Automatic Pass Feature">
    To force a successful verification for any test subject:

    ```plaintext theme={null}
    Set middle_name = "passall"
    ```
  </Accordion>

  <Accordion title="Special Result Types">
    The sandbox supports different verification outcomes based on test data markers:

    <CardGroup>
      <Card title="Basic Checks" icon="check">
        * CLEAR: Clean record
        * PEP: Politically Exposed Person
        * SANCTION: Sanctions list match
        * FRAUD: Fraud indicators present
      </Card>

      <Card title="Advanced Checks" icon="code-branch">
        Records marked as **SKIP** will fetch detailed results from an external test service, providing comprehensive response data.
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

***

## v2 API Test Data Examples

<Warning>
  **Never use real customer data in testing environments.** Always use the testbed data below. Do not use fictional names like "John Smith" or "Jane Doe" — use the actual testbed names for consistent, reliable results.
</Warning>

The following examples show v2 API request payloads for common test scenarios. These use FrankieOne's official testbed records (TESTONE, TESTTWO, etc.) which produce predictable results in UAT.

<Note>
  **v2 format reminders:**

  * Dates use objects: `{"year": "YYYY", "month": "MM", "day": "DD"}`
  * Address fields: `locality` (not suburb), `subdivision` (not state), `postalCode` (not postcode)
  * Documents nested by category: `documents.IDENTITY[...]`
  * Document ID field: `primaryIdentifier` (not idNumber)
</Note>

### Test Scenario Summary

| Test Name                 | Expected Result      | Document Type               | Country |
| ------------------------- | -------------------- | --------------------------- | ------- |
| JAMES TESTONE             | CLEAR (PASS)         | Driver's License + Medicare | AUS     |
| JUDY TESTTWO              | CLEAR (PASS)         | Driver's License            | AUS     |
| PETER TESTTHREE           | CLEAR (PASS)         | Driver's License            | AUS     |
| MARY TESTFOUR             | CLEAR (PASS)         | Driver's License            | AUS     |
| GEOFF TESTSEVEN           | CLEAR (PASS)         | Medicare                    | AUS     |
| JENNY TESTEIGHT           | FAIL (KYC Not Found) | Driver's License            | AUS     |
| JAMES G TESTELEVEN        | PEP match            | Passport                    | AUS     |
| BRUCE TESTNINETEEN        | SANCTION match       | —                           | AUS     |
| STACY K TESTTWENTY        | PEP + SANCTION       | —                           | AUS     |
| Doug J Jeffries           | CLEAR (PASS)         | SSN (NATIONAL\_ID)          | USA     |
| RONALD Testonehundredfour | CLEAR (PASS)         | Aadhaar (NATIONAL\_ID)      | IND     |
| THOMAS Testninetythree    | CLEAR (PASS)         | National ID                 | CHN     |

### Australian Scenarios

<AccordionGroup>
  <Accordion title="PASS - JAMES TESTONE (Driver's License)">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "JAMES",
          "middleName": "A",
          "familyName": "TESTONE"
        },
        "dateOfBirth": {
          "year": "1950",
          "month": "01",
          "day": "01"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "status": "CURRENT",
            "unitNumber": "U 1",
            "streetNumber": "35",
            "streetName": "CONN",
            "streetType": "STREET",
            "locality": "FERNTREE GULLY",
            "subdivision": "VIC",
            "postalCode": "3156",
            "country": "AUS",
            "unstructuredLongForm": "U 1/35 CONN STREET, FERNTREE GULLY, VIC 3156"
          }
        ],
        "documents": {
          "IDENTITY": [
            {
              "type": "DRIVERS_LICENSE",
              "class": "IDENTITY",
              "primaryIdentifier": "283229690",
              "secondaryIdentifier": "P5403241",
              "country": "AUS",
              "subdivision": "VIC"
            }
          ]
        },
        "consents": [
          {
            "type": "GENERAL"
          },
          {
            "type": "DOCS"
          },
          {
            "type": "CREDITHEADER"
          },
          {
            "type": "UNDER18"
          }
        ]
      }
    }
    ```

    **Expected Result:** CLEAR (PASS)
  </Accordion>

  <Accordion title="FAIL (KYC Not Found) - JENNY TESTEIGHT (Driver's License)">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "JENNY",
          "familyName": "TESTEIGHT"
        },
        "dateOfBirth": {
          "year": "1957",
          "month": "01",
          "day": "01"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "streetNumber": "56",
            "streetName": "VICTORIA",
            "streetType": "STREET",
            "locality": "FINGAL",
            "subdivision": "TAS",
            "postalCode": "7214",
            "country": "AUS",
            "unstructuredLongForm": "56 VICTORIA STREET, FINGAL, TAS 7214"
          }
        ],
        "documents": {
          "IDENTITY": [
            {
              "type": "DRIVERS_LICENSE",
              "class": "IDENTITY",
              "primaryIdentifier": "T56543",
              "secondaryIdentifier": "T03989853",
              "country": "AUS",
              "subdivision": "TAS"
            }
          ]
        },
        "consents": [
          {
            "type": "GENERAL"
          },
          {
            "type": "DOCS"
          },
          {
            "type": "CREDITHEADER"
          },
          {
            "type": "UNDER18"
          }
        ]
      }
    }
    ```

    **Expected Result:** FAIL - KYC Not Found
  </Accordion>

  <Accordion title="PASS - GEOFF TESTSEVEN (Medicare Card)">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "GEOFF",
          "middleName": "E",
          "familyName": "TESTSEVEN"
        },
        "dateOfBirth": {
          "year": "1956",
          "month": "01",
          "day": "01"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "streetNumber": "31",
            "streetName": "POYNTON",
            "streetType": "STREET",
            "locality": "CEDUNA",
            "subdivision": "SA",
            "postalCode": "5690",
            "country": "AUS"
          }
        ],
        "documents": {
          "IDENTITY": [
            {
              "type": "NATIONAL_HEALTH_ID",
              "class": "IDENTITY",
              "primaryIdentifier": "2515129631",
              "subtype": "G",
              "country": "AUS",
              "subdivision": "SA",
              "expiryDate": {
                "year": "2030",
                "month": "01",
                "day": "01",
                "unstructured": "2030-01-01",
                "type": "GREGORIAN"
              },
              "supplementaryData": {
                "type": "NATIONAL_HEALTH_ID",
                "reference": "3",
                "nameOnCardLine1": "GEOFF E TESTSEVEN",
                "nameOnCardLine2": "null",
                "nameOnCardLine3": "null",
                "nameOnCardLine4": "null",
                "middleNameOnCard": "null"
              }
            }
          ]
        },
        "consents": [
          {
            "type": "GENERAL"
          },
          {
            "type": "DOCS"
          },
          {
            "type": "CREDITHEADER"
          },
          {
            "type": "UNDER18"
          }
        ]
      }
    }
    ```

    **Note:** Australian Medicare cards require:

    * `primaryIdentifier`: Medicare card number (10 digits)
    * `subtype`: Card color — `G` (Green), `B` (Blue), or `Y` (Yellow)
    * `supplementaryData.reference`: Individual reference number on card (1-9)
    * `supplementaryData.nameOnCardLine1`: Name as printed on the card
    * `expiryDate`: Must include `unstructured` (YYYY-MM-DD) and `type` ("GREGORIAN")

    **Expected Result:** CLEAR (PASS)
  </Accordion>

  <Accordion title="PASS - Australian Passport">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "Sarah",
          "familyName": "Johnson"
        },
        "dateOfBirth": {
          "year": "1985",
          "month": "03",
          "day": "20"
        },
        "nationality": "AUS",
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "locality": "Melbourne",
            "subdivision": "VIC",
            "postalCode": "3000",
            "country": "AUS"
          }
        ],
        "documents": {
          "IDENTITY": [
            {
              "type": "PASSPORT",
              "class": "IDENTITY",
              "primaryIdentifier": "N1234567",
              "country": "AUS",
              "expiryDate": {
                "normalized": "2030-01-14",
                "year": "2030",
                "month": "01",
                "day": "14",
                "type": "GREGORIAN"
              }
            }
          ]
        },
        "consents": [
          {
            "type": "GENERAL"
          },
          {
            "type": "DOCS"
          },
          {
            "type": "CREDITHEADER"
          },
          {
            "type": "UNDER18"
          }
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="Minor (Under 18)">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "Oliver",
          "middleName": "J",
          "familyName": "YOUNGTEN"
        },
        "dateOfBirth": {
          "year": "2015",
          "month": "06",
          "day": "15"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "streetNumber": "35",
            "streetName": "Conn",
            "streetType": "Street",
            "locality": "Ferntree Gully",
            "subdivision": "VIC",
            "postalCode": "3156",
            "country": "AUS"
          }
        ],
        "consents": [
          {
            "type": "GENERAL"
          },
          {
            "type": "DOCS"
          },
          {
            "type": "CREDITHEADER"
          },
          {
            "type": "UNDER18"
          }
        ]
      }
    }
    ```

    **Note:** Must include `UNDER18` consent type. May require guardian information — check with FrankieOne.
  </Accordion>
</AccordionGroup>

### AML Screening Scenarios

<AccordionGroup>
  <Accordion title="PEP Match - JAMES G TESTELEVEN">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "JAMES",
          "middleName": "G",
          "familyName": "TESTELEVEN"
        },
        "dateOfBirth": {
          "year": "1960",
          "month": "01",
          "day": "01"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "streetNumber": "23",
            "streetName": "ISA",
            "streetType": "STREET",
            "locality": "FYSHWICK",
            "subdivision": "ACT",
            "postalCode": "2609",
            "country": "AUS"
          }
        ],
        "documents": {
          "IDENTITY": [
            {
              "type": "PASSPORT",
              "class": "IDENTITY",
              "primaryIdentifier": "E55173628",
              "country": "AUS",
              "expiryDate": {
                "normalized": "2030-01-01",
                "year": "2030",
                "month": "01",
                "day": "01",
                "type": "GREGORIAN"
              }
            }
          ]
        },
        "consents": [
          {
            "type": "GENERAL"
          },
          {
            "type": "DOCS"
          },
          {
            "type": "CREDITHEADER"
          },
          {
            "type": "UNDER18"
          }
        ]
      }
    }
    ```

    **Expected Result:** PEP match
  </Accordion>

  <Accordion title="SANCTION Match - BRUCE TESTNINETEEN">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "BRUCE",
          "familyName": "TESTNINETEEN"
        },
        "dateOfBirth": {
          "year": "1968",
          "month": "01",
          "day": "01"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "country": "AUS"
          }
        ],
        "consents": [
          {
            "type": "GENERAL"
          },
          {
            "type": "DOCS"
          },
          {
            "type": "CREDITHEADER"
          },
          {
            "type": "UNDER18"
          }
        ]
      }
    }
    ```

    **Expected Result:** SANCTION match

    **Note:** This example does not include an identity document. Use a workflow that does not require ID verification, such as `AUS-Basic3V-TwoPlus`.
  </Accordion>

  <Accordion title="Combined PEP + SANCTION - STACY K TESTTWENTY">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "STACY",
          "middleName": "K",
          "familyName": "TESTTWENTY"
        },
        "dateOfBirth": {
          "year": "1969",
          "month": "01",
          "day": "01"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "country": "AUS"
          }
        ],
        "consents": [
          {
            "type": "GENERAL"
          },
          {
            "type": "DOCS"
          },
          {
            "type": "CREDITHEADER"
          },
          {
            "type": "UNDER18"
          }
        ]
      }
    }
    ```

    **Expected Result:** PEP + SANCTION (both flags)

    **Note:** This example does not include an identity document. Use a workflow that does not require ID verification, such as `AUS-Basic3V-TwoPlus`.
  </Accordion>
</AccordionGroup>

<Note>
  **Workflows without ID documents:** The SANCTION and combined PEP + SANCTION examples above do not include identity documents. When testing without ID documents, use a workflow that does not require ID verification, such as `AUS-Basic3V-TwoPlus`. If you use a workflow that expects an ID document (e.g., `AUS-Basic3V-TwoPlusID` or `AUS-Basic1V-IDOnly`), you will receive a `BAD_DATA_ID` error.
</Note>

### International Scenarios

<Note>
  **Workflow names for international scenarios:**

  * **USA:** Use `USA-Basic1V-OnePlus`
  * **Global (India, China, UK, etc.):** Use `GLB-Basic1V-OnePlus`
</Note>

<AccordionGroup>
  <Accordion title="USA - Social Security Number (SSN)">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "Doug",
          "middleName": "J",
          "familyName": "Jeffries"
        },
        "dateOfBirth": {
          "year": "1974",
          "month": "08",
          "day": "08"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "country": "USA"
          }
        ],
        "nationality": "USA",
        "documents": {
          "IDENTITY": [
            {
              "type": "NATIONAL_ID",
              "class": "IDENTITY",
              "primaryIdentifier": "123456789",
              "country": "USA"
            }
          ]
        },
        "consents": [
          {
            "type": "GENERAL"
          },
          {
            "type": "DOCS"
          },
          {
            "type": "CREDITHEADER"
          },
          {
            "type": "UNDER18"
          }
        ]
      }
    }
    ```

    **Note:**

    * Use `NATIONAL_ID` document type for SSN (not `TAX_ID`)
    * Format: 9 digits without hyphens (e.g., "123456789")
    * **Workflow:** `USA-Basic1V-OnePlus`

    **Expected Result:** CLEAR
  </Accordion>

  <Accordion title="India - Aadhaar">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "RONALD",
          "familyName": "Testonehundredfour"
        },
        "dateOfBirth": {
          "year": "1970",
          "month": "01",
          "day": "01"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "country": "IND"
          }
        ],
        "nationality": "IND",
        "documents": {
          "IDENTITY": [
            {
              "type": "NATIONAL_ID",
              "class": "IDENTITY",
              "primaryIdentifier": "304365000000",
              "country": "IND"
            }
          ]
        },
        "consents": [
          {
            "type": "GENERAL"
          },
          {
            "type": "DOCS"
          },
          {
            "type": "CREDITHEADER"
          },
          {
            "type": "UNDER18"
          }
        ]
      }
    }
    ```

    **Note:**

    * Use `NATIONAL_ID` document type
    * Format: 12 digits without dashes
    * **Workflow:** `GLB-Basic1V-OnePlus`

    **Expected Result:** CLEAR
  </Accordion>

  <Accordion title="China - National ID">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "THOMAS",
          "familyName": "Testninetythree"
        },
        "dateOfBirth": {
          "year": "1959",
          "month": "01",
          "day": "01"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "country": "CHN"
          }
        ],
        "nationality": "CHN",
        "documents": {
          "IDENTITY": [
            {
              "type": "NATIONAL_ID",
              "class": "IDENTITY",
              "primaryIdentifier": "ABC-123456789",
              "country": "CHN",
              "givenName": "THOMAS",
              "familyName": "TESTNINETYTHREE",
              "dateOfBirth": "1959-01-01",
              "supplementaryData": {
                "type": "NATIONAL_ID",
                "homeCountryFullName": "张伟明"
              }
            }
          ]
        },
        "consents": [
          {
            "type": "GENERAL"
          },
          {
            "type": "DOCS"
          },
          {
            "type": "CREDITHEADER"
          },
          {
            "type": "UNDER18"
          }
        ]
      }
    }
    ```

    **Note:**

    * Use `NATIONAL_ID` document type
    * `givenName` / `familyName` on the document must be **Pinyin in uppercase** as shown on the ID card
    * `supplementaryData.homeCountryFullName` contains the full name in **Chinese characters** (simplified or traditional, as on the ID)
    * `homeCountryFullName` enables the optional `NAME_VALIDATION` workflow step (transliteration check between Pinyin and Chinese characters)
    * `primaryIdentifier`: 18 digits in production (testbed uses placeholder)
    * **Workflow:** `GLB-Basic1V-OnePlus`

    **Expected Result:** CLEAR
  </Accordion>

  <Accordion title="UK - Passport (International Individual)">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "Emma",
          "familyName": "Williams"
        },
        "dateOfBirth": {
          "year": "1988",
          "month": "11",
          "day": "05"
        },
        "nationality": "GBR",
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "locality": "London",
            "postalCode": "SW1A 1AA",
            "country": "GBR"
          }
        ],
        "documents": {
          "IDENTITY": [
            {
              "type": "PASSPORT",
              "class": "IDENTITY",
              "country": "GBR",
              "primaryIdentifier": "123456789",
              "expiryDate": {
                "normalized": "2030-01-14",
                "year": "2030",
                "month": "01",
                "day": "14",
                "type": "GREGORIAN"
              }
            }
          ]
        },
        "consents": [
          {
            "type": "GENERAL"
          },
          {
            "type": "DOCS"
          },
          {
            "type": "CREDITHEADER"
          },
          {
            "type": "UNDER18"
          }
        ]
      }
    }
    ```

    **Note:**

    * Use correct ISO 3166-1 alpha-3 country codes (GBR, USA, CAN, etc.)
    * **Workflow:** `GLB-Basic1V-OnePlus`
  </Accordion>
</AccordionGroup>

***

## v2 Document Type Reference

<Note>
  **Important:** Use **`DRIVERS_LICENSE`** (American spelling with underscore), not `DRIVERS_LICENCE`.
</Note>

### Country-Specific Document Requirements

| Country       | Document Type        | Primary ID                  | Secondary ID                                                                                              | Notes                                          |
| ------------- | -------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| **Australia** | `DRIVERS_LICENSE`    | License number              | Card/document number                                                                                      | Both required                                  |
| **Australia** | `NATIONAL_HEALTH_ID` | Medicare number (10 digits) | `supplementaryData.reference` (1-9), `subtype` (G/B/Y), `nameOnCardLine1`                                 | All required                                   |
| **Australia** | `PASSPORT`           | Passport number             | —                                                                                                         | Include issue/expiry dates                     |
| **USA**       | `NATIONAL_ID`        | SSN (9 digits, no dashes)   | —                                                                                                         | Use for Social Security Number                 |
| **India**     | `NATIONAL_ID`        | Aadhaar (12 digits)         | —                                                                                                         | No dashes in testbed                           |
| **China**     | `NATIONAL_ID`        | 18-digit ID number          | `supplementaryData.homeCountryFullName` (Chinese characters), Pinyin `givenName`/`familyName` on document | `homeCountryFullName` enables NAME\_VALIDATION |

### Document Examples

**Australian Driver's License:**

```json theme={null}
{
  "type": "DRIVERS_LICENSE",
  "class": "IDENTITY",
  "primaryIdentifier": "283229690",
  "secondaryIdentifier": "P5403241",
  "country": "AUS",
  "subdivision": "VIC"
}
```

**Australian Medicare Card:**

```json theme={null}
{
  "type": "NATIONAL_HEALTH_ID",
  "class": "IDENTITY",
  "primaryIdentifier": "6603984391",
  "subtype": "G",
  "country": "AUS",
  "subdivision": "VIC",
  "expiryDate": {
    "year": "2030",
    "month": "01",
    "day": "01",
    "unstructured": "2030-01-01",
    "type": "GREGORIAN"
  },
  "supplementaryData": {
    "type": "NATIONAL_HEALTH_ID",
    "reference": "1",
    "nameOnCardLine1": "JAMES A TESTONE",
    "nameOnCardLine2": "null",
    "nameOnCardLine3": "null",
    "nameOnCardLine4": "null",
    "middleNameOnCard": "null"
  }
}
```

**USA Social Security Number:**

```json theme={null}
{
  "type": "NATIONAL_ID",
  "class": "IDENTITY",
  "primaryIdentifier": "123456789",
  "country": "USA"
}
```

### Valid Document Types

| Document Type        | Usage                                      |
| -------------------- | ------------------------------------------ |
| `DRIVERS_LICENSE`    | Driver's license (American spelling)       |
| `PASSPORT`           | Passport                                   |
| `NATIONAL_ID`        | National ID (SSN, Aadhaar, China ID, etc.) |
| `NATIONAL_HEALTH_ID` | Health card (Australian Medicare)          |
| `TAX_ID`             | Tax identification number                  |
| `VISA`               | Visa                                       |
| `IMMIGRATION`        | Immigration document                       |
| `BIRTH_CERT`         | Birth certificate                          |
| `CITIZENSHIP`        | Citizenship certificate                    |
| `MARRIAGE_CERT`      | Marriage certificate                       |
| `UTILITY_BILL`       | Utility bill                               |
| `BANK_STATEMENT`     | Bank statement                             |
| `CONCESSION`         | Concession card                            |
| `PENSION`            | Pension card                               |
| `MILITARY_ID`        | Military ID                                |
| `OTHER`              | Other document type                        |

***

## Simulating Credit Header Failures

<Callout icon="star">
  You can simulate credit bureau failures by using specific street names in your test payload.
</Callout>

To force a credit header failure, simply set the street name in the address to one of the following bureau names:

* `Equifax`
* `Experian`

The service will then return a failed credit header response for the specified bureau.

<Callout icon="star">
  For more advanced testing scenarios and error simulation, check out our guide on [API Testing Tips](https://docs.frankieone.com/v2/api/developers/postman-tips).
</Callout>


# Hosted OneSDK (Low-Code)
Source: https://docs.frankieone.com/docs/using-hosted-onesdk

An alternative low-code integration for customers that want to onboard as soon as possible with as litle as possible.

<Info>
  ### Subscription Required

  Hosted OneSDK is available through a monthly subscription. Contact your
  customer success manager to get started. Our team will handle the setup
  process for you.
</Info>

## Overview

<Frame>
  <img alt="Hosted OneSDK Overview" />
</Frame>

<Columns>
  <Card title="Automatic Updates" icon="rotate">
    Stay current with automatic security and compliance updates
  </Card>

  <Card title="Low-Code Solution" icon="code">
    Minimize engineering effort and accelerate deployment
  </Card>

  <Card title="Multi-Platform" icon="desktop">
    Single API for both web and mobile applications
  </Card>

  <Card title="Managed Service" icon="gear">
    FrankieOne handles hosting and maintenance
  </Card>
</Columns>

## Key Benefits

<AccordionGroup>
  <Accordion title="Technical Benefits">
    * Unified API integration for web and mobile
    * Managed hosting and maintenance
    * Automatic feature updates
    * Flexible deployment options (iFrame/WebView)
  </Accordion>

  <Accordion title="Business Benefits">
    * Faster time to market
    * Reduced development costs
    * Enhanced security compliance
    * Improved user onboarding experience
  </Accordion>
</AccordionGroup>

## Implementation Guide

<Steps>
  <Step title="Generate Onboarding URL">
    Use the [Hosted Onboarding API](/api-reference/provide-onboarding-url-for-hosted-onesdk) to create your URL.

    <Accordion title="Available Flow Types">
      | Flow ID                 | Purpose                                     |
      | :---------------------- | :------------------------------------------ |
      | `doc_upload`            | Document attachment for business entities   |
      | `idv`                   | Complete IDV flow with OCR and Biometrics   |
      | `idv_review`            | IDV flow with user review/edit capability   |
      | `individual_doc_upload` | Document attachment for individual entities |
      | `manual_kyc`            | eKYC-only flow                              |
      | `ocr_only`              | Document OCR without biometrics             |
    </Accordion>

    <Tabs>
      <Tab title="New Customer">
        ```json theme={null}
        {
          "applicationRef": "UNIQUE_APPLICATION_REF",
          "customerRef": "UNIQUE_REFERENCE",
          "consent": true,
          "flowId": "idv",
          "phoneNumber": "04xxxxxxxx",
          "phoneCode": "+61",
          "recipientName": "TEST",
          "sendSMS": true
        }
        ```
      </Tab>

      <Tab title="Existing Entity">
        ```json theme={null}
        {
          "consent": true,
          "phoneNumber": "04xxxxxxxx",
          "phoneCode": "+61",
          "flowId": "idv",
          "sendSMS": true,
          "entity": {
            "entityId": "",
            "addresses": [
              {
                "country": "AUS"
              }
            ],
            "extraData": [
              {
                "kvpKey": "application_reference",
                "kvpType": "id.external",
                "kvpValue": "<UNIQUE_APPLICATION_REF>"
              },
              {
                "kvpKey": "customer_reference",
                "kvpType": "id.external",
                "kvpValue": "<UNIQUE_REFERENCE>"
              }
            ],
            "name": {
              "displayName": "",
              "familyName": "Test",
              "givenName": "Test"
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    <Callout icon="star">
      ##### SMS Delivery

      Enable automatic SMS delivery by setting `sendSMS: true` and providing a
      `phoneNumber`. Contact Technical Support to customize SMS content and URL
      expiry.
    </Callout>
  </Step>

  <Step title="Configure Entity Profile (Optional)">
    Update the entity profile to specify verification requirements:

    ```json theme={null}
    {
      "entityId": "your_entity_id",
      "entityProfile": "your_recipe_name"
    }
    ```
  </Step>

  <Step title="Implement URL Handling">
    <Tabs>
      <Tab title="Android (Java)">
        ```java theme={null}
        webAppInterface = WebAppInterface(requireContext())
        binding.webView.apply {
            webViewClient = MyWebViewClient()
            webChromeClient = MyWebChromeClient()
            addJavascriptInterface(webAppInterface, "Android")
            loadUrl("https://verify.uat.frankie.one?t=dFLfq4pbfMfnWUZ4SR8W5i")
        }
        ```
      </Tab>

      <Tab title="React Native">
        ```javascript theme={null}
        import { useState } from "react";
        import { Button, View } from "react-native";
        import * as WebBrowser from "expo-web-browser";

        export default function App() {
          const [result, setResult] = useState(null);

          const handlePressButtonAsync = async () => {
            const result = await WebBrowser.openBrowserAsync(
              "https://verify.uat.frankie.one?t=dFLfq4pbfMfnWUZ4SR8W5i"
            );
            setResult(result);
          };

          return (
            <View style={styles.container}>
              <Button title="Start Verification" onPress={handlePressButtonAsync} />
            </View>
          );
        }
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Portal Integration

<Info>
  The Portal provides additional capabilities for managing onboarding URLs and
  document collection.
</Info>

### Sending Onboarding URLs

<Steps>
  <Step title="Access Entity Profile">
    Navigate to the entity profile page or create a new profile
  </Step>

  <Step title="Generate QR Code">
    <Frame>
      <img alt="QR Code Example" />
    </Frame>
  </Step>

  <Step title="Track Progress">
    Monitor profile updates as users complete onboarding
  </Step>
</Steps>

## Document Collection

<AccordionGroup>
  <Accordion title="API Configuration">
    **Production Endpoint:**

    ```
    POST https://api.frankie.one/idv/v2/idvalidate/onboarding-url
    ```

    **UAT Endpoint:**

    ```
    POST https://api.uat.frankie.one/idv/v2/idvalidate/onboarding-url
    ```

    **Headers:**

    ```
    X-Frankie-Customerid: YOUR_CUSTOMER_ID
    X-Frankie-CustomerChildID: YOUR_CUSTOMER_CHILD_ID
    api_key: YOUR_API_KEY
    ```
  </Accordion>

  <Accordion title="Document Request for Individual Entities">
    Individual Document Upload flow has 3 different document types:

    * Required documents `requestedDocuments`
    * Partial documents `partialDocuments`, which can consists of multiple groups with configurable title and minimum required document per groups
    * Optional documents `optionalDocuments`

    ```json theme={null}
    {
      "flowId": "individual_doc_upload",
      "senderName": "OneSDK-Testing-Sender-Name",
      "requestedDocuments": [
      {
            "documentType": "BIRTH_CERT"
          },
          {
            "documentType": "CITIZENSHIP"
          }
    ],
      "partialDocuments": [
          {
            "title": "Additional Documents",
            "minimumRequirement": 2,
            "documents": [
              {
                "documentType": "VISA"
              },
              {
                "documentType": "UTILITY_BILL"
              },
              {
                "documentType": "VEHICLE_REGISTRATION"
              }
            ]
          }
      ],
      "optionalDocuments": [
          {
            "documentType": "NAME_CHANGE"
          },
          {
            "documentType": "MARRIAGE_CERT"
          }
      ],
      "entity": {
        "entityId": "bc335f79-c167-36f6-3c70-d3c0a2d8c8b8"
      }
    }
    ```
  </Accordion>

  <Accordion title="Document Request for Business Entities">
    ```json theme={null}
    {
      "flowId": "doc_upload",
      "senderName": "OneSDK-Testing-Sender-Name",
      "requestedDocuments": [
        {
          "documentType": "BANK_STATEMENT"
        },
        {
          "documentType": "TRUST_DEED"
        }
      ],
      "entity": {
        "entityId": "bc335f79-c167-36f6-3c70-d3c0a2d8c8b8"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

<Callout icon="check">
  Documents will appear in the "Supporting Documents" tab of the business
  entity's Portal profile once uploaded.
</Callout>


# Version History
Source: https://docs.frankieone.com/docs/v1/onesdk/oneSDK/sdk-version-log



## v1.9.40

**07 Sep 2026**

* **Dynamic Review Screen Forms:**  Underlying updates to prepare support for Kenya, Ghana, South Africa, Singapore and Malaysia country fields in the review screen and future OneSDK versions.
* **Review screen:** Improved review screen by handling multi-doc and non-multi-doc flows correctly. This provides more focused information during the review process.

## v1.9.39

**31 Aug 2026**

* **Dynamic Review Screen Forms:**  Underlying updates to prepare support for UK, HK, Philippines, Taiwan and Thailand  country fields in the review screen and future OneSDK versions.
* **Daon Face Capture Instruction Screen:** Resolved an issue where an unnecessary face capture instruction screen was displayed during the biometric verification flow for certain customers, ensuring a smoother user experience.

## v1.9.38

**19 Aug 2026**

* **Biometrics Camera Access Warnings:**  OneSDK now emits detailed warning events when a user encounters camera permission issues during biometrics capture, providing better visibility into user journey blockers. These warnings are integrated into existing event channels for easier tracking without requiring new subscriptions.
* **Onfido Mobile Biometrics Loading State:**  Resolved an issue where a loading state obscured the biometrics widget during the transition from OCR to biometrics on mobile devices, ensuring a smoother user experience during identity verification.
* **Biometrics Module:**  Resolved an issue where the exit button was not displayed in the biometrics module, preventing users from easily exiting the flow. Users can now close the biometrics screen as intended.

## v1.9.37

**13 Aug 2026**

* **Manual KYC Field Rendering:**  Fixed a regression where customized fields in the manual KYC flow were not rendering correctly, ensuring all fields now display as expected.
* **User Interface in Review Screen:**  The maternal last name field on the OCR review screen is now optional for users in Mexico, Spain, and Colombia, allowing for greater flexibility in data entry.
* **Country of Residence Update:** Resolved an issue where the country of residence was incorrectly updated during identity verification, ensuring that the initial country selection is preserved and preventing applications from being approved under restricted or incorrect regions.
* **Dynamic Review Screen Forms:**  Underlying updates to prepare support for Mexico, Colombia, Canada, India and Spain country fields in the review screen and future OneSDK versions.

## v1.9.36

**10 Aug 2026**

* **Incode Consent API:**  We've enhanced the API to allow passing user consent directly to Incode, supporting both mandatory and optional consent types for biometric data use and system enhancement. This streamlines the consent process for custom consent screens.
* **Expiry Date in eKYC flow:** We’ve enhanced the manual eKYC ID entry flow by adding an optional “Date of Expiry” field when customers select Passport, aligning the experience with the existing Driver’s Licence flow.
* **Onfido OCR Module Event Ordering:** Resolved a race condition in some Onfido OCR flows that could end the session before OCR results were received. We now deliver OCR results before closing the session, improving speed and consistency of results availability.
* **OneSDK Credit-check messaging improvement:** We fixed an issue where the OneSDK could display a credit-check related notice even when no credit check was actually performed (e.g., ID-only verification flows). With this update, credit-check messaging is now shown only when a credit check is genuinely applicable based on the check results.
* **Form Validation:**  Improved form validation on the 'Are your details correct?' page. When submitting the form with missing or invalid information, specific error messages and visual cues will now appear next to the affected fields, making it easier to identify and correct errors.

## v1.9.35

**30 July 2026**

* **Form field Validation:**  The  review screen now correctly handles spaces in address fields, preventing validation errors for valid addresses and automatically trimming leading or trailing spaces upon submission. This ensures a smoother user experience when entering address details.
* **Maintenance & dependency housekeeping:** removes an unused internal dependency as part of routine maintenance. There is no change to SDK functionality, behaviour, or public API — no action is required to upgrade. This update also streamlines the SDK's  dependency footprint, which may reduce noise in downstream dependency scans.

## v1.9.34

**22 July 2026**

* **International Address Support:** The OCR review screen now supports selecting Italian provinces for residential addresses and document regions, improving international address data capture. This enhancement also lays the groundwork for adding subdivision support for other countries in the future OneSDK versions.

## v1.9.33

**07 July 2026**

* **RDaon Address Field Handling:** Address fields returned from OCR or stored in the backend will now automatically trim leading/trailing whitespace, preventing validation errors and ensuring clean data display and submission.
* **RTruuth User Experience:** When a user chooses to return later, the system now directly redirects them, skipping an unnecessary intermediate page for a smoother experience in Truuth integration.

## v1.9.32

**02 July 2026**

* **Review Screen Submissions:**  Disabled address and document fields on review and personal details screens are now preserved upon submission, preventing accidental data loss.
* **Hosted Review Screen:** Resolved an issue where submitting the hosted review screen incorrectly cleared name fields and where the IDV completion webhook fired prematurely. Name fields will now persist correctly, and the webhook will fire only after the review screen is submitted, ensuring reliable signal for review completion.
* **Language Control:**  Added capability to programmatically set the language for Onfido and Incode within OneSDK, providing insights into the level of control available for displayed languages.
* **Credit Bureau Header Notifications:**  OneSDK now displays a notification when a credit bureau header data source fails to find a match during a KYC check, ensuring compliance with regulatory requirements and informing users of the mismatch.

## v1.9.30

**04 June 2026**

* **Biometric Page Extraction:** Resolved an issue where users could get stuck on the page extraction screen after completing biometrics, ensuring a smoother transition to the next step.
* **Daon Error Handling:** Error codes and messages from the Daon Process Definition (PD) flow are now displayed in the portal, allowing for quicker diagnosis and resolution of issues.

## v1.9.29

**28 May 2026**

* **Improved User Guidance:**  We have updated the helper text for Australian driver's license card numbers during manual verification to accurately guide users on where to find the card number for each state, especially for Victorian licenses where it is now correctly stated to be on the back of the card.
* **Document Upload:** OneSDK can now handle multiple document upload of the same type, improving flexibility and efficiency when submitting required information.

## v1.9.28

**25 May 2026**

* **Daon Session Timeout Handling:** We’ve introduced a new screen for Daon biometric sessions that have timed out due to inactivity, providing a clear visual indication to users and allowing for better handling of these scenarios by developers.
* **OCR Review Screen Improvements:** The OCR review screen has been updated to improve clarity and consistency, including corrected spelling, adjusted field labels, and reordered document information for a more intuitive user experience.
* **Result Screen Customization:** OneSDK now allows developers to customize the result screen with their own images, either by providing a base64 encoded image or a URL to an image, enhancing the visual experience.
* **Address Field Improvements:** We’ve enhanced the review screen to correctly display full address details, including unit numbers and proper separation of suburb and town. Additionally, address pre-fill now supports state acronyms, and the name field accepts hyphens, preventing previous submission errors.

## v1.9.27

**18 May 2026**

* **Result Screen Descriptions:**  The result screen description field now supports rendering HTML elements, allowing for richer text formatting like bold and italics to improve clarity and user experience.
* **Document Identification UI:**  Enable configuration of field labels for document identification to clearly indicate the source of information (e.g., "From your driver's licence" or "From your passport") and to display the expiry date for passports, improving clarity and compliance.
* **Biometric Review Screen:**  OneSDk review screen now accepts and displays hyphenated names properly allowing users with such names from completing the submission process.
* **OneSDK Forms:**  Resolved an issue where overriding form field configurations with partial objects caused dropdowns to display "No records"; dropdown options will now correctly fall back to default values if not explicitly provided in the override.

## v1.9.26

**12 May 2026**

* **Multi-Document Review Screen:** The review screen now supports displaying information from multiple documents, such as a Driver's License and Passport, in a single view, providing a more comprehensive and dynamic review experience.

## v1.9.25

**6 May 2026**

* **Library Update::** We have addressed dependency issue with the lodash library in the OneSDK package.

## v1.9.24

**29 April 2026**

* **Daon IDV Processing:** The Daon identity verification process now emits a 'loading' event, providing clearer status updates for embedded customers during check processing.

## v1.9.23

**22 April 2026**

* **Daon Error and Events:** We have significantly improved how we communicate IDV results. By introducing more granular error codes and descriptive messages, we are providing clearer insights into why a verification attempt might have failed, allowing for faster resolution and a smoother customer experience.

## v1.9.22

**16 April 2026**

* **Onboarding Journey Logging:**  We've enhanced event logging for the onboarding journey, providing customers with detailed visibility into end-user progress and drop-off points within the onboarding flow.
* **eKYC Hosted OneSDK Flow:**  Resolved an issue where changes made on the eKYC hosted OneSDK flow review page were not being saved, ensuring all user inputs are now correctly reflected.

## v1.9.21

**9 April 2026**

* **Hosted OneSDK Review Screen:**  The Hosted OneSDK Review screen now includes an 'Other names known by' field, allowing for the capture of additional name details such as middle names.
* **Onfido Document Visibility:** Resolved an issue where documents submitted during VOI were not appearing in Frankie for certain profiles, ensuring all uploaded documents are now correctly displayed.

## v1.9.20

**1 April 2026**

* **Build Fix:**  Resolved an issue where the SDK prevented Next.js 15+ applications from building when Turbopack was enabled, ensuring smoother development for users leveraging modern build tools.

## v1.9.19

**18 March 2026**

* **Incode Translation Feature:** You can now customize translations for the Incode biometrics and identity verification provider, allowing you to tailor the user experience to your preferred language. This enhancement gives you greater control over how verification prompts and messages appear to your end users.
* **Review Screen Layout:**  The ‘Address search' option on the review screen can now be configured to change its position through this setting addressSearchPosition. This provides flexibility to adjust to the UI to customers' preference.
* **Incode SDK Integration:**  We've enhanced the Incode SDK integration to allow passing additional options to the renderCamera method, providing more flexibility for OCR and biometrics flows.
* **Flexible Identity Verification Flows:** You can now customize your Incode verification by choosing between standalone document scanning or document scanning with biometrics, providing more control over your identity verification process

## v1.9.18

**10 March 2026**

* **OneSDK Form Validation:**  Improved data validation and form-saving reliability within the OneSDK for a more seamless user experience.
* **Onfido Integration:**  A new `hideCountrySelection` option is now available for Onfido integrations, allowing the country selection step to be hidden during identity verification and optical character recognition processes when not required.
* **Individual Module Document:** Improved submission reliability by ensuring document modifications are processed correctly regardless of the underlying object instance.

## v1.9.17

**2 March 2026**

* **Session Error Handling:**  Fixed an issue where session error events for iframe integrations had an empty payload, ensuring consistent error data for developers.
* **Onfido Event Standardisation:** We have standardised event emissions across all Onfido modules, ensuring consistent and reliable event tracking for user interactions, including successful completions and user-initiated exits.

## v1.9.16

**16 February 2026**

* **Daon Event Handling:**  The system now correctly processes events from Daon for IDV, OCR, and Biometrics modules, ensuring proper workflow completion, error handling, and event emission for both scenarios with and without a redirect URL.
* **React Version Support:**  The OneSDK now officially supports React 19, and React has been updated to a peer dependency. This change improves compatibility and simplifies dependency management for applications integrating with the SDK.

## v1.9.15

**5 February 2026**

* **Daon Brand-specific styling:**  The OneSDK now supports passing brand information to Daon, enabling brand-specific styling for Customer’s different brands within Daon-hosted web pages for a more consistent user experience.
* **Daon Document Selection:**  The SDK can now bypass the document selection screen, allowing clients to pre-select a document type and streamline the capture process for users.
* **OneSDK Event Handling and Teardown:** Addressed issues with OneSDK event relay for Onfido, improved teardown functionality to ensure proper cleanup, and enhanced handling of expired tokens for a more robust integration.

## v1.9.14

**26 January 2026**

* **Incode Language Parameter:**  The Incode integration now supports a language parameter, allowing the Incode page to load in Spanish by default for an improved user experience.
* **Daon Selfie Flow:**  Resolved an issue where the selfie capture flow would crash and get stuck in an infinite loop due to incorrect iframe message handling, preventing users from completing the selfie verification process.
* **Document Processing:**  Resolved an issue where processing large base64 encoded documents could cause a system error, improving the stability of document handling.

## v1.9.13

**12 January 2026**

* **Status Polling Configuration:** Apply polling configuration for Daon standard flow.
* **Document Upload:** Improved OneSDK flow to correctly display document types during the KYC document upload flow, ensuring a consistent user experience regardless of how the flow is initiated.
* **Onfido Integration Improvements:**   Enhanced the Onfido IDV module within OneSDK to better respect recipe configurations for the useOneStep flow. It introduces the ability to configure an exit button and refines how document types and biometric options are passed to the Onfido SDK, addressing a client's need for flexible IDV processes.
* **Camera Management for Incode:**  We've added a manual teardown function to ensure the camera properly turns off when a user leaves a page, preventing the camera from remaining active unexpectedly.

## v1.9.12

**16 Dec 2025**

* **Critical Error Fix:**  Added telemetry to detect critical error that occasionally prevented OneSDK from loading individual details, ensuring a more stable and reliable experience.

## v1.9.11

**11 Dec 2025**

* **Process Initialization for Daon Provider:**  Enhanced the status polling mechanism for process initialization to improve reliability and provide a smoother user experience during critical operations.

## v1.9.10

**04 Dec 2025**

* **Data Mapping:** Resolved an issue where Daon data was not correctly mapping to the V2 Portal, ensuring all entity details and images are now displayed accurately and consistently.
* **IDV Service Stability:** A critical bug causing the IDV service to crash when attempting to find a selfie ID for entities without an ID document has been resolved, improving system stability and reliability.
* **Driver's License Expiry Date:**  The eKYC form now includes an 'Expiry Date' field for Driver's Licenses, allowing customers to capture this information during onboarding and improving data completeness for connectors.
* **IDV Review:**  Fixed an issue where the IDV Review was not displaying document fields correctly when identity documents contained a self-image without an OCR run date, ensuring all relevant document information is now visible.
* **Biometric Review Page:**  The biometric review page now correctly accepts apostrophes in name fields, resolving an issue that previously caused Know Your Customer (KYC) checks to fail for users with apostrophes in their legal names.
* **Performance Improvement for Truuth IDV vendor:** We've significantly improved the loading speed of identity verification screens, reducing load times to under 5 seconds for a smoother user experience.
* **Date of Birth Input:**  The Date of Birth field in OneSDK screens now accurately validates month entries, displaying error messages only after all DOB fields are completed.

## v1.9.9

**01 Dec 2025**

* **IDV Processing for Daon:** OneSDK now includes a new feature to poll the status of identity verification (IDV) requests when the initial process indicates 'CHECK\_PROCESSING'. This enhancement ensures that users are informed about the ongoing processing of their IDV requests, preventing indefinite waiting times.

## v1.9.8

**26 Nov 2025**

* **Biometric SMS Links:**  Fixed an issue where biometric SMS links failed to send to New Zealand phone numbers with non-standard digit lengths (9 or 11 digits), ensuring all valid NZ phone numbers can now successfully receive these links.
* **OnFido Configuration:**  OneSDK now supports configuring Onfido to enforce mobile-only ID verification, allowing users to seamlessly complete the process on their mobile devices via QR code or link.
* **User Interface Consistency for Incode:** Resolved an issue where font sizing on message displays was inconsistent, ensuring a uniform and polished appearance for users.

## v1.9.7

**12 November 2025**

* **Additional Document Collection:**  The OneSDK now supports a standardized flow for collecting additional identification documents (Passport and Driver's License) via Daon, ensuring consistent processing and improved user experience.

## v1.9.6

**30 October 2025**

* **IDVerse Image Assets**: Resolved an issue where SVG image assets were failing to load correctly, particularly impacting the selfie modal. This fix ensures all images display as intended.
* **IDVerse SDK Asset Loading**: Fixed an issue where the SDK was incorrectly attempting to load image assets from the local file system, which caused icons to be missing in dialogs for some users. This update ensures all icons display correctly

## v1.9.13

**23 Jan 2026**

* **Status Polling Configuration:** Apply polling configuration for Daon standard flow.
* **Document Upload:** Improved OneSDK flow to correctly display document types during the KYC document upload flow, ensuring a consistent user experience regardless of how the flow is initiated.
* **Onfido Integration Improvements:**   Enhanced the Onfido IDV module within OneSDK to better respect recipe configurations for the useOneStep flow. It introduces the ability to configure an exit button and refines how document types and biometric options are passed to the Onfido SDK, addressing a client's need for flexible IDV processes.
* **Camera Management for Incode:**  We've added a manual teardown function to ensure the camera properly turns off when a user leaves a page, preventing the camera from remaining active unexpectedly.

***

## v1.9.12

**16 Dec 2025**

* **Critical Error Fix:**  Added telemetry to detect critical error that occasionally prevented OneSDK from loading individual details, ensuring a more stable and reliable experience.

***

## v1.9.11

**11 Dec 2025**

* **Process Initialization for Daon Provider:**  Enhanced the status polling mechanism for process initialization to improve reliability and provide a smoother user experience during critical operations.

***

## v1.9.10

**04 Dec 2025**

* **Data Mapping:** Resolved an issue where Daon data was not correctly mapping to the V2 Portal, ensuring all entity details and images are now displayed accurately and consistently.
* **IDV Service Stability:** A critical bug causing the IDV service to crash when attempting to find a selfie ID for entities without an ID document has been resolved, improving system stability and reliability.
* **Driver's License Expiry Date:**  The eKYC form now includes an 'Expiry Date' field for Driver's Licenses, allowing customers to capture this information during onboarding and improving data completeness for connectors.
* **IDV Review:**  Fixed an issue where the IDV Review was not displaying document fields correctly when identity documents contained a self-image without an OCR run date, ensuring all relevant document information is now visible.
* **Biometric Review Page:**  The biometric review page now correctly accepts apostrophes in name fields, resolving an issue that previously caused Know Your Customer (KYC) checks to fail for users with apostrophes in their legal names.
* **Performance Improvement for Truuth IDV vendor:** We've significantly improved the loading speed of identity verification screens, reducing load times to under 5 seconds for a smoother user experience.
* **\[v1.9.10] Date of Birth Input:**  The Date of Birth field in OneSDK screens now accurately validates month entries, displaying error messages only after all DOB fields are completed.

***

## v1.9.9

**01 Dec 2025**

* **IDV Processing for Daon:** OneSDK now includes a new feature to poll the status of identity verification (IDV) requests when the initial process indicates 'CHECK\_PROCESSING'. This enhancement ensures that users are informed about the ongoing processing of their IDV requests, preventing indefinite waiting times.

\---=

## v1.9.8

**26 Nov 2025**

* **Biometric SMS Links:**  Fixed an issue where biometric SMS links failed to send to New Zealand phone numbers with non-standard digit lengths (9 or 11 digits), ensuring all valid NZ phone numbers can now successfully receive these links.
* OnFido Configuration:\*\*  OneSDK now supports configuring Onfido to enforce mobile-only ID verification, allowing users to seamlessly complete the process on their mobile devices via QR code or link.
* User Interface Consistency for Incode:\*\* Resolved an issue where font sizing on message displays was inconsistent, ensuring a uniform and polished appearance for users.

***

## v1.9.7

**12 November 2025**

**Additional Document Collection:**  The OneSDK now supports a standardized flow for collecting additional identification documents (Passport and Driver's License) via Daon, ensuring consistent processing and improved user experience.

***

## v1.9.6

**30 October 2025**

* **IDVerse Image Assets**: Resolved an issue where SVG image assets were failing to load correctly, particularly impacting the selfie modal. This fix ensures all images display as intended.
* **IDVerse SDK Asset Loading**: Fixed an issue where the SDK was incorrectly attempting to load image assets from the local file system, which caused icons to be missing in dialogs for some users. This update ensures all icons display correctly

***

## v1.9.5

**17 October 2025**

* **Performance Monitoring:**  We've added an event to detect when memory limits are reached due to multiple browser tabs, helping us improve system stability and performance.
* **Driver's Licence Expiry Date:**  The Driver's Licence form in OneSDK now supports the expiry date as an optional field by default, ensuring compliance with FrankieOne's updated identity checks and preventing failed verifications.
* **IDVerse Event Handling:**  The `supportConfirm` event has been renamed to `validDocumentConfirmed` in the SDK to provide clearer insight into document validation outcomes, allowing for more precise handling of user responses to ID document validity.
* **OCR Endpoint:**  The OCR endpoint now supports an optional token for enhanced session management and authentication when attaching OCR documents.

***

## v1.9.4

**1 October 2025**

* **Address Form**: Improve behavior of address state field reset when changing the country in the review form, ensuring accurate address data entry
* **Review Screen Pre-population**: Fixed an issue where the phone number was not prepopulated on the 1SDK review screen, ensuring a smoother user experience when completing IDV flows.

***

## v1.9.3

**15 September 2025**

* **Incode SDK Integration**: Capability to configure Incode SDK to expose a option within the settings, allowing for a tutorial screen to be displayed before document scanning on both desktop and mobile devices.
* **Address Input**: When a quota error occurs during address input via Google API, users can now manually enter their address details, ensuring a smoother onboarding experience.

***

## v1.9.2

**15 September 2025**

* **IDV Workflow**:  Improve behavior of confirmation checkbox in the IDV workflow, ensuring users must now check the box to proceed and complete the process.
* **OCR-only Flow Process**: Integrates support for Incode’s combined consent and document selector features, providing enhanced flexibility and control over the user onboarding flow within OCR-only processes.

***

## v1.9.1

**12 September 2025**

* **Support IDV Flow with Truuth**: We are now supporting Truuth, a new IDV vendor to perform IDV flow with OCR extraction and Biometrics. This update ensures seamless onboarding experience using the Truuth’s interface.
* **Onfido biometric variants in OneSDK**: OneSDK now supports exposing different Onfido ‘requestedVariant’ configurations, allowing for more flexible integration with Onfido’s biometric verification options (video, motion, and standard).

***

## v1.9.0

**09 September 2025**

* **Start Screen Image Display:**  The start screen now correctly maintains the aspect ratio of images, ensuring they display as intended without distortion.
* **Document Upload:**  We have added a latest feature enhancement to Hosted OneSDK. Users can now seamlessly generate secure, standalone links that allow their customers to upload their ID documents safely. This solution drastically minimizes the risks associated with insecure email submissions, ensuring both new and existing entities enjoy a safer, more efficient process. [Learn more here](https://docs.frankieone.com/docs/using-hosted-onesdk#document-collection)

***

## v1.8.16

**02 September 2025**

* **Form Review**: The form review screen now improved submission email and phone number fields, ensuring all user-provided contact information is captured.
* **IDVerse Integration**: OneSDK has been updated to use a new IDVerse build, improving the reliability and accuracy of identity verification processes for passports and driver's licenses.
* **Embedded IDV Flow Styling and Performance**: We've enhanced the Embedded IDV flow to allow for custom styling, providing greater flexibility in user interface design. Additionally, improvements have been made to optimize data handling, preventing app crashes during repeated use of the IDV flow.

***

## v1.8.15

**28 August 2025**

* **Improved Performance on Handling Multiple Attachments**: Resolved an issue where the OneSDK would crash or slow down significantly when handling multiple attachments, particularly during biometric flows. This fix prevents crashes and improves performance by optimizing how image data is handled, ensuring a smoother user experience during retries.
* **Daon Initialisation Improvement**: We have resolved an issue where the Daon IDV process was not correctly initializing, ensuring smoother identity verification workflows.

***

## v1.8.14

**21 August 2025**

* **IDVerse Error Handling:**  Improved error handling for IDVerse scans by introducing a new error type, `IDVerseScanFailedAndDestroyed`, which is triggered after multiple failed OCR or biometric attempts. This provides clearer feedback when an IDVerse scan cannot be completed.
* **IDVerse Biometric Workflow:**  The system now prevents users from starting biometric verification for a new transaction if OCR has not been completed, ensuring a more streamlined and correct workflow.
* **Additional Error Tracking:**  The SDK now captures and externalizes `out of bounds memory` errors from the Incode OCR component, improving error handling and stability.

***

## v1.8.13

**20 August 2025**

* **Enhance User Experience with Start Screen.** The new start screen now dynamically renders the logo and call-to-action (CTA) based on provided configurations, ensuring a tailored user experience. It emits specific events upon loading, CTA interaction, and error occurrences, enhancing responsiveness and feedback mechanisms. [Read more…](https://docs.frankieone.com/docs/implementation-guide/module/ekyc/start)
* **Enhanced Network Failure Handling in OneSDK.** In this update, OneSDK improves the IDV review flow by gracefully handling network failures during the KYC process. Users are now given the opportunity to retry submissions up to three times, with clear error messages guiding them through network issues, ensuring a smoother and more transparent user experience.

***

## v1.8.12

**05 August 2025**

* **Support OCR-only flow with Daon**: We are now supporting Daon, a new IDV vendor to perform OCR-only extraction on document uploads.
* **Support Biometrics and OCR Split flow with Daon**: We are now supporting Daon, a new IDV vendor to perform split flow for OCR extraction and Biometrics. This update ensures seamless handling of verifications across diverse document types and countries, providing a secure onboarding experience.
* **Support IDV Flow with Daon**: Implement Headed IDV flow with OCR extraction and Biometrics. This update ensures seamless onboarding experience using the Daon’s interface.
* **Phone Number Field Enhancement**: This update improves the handling of phone numbers in fields with available code options, ensuring correct separation of area codes and numbers. It addresses various formats, including those with and without the '+' sign and '-' separators, enhancing data submission accuracy.

***

## v1.8.11

**21 July 2025**

***IDVerse Updates***

* **Improved Handling of Multiple Document Attempts**: This update addresses issues related to multiple document submission attempts, enhancing the overall user experience and stability.
* **Enabled Skip Face Scan Intro Option**: You now have the option to skip the introductory screen for face scans.
* **Exposed `scanFail` Error Events**: We have exposed `scanFail` error events, providing more detailed feedback and enabling better error handling within your applications.

<Note>
  - **IDVerse Integration**: This release utilises the IDVerse release version from July 9, 2025.
  - `skipFaceScanIntro` **Flag**: The `skipFaceScanIntro` flag is set to `FALSE` by default. To enable this feature and set it to TRUE, you can include the `skipFaceScanIntro` flag within the `biometrics` component configuration, either on the `OneSdk` instance or directly on the biometrics component.

  ```js Example Usage theme={null}
  // On OneSDK Instance
  const oneSdk = await OneSdk({
      session: sessionObjectFromBackend,
      mode: "production",
      recipe: {
          ocr: {
              provideReviewScreen: false,
              provider: {
                  name: "idverse",
              }
          },
          biometrics: {
              provider: {
                  name: "idverse",
                  skipFaceScanIntro: true, // Set to true to skip the intro
              }
          }
      }
  });

  // OR on biometrics component
  const biometrics = oneSdk.component('biometrics', {
      provider: {
          name: 'idverse',
          skipFaceScanIntro: true, // Set to true to skip the intro
      }
  }); 
  ```
</Note>

<Warning>
  * **Biometrics Screen Stuck on Phone (with** `skipFaceScanIntro` **enabled)**: When `skipFaceScanIntro` is enabled and the user's journey begins on a mobile phone, we have identified an issue where the user may get stuck on the biometrics screen and cannot proceed. This issue is **not observed** when the journey starts from a desktop device. We are actively investigating this and will provide a fix in a future release.
</Warning>

***Hosted OneSDK***

* **Enhanced Success Screen:** Use the customisable success screen so that customers can make configuration changes to it such as title and description.

***

## v1.8.10

**15 July 2025**

The following changes are included in this release:

* **Enhanced Result Screen Flow**: In the hosted OneSDK versions v1 and v2, for both IDV review and KYC fraud processes, the success screen now consistently displays a success message with only one full stop for better user experience.
* **Safari Cookie Blocking Causes LocalStorage SecurityError**: In Safari on macOS, enabling "Block all cookies" in Preferences -> Privacy results in a SecurityError when websites attempt to use localStorage. Consider using SessionStorage as a fallback or advise users not to block all cookies.
* **Customizable Checkbox Colors in OneSDK/HostedOneSDK V2**: FrankieOne now offers enhanced customization in its OneSDK/HostedOneSDK V2, allowing businesses to tailor checkbox colors to match their brand themes.

***

## v1.8.9

**09 July 2025**

The following changes are included in this release:

* **Customizable Branding in HostedOneSDK**: This feature allows customers to customize and add their company logo. This enhancement enables seamless alignment with your company’s branding, providing a more personalized and cohesive user experience.
* **Enhanced OCR Review Page Stability**: Users can now set the document type to "Driver License" and select "NZL" as the country without the country field disappearing.
* **\[Hosted] Better handling of ocr\_only flow in Hosted OneSDK**:  Improved the user experience by addressing issues that occur when starting the OCR-only flow with Incode, preventing users from being redirected to an error page.

***

## v1.8.8

**30 June 2025**

The following changes are included in this release:

* **FrankieOne Enhances Onboarding with New Consent Flow**. FrankieOne introduces a Welcome & Consent screen for new entities without prior consent across OCR-only, IDV, and IDV-review flows. This update ensures compliance and a seamless onboarding experience, reinforcing FrankieOne's commitment to user-friendly and secure identity verification solutions.
* **FrankieOne Introduces Enhanced Vendor Switching in OneSDK for Seamless Identity Verification**: We have updated our OneSDK platform, enabling seamless switching between identity verification vendors like Incode, Onfido, and Sumsub within the embedded environment. This enhancement offers businesses greater flexibility and efficiency with real-time results displayed in the portal. Ideal for fintech and regtech sectors, this update streamlines compliance and optimizes customer onboarding.
* **Enhanced Error Logging for failure to load external script**: In the event of network issues preventing the loading of Incode scripts for OCR and Biometrics components, error messages will now be logged on Cloudwatch. This ensures prompt identification and resolution of script load errors, enhancing system reliability and user experience.
* **Handle empty phone number country code**: Since V2 now requires phone number country code, handle empty value instead of returning an error

***

## v.1.8.7

**24 June 2025**

The following changes are included in this release:

* **SDK Memory Usage:** Reduce the OneSDK memory usage during code build
* **Enhances Date Input Validation:** Defer the input validation when user has completed all the date components. If date is prefilled, validate the input promptly to alert users of any discrepancies.
* **Better user experience when unable to fetch Onfido SDK:** We've improved the user experience by addressing the issue where a blank screen appeared when OneSDK was unable to load the Onfido SDK. This update ensures seamless continuity, providing users with a more intuitive interaction.
* **IDVerse Engine 5 Support**
  We're introducing support for split OCR + Biometrics workflows powered by IDVerse Engine 5.
  ✅ **Verified Scenarios**:
  * **Passport-based flows** successfully tested with documents from:
    * New Zealand 🇳🇿
    * Australia 🇦🇺
    * India 🇮🇳
    * Canada 🇨🇦
  * **Australian Driver’s License-based flows** validated as part of our UAT testing efforts.
    ⚠️ **Known Issues**
  * **Front/Back scan inconsistency** — failures common in NT, WA, TAS, QLD (likely due to fake IDs)
  * **OCR issues for DOB/Expiry** — affects ACT, NSW, SA, VIC; under investigation (likely due to fake IDs)
  * This enhancement improves flexibility and future-proofs biometric verification flows for evolving compliance needs and document formats.

***

## v1.8.6

**04 June 2025**

The following changes are included in this release:

* **Sumsub as new additional IDV partner**: We've added Sumsub as an IDV partner, to provide additional options for customers especially for cryptocurrency companies. Contact your Customer Success team member if you are interested learn more.
* **Eliminate separate calls for OCR and Biometrics**: We've improved how we process results from Onfido. Now, a single API call handles both OCR and Biometrics, eliminating the need for separate calls. This update simplifies the process and enhances reliability, ensuring you receive accurate results more efficiently.
* **Telemetry improvements**: The OCR, Biometrics, and IDV modules now emit more granular events, giving you richer insights for monitoring and troubleshooting.

***

## v1.8.5

**23 May 2025**

The following changes are included in this release:

* **Enhanced Tracking**: Hosted OneSDK (using iframe) will now send a notification to our event system when they receive a "window unload" message from the parent window. This helps us track when the application is being closed or navigated away from.
* **Custom Retry Pages and Outage for DVS**: Introduced a feature to customize retry pages based on specific field errors during verification or front-end validation processes. This allows users to focus on correcting only the necessary fields rather than all fields. This covers Personal Information Errors and Document Errors. Display an error screen advising customers to try again later due to system unavailability (500 - timeout).
* **Handle invalid document type event**: Emit appropriate `event: input_required` when we received invalid document type from backend.

***

## v1.8.4

**19 May 2025**

The following changes are included in this release:

* **Window Unload Event Tracking** We've added tracking to identify when users leave the biometric verification process early. This helps distinguish between system issues and user-initiated page closure. This is applicable to embedded and non iframe hosted.

***

## v1.8.3

**13 May 2025**

The following change is included in this release:

* **Country filter on manual driver’s licence screen**: Resolved an issue that prevented the manual driver’s licence screen from limiting the country selector to Australia. The screen now reliably displays only “Australia (AUS).”

***

## v1.8.2

**28 Apr 2025**

The following changes are included in this release:

* **Date-of-birth validation fix**: Eliminated the false “Enter a valid date of birth” error that appeared even when the format and value were correct.
* **Hosted OneSDK runtime error screen**: Added a dedicated error screen that appears if a problem is encountered during Hosted OneSDK execution, giving users a clear recovery path.
* **Device-permission logging**: Implemented an event handler that records Incode device-permission requests, helping developers diagnose camera and microphone access issues faster.
* **New Zealand passport expiry validation fix**: Corrected a defect that incorrectly flagged valid NZ passport expiry dates.

***

## v1.8.1

**10 Apr 2025**

The following changes are included in this release:

* **Handling Consent**: \[Fixed] Consent from manual forms not passed correctly for a specific customer scenario
* **Hosted OneSDK Success Event Format**: \[Fixed] Incorrect format of Hosted OneSDK `idv:success event`
* **Phone Number Validation**: \[Fixed] Phone number validation failed despite correct format
* **General Improvement**: \[Fixed] To improve security, we've updated our system to prevent the header from request being logged, ensuring a safer experience for users.

***

## v1.8.0

**07 Apr 2025**

The following changes are included in this release:

* **Expanded Onfido Support**: We’ve added support for Onfido version 14.\* in OneSDK. To take advantage of the latest improvements, please contact our customer support team to update your configuration.

***

## v1.7.21

**26 Mar 2025**

The following changes are included in this release:

* **Display Name Update Issue Resolved**: Fixed an issue where the DisplayName was being incorrectly updated upon verification, leading to invalidation and a suspected status.
* **OCR Component Failure Screen**: Addressed a bug that now correctly shows a failure screen if the OCR (Object Character Recognition) component fails during processing.

***

## v1.7.20

**19 Mar 2025**

The following changes are included in this release:

* **Order Fields in Personal Details**: You can now customize the order of fields when entering personal details, enhancing the flexibility and organization of your data input.
* **Fixed Loading Issue**: Resolved an issue where OneSDK would fail to load if the entity had a customer reference set. This fix ensures smoother initialization and operation.
* **Onfido Modal Enhancement**: The Onfido modal now includes a confirmation dialog to prevent users from accidentally closing it by clicking the overlay. This enhancement prevents unintended session termination.
* **OneSDK CLI Customizations**: Apply customizations more effectively in IDV + Review through the OneSDK command-line interface, providing more control and efficiency in operations.

***

## v1.7.19

**07 Mar 2025**

The following changes are included in this release:

* **Fixed Retry Screen Issue**: Resolved the problem where the Retry screen persistently asked for additional ID verification. This fix ensures a smoother user experience without repetitive requests for identification.
* **Improved Redirect Links**: Enhanced the handling of redirect links, ensuring they are correctly applied across various flow IDs<br />This update applies to:
* IDV + Review
* IDV + KYC
* Manual + KYC
* OCR Only

***

## v1.7.18

**27 Feb 2025**

The following changes are included in this release:

* **Edit Button Customization**: You can now customize the edit button on the review screen, enhancing the user interface according to your brand needs.
* **Disabled Button Background Color**: Customize the background color of disabled buttons to match your application's aesthetic.
* **Credit Header Description Customization**: Tailor the `credit_header_description` to provide clearer guidance and context to users.
* **Multiple IDs/Retry Flow Text Customization**: Modify the text displayed during multiple ID submissions or retry flows to improve user understanding and reduce errors.
* **Address Search Label Update**: For address searches, the label now uses the value from `formatted_address` from the Google Search API, replacing the previous use of `description` from Google Predictions API. This change aims to provide more accurate and user-friendly address suggestions.

**Fixes**

* **Project Build Issue**: Resolved an issue where projects could not be built using the latest version of OneSDK. Ensure seamless integration and deployment with this fix.

***

## v1.7.17

**24 Feb 2025**

The following updates are included in this version:

* Improve OCR module to read expiry date when switching between different ID types.
* The OCR module's events have been updated to match the order and format of the Biometrics module.
* Previously, OCR vendor loaded event is only emitted when OCR is done. Now, vendor loaded event is emitted before ready event regardless if OCR is done or not.
* Adjusted the credit header text for passed KYC checks.
* Trigger Google API requests when typing is complete. This optimization reduces the number of API calls and associated costs.

**Additional configurable components**:

* HTML link tags: Updated the HTML sanitization logic to allow the `<a target="_blank">` tag. This allows customers to include links that open in a new tab within consent screens, enhancing user experience.
* Checkbox colors: Added the ability to customize the color of checkboxes using the .ff-checkbox CSS class and the accent-color property. This allows for greater flexibility in styling consent screens.

***

## v1.7.16

**17 Feb 2025**

This version of the OneSDK includes the latest enhancements and updates that we’ve made to improve your experience with our platform. It also fixes issues previously encountered.

***

## v1.7.15

**27 Jan 2025**

The following changes have been implemented in this version:

* General improvements, including improved logic for handling entity information updates and status flagging.
* Resolved an issue where the UI was not visible in dark mode.
* Updated the messaging on the result screen for KYC check results.

***

## v1.7.13

**13 Jan 2025**

The following updates are included in this version:

* **Enhanced OCR Review with Manual Address Input**: The OCR review screen now defaults to manual address input, ensuring accurate and complete address information by requiring users to fill in individual address fields.
* **Configurable OCR Field Extraction**: Customers can now configure which specific fields should be pre-filled after OCR extraction, providing greater control over the data review process.
* **Rate Limit Investigation for OneSDK Calls**: We've implemented measures to investigate and potentially rate-limit critical calls within the OneSDK to ensure stability and prevent rapid successive executions.
* **Additional Error Handling**:

1. We've addressed several scenarios to provide clearer error messages and a smoother user experience, particularly when encountering issues with OCR or missing permissions.
2. **Improved error Response of OCR Failures**. When it fails or an invalid document is provided, system now returns a more informative error code (not a generic 500), allowing for better error handling.

* **Incode version 1.75.2 support is now available**. For those using embedded, you may update sdkversion to point this while customers using Hosted OneSDK will automatically fetch this version

***

## v1.7.12

**16 Dec 2024**

The following updates have been implemented in OneSDK:

* UI issue on Driver’s Licence button text misalignment and instruction text during selfie capture
* Missing middle name initial option for Medicare Card in eKYC form and requirement config not working
* Unable to override Labels for Personal details in Review screen
* Update Address breakdown issue
* Added ability to view and non-editable personal information (Name + DOB + Address) in the review screen and generic document screen

***

## v1.7.11

**26 Nov 2024**

* Improvements on phone, email and device information for fraud check

***

## v1.7.10

**22 Nov 2024**

The following updates are included in this version:

* The review screen is skipped when an Incomplete status is received from the backend.
* Document Restrictions Not Working for Passports
* Navigation not clearing the form
* Mounting of result screen
* Document configuration for passport and driver’s licence
* Document configuration for passport and driver’s licence
* Ability to disable edit button on review screen
* Prevent OneSDK’s styling from overriding customer's styling

***

## v1.7.7

**21 Oct 2024**

Allow retries after partial error before directing

**Fixes**

* Issue with phone number not updating individual module
* ID expiry date allows date prior to current date
* Cosmetic issue with field borders

***

## v1.7.6

**26 Sept 2024**

OneSDK now emits a clear event when the Onfido modal is closed, ensuring seamless integration and improved user experience.

***

## v1.7.5

**19 Sept 2024**

Added the new Hosted OneSDK flow, `idv_kyc`. This new flow provides a complete end-to-end flow, including IDV and KYC

***

## v1.7.4

**16 Sept 2024**

We've introduced the ability to set and remove key-value pairs (KVPs) on an entity. This enhancement enables customers to add extra information, such as a preferred name `preferredName`, to the entity using OneSDK.

***

## v1.7.3

**03 Sept 2024**

* We've added Webpack Support to expand the compatibility of OneSDK with build tools.

**Fixes**

* The ID Type wasn't being highlighted when a document was already added. This is now fixed.
* The timestamp in the Portal now correctly shows the submission time of the entity details.
* Previously, it displayed the time when OneSDK was initialized.
* Fixed a bug where a duplicate screen appeared when the back button was disabled in a single-page customer implementation.
* An error has been fixed where it was mistakenly showing up in headless OCR.
* The biometric instructions text for users has been fixed to ensure it doesn't appear too low on the screen.

***

## v1.7.2

**01 Aug 2024**

Onboarding Forms: New onboarding forms extracted address mapping.<br />Onboarding Forms: Fix issue with country address mapped to Passport issuing country

***

## v1.7.1

**15 July 2024**

New Onboarding Forms: Fix Review screen input configuration

***

## v1.7.0

**27 June 2024**

**Introducing OneSDK Onboarding Forms**

We're thrilled to announce that in 2024 we're launching our new OneSDK Onboarding Forms, to replace Smart UI.

OneSDK Onboarding Forms was developed through insight and feedback from valued clients, like yourself. We're confident that it ill yield substantial benefits for both your organisation and your end-users, delivering a faster experience that isn't only superior but also more cost-effective, and enables:

**Better outcomes**

* Improved Pass Rates (5-10%+ uplift)
* 2X Faster Onboarding with Biometrics-first
* Capability to conduct A/B testing of screens
* OneSDK Analytics to track user behaviour**More flexibility**
* Modular forms for easy UX optimisation, facilitating rapid deployment of new designs in less than a day
* Availability of our Hosted OneSDK, managed by FrankieOne, facilitating seamless improvements and patches directly to you without involving your engineers
* Future access to our Business Onboarding Forms

***

## v1.6.1-beta

**30 May 2024**

**OneSDK Enhancements**<br />*Updates:*<br />Onfido: You can now limit the country and document type in the OCR header.<br />Onfido: Custom UI is now exposed for easier customization.<br />Individual Module: The entityProfile is now accessible for use.

*Fixed*<br />Mock Mode: Issues with exit/error functionality have been resolved.

**Hosted OneSDK Updates**<br />*FIxed*<br />Loading Spinner: The problem with the loading spinner not working has been fixed.

***

## v1.5.0-beta

**30 April 2024**

**Introducing OneSDK Onboarding Forms**<br />We're thrilled to announce that in 2024 we're launching our new OneSDK Onboarding Forms, to replace Smart UI.

OneSDK Onboarding Forms was developed through insight and feedback from valued clients, like yourself. We're confident that it will yield substantial benefits for both your organisation and your end-users, delivering a faster experience that isn't only superior but also more cost-effective, and enables:

**Better outcomes**

* Improved Pass Rates (5-10%+ uplift)
* 2X Faster Onboarding with Biometrics-first
* Capability to conduct A/B testing of screens
* OneSDK Analytics to track user behaviour<br />**More flexibility**
* Modular forms for easy UX optimisation, facilitating rapid deployment of new designs in less than a day
* Availability of our Hosted OneSDK, managed by FrankieOne, facilitating seamless improvements and patches directly to you without involving your engineers
* Future access to our Business Onboarding Forms

***

## v1.4.4-beta

**11 April 2024**

This version of the OneSDK contains the following updates:

* For Incode, we’ve added the ability to force a specific document type for OCR processing.
* Handling of CSS within the OneSDK has also been improved.
* We’ve introduced support for DigitalID in OCRLabs
* Our team also resolved issues related to the NPM package.

***

## v.1.4.3-beta

**28 March 2024**

This version of the OneSDK contains the following updates:

* Added the full Smart UI configuration in the Form component in OneSDK.
* Additional changes to implement Smart UI into OneSDK

***

## v.1.3.2-beta

**19 March 2024**

This version of the OneSDK contains the following update:<br />A hotfix was implemented to address an issue related to capturing driver’s license information using Incode SDK 1.66.0.<br />To address this issue, the default version was reverted to 1.59.0, and dynamic version selection in the recipe now permits using an alternative version.

***

## v.1.3.1-beta

**08 March 2024**

This version of the OneSDK contains the following update:<br />A **hotfix** was applied to resolve an issue where iOS users encounter an error related to screen orientation.

***

## v1.3.0-beta

**05 March 2024**

This version of the OneSDK contains the following update:<br />To align with Incode's new policy, we've enabled the option to re-use the token from the IDV service.

***

## v1.2.0-beta

**23 January 2024**

This version of the OneSDK contains the following update:<br />**Onfido IDV flow into OneSDK (OCR + Biometrics)**

***

## v1.1.0-beta

**05 December 2023**

This version of the OneSDK contains the following update:<br />**OCR with review screen**<br />**SmartUI within OneSDK**

* Minor fixes and updates

***

## v1.0.0-beta

**01 November 2023**

This version of the OneSDK contains the following update:<br />**Incode for OCR and Biometrics**

***

## v0.8.6-alpha

**17 October 2023**

This version of the OneSDK contains the following update:<br />**Hotfix for Onfido Motion**<br />A fix was implemented to prevent the issue where the user isn't able to proceed to OCR flow due to an infinite loop.

***

## v0.8.3-alpha

**19 September 2023**

This version of the OneSDK contains the following update:

**Onfido for OCR and Biometrics (Motion)**

***

## v0.8.0-alpha

**01 August 2023**

This version of the OneSDK contains the following update:

**Addition of IDV flow**

***

## v0.7.4-alpha

**28 July 2023**

This version of the OneSDK contains the following features:

**Capture details from an individual**<br />Use the IDV component to capture and verify the details of an individual

**Document OCR flow**<br />The OCR component provided by OneSDK to extract document details from a document images supplied by the user

**Biometrics (selfie and liveliness)**<br />Leverage the Biometrics component or the OCR component via the OneSDK.

**Device characteristics and behavioral biometrics** Evaluate potential fraud indicators from the characteristics of their device as well as al their form-filling behavior using OneSDK

**Support Federated Identity**<br />Use OneSDK's Federation component to import data from various Identity Providers (**IdP**s) that support OpenID Connect or OAuth2.

Additional features help developers build and test the OneSDK:

**Test mode**<br />Use mock data during development to accelerate integration by enabling your frontend and backend teams to work parallel

**Headless UI**<br />Integrate seamlessly into your existing design system to match yhour application's look and feel

**Install via CDN or npm**<br />Choose how to integrate into your codebase.

**RX.JSObservable support**<br />Integrate into popular frontend frameworks such as Vue, Angular, or React with support for RXKS.Observable

***


# FrankieOne Help
Source: https://docs.frankieone.com/docs/v2-frankieone-help



## Overview

The FrankieOne help feature allows users to access support, interact with the **Frank** AI chatbot, and provide feedback. This guide provides a comprehensive overview of the new features, usage instructions, and known limitations.

### Video Guide

<div>
  <iframe />
</div>

<CardGroup>
  <Card title="Easy Access" icon="keyboard">
    FrankieOne Help is accessible directly from the portal interface, making it convenient for quick query resolutions.
  </Card>

  <Card title="Guided Navigation" icon="list">
    Provides step-by-step guidance to help users navigate through various portal functionalities.
  </Card>

  <Card title="Public Documentation Support" icon="book">
    Frank AI leverages the public knowledge base to offer accurate and up-to-date information.
  </Card>

  <Card title="Feedback Mechanism" icon="comments">
    Includes a feedback system to capture user suggestions for continuous improvement.
  </Card>
</CardGroup>

## New Help Feature Updates

* The help icon at the bottom right of the screen has been replaced with the **FrankieOne logo**.

* This serves as the primary access point for the updated help interface.

* Users can now:
  * **Interact with Frank** chatbot to ask questions.
  * **Submit support requests** to the Support site.
  * **Provide feedback** through a survey form.

## How to Use the Help Feature

### Interacting with the Chatbot

1. Click on the **FrankieOne** logo at the bottom right of the screen.
2. Type your question or concern in the input box.
3. Click **Submit** to send your request.

### Submitting a Support Request

* Selecting **Submit a request** will redirect you to the **FrankieOne Support** site, where you can submit reques tickets or get in touch with us.

### Providing Feedback

* Selecting **Give feedback** will open a new tab with a feedback survey form.

## Limitations

While the Frank AI provides useful assistance, there are several limitations to be aware of:

### Data Accessibility

* The chatbot **does not** have access to **private** data or sensitive data in your account.
* It is limited to our **public documentation** ([https://docs.frankieone.com](/docs/welcome-to-frankie)).

### Query Limitations

* The chatbot **cannot** provide:
  * **User-specific data** (for example: passing rates, metrics, or entity details).
  * **Automated workflow execution** within the FrankieOne platform.
  * **API-related, payload-related, or code-related responses**.

### File and Image Input

* The chatbot **only** supports **text-based** queries.
* It does **not** allow file uploads or image-based inputs.

<Callout icon="bell">
  ##### Disclaimer

  * Our chatbot is powered by AI, answers may not always be 100% accurate.
  * We do not train the AI on questions or information entered in the chat. The AI will only remember what’s in the context of the chat to give tailored responses.
  * As a precaution, do not enter sensitive information or PII in the chat.
</Callout>


# Viewing your KYC rulesets
Source: https://docs.frankieone.com/docs/view-kyc-ruleset



The KYC Rulesets page lets you see the verification rules configured for your account in one place.  No more emails or spreadsheets to answer "what runs on this workflow?" or "why did this entity pass?".

## Accessing your KYC rulesets

You can view your account's KYC rulesets by clicking **Rulesets** under **Risk and rules** on the sidebar. The page is only visible to users with one of the following roles:

1. Administrator
2. Super Admin
3. Compliance Officer

## How to view your account rulesets

A customer passes KYC verification when they meet the requirements of at least one ruleset. Each ruleset defines the minimum data matches needed for verification.

<Frame>
  <img alt="Ruleset 1 1" />
</Frame>

### **Understanding match requirements**

Each ruleset specifies the minimum number of matches required across four data types:

* **Name matches** — sources that must verify the entity's name
* **Address matches** — sources that must verify the entity's address
* **Date of birth matches** — sources that must verify the entity's date of birth
* **Government ID matches** — sources that must verify the entity's government ID

For example, the `one_plus` ruleset requires `1×` name match and `1×` (address OR DOB) match. No government ID is required.

<Info>
  For more information, see [A Detailed Guide to eKYC Rulesets - frankieone](https://docs.frankieone.com/docs/ekyc-rulesets)
</Info>

## How to see why an entity passed or failed

You can view the ruleset evaluation for a specific entity from the page.

<Frame>
  <img alt="Ruleset 2 1" />
</Frame>

1. **KYC step result** — the verification step that ran, with the applied ruleset shown in the workflow label (for example, `Ruleset: one_plus_gov_id`)
2. **Ruleset match requirements** — the data and match thresholds required by the applied ruleset
3. **Matches found** — the data points that were successfully matched
4. **Outcome** — the outcome of the KYC check (eg Pass, Fail)

This breakdown shows which ruleset was applied, what was required, what was matched, and the outcome.

## How to see Required vs. optional checks

When you review a verification result, you'll see two types of checks:

* **Required checks that did not match** — checks the ruleset required, where no source confirmed the data. These cause the verification to fail and are shown as a failure.
* **Optional checks that did not match** — checks that weren't required by the ruleset, or where another rule already satisfied the requirement. These are acceptable and are shown with an **Optional** badge alongside the source.

The distinction helps you tell at a glance whether an unmatched check is a real problem (required but missing) or expected (optional and accounted for).

<Frame>
  <img alt="Ruleset 3 1" />
</Frame>

## Coming soon

* Granular KYC issue codes on entity profiles  for faster troubleshooting of failed verifications
* Historical ruleset change tracking


# Comments
Source: https://docs.frankieone.com/docs/viewing-comments



# View comments

Comments added on manual actions (e.g. changing workflow status) can be seen in various pages within the portal.

## Global comments

If there are comments available, selecting the Global comment icon would show an expanded icon.

<Frame>
  <img alt="" />
</Frame>

## Latest comments

On certain sections of each page, hovering on the comment icon would display the latest comment. For example:

<Frame>
  <img alt="" />
</Frame>

# Review comments

## Workflow events

<Frame>
  <img alt="" />
</Frame>

The expanded comments view would show the comments related to Workflow status updates as well as comments for each of the workflow check results.

<Frame>
  <img alt="" />
</Frame>

## Profile

The expanded comments view would show the comments related to Entity updates (which relates to KYC database checks) such as adding documents, correcting names, etc.

<Frame>
  <img alt="" />
</Frame>

Hovering on the comment icon would display the latest comment on the personal info updates.

<Frame>
  <img alt="" />
</Frame>


# Managing Entity & Workflow Risk
Source: https://docs.frankieone.com/docs/viewing-risk-scores



This walkthrough explains how FrankieOne tracks and controls customer risk within the Portal. It distinguishes between **Workflow Risk** (the result of a single check) and **Entity Risk** (the customer’s ongoing risk profile). It also shows how to view risk scorecards, identify outdated data, and perform manual overrides to update a customer's status for compliance purposes.

## <Icon icon="person-circle-check" />

## Viewing entity risk

<Info>
  The **Entity risk score** is always determined by the **latest workflow risk**.
</Info>

1. Navigate to an Entity page and click the **Profile** tab.
2. The **Entity risk** is shown as a color-coded badge in the **Personal info** section.

<Frame>
  <img alt="Image" />
</Frame>

3. When you click on the badge, the **risk scorecard** panel will appear on the right side of the screen. All the risk values here are based on the entity’s **latest workflow risk**.
   <Frame>
     <img alt="Image" />
   </Frame>

## <Icon icon="diagram-project" />

## Viewing latest workflow risk

<Info>
  If the same workflow has been run multiple times, only the workflow risk of the latest run/attempt is displayed.
</Info>

1. In the Portal, navigate to an **Entity** page to view its workflow events.
2. By default, the first workflow you see is also the latest one. The **workflow risk level** is shown on the right side. Click the **Risk score** button — this will open a panel on the right side of the screen.

<Frame>
  <img alt="Image" />
</Frame>

3. The **risk scorecard** panel shows all risk factors and scores used in the workflow run.
   <Frame>
     <img alt="Image" />
   </Frame>

## <Icon icon="scroll-old" />

## Viewing an outdated workflow risk

<Info>
  There may be cases where different workflows were run for an Entity.
</Info>

1. In the **Workflow Events** tab, navigate to an older workflow.
   <Frame>
     <img alt="Image" />
   </Frame>
2. When you click the **Risk score** button and open the risk scorecard, you should instantly see that this workflow risk score is already stale. You can choose to view the latest workflow risk, or run the workflow again to get a fresh risk assessment.
   <Frame>
     <img alt="Image" />
   </Frame>

<Icon icon="arrows-split-up-and-left" />

## Overriding risk

In some cases, the workflow risk may need to be manually overridden - for example, to escalate it to Medium or High following a manual review that identifies additional concerns.

<Info>
  **Who can use this feature:** Administrators, Operators and Compliance Officers have the relevant permissions by default
</Info>

1. Navigate to the Entity’s latest workflow event and click **Risk score.**
2. Click **Manual override** on the top right corner.
   <Frame>
     <img alt="Image" />
   </Frame>
3. Select the new risk level and add a comment to record any rationale/note for audit trail purposes.
   <Frame>
     <img alt="Image" />
   </Frame>
4. After you proceed, the override will be immediately reflected in the risk scorecard.

<Info>
  A manual override will remain in effect until **any underlying risk factor changes in a future workflow run**. When that happens, the system recalculates risk and clears the old override.
</Info>

<Callout icon="thumbtack">
  **Best practices**

  Resolve individual risk factors where possible (e.g. mark false positives) rather than overriding the total score. This keeps your audit trail clean and ensures risk reflects the entity's actual profile.
</Callout>


# Vue
Source: https://docs.frankieone.com/docs/vuejs-onesdk-implementation

This guide will walk you through integrating OneSDK with a Vue.js application, covering both Webpack and Vite setups.

## Quick Start

<Steps>
  <Step title="Create a New Vue Project">
    Choose your preferred bundler:

    <Tabs>
      <Tab title="Webpack">
        ```shell # Install Vue CLI globally npm install -g @vue/cli # Create new theme={null}
        project vue create my-onesdk-app 
        ```
      </Tab>

      <Tab title="Vite">
        ```shell theme={null}
        # Create new project with Vite 
        npm create vue@latest 
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Install OneSDK">
    ```shell theme={null}
    npm install @frankieone/one-sdk
    ```
  </Step>

  <Step title="Configure Environment Variables">
    Create a `.env` file in your project root:

    ```plaintext theme={null}
    VUE_APP_CUSTOMER_ID=your_customer_id
    VUE_APP_CUSTOMER_CHILD_ID=your_child_id
    VUE_APP_API_KEY=your_api_key
    ```

    <Callout icon="bell">
      Never commit sensitive credentials to version control. Add `.env` to your `.gitignore` file.
    </Callout>
  </Step>
</Steps>

## Implementation

<Accordion title="App.vue Implementation">
  Create or update your `./src/App.vue`:

  ```vue App.vue theme={null}
  <script setup>
  import { onMounted, ref } from 'vue'
  import OneSDK from '@frankieone/one-sdk'

  // Configuration references
  const CUSTOMER_ID = import.meta.env.VITE_CUSTOMER_ID
  const CUSTOMER_CHILD_ID = import.meta.env.VITE_CUSTOMER_CHILD_ID
  const API_KEY = import.meta.env.VITE_API_KEY

  const session = ref(null)
  const tokenResult = ref(null)

  onMounted(async () => {
  // Initialize session
  const tokenResult = await initializeSession()

  // Configure OneSDK
  const oneSdk = await setupOneSDK(tokenResult)

  // Setup individual verification
  const individual = setupIndividual(oneSdk)

  // Initialize IDV flow
  setupIDVFlow(oneSdk)
  })

  // Session initialization
  async function initializeSession() {
  const response = await fetch("https://backend.latest.frankiefinancial.io/auth/v2/machine-session", {
  method: "POST",
  headers: {
  "authorization": "machine " + btoa(`${CUSTOMER_ID}:${CUSTOMER_CHILD_ID}:${API_KEY}`),
  "Content-Type": "application/json"
  },
  body: JSON.stringify({
  permissions: {
  "preset": "one-sdk",
  "reference": `demo-${new Date().toISOString()}`
  }
  })
  })
  return await response.json()
  }

  // OneSDK configuration
  async function setupOneSDK(tokenResult) {
  const sdk = await OneSDK({
  session: tokenResult.session,
  mode: "development",
  recipe: {
  form: {
  provider: {
  name: 'react',
  googleApiKey: 'YOUR_GOOGLE_API_KEY'
  },
  }
  }
  })

  sdk.on('\*', console.log)
  return sdk
  }

  // Individual verification setup
  function setupIndividual(sdk) {
  const individual = sdk.individual()
  individual.addConsent("general")
  individual.addConsent("docs")
  individual.addConsent("creditheader")
  return individual.submit()
  }

  // IDV flow setup
  function setupIDVFlow(sdk) {
  const idv = sdk.flow("idv")
  const components = {
  loading1: sdk.component("form", {
  name: "LOADING",
  title: { label: "Loading..." },
  descriptions: [{ label: "" }]
  }),
  loading2: sdk.component("form", {
  name: "LOADING",
  title: { label: "Processing results..." },
  descriptions: [{
  label: "Hold tight, this can take up to 30 seconds. Please don't refresh this page."
  }]
  }),
  review: sdk.component("form", {
  name: "REVIEW",
  type: "ocr"
  })
  }

  setupIDVEventHandlers(idv, components)
  idv.mount("#e2e-idv-container")
  }

  // Event handlers setup
  function setupIDVEventHandlers(idv, components) {
  let isInitialLoading = true

  idv.on("loading", (display) => handleLoading(display, components, isInitialLoading))
  idv.on("results", (data) => handleResults(data, components))
  idv.on("error", handleError)
  idv.on("detection_complete", handleDetectionComplete)

  components.review.on("form:review:ready", handleReviewReady)
  }

  </script>

  <template>
    <div class="onesdk-container">
      <div id="e2e-idv-container" class="idv-container"></div>
      <div id="e2e-idv-loading1"></div>
      <div id="e2e-idv-loading2"></div>
    </div>
  </template>

  <style scoped>
  .onesdk-container {
    width: 100%;
    height: 85vh;
  }

  .idv-container {
    width: 100%;
    height: 100%;
  }
  </style>

  ```
</Accordion>

## Event Handling

<AccordionGroup>
  <Accordion title="Loading Events">
    ```javascript theme={null}
    function handleLoading(display, components, isInitialLoading) {
      if (display) {
        if (isInitialLoading) {
          components.loading1.mount("#e2e-idv-loading1")
        }
      } else {
        if (isInitialLoading) {
          components.loading1.unmount()
          isInitialLoading = false
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Results Events">
    ```javascript theme={null}
    function handleResults({ checkStatus }, components) {
      if (checkStatus) {
        console.log("Verification successful")
        components.loading2.unmount()
        components.review.mount("#e2e-idv-container")
      } else {
        console.warn("No data returned")
      }
    }
    ```
  </Accordion>

  <Accordion title="Error Handling">
    ```javascript theme={null}
    function handleError({ message, payload }) {
      console.error("Verification error:", message, payload)
    }
    ```
  </Accordion>
</AccordionGroup>

## Running the Application

<Steps>
  <Step title="Start Development Server">
    <Tabs>
      <Tab title="Webpack">
        ```shell theme={null}
        npm run serve
        ```
      </Tab>

      <Tab title="Vite">
        ```shell theme={null}
        npm run dev
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Access the Application">
    Open your browser and navigate to:

    * Webpack: `http://localhost:8080`
    * Vite: `http://localhost:5173`
  </Step>
</Steps>

<Callout icon="star">
  ##### Development Best Practices

  * Keep sensitive configuration in `.env` files
  * Implement proper error handling for API calls
  * Use Vue's Composition API for better code organization
  * Consider implementing loading states for better UX
</Callout>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Common Issues">
    * **Session Token Issues**: Ensure your credentials are correct in the `.env` file
    * **Mounting Errors**: Check that container IDs match exactly
    * **Component Loading**: Verify all required components are properly initialized
  </Accordion>

  <Accordion title="Environment Setup">
    * **Vue Version**: Ensure you're using Vue 3.x
    * **Node Version**: Use Node.js 18.x or later
    * **Build Issues**: Clear npm cache and node\_modules if encountering build problems
  </Accordion>
</AccordionGroup>


# Why You Should Migrate from SmartUI to OneSDK
Source: https://docs.frankieone.com/docs/why-migrate



## SmartUI Has Reached End of Life

SmartUI was built on deprecated frontend technologies (Vue 2), which reached [official end-of-life <Icon icon="arrow-up-right-from-square" />](https://v2.vuejs.org/eol/). We’re officially discontinuing Smart UI support and updates effective **December 31, 2024**.

That means:

* No new feature requests will be accepted
* Risks to potential security or browser compatibility issues (no known issue at this point)
* Limited support for new FrankieOne or vendor features
* Gradually increasing maintenance requirements for your team

While FrankieOne will continue to honour existing SmartUI flows, **it will no longer be actively maintained or recommended**. All new features and improvements are released exclusively through OneSDK, ensuring you stay current with the latest capabilities and enhancements..

<Callout icon="bell">
  Using SmartUI post-EOL may result in browser breakage, degraded UX and pass rates, or failure to support future vendor SDKs.
</Callout>

## Upgrade to OneSDK: A Better, More Flexible Experience

OneSDK is our modern SDK platform that supports both hosted and embedded options. It unlocks features, flexibility, and improved reliability.

| Feature                                                                                                       | SmartUI | OneSDK |
| :------------------------------------------------------------------------------------------------------------ | :------ | :----- |
| Modular Flows                                                                                                 | ❌       | ✅      |
| FrankieOne Hosted Options (No Dev Effort)                                                                     | ❌       | ✅      |
| Link Generation via Portal                                                                                    | ❌       | ✅      |
| Multi-vendor Support                                                                                          | ❌       | ✅      |
| Additional Regional Support                                                                                   | ❌       | ✅      |
| Fraud Detection & Device Risk                                                                                 | ❌       | ✅      |
| Enhanced Branding Options                                                                                     | ❌       | ✅      |
| OCR Autofill Forms                                                                                            | ❌       | ✅      |
| API v2 Compatibility                                                                                          | ❌       | ✅      |
| Upcoming Features, e.g. <br /> Document Upload Module, <br />Risk Assessment Onboarding, <br />KYB Onboarding | ❌       | ✅      |

<Callout icon="thumbtack">
  Customers switching to OneSDK typically see **pass rate improvements of \~5%** and a significant reduction in support issues.
</Callout>

## Risks of Staying on SmartUI

While Vue 2 has had few minor known vulnerabilities, **running unsupported frameworks is increasingly seen as a risk by compliance and security teams**, especially if:

* You're shipping with SLAs or under audit
* Your browser support matrix is wide
* You require vendor SDK updates or fraud modules

<Callout icon="thumbtack">
   Browsers can break legacy frontend libraries without warning (for example, Shadow DOM changes, deprecated API handling).
</Callout>

## Your Migration Options

### Hosted OneSDK

* FrankieOne builds and hosts the UI with your branding & regional customisation
* Receive a code snippet to drop into your app or redirect to
* Fastest implementation (1–2 weeks to UAT)

### Embedded OneSDK

* Full control over UI and customer experience
* Requires engineering effort (\~4-8 weeks)
* Best for bespoke workflows or native app flows

## Migration is Easier Than You Think

For Hosted Flows:

1. **Select a standard flow** (e.g. IDV only, eKYC+Review)
2. **Branding and configuration** via customisation form or Studio
3. **Receive preview link + UAT access**
4. **Sign off and go live**

<Callout icon="thumbtack">
  Migration can be completed in **2-4 weeks** with minimal dev effort.
</Callout>

## FAQs

**Can I keep my current vendor?**
Yes — OneSDK supports both Incode and Onfido (and more). You can even switch between vendors per flow easily.

**Will my config carry over?**
Yes — our team maps your current settings during migration and recreates the required JSON + UI setup. The functionality, look and feel of your implementation will be retained, however, we cannot promise a 1:1 match on UI elements.

**Can I fully customise branding in hosted implementation?**
Yes — logos, colours, messages, and result screens are all customisable in Hosted mode. We will continue to release updates to allow more bespoke experience in our hosted flows.

**How do I decide between hosted vs embedded?**

* Hosted = faster setup, low effort, FrankieOne managed
* Embedded = full control, longer dev time, requires resources
* See hosted vs embedded decision tree below

<img />

## What’s Next

* ✅ Book your migration kickoff call
* ✅ Browse sample [OneSDK flows](/docs/hosted-common-use-cases) and decide what suits your users best

## Timeline Overview

| Phase       | Duration                                    |
| :---------- | :------------------------------------------ |
| UAT Setup   | 1–2 weeks                                   |
| UAT Testing | 1-2 weeks for hosted; 4 weeks+ for embedded |
| Go Live     | 1-2 weeks                                   |

Still have questions? Reach out to your CSM or contact us via [support@frankieone.com <Icon icon="arrow-up-right-from-square" />](mailto:support@frankieone.com)


# Workflow events tab
Source: https://docs.frankieone.com/docs/workflow-events-tab



### Video Guide

<iframe />

## What are Workflows for individuals?

<img alt="" />

A workflow is a predefined sequence of checks—KYC, OCR, Biometrics, AML, Fraud—that FrankieOne runs on an entity. The **Workflow events** tab lists each execution (event) and its results.

### Monitoring workflows vs. Standard

| Type           | Purpose                                                                                  | Runs automatically?                                    |
| :------------- | :--------------------------------------------------------------------------------------- | :----------------------------------------------------- |
| **Standard**   | Onboard or re-verify a customer with the chosen checks.                                  | Triggered manually (Save & Verify, Send link, or API). |
| **Monitoring** | Re-screen an existing profile at regular intervals (for example, daily sanctions watch). | Yes—scheduled or rule-based.                           |

### Multiple workflows on an entity

You can run different workflows on the same entity. Each run appears as a separate **event** in the list (Attempt #1, Attempt #2). Use this to:

* Retry a failed onboarding workflow after data fixes.
* Add an extra “Enhanced Due Diligence” workflow on high-risk profiles.

## What is an Event, attempt or execution, event ID

An event (also called an attempt or execution) is a single run of a workflow on an entity. When you press Save & verify, resend a Smart UI link, or schedule a monitoring cycle, the Portal creates a fresh event and tags it with an Event ID—a unique reference you can use in audit logs, API calls, or support tickets.

### Key points

* Each event shows its own status (Pass, Fail, Needs attention, and so on).
* The Workflow events tab lists events in reverse order: Attempt #1, Attempt #2, Attempt #3 … so you can track every execution.
* You can copy the Event ID from the Audit Report or the URL path when drilling into check details.

## Risk score

Click **Risk score** to view the numeric score and the factors that changed it. Scores update every time a workflow finishes.

<img alt="" />

### Workflow status

The coloured badge beside each event shows the outcome.

#### Pass

All checks passed. No action needed.

#### Fail

Blocking issue found. Review Check summary to see why.

#### Manual pass / manual fail

A user overrode the automatic result (comment is logged).

#### Need attention

At least one check needs manual review.

#### Unchecked

Event started but checks have not finished yet.

## Check summary

The lower pane lists every check in the order executed, showing:

* Data source used (for example, **DVS**, **Adverse Media**).
* Match count or pass/fail result.
* Comments icon for manual overrides or notes.


# Workflow Viewer
Source: https://docs.frankieone.com/docs/workflow-viewer



## Video Guide

<iframe />

## Introduction

The Workflow Viewer is a powerful tool designed to help you and your team members understand verification workflows. It provides an intuitive interface for viewing the configured verification processes that has been setup for your account.

## Benefits

<CardGroup>
  <Card title="Complete Visibility" icon="eye">
    Instantly view and explore every verification step, condition, and action in your workflows.
  </Card>

  <Card title="Faster Training" icon="sliders">
    Use clear visual diagrams to train new staff with confidence.
  </Card>

  <Card title="Compliance Made Simple" icon="arrows-rotate">
    Quickly validate workflow configurations for audits and regulators.
  </Card>

  <Card title="Clear visual overview" icon="eye">
    Easily see the overall structure of your workflow for fast review and verification of key information.
  </Card>
</CardGroup>

## User Interface overview

### Main screen

<img alt="" />

#### Workflow

This is a dropdown displaying all the workflows available in your account.

**Canvas**

The main workspace where the workflow’s details is visualized based on how it’s been configured for your account with all the different services and conditions.

**Canvas Navigation**

* **Pan**: Click and drag on empty areas of the canvas to move around

* **Zoom**: Use mouse wheel or zoom controls to adjust the view

* The canvas provides visual feedback through cursor changes to reflect different actions

**Controls**

These are canvas controls that allows you to zoom-in, zoom-out, or adjust the canvas to fit the whole workflow in your view.

### Properties

When you select a workflow component on the canvas, this panel displays its properties and configuration options.

## Workflow Components

The Workflow Visualiser includes various components such as but not limited to:

### Verification Checks

* **Gov ID**: Identity document verification

* **Biometrics**: Facial recognition and liveness detection

* **Supporting Documents**: Upload and verification of additional documents

* **PEP/Sanction/Adverse Media**: Politically exposed persons and sanctions screening

* **Name Validation**: Verification of identity details

* **Visa**: Visa validation checks

* **Blocklist**: Check against blocklisted entities

* **Duplicate**: Check for duplicate entities

* **IDV**: Identity verification

* **KYC Steps**: Know Your Customer verification (includes Equifax and Experian)

* **Risk Decision**: Risk assessment and decisioning

### Flow Control

* **Integration Trigger**: Starting point of the workflow

* **Conditionals**: Logic branches based on verification results

* **Set Entity Recommendations**: Configure recommendations based on verification outcomes

## Common Issues

<AccordionGroup>
  <Accordion title="Connection Errors">
    **Issue**: FrankieOne service is unavailable and is unable to retrieve your workflow configuration.

    <img alt="" />

    ***

    **Issue**: Workflow service is down and is unable to retrieve your workflow configuration.

    <img alt="" />

    **Recommended action**: It is advised to refresh the page after some time or reach out to FrankieOne if issue persists.
  </Accordion>

  <Accordion title="Configuration Errors">
    **Issue**: Workflow has not been fully configured. Verify that all required properties are set for each component.

    <img alt="" />

    **Recommended action**: Reach out to FrankieOne to help complete the configuration.
  </Accordion>

  <Accordion title="No workflows have been setup">
    <img alt="" />

    **Recommended action**: Reach out to FrankieOne to help complete the configuration.
  </Accordion>
</AccordionGroup>


# API Testing Tips
Source: https://docs.frankieone.com/v2/api/developers/api-testing-guide

Getting Started with Postman or Bruno for FrankieOne v2 API

## A Practical Guide to Testing FrankieOne v2 APIs

### Document Overview

This guide explains how to use **Postman** or **Bruno** to explore and test FrankieOne's **v2 APIs**, helping you understand how our platform works before integrating it into your application.

**API Version:** This guide focuses on **v2 APIs** (recommended for all new integrations)

### What You'll Learn

* What Postman and Bruno are and why they're useful
* How to choose the right tool for your team
* How to access FrankieOne's v2 API collection
* How to set up your environment
* How to create entities using v2 payloads
* How to run verification checks
* How to view results in the FrankieOne Portal
* Common testing scenarios with v2
* Troubleshooting tips

### Who Should Read This

* Developers evaluating FrankieOne
* Technical teams planning integration
* Anyone wanting to understand FrankieOne's v2 APIs
* Teams testing verification workflows

***

## Table of Contents

1. [Choosing Your API Client](#choosing-your-api-client)
2. [Getting Started](#getting-started)
3. [Setting Up Your Environment](#setting-up-your-environment)
4. [Understanding the v2 API Collection](#understanding-the-v2-api-collection)
5. [Using Testbed Data](#using-testbed-data)
6. [Running Your First v2 API Call](#running-your-first-v2-api-call)
7. [Viewing Results in the Portal](#viewing-results-in-the-portal)
8. [Common Testing Scenarios](#common-testing-scenarios)
9. [Understanding API Responses](#understanding-api-responses)
10. [Best Practices](#best-practices)
11. [Troubleshooting](#troubleshooting)
12. [Next Steps](#next-steps)
13. [FAQs](#faqs)

***

## Choosing Your API Client

### What Are API Clients?

API clients are tools that allow you to send API requests without writing code, see responses in real-time, and test different scenarios easily.

**Think of them as:** A visual interface for interacting with APIs—like a web browser for APIs instead of websites.

### Postman vs Bruno

| Feature               | Postman                 | Bruno                           |
| --------------------- | ----------------------- | ------------------------------- |
| **Price**             | Free tier (with limits) | Completely free and open-source |
| **Storage**           | Cloud-based             | Local filesystem                |
| **Account Required**  | Yes (for full features) | No                              |
| **Collaboration**     | Postman cloud           | Git version control             |
| **Offline Use**       | Limited                 | Full support                    |
| **Collection Format** | JSON                    | Bru (plain text)                |
| **Learning Curve**    | Beginner-friendly       | Beginner-friendly               |

### Which Should You Choose?

<CardGroup>
  <Card title="Choose Postman if you:">
    * Want cloud sync across devices
    * Prefer a polished, feature-rich interface
    * Need built-in team collaboration features
    * Are already familiar with Postman
  </Card>

  <Card title="Choose Bruno if you:">
    * Want to version control your API collections with Git
    * Prefer data stored locally (privacy-focused)
    * Don't want to create an account
    * Work offline frequently
    * Want a lightweight, fast tool
  </Card>
</CardGroup>

<Note>
  Both tools work equally well with FrankieOne's v2 APIs. Choose based on your team's preferences.
</Note>

***

## Getting Started

### Step 1: Install Your Chosen Tool

<Tabs>
  <Tab title="Postman">
    **Download:**

    * Visit: [https://www.postman.com/downloads/](https://www.postman.com/downloads/)
    * Choose your operating system (Windows, Mac, Linux)
    * Download and install
    * Create a free account (optional but recommended)

    **Alternative:** Use Postman Web (browser-based) at [https://web.postman.co](https://web.postman.co)
  </Tab>

  <Tab title="Bruno">
    **Download:**

    * Visit: [https://www.usebruno.com/downloads](https://www.usebruno.com/downloads)
    * Choose your operating system (Windows, Mac, Linux)
    * Download and install
    * No account required

    **Alternative (Command Line):**

    ```bash theme={null}
    # macOS (Homebrew)
    brew install bruno

    # Windows (Chocolatey)
    choco install bruno

    # Linux (Snap)
    snap install bruno
    ```
  </Tab>
</Tabs>

### Step 2: Get FrankieOne's v2 API Collection

#### Where to Find It

* FrankieOne Developer documentation: [https://docs.frankieone.com/docs/introduction/resources](https://docs.frankieone.com/docs/introduction/resources)
* Contact your FrankieOne representative

#### What You'll Get

* Collection file (.json format)
* Pre-configured v2 API requests
* Example requests for all v2 endpoints
* Organized by functionality

### Step 3: Import the Collection

<Tabs>
  <Tab title="Postman">
    1. Click **"Import"** (top left)
    2. Choose file or drag and drop
    3. Select the FrankieOne v2 collection file
    4. Click **"Import"**

    **Result:** Collection appears in left sidebar, ready to use.
  </Tab>

  <Tab title="Bruno">
    1. Click **"Import Collection"**
    2. Select **"Postman Collection"**
    3. Choose the FrankieOne v2 collection file (.json)
    4. Select a folder location to store the collection
    5. Click **"Import"**

    **Result:** Bruno converts the collection to Bru format and stores it locally.

    <Tip>
      Since Bruno stores collections as files, you can immediately add them to Git for version control.
    </Tip>
  </Tab>
</Tabs>

### Step 4: Get Your API Credentials

**You'll need:**

| Credential                | Description                                          |
| ------------------------- | ---------------------------------------------------- |
| X-Frankie-CustomerID      | Your main customer/account ID                        |
| X-Frankie-CustomerChildID | Optional - for sub-account isolation (if configured) |
| api\_key                  | Your API authentication key                          |
| Environment               | UAT/Sandbox for testing                              |

**How to Get Them:**

1. Contact your FrankieOne representative
2. Request UAT/Sandbox access
3. Ask about Customer Child ID (if you have sub-accounts)
4. Receive credentials via secure channel
5. Keep credentials secure

**Environments:**

| Environment | Base URL                      | Purpose                                               |
| ----------- | ----------------------------- | ----------------------------------------------------- |
| UAT         | `https://api.uat.frankie.one` | User Acceptance Testing—for testing before production |
| Production  | `https://api.frankie.one`     | Live use only (not for testing)                       |

### Understanding Customer Child ID

**What is Customer Child ID?**

`X-Frankie-CustomerChildID` is an optional header used for **sub-account isolation** within your main FrankieOne account.

**When to Use It:**

| Scenario                          | Use CustomerChildID?                |
| --------------------------------- | ----------------------------------- |
| Single account, no sub-divisions  | ❌ No - leave blank                  |
| Multiple business units or brands | ✅ Yes - if configured by FrankieOne |
| White-label implementations       | ✅ Yes - if configured by FrankieOne |
| Reseller/partner accounts         | ✅ Yes - if configured by FrankieOne |

**How It Works:**

```mermaid theme={null}
graph TD
    A[Main Customer Account] --> B[X-Frankie-CustomerID: main-account-123]
    B --> C[Child 1: Brand A]
    B --> D[Child 2: Brand B]
    B --> E[Child 3: Region APAC]
    C --> F[X-Frankie-CustomerChildID: brand-a]
    D --> G[X-Frankie-CustomerChildID: brand-b]
    E --> H[X-Frankie-CustomerChildID: apac]
    
    style A fill:#e1f5ff,stroke:#333,stroke-width:2px
    style B fill:#d4edda,stroke:#333,stroke-width:2px
    style C fill:#fff3cd,stroke:#333,stroke-width:1px
    style D fill:#fff3cd,stroke:#333,stroke-width:1px
    style E fill:#fff3cd,stroke:#333,stroke-width:1px
```

**Key Points:**

* CustomerChildID is **configured by FrankieOne** - you cannot create child IDs via API
* All entities created with a specific CustomerChildID are isolated to that sub-account
* Reporting and data access are separated by CustomerChildID
* If you don't have sub-accounts, leave this header blank or omit it

<Warning>
  **Important:** If you have CustomerChildID configured, you must use the correct value in the header. Using the wrong CustomerChildID or omitting it when required may result in entities being created in the wrong sub-account or authentication errors.
</Warning>

**To Get Your CustomerChildID:**

1. Contact your FrankieOne representative
2. Ask if you have sub-accounts configured
3. Receive CustomerChildID values if applicable
4. Add to your environment variables

***

## Setting Up Your Environment

### What Are Environments?

Environments store variables like your API base URL, Customer ID, and API Key. They let you:

* Switch between UAT and Production easily
* Keep credentials secure
* Reuse variables across all requests
* Share collections without exposing keys

### Required Variables for v2 API

The following variables match the FrankieOne Postman environment:

| Variable                    | Example Value                     | Description                                                            |
| --------------------------- | --------------------------------- | ---------------------------------------------------------------------- |
| `frankie-environment`       | `uat`                             | Environment segment for URL construction (e.g., `uat`)                 |
| `X-Frankie-CustomerID`      | `your-customer-id`                | Your Customer ID provided by FrankieOne                                |
| `X-Frankie-CustomerChildID` | `your-customer-child-id`          | Optional: Customer Child ID for sub-account isolation                  |
| `api_key`                   | `your-api-key`                    | Your API Key (stored as secret)                                        |
| `serviceName`               | (provided by FrankieOne)          | Service profile name for workflow execution                            |
| `workflowName`              | (provided by FrankieOne)          | Workflow name for execution                                            |
| `entityId`                  | (populated after creating entity) | Entity ID for subsequent requests                                      |
| `executionId`               | (populated after workflow run)    | Workflow execution ID for retrieving results                           |
| `X-Frankie-Username`        | (optional)                        | Username of the API caller                                             |
| `X-Frankie-Channel`         | (optional)                        | Channel the request originates from (e.g., `api`, `portal`, `smartui`) |

<Note>
  **Additional element-level variables** are also available in the Postman environment for use after entity creation: `nameId`, `dateOfBirthId`, `addressId`, `documentId`, `phoneNumberId`, `emailAddressId`, `attachmentId`, and `sessionToken`. These are typically auto-populated by test scripts in the Postman collection.
</Note>

### Creating Your Environment

<Tabs>
  <Tab title="Postman">
    **Step 1: Create New Environment**

    1. Click **"Environments"** (left sidebar)
    2. Click **"+"** to create new
    3. Name it: `FrankieOne KYC V2 AUS`

    **Step 2: Add Variables**

    | Variable                    | Initial Value      | Current Value      | Type    |
    | --------------------------- | ------------------ | ------------------ | ------- |
    | `frankie-environment`       | `uat`              | `uat`              | default |
    | `X-Frankie-CustomerID`      | `your-customer-id` | `your-customer-id` | default |
    | `X-Frankie-CustomerChildID` | (optional)         | (optional)         | default |
    | `api_key`                   | `your-api-key`     | `your-api-key`     | secret  |
    | `serviceName`               |                    |                    | default |
    | `workflowName`              |                    |                    | default |
    | `entityId`                  |                    |                    | default |
    | `executionId`               |                    |                    | default |
    | `X-Frankie-Username`        | (optional)         | (optional)         | default |
    | `X-Frankie-Channel`         | (optional)         | (optional)         | default |

    **Step 3: Activate Environment**

    1. Click **"Save"**
    2. Select environment from dropdown (top right)
  </Tab>

  <Tab title="Bruno">
    **Step 1: Open Environment Settings**

    1. Click the **gear icon** (Environments)
    2. Click **"Create Environment"**
    3. Name it: `FrankieOne KYC V2 AUS`

    **Step 2: Add Variables**

    ```text theme={null}
    frankie-environment: uat
    X-Frankie-CustomerID: your-customer-id
    X-Frankie-CustomerChildID: your-customer-child-id
    api_key: your-api-key
    serviceName:
    workflowName:
    entityId:
    executionId:
    X-Frankie-Username:
    X-Frankie-Channel:
    ```

    <Note>
      **X-Frankie-CustomerChildID** is optional and used for sub-account isolation. Leave blank if not applicable.
    </Note>

    **Step 3: Activate Environment**

    1. Click **"Save"**
    2. Select `FrankieOne KYC V2 AUS` from the environment dropdown

    <Tip>
      Environment files are stored as `.bru` files in your collection's `environments/` folder. You can edit them directly in any text editor.
    </Tip>
  </Tab>
</Tabs>

### Using Variables in Requests

Both Postman and Bruno use the same syntax for variables:

```text theme={null}
{{variableName}}
```

**Example v2 Request URL:**

```text theme={null}
https://api.{{frankie-environment}}.frankie.one/v2/individuals
```

**Example Headers:**

```text theme={null}
api_key: {{api_key}}
X-Frankie-CustomerID: {{X-Frankie-CustomerID}}
X-Frankie-CustomerChildID: {{X-Frankie-CustomerChildID}}
X-Frankie-Channel: {{X-Frankie-Channel}}
X-Frankie-Username: {{X-Frankie-Username}}
Content-Type: application/json
```

<Note>
  **Optional headers:** `X-Frankie-CustomerChildID`, `X-Frankie-Channel`, and `X-Frankie-Username` are all optional. Include them only when applicable to your configuration. In the Postman collection, these optional headers are present but disabled by default.
</Note>

The tool automatically replaces `{{variableName}}` with the actual value from your environment.

***

## Understanding the v2 API Collection

### v2 API Structure

FrankieOne's v2 API collection is organized by entity type and functionality. The following reflects the folder structure in the FrankieOne Postman collection:

```text theme={null}
FrankieOne KYC V2 AUS
│
├── Individual Entities
│   ├── Create Entity with Aus Passport
│   ├── Update Entity
│   ├── Get Entity
│   └── Delete Entity
│
├── Individual Workflows
│   ├── Get Workflows
│   ├── Create Entity and Execute Workflow
│   ├── Execute Workflow
│   ├── Get a Workflow Execution
│   └── Get a List of Workflow Executions
│
├── Individual Documents
│   ├── Create Document
│   └── Delete Document
│
├── Individual IDV
│   ├── Get IDV Token
│   └── Process IDV OCR
│
├── Individual Service Profiles
│   └── Get Service Profile for Entity
│
├── Individual Results
│   ├── Create mKYC results
│   ├── Update AML results
│   └── Get results
│
├── Individual Monitoring
│   └── Toggle AML Monitoring
│
└── Search
    └── Search Service Profiles
```

### Key v2 Endpoints

| Category             | Endpoint                                                                                                     | Method   | Purpose                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------------ | -------- | -------------------------------------------------- |
| **Individuals**      | `/v2/individuals`                                                                                            | `POST`   | Create an individual entity                        |
|                      | `/v2/individuals/{entityId}`                                                                                 | `GET`    | Retrieve individual details                        |
|                      | `/v2/individuals/{entityId}`                                                                                 | `PATCH`  | Update individual information                      |
|                      | `/v2/individuals/{entityId}`                                                                                 | `DELETE` | Delete an individual entity                        |
| **Workflows**        | `/v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/execute`                  | `POST`   | Execute verification workflow                      |
|                      | `/v2/individuals/new/serviceprofiles/{serviceName}/workflows/{workflowName}/execute`                         | `POST`   | Create individual and execute workflow in one call |
|                      | `/v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions`               | `GET`    | List workflow executions                           |
|                      | `/v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions/{executionId}` | `GET`    | Get a specific workflow execution                  |
| **Documents**        | `/v2/individuals/{entityId}/documents`                                                                       | `POST`   | Create a new document for an individual            |
|                      | `/v2/individuals/{entityId}/documents`                                                                       | `GET`    | Get all documents for an entity                    |
| **IDV**              | `/v2/individuals/{entityId}/actions/idv/token`                                                               | `POST`   | Get IDV token for provider SDK                     |
| **Results**          | `/v2/individuals/{entityId}/results`                                                                         | `GET`    | Get verification results                           |
|                      | `/v2/individuals/{entityId}/results/aml`                                                                     | `PATCH`  | Update AML result status                           |
|                      | `/v2/individuals/{entityId}/results/mkyc`                                                                    | `POST`   | Approve manual KYC                                 |
| **Monitoring**       | `/v2/individuals/{entityId}/monitoring`                                                                      | `PATCH`  | Toggle AML monitoring on/off                       |
| **Service Profiles** | `/v2/individuals/{entityId}/serviceprofiles/{serviceName}`                                                   | `GET`    | Get service profile for entity                     |
| **Search**           | `/v2/search/serviceprofiles`                                                                                 | `POST`   | Search for entity profiles                         |

<Note>
  All v2 endpoint paths start directly with `/v2/`. There is no base path prefix such as `compliance/v1.2` (that belongs to the v1 API).
</Note>

***

## Using Testbed Data

### What is Testbed Data?

Testbed data is pre-configured test data that produces predictable results in the FrankieOne UAT environment.

**Purpose:**

* Test different scenarios
* No real customer data needed
* Consistent, repeatable results
* Safe for testing

**Available at:** [https://docs.frankieone.com/docs/test-data](https://docs.frankieone.com/docs/test-data)

### Test Scenario Types

| Scenario          | Result                              | Use Case                    |
| ----------------- | ----------------------------------- | --------------------------- |
| **PASS (CLEAR)**  | Verification succeeds               | Test successful onboarding  |
| **FAIL (FRAUD)**  | Verification fails / fraud detected | Test rejection flows        |
| **REVIEW**        | Manual review required              | Test escalation workflows   |
| **PEP**           | Politically Exposed Person match    | Test AML screening          |
| **SANCTION**      | Sanctions list match                | Test AML screening          |
| **PEP, SANCTION** | Both PEP and sanctions match        | Test combined AML scenarios |

### v2 Testbed Data Examples

<AccordionGroup>
  <Accordion title="PASS Scenario (Australia) - v2 Format">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "JAMES",
          "middleName": "A",
          "familyName": "TESTONE"
        },
        "dateOfBirth": {
          "year": "1950",
          "month": "01",
          "day": "01"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "status": "CURRENT",
            "unitNumber": "U 1",
            "streetNumber": "35",
            "streetName": "CONN",
            "streetType": "STREET",
            "locality": "FERNTREE GULLY",
            "subdivision": "VIC",
            "postalCode": "3156",
            "country": "AUS",
            "unstructuredLongForm": "U 1/35 CONN STREET, FERNTREE GULLY, VIC 3156"
          }
        ],
        "documents": {
          "IDENTITY": [
            {
              "type": "DRIVERS_LICENSE",
              "primaryIdentifier": "283229690",
              "secondaryIdentifier": "P5403241",
              "country": "AUS",
              "subdivision": "VIC"
            }
          ]
        },
        "consents": [
          {
            "type": "GENERAL"
          },
          {
            "type": "DOCS"
          }
        ]
      }
    }
    ```

    **Expected Result:** CLEAR (PASS)
  </Accordion>

  <Accordion title="FAIL Scenario - v2 Format">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "JENNY",
          "familyName": "TESTEIGHT_FAIL"
        },
        "dateOfBirth": {
          "year": "1957",
          "month": "01",
          "day": "01"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "streetNumber": "56",
            "streetName": "VICTORIA",
            "streetType": "STREET",
            "locality": "FINGAL",
            "subdivision": "TAS",
            "postalCode": "7214",
            "country": "AUS",
            "unstructuredLongForm": "56 VICTORIA STREET, FINGAL, TAS 7214"
          }
        ],
        "documents": {
          "IDENTITY": [
            {
              "type": "DRIVERS_LICENSE",
              "primaryIdentifier": "T56543",
              "secondaryIdentifier": "T03989853",
              "country": "AUS",
              "subdivision": "TAS"
            }
          ]
        },
        "consents": [
          {
            "type": "GENERAL"
          }
        ]
      }
    }
    ```

    **Expected Result:** FAIL
  </Accordion>

  <Accordion title="Minor (Under 18) - v2 Format">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "Oliver",
          "middleName": "J",
          "familyName": "Youngten"
        },
        "dateOfBirth": {
          "year": "2015",
          "month": "06",
          "day": "15"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "streetNumber": "35",
            "streetName": "Conn",
            "streetType": "Street",
            "locality": "Ferntree Gully",
            "subdivision": "VIC",
            "postalCode": "3156",
            "country": "AUS"
          }
        ],
        "consents": [
          {
            "type": "GENERAL"
          },
          {
            "type": "UNDER18"
          }
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="With Australian Passport - v2 Format">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "Sarah",
          "familyName": "Johnson"
        },
        "dateOfBirth": {
          "year": "1985",
          "month": "03",
          "day": "20"
        },
        "nationality": "AUS",
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "locality": "Melbourne",
            "subdivision": "VIC",
            "postalCode": "3000",
            "country": "AUS"
          }
        ],
        "documents": {
          "IDENTITY": [
            {
              "type": "PASSPORT",
              "primaryIdentifier": "N1234567",
              "country": "AUS",
              "issueDate": {
                "year": "2020",
                "month": "01",
                "day": "15"
              },
              "expiryDate": {
                "year": "2030",
                "month": "01",
                "day": "14"
              }
            }
          ]
        },
        "consents": [
          {
            "type": "GENERAL"
          },
          {
            "type": "DOCS"
          }
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="PEP (Politically Exposed Person) - v2 Format">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "JAMES",
          "familyName": "TESTELEVEN"
        },
        "dateOfBirth": {
          "year": "1960",
          "month": "01",
          "day": "01"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "streetNumber": "23",
            "streetName": "ISA",
            "streetType": "STREET",
            "locality": "FYSHWICK",
            "subdivision": "ACT",
            "postalCode": "2609",
            "country": "AUS"
          }
        ],
        "documents": {
          "IDENTITY": [
            {
              "type": "PASSPORT",
              "primaryIdentifier": "E55173628",
              "country": "AUS"
            }
          ]
        },
        "consents": [
          {
            "type": "GENERAL"
          }
        ]
      }
    }
    ```

    **Expected Result:** PEP match
  </Accordion>

  <Accordion title="SANCTION - v2 Format">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "BRUCE",
          "familyName": "TESTNINETEEN"
        },
        "dateOfBirth": {
          "year": "1968",
          "month": "01",
          "day": "01"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "country": "AUS"
          }
        ],
        "consents": [
          {
            "type": "GENERAL"
          }
        ]
      }
    }
    ```

    **Expected Result:** SANCTION match
  </Accordion>

  <Accordion title="Combined PEP + SANCTION - v2 Format">
    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "STACY",
          "familyName": "TESTTWENTY"
        },
        "dateOfBirth": {
          "year": "1969",
          "month": "01",
          "day": "01"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "country": "AUS"
          }
        ],
        "consents": [
          {
            "type": "GENERAL"
          }
        ]
      }
    }
    ```

    **Expected Result:** PEP, SANCTION (both flags)
  </Accordion>
</AccordionGroup>

<Note>
  **About Testbed Data:**

  These examples use FrankieOne's official testbed data with test names like TESTONE, TESTTWO, TESTELEVEN, etc. These are real test records in the UAT environment that produce predictable results.

  **Do not use fictional names** like "John Smith" or "Jane Doe" - use the actual testbed names provided above for consistent, reliable testing.
</Note>

<Note>
  **Important: Document Type Values in v2**

  Use **`DRIVERS_LICENSE`** (American spelling with underscore), not `DRIVERS_LICENCE`.

  **Common Document Types (subset — see API reference for complete list):**

  * `DRIVERS_LICENSE` ✅ (correct - American spelling)
  * `PASSPORT`
  * `NATIONAL_ID`
  * `VISA`
  * `IMMIGRATION`
  * `NATIONAL_HEALTH_ID`
  * `TAX_ID`
  * `BIRTH_CERT`
  * `CITIZENSHIP`
  * `MARRIAGE_CERT`
  * `UTILITY_BILL`
  * `BANK_STATEMENT`
  * `CONCESSION`
  * `PENSION`
  * `MILITARY_ID`
  * `OTHER`

  The full `Document-Type` enum in the OpenAPI specification includes additional types such as `HEALTH_CONCESSION`, `DEATH_CERT`, `NAME_CHANGE`, `BANK_ACCOUNT`, `INTENT_PROOF`, `ATTESTATION`, `SELF_IMAGE`, `DEVICE`, `VEHICLE_REGISTRATION`, `PROOF_OF_ADDRESS`, `HOUSE_REGISTRATION`, `WORK_PERMIT`, `EMPLOYMENT_CERTIFICATE`, and several business-related document types. Refer to the [v2 API reference](https://docs.frankieone.com) for the complete list.

  **Australian Driver's License Requirements:** For Australian driver's licenses, you must include both:

  * `primaryIdentifier` - License number (e.g., "283229690")
  * `secondaryIdentifier` - Document number / Card number (e.g., "P5403241")

  Example:

  ```json theme={null}
  {
    "type": "DRIVERS_LICENSE",
    "primaryIdentifier": "283229690",
    "secondaryIdentifier": "P5403241",
    "country": "AUS",
    "subdivision": "VIC"
  }
  ```

  **Common Mistakes:**

  * ❌ `DRIVERS_LICENCE` (British spelling)
  * ❌ `DRIVER_LICENSE` (missing S)
  * ❌ Abbreviations like `DL`
</Note>

<Note>
  **Important v2 Differences from v1:**

  * Dates use objects: `{year: "YYYY", month: "MM", day: "DD"}`
  * Address fields: `locality` (not suburb), `subdivision` (not state), `postalCode` (not postcode)
  * Documents nested by category: `documents.IDENTITY[]`
  * Document ID field: `primaryIdentifier` (not idNumber)
  * `schemaVersion` is a `readOnly` response field — it is **not required** in requests
  * Base URL uses `frankie.one` domain (not `frankiefinancial.io`)
  * No base path prefix — endpoints start directly with `/v2/`
</Note>

***

## Running Your First v2 API Call

### Overview: Create Individual Entity (v2)

This walkthrough demonstrates:

1. Creating an individual entity using v2 API
2. Understanding the v2 response
3. Saving the entity ID for subsequent requests

### Step 1: Select the Create Individual Request (v2)

<Tabs>
  <Tab title="Postman">
    1. Expand **"Individual Entities"** folder in left sidebar
    2. Click **"Create Entity with Aus Passport"**
    3. Request details appear on right
  </Tab>

  <Tab title="Bruno">
    1. Expand **"Individual Entities"** folder in left sidebar
    2. Click **"Create Entity with Aus Passport"**
    3. Request details appear in main panel
  </Tab>
</Tabs>

### Step 2: Review the v2 Request

**URL:**

```text theme={null}
POST https://api.{{frankie-environment}}.frankie.one/v2/individuals
```

**Headers:**

```text theme={null}
api_key: {{api_key}}
X-Frankie-CustomerID: {{X-Frankie-CustomerID}}
X-Frankie-CustomerChildID: {{X-Frankie-CustomerChildID}}
X-Frankie-Channel: {{X-Frankie-Channel}}
X-Frankie-Username: {{X-Frankie-Username}}
Content-Type: application/json
```

<Note>
  **Header Details:**

  * `api_key` (required): Your API authentication key
  * `X-Frankie-CustomerID` (required): Your main customer/account ID
  * `X-Frankie-CustomerChildID` (optional): Used for sub-account isolation when configured by FrankieOne
  * `X-Frankie-Channel` (optional): Identifies the channel the request originates from. Can be used in routing and risk calculations. Default values include `api`, `portal`, `smartui`, or any alphanumeric string.
  * `X-Frankie-Username` (optional): Username of the API caller
  * `Content-Type`: Always `application/json` for v2 API requests

  In the Postman collection, `X-Frankie-CustomerChildID`, `X-Frankie-Channel`, and `X-Frankie-Username` are present but **disabled by default**. Enable them as needed for your configuration.
</Note>

**Body (JSON) - v2 Format:**

```json theme={null}
{
  "individual": {
    "name": {
      "givenName": "JUDY",
      "middleName": "B",
      "familyName": "TESTTWO"
    },
    "dateOfBirth": {
      "year": "1951",
      "month": "01",
      "day": "01"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "status": "CURRENT",
        "streetNumber": "17",
        "streetName": "HUME",
        "streetType": "STREET",
        "locality": "PARKES",
        "subdivision": "NSW",
        "postalCode": "2870",
        "country": "AUS",
        "unstructuredLongForm": "17 HUME STREET, PARKES, NSW 2870"
      }
    ],
    "emailAddresses": [
      {
        "type": "PERSONAL",
        "email": "judy.testtwo@example.com",
        "isPreferred": true
      }
    ],
    "phoneNumbers": [
      {
        "type": "MOBILE",
        "number": "+61412345678",
        "isPreferred": true
      }
    ],
    "consents": [
      {
        "type": "GENERAL"
      },
      {
        "type": "DOCS"
      }
    ]
  }
}
```

<Note>
  **Example uses FrankieOne testbed data:** JUDY TESTTWO is a real test record in UAT that produces CLEAR (PASS) results. Use actual testbed names for reliable testing.
</Note>

<Note>
  **v2 Key Features:**

  * Dates are objects, not strings
  * Addresses use `locality`, `subdivision`, `postalCode`
  * Email and phone are arrays with type and preference
  * All wrapped in `individual` object
  * `schemaVersion` is **not required** in requests (it is a `readOnly` response field per the OpenAPI spec)
</Note>

### Step 3: Send the Request

<Tabs>
  <Tab title="Postman">
    * Click the blue **"Send"** button (top right)
    * Wait for response (usually 1-3 seconds)
    * Response appears in bottom panel
  </Tab>

  <Tab title="Bruno">
    * Click **"Send"** or press `Cmd/Ctrl + Enter`
    * Wait for response (usually 1-3 seconds)
    * Response appears in right panel
  </Tab>
</Tabs>

### Step 4: Review the v2 Response

**Response Status:** `201 Created`

**`Response Body (illustrative — actual structure per OpenAPI individuals_entity_response schema):`**

```json theme={null}
{
  "requestId": "01HM5XJ7VASZ3EJMB1VQGTBFJ4",
  "individual": {
    "entityId": "abc123-def456-ghi789-jkl012",
    "schemaVersion": 2,
    "name": {
      "nameId": "name-uuid-here",
      "givenName": "JUDY",
      "middleName": "B",
      "familyName": "TESTTWO"
    },
    "dateOfBirth": {
      "dateOfBirthId": "dob-uuid-here",
      "year": "1951",
      "month": "01",
      "day": "01"
    },
    "addresses": [
      {
        "addressId": "addr-uuid-here",
        "type": "RESIDENTIAL",
        "status": "CURRENT",
        "streetNumber": "17",
        "streetName": "HUME",
        "streetType": "STREET",
        "locality": "PARKES",
        "subdivision": "NSW",
        "postalCode": "2870",
        "country": "AUS"
      }
    ],
    "emailAddresses": [
      {
        "emailAddressId": "email-uuid-here",
        "type": "PERSONAL",
        "email": "judy.testtwo@example.com",
        "isPreferred": true
      }
    ],
    "consents": [
      {
        "type": "GENERAL"
      },
      {
        "type": "DOCS"
      }
    ]
  },
  "serviceProfiles": [
    {
      "serviceName": "your-service-name"
    }
  ]
}
```

<Note>
  **Response structure note:** The response wraps the individual data inside an `individual` object and may include a `serviceProfiles` array and a top-level `requestId`. The exact fields returned depend on your configuration. The Postman collection's test scripts extract values like `jsonData.individual.entityId` and `jsonData.serviceProfiles[0].serviceName`, confirming this nested structure.
</Note>

**Key Information:**

| Field                                  | Description                                          |
| -------------------------------------- | ---------------------------------------------------- |
| `requestId`                            | Unique request identifier for tracing                |
| `individual.entityId`                  | Unique identifier for this individual—**save this!** |
| `individual.schemaVersion`             | Confirms v2 format (returned in response)            |
| `individual.name.nameId`               | Assigned ID for the name record                      |
| `individual.dateOfBirth.dateOfBirthId` | Assigned ID for the DOB record                       |
| `serviceProfiles[].serviceName`        | Service profile name (use in workflow execution)     |

### Step 5: Save the Entity ID

You'll need the `entityId` for subsequent requests (workflows, documents, verifications).

<Tabs>
  <Tab title="Postman">
    **Manual Method:**

    1. Copy `entityId` from response (at `individual.entityId`)
    2. Go to your environment (click environment dropdown > Edit)
    3. Update variable: `entityId` = `abc123-def456-ghi789-jkl012`
    4. Save environment

    **Automatic Method (Post-response Script):** The Postman collection includes pre-built test scripts that automatically save key variables. For example, the "Create Entity with Aus Passport" request includes:

    ```javascript theme={null}
    var jsonData = JSON.parse(responseBody);
    pm.environment.set("entityId", jsonData.individual.entityId);
    pm.environment.set("nameId", jsonData.individual.name.nameId);
    pm.environment.set("dateOfBirthId", jsonData.individual.dateOfBirth.dateOfBirthId);
    pm.environment.set("addressId", jsonData.individual.addresses[0].addressId);
    pm.environment.set("documentId", jsonData.individual.documents.IDENTITY[0].documentId);
    pm.environment.set("serviceName", jsonData.serviceProfiles[0].serviceName);
    ```
  </Tab>

  <Tab title="Bruno">
    **Manual Method:**

    1. Copy `entityId` from response (at `individual.entityId`)
    2. Click gear icon and select your environment
    3. Add/update: `entityId: abc123-def456-ghi789-jkl012`
    4. Save

    **Automatic Method (Post-response Script):** Add this to the request's post-response script section:

    ```javascript theme={null}
    const response = res.getBody();
    bru.setEnvVar("entityId", response.individual.entityId);
    ```
  </Tab>
</Tabs>

<Check>
  **Success!** You've created a v2 individual entity.
</Check>

***

## Executing a Workflow (v2)

### What Are Workflows?

Workflows in FrankieOne v2 are pre-configured verification processes that can include:

* KYC (Electronic verification)
* IDV (Document verification)
* AML (Screening)
* Risk assessment

Workflows are **configured by FrankieOne** based on your requirements. You execute them via API but cannot configure them via API.

### Step 6: Execute a Workflow

**Select the Request:**

1. Expand **"Individual Workflows"** folder
2. Click **"Execute Workflow"**

**URL:**

```text theme={null}
POST https://api.{{frankie-environment}}.frankie.one/v2/individuals/{{entityId}}/serviceprofiles/{{serviceName}}/workflows/{{workflowName}}/execute
```

**Required Variables:**

| Variable       | Example Value            | Description            |
| -------------- | ------------------------ | ---------------------- |
| `entityId`     | From previous step       | Individual's entity ID |
| `serviceName`  | (provided by FrankieOne) | Service profile name   |
| `workflowName` | (provided by FrankieOne) | Workflow name          |

**Body:**

```json theme={null}
{
  "comment": {
    "text": "Initial verification workflow"
  }
}
```

Or if updating individual data and executing workflow:

```json theme={null}
{
  "individual": {
    "documents": {
      "IDENTITY": [
        {
          "type": "DRIVERS_LICENSE",
          "primaryIdentifier": "283229690",
          "secondaryIdentifier": "P5403241",
          "country": "AUS",
          "subdivision": "VIC"
        }
      ]
    }
  },
  "comment": {
    "text": "Adding document and executing verification"
  }
}
```

**Send the Request** and review the response.

**Workflow Execute Response (illustrative — per OpenAPI spec):**

The response may return synchronously (`200`) or asynchronously (`202`):

```json theme={null}
{
  "requestId": "01HM5XJ7VASZ3EJMB1VQGTBFJ4",
  "workflowResult": {
    "workflowExecutionId": "wf-exec-12345"
  },
  "serviceProfile": {
    "serviceName": "your-service-name"
  },
  "individual": {
    "entityId": "abc123-def456-ghi789-jkl012"
  }
}
```

The Postman collection's test script extracts the execution ID automatically:

```javascript theme={null}
var jsonData = JSON.parse(responseBody);
postman.setEnvironmentVariable("executionId", jsonData.workflowResult.workflowExecutionId);
```

<Note>
  **Synchronous vs Asynchronous:** Workflow execution may return `200` (completed) or `202` (accepted for async processing). For async requests, use the `requestId` or `workflowExecutionId` to retrieve results via `GET /v2/individuals/{entityId}/results`. You can also set the `X-Frankie-Background` header to `1` to explicitly request asynchronous processing.
</Note>

### Create and Execute in One Call

The v2 API also supports creating an individual and executing a workflow in a single request:

**URL:**

```text theme={null}
POST https://api.{{frankie-environment}}.frankie.one/v2/individuals/new/serviceprofiles/{{serviceName}}/workflows/{{workflowName}}/execute
```

This endpoint accepts the full `individual` object in the request body and returns the combined response with `workflowResult`, `serviceProfile`, and `individual` data.

***

## Viewing Results in the Portal

### Why Use the Portal?

| Your API Client Shows    | Portal Shows                  |
| ------------------------ | ----------------------------- |
| API request and response | Visual representation         |
| Technical details        | Complete verification details |
| Raw data                 | Risk assessment with context  |
|                          | Timeline of events            |
|                          | Easy-to-understand format     |

**Use both together:** Send requests in Postman/Bruno, then view detailed results in the Portal.

### Accessing the Portal

Contact your FrankieOne representative for the correct portal URLs for your environments.

**Login:** Use credentials provided by FrankieOne (same account as API credentials).

### Finding Your Individual

**Method 1: Search by Name**

1. Click **"Entities"** in navigation
2. Enter customer name in search
3. Click on individual to view

**Method 2: Search by Entity ID**

1. Copy `entityId` from your API response
2. Paste into search bar
3. Click on individual

**Method 3: View Recent**

1. Click **"Entities"**
2. Sort by **"Most Recent"**
3. Your test individual should be at top

### Understanding the Portal View

| Section                 | What You'll See                                                |
| ----------------------- | -------------------------------------------------------------- |
| **Individual Overview** | Name, overall status, risk rating, created date                |
| **Verification Checks** | Workflow results, check statuses, timestamps                   |
| **Risk Assessment**     | Overall score, risk factors, contributing elements             |
| **Timeline**            | Chronological view of all events and status changes            |
| **Documents**           | Uploaded documents and verification results (if IDV performed) |

### Real-Time Updates

The Portal updates in real-time:

1. Send API request via Postman/Bruno
2. Refresh Portal (or wait for auto-refresh)
3. See new results immediately

***

## Common Testing Scenarios

### Scenario 1: Create Individual with Minimal Data

**Objective:** Test minimal required fields for v2 individual creation

**v2 Payload:**

```json theme={null}
{
  "individual": {
    "name": {
      "givenName": "PETER",
      "middleName": "C",
      "familyName": "TESTTHREE"
    },
    "dateOfBirth": {
      "year": "1952",
      "month": "01",
      "day": "01"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "country": "AUS"
      }
    ],
    "consents": [
      {
        "type": "GENERAL"
      }
    ]
  }
}
```

**Expected Result:**

* Status: `201 Created`
* Returns `entityId` within the `individual` object
* Individual created successfully
* Testbed result: CLEAR (PASS)

***

### Scenario 2: Create Individual with Document

**Objective:** Create individual with identity document for verification

**v2 Payload:**

```json theme={null}
{
  "individual": {
    "name": {
      "givenName": "MARY",
      "familyName": "TESTFOUR"
    },
    "dateOfBirth": {
      "year": "1953",
      "month": "01",
      "day": "01"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "streetNumber": "17",
        "streetName": "WATTLE",
        "streetType": "AVENUE",
        "locality": "WARWICK",
        "subdivision": "QLD",
        "postalCode": "4370",
        "country": "AUS"
      }
    ],
    "documents": {
      "IDENTITY": [
        {
          "type": "DRIVERS_LICENSE",
          "primaryIdentifier": "103188691",
          "secondaryIdentifier": "QUSQP650QB",
          "country": "AUS",
          "subdivision": "QLD"
        }
      ]
    },
    "consents": [
      {
        "type": "GENERAL"
      },
      {
        "type": "DOCS"
      }
    ]
  }
}
```

**Expected Result:**

* Individual created with document
* Ready for workflow execution
* Document details stored
* Testbed result: CLEAR (PASS)

***

### Scenario 3: Minor (Under 18)

**Objective:** Create individual under 18 years old

**v2 Payload:**

```json theme={null}
{
  "individual": {
    "name": {
      "givenName": "Oliver",
      "middleName": "J",
      "familyName": "Young"
    },
    "dateOfBirth": {
      "year": "2015",
      "month": "06",
      "day": "15"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "streetNumber": "35",
        "streetName": "Conn",
        "streetType": "Street",
        "locality": "Ferntree Gully",
        "subdivision": "VIC",
        "postalCode": "3156",
        "country": "AUS"
      }
    ],
    "consents": [
      {
        "type": "GENERAL"
      },
      {
        "type": "UNDER18"
      }
    ]
  }
}
```

**Key Points:**

* Must include `UNDER18` consent
* Age calculated from `dateOfBirth`
* May require guardian information (check with FrankieOne)

***

### Scenario 4: Individual with Custom Attributes

**Objective:** Store custom business data with individual

**v2 Payload:**

```json theme={null}
{
  "individual": {
    "name": {
      "givenName": "Sarah",
      "familyName": "Johnson"
    },
    "dateOfBirth": {
      "year": "1992",
      "month": "03",
      "day": "10"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "country": "AUS"
      }
    ],
    "customAttributes": {
      "customerSegment": {
        "type": "STRING",
        "value": "premium"
      },
      "accountType": {
        "type": "STRING",
        "value": "savings"
      },
      "vipStatus": {
        "type": "BOOLEAN",
        "value": "true"
      },
      "creditLimit": {
        "type": "INTEGER",
        "value": "50000"
      }
    },
    "consents": [
      {
        "type": "GENERAL"
      }
    ]
  }
}
```

**Use Cases:**

* Store business-specific data
* Track customer segments
* Store account types
* Custom workflow routing

***

### Scenario 5: International Individual (Non-Australian)

**Objective:** Create individual from another country

**v2 Payload:**

```json theme={null}
{
  "individual": {
    "name": {
      "givenName": "Emma",
      "familyName": "Williams"
    },
    "dateOfBirth": {
      "year": "1988",
      "month": "11",
      "day": "05"
    },
    "nationality": "GBR",
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "locality": "London",
        "postalCode": "SW1A 1AA",
        "country": "GBR"
      }
    ],
    "documents": {
      "IDENTITY": [
        {
          "type": "PASSPORT",
          "country": "GBR",
          "primaryIdentifier": "123456789",
          "issueDate": {
            "year": "2020",
            "month": "01",
            "day": "15"
          },
          "expiryDate": {
            "year": "2030",
            "month": "01",
            "day": "14"
          }
        }
      ]
    },
    "consents": [
      {
        "type": "GENERAL"
      }
    ]
  }
}
```

**Key Points:**

* Use correct ISO 3166-1 alpha-3 country codes (GBR, USA, CAN, etc.)
* Include `nationality` field
* Document types vary by country

***

## Understanding API Responses

### HTTP Status Codes

| Code                        | Meaning                         | Action                                   |
| --------------------------- | ------------------------------- | ---------------------------------------- |
| `200 OK`                    | Success                         | Process response data                    |
| `201 Created`               | Resource created                | Save the new resource ID (entityId)      |
| `202 Accepted`              | Async request accepted          | Use requestId to poll for results        |
| `400 Bad Request`           | Invalid request                 | Check request format and required fields |
| `401 Unauthorized`          | Authentication failed           | Verify API key and Customer ID           |
| `404 Not Found`             | Resource not found              | Verify entity ID exists                  |
| `422 Unprocessable Entity`  | Validation error                | Check field formats and required fields  |
| `500 Internal Server Error` | Server issue                    | Retry or contact support                 |
| `502 Bad Gateway`           | Gateway error                   | Retry or contact support                 |
| `503 Service Unavailable`   | Service temporarily unavailable | Retry after a short delay                |

### Common v2 Response Fields

**Success Response (Create Individual) — per OpenAPI spec:**

```json theme={null}
{
  "requestId": "01HM5XJ7VASZ3EJMB1VQGTBFJ4",
  "individual": {
    "entityId": "abc123-def456-ghi789",
    "schemaVersion": 2,
    "name": {
      "nameId": "...",
      "givenName": "John",
      "familyName": "Smith"
    },
    "dateOfBirth": {
      "dateOfBirthId": "...",
      "year": "1990",
      "month": "01",
      "day": "15"
    },
    "addresses": [...],
    "consents": [...]
  },
  "serviceProfiles": [...]
}
```

**Error Response — per OpenAPI spec:**

```json theme={null}
{
  "errorCode": "API-0400",
  "errorMsg": "Multiple Errors: See Issues list",
  "details": [
    {
      "issue": "entityId in path must be of type uuid: \"test\"",
      "issueLocation": "VALIDATE-entityId"
    }
  ],
  "requestId": "01HM5XJ7VASZ3EJMB1VQGTBFJ4"
}
```

**Authentication Error — per OpenAPI spec:**

```json theme={null}
{
  "errorCode": "AUTH-0002",
  "errorMsg": "Unauthorized",
  "details": [
    {
      "issue": "Invalid Authentication provided. Access denied.",
      "issueLocation": "request"
    }
  ],
  "requestId": "00000000S6MNG7624K2TDXT1E3"
}
```

### Common Validation Errors in v2

| Error                         | Cause                                | Solution                                      |
| ----------------------------- | ------------------------------------ | --------------------------------------------- |
| `Invalid date format`         | Using string instead of object       | Use `{year, month, day}` format               |
| `Unknown field: suburb`       | Using v1 field names                 | Use v2 field names (`locality`, not `suburb`) |
| `documents must be an object` | Using array instead of nested object | Use `documents.IDENTITY: [...]` structure     |
| `Invalid field value`         | Incorrect data type or format        | Check OpenAPI spec for field requirements     |

***

## Best Practices

### 1. schemaVersion is Optional in Requests

`schemaVersion` is marked as `readOnly` in the OpenAPI specification. It is primarily a response field returned by the API. You **do not need** to include it in your request payloads.

```json theme={null}
{
  "individual": {
    "name": {...},
    "dateOfBirth": {...}
  }
}
```

### 2. Use Correct v2 Field Names

**v2 Uses:**

* `locality` (not `suburb`)
* `subdivision` (not `state`)
* `postalCode` (not `postcode`)
* `primaryIdentifier` (not `idNumber`)

### 3. Use Date Objects, Not Strings

**Correct v2 Format:**

```json theme={null}
{
  "dateOfBirth": {
    "year": "1990",
    "month": "01",
    "day": "15"
  }
}
```

**Incorrect (v1 format):**

```json theme={null}
{
  "dateOfBirth": "1990-01-15"
}
```

### 4. Structure Documents Correctly

**Correct v2 Format:**

```json theme={null}
{
  "documents": {
    "IDENTITY": [
      {
        "type": "PASSPORT",
        ...
      }
    ]
  }
}
```

**Incorrect:**

```json theme={null}
{
  "document": {
    "type": "PASSPORT",
    ...
  }
}
```

### 5. Use Environment Variables

**Why:**

* Easy to switch between UAT and Production
* Keep credentials secure
* Reuse across requests
* Save entityId automatically

### 6. Use Testbed Data Only

* **Never** use real customer data in testing
* Testbed data provides predictable results
* Safe and compliant
* Repeatable tests

### 7. Check Both API Response and Portal

Complete testing workflow:

1. Send request in Postman/Bruno
2. Check API response
3. View in Portal
4. Verify both match
5. Understand complete picture

### 8. Version Control (Bruno)

Since Bruno stores collections as files:

```bash theme={null}
cd "FrankieOne KYC V2 AUS"
git init
git add .
git commit -m "Initial FrankieOne v2 API collection"
```

<Warning>
  Add your environment files to `.gitignore` to avoid committing credentials:

  ```
  # .gitignore
  environments/*.bru
  ```
</Warning>

### 9. Test Edge Cases

Don't just test the happy path:

* Missing optional fields
* Invalid data formats
* Different countries
* Various document types
* Minors vs adults
* Multiple addresses

***

## Troubleshooting

### Authentication Error (401)

**Problem:** `Unauthorized` or `Invalid API key`

**Solutions:**

| Check             | Action                                                                                                              |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- |
| API key           | Verify it's correct and not expired                                                                                 |
| Customer ID       | Confirm `X-Frankie-CustomerID` matches your account                                                                 |
| Customer Child ID | If you have sub-accounts, verify `X-Frankie-CustomerChildID` is correct                                             |
| Environment       | Ensure correct environment is selected and `frankie-environment` variable is set (e.g., `uat`)                      |
| Headers           | Verify `api_key` and `X-Frankie-CustomerID` headers are present and enabled                                         |
| Header names      | Use exact header names as specified: `api_key`, `X-Frankie-CustomerID`, `X-Frankie-CustomerChildID`                 |
| Base URL          | Ensure you're using `https://api.{{frankie-environment}}.frankie.one` (not the legacy `frankiefinancial.io` domain) |

<Note>
  **Common Authentication Issues with CustomerChildID:**

  * Using CustomerChildID when you don't have sub-accounts configured
  * Using wrong CustomerChildID value
  * Omitting CustomerChildID when you have sub-accounts
  * Typos in header name (must be exactly `X-Frankie-CustomerChildID`)
</Note>

***

### Date Format Error

**Problem:** `Invalid date format` or date validation errors

**Solutions:**

| Check         | Action                                                 |
| ------------- | ------------------------------------------------------ |
| Use objects   | Dates must be objects: `{year, month, day}`            |
| Not strings   | Don't use `"1990-01-15"` (that's v1 format)            |
| String values | Year, month, day are strings: `"1990"`, not `1990`     |
| Padding       | Month and day should be zero-padded: `"01"`, not `"1"` |

**Correct:**

```json theme={null}
{
  "dateOfBirth": {
    "year": "1990",
    "month": "01",
    "day": "15"
  }
}
```

***

### Field Name Error

**Problem:** `Unknown field` or field not recognized

**Solutions:**

| v1 Field (Wrong) | v2 Field (Correct)       |
| ---------------- | ------------------------ |
| `suburb`         | `locality`               |
| `state`          | `subdivision`            |
| `postcode`       | `postalCode`             |
| `document`       | `documents`              |
| `idNumber`       | `primaryIdentifier`      |
| `region`         | `subdivision`            |
| `emailAddress`   | `emailAddresses` (array) |
| `phoneNumber`    | `phoneNumbers` (array)   |

***

### Document Structure Error

**Problem:** `Invalid document structure` or validation errors

**Solutions:**

**Correct v2 Structure:**

```json theme={null}
{
  "documents": {
    "IDENTITY": [
      {
        "type": "DRIVERS_LICENSE",
        "primaryIdentifier": "12345678",
        "country": "AUS",
        "subdivision": "NSW"
      }
    ]
  }
}
```

**Common Mistakes:**

* Using `document` instead of `documents`
* Not nesting under category (`IDENTITY`)
* Using array instead of object for `documents`
* Using `idNumber` instead of `primaryIdentifier`

***

### Entity Not Found (404)

**Problem:** `Entity not found`

**Solutions:**

| Check           | Action                                                                   |
| --------------- | ------------------------------------------------------------------------ |
| Entity ID       | Verify it's correct (copy/paste carefully)                               |
| Environment     | Confirm you're using the same environment where entity was created       |
| Entity creation | Check that the create request succeeded                                  |
| URL format      | Ensure URL uses `/v2/individuals/{entityId}` with no extra path segments |

***

### No Results in Portal

**Problem:** Can't find individual in Portal

**Solutions:**

| Check       | Action                                                                       |
| ----------- | ---------------------------------------------------------------------------- |
| Environment | Verify you're logged into the correct Portal environment (UAT vs Production) |
| Customer ID | Confirm it matches your API credentials                                      |
| Search      | Try searching by entity ID instead of name                                   |
| Timing      | Wait a few seconds and refresh                                               |
| Filters     | Check if any filters are applied in Portal                                   |

***

### Bruno-Specific Issues

**Collection Not Loading:**

* Ensure the folder contains a valid `bruno.json` file
* Check file permissions on the collection folder
* Verify you're opening the correct folder

**Import Issues:**

* Bruno supports Postman Collection v2.1 format
* If import fails, try exporting from Postman as Collection v2.1
* Check for special characters in collection name

**Environment Variables Not Working:**

* Ensure environment is activated (check dropdown)
* Verify variable syntax: `{{variableName}}`
* Check for typos in variable names

***

### Getting Help

**FrankieOne Support:**

* Contact your FrankieOne representative
* Email: [help@frankieone.com](mailto:help@frankieone.com)
* Include: Entity ID, requestId, full request/response, error messages, screenshots

**Documentation:**

* v2 API Documentation: [https://docs.frankieone.com](https://docs.frankieone.com)
* OpenAPI Specification: Request from FrankieOne
* Testbed Data Guide: [https://docs.frankieone.com/docs/test-data](https://docs.frankieone.com/docs/test-data)

***

## Next Steps

### After Testing v2 APIs

1. **Understand the v2 APIs**
   * Review all v2 endpoints
   * Test various scenarios
   * Document requirements
2. **Plan Your Integration**
   * Determine which v2 APIs you need
   * Design workflow
   * Plan error handling
   * Consider migration from v1 if applicable
3. **Review Documentation**
   * v2 API reference
   * Integration guides
   * Security guidelines
   * Best practices
4. **Start Development**
   * Use your test collection as reference
   * Implement in your application
   * Follow v2 payload structure
   * Handle v2 responses correctly
5. **Move to Production**
   * Complete UAT testing
   * Get production credentials
   * Update `frankie-environment` variable (remove `uat` segment — production URL is `https://api.frankie.one`)
   * Deploy

***

## FAQs

### General

<AccordionGroup>
  <Accordion title="Should I use v1 or v2?">
    **Use v2** for all new integrations. v2 is the current recommended version with:

    * Better structure for complex scenarios
    * Active development and support
    * Clearer entity type separation
    * More explicit field names

    v1 is maintained for backward compatibility only.
  </Accordion>

  <Accordion title="Can I mix v1 and v2?">
    No. Choose one API version and use it consistently throughout your integration.
  </Accordion>

  <Accordion title="Do I need to pay for Postman or Bruno?">
    Bruno is completely free and open-source. Postman has a free tier that's sufficient for testing FrankieOne v2 APIs.
  </Accordion>

  <Accordion title="Can I use real customer data for testing?">
    **No.** Always use testbed data. Never use real customer data in testing environments.
  </Accordion>
</AccordionGroup>

### v2 Specific

<AccordionGroup>
  <Accordion title="What's different in v2 compared to v1?">
    Key differences:

    * **Base URL:** `https://api.{env}.frankie.one` (not `frankiefinancial.io`)
    * **Path:** Endpoints start at `/v2/` directly (no `compliance/v1.2` prefix)
    * **Date format:** Objects `{year, month, day}` instead of strings `"YYYY-MM-DD"`
    * **Field names:** `locality`, `subdivision`, `postalCode` (not `suburb`, `state`, `postcode`)
    * **Documents:** Nested by category `documents.IDENTITY[]`
    * **Entity type:** Implied by endpoint (`/individuals` vs `/organizations`)
    * **Schema version:** `readOnly` response field — not required in requests
    * **Email/Phone:** Arrays instead of single values
    * **Response structure:** Data nested under `individual` object with `requestId` at top level
  </Accordion>

  <Accordion title="Is schemaVersion required?">
    **No.** `schemaVersion` is marked as `readOnly` in the OpenAPI specification. It is a response field returned by the API and is **not required** in request payloads.
  </Accordion>

  <Accordion title="Why do dates use objects instead of strings?">
    v2's object format provides:

    * More explicit structure
    * Better validation
    * Clearer parsing
    * Support for partial dates
  </Accordion>

  <Accordion title="Can I include multiple documents?">
    Yes. v2 supports multiple documents per category:

    ```json theme={null}
    {
      "documents": {
        "IDENTITY": [
          {"type": "PASSPORT", ...},
          {"type": "DRIVERS_LICENSE", ...}
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="What are the valid consent types?">
    The OpenAPI specification defines the following consent types:

    * `GENERAL` — General consent for verification
    * `DOCS` — Consent for document verification
    * `CREDITHEADER` — Consent for credit header checks
    * `UNDER18` — Consent for minors under 18
    * `PAYROLL` — Consent for payroll verification
    * `INSURANCE` — Consent for insurance verification
    * `SUPERANNUATION` — Consent for superannuation verification
  </Accordion>
</AccordionGroup>

### Tool-Specific

<AccordionGroup>
  <Accordion title="Can I share my collection with my team?">
    * **Postman:** Export and share, or use Postman team workspaces
    * **Bruno:** Share via Git repository (add environment files to `.gitignore`)
  </Accordion>

  <Accordion title="Can I switch from Postman to Bruno?">
    Yes. Bruno can import Postman collections directly (v2.1 format).
  </Accordion>

  <Accordion title="Which tool is better for CI/CD?">
    Both support automation:

    * **Postman:** Newman CLI for running collections
    * **Bruno:** Bruno CLI (`bru run`) for running collections
  </Accordion>

  <Accordion title="How do I auto-save entityId?">
    The FrankieOne Postman collection includes pre-built test scripts that automatically save `entityId` and other variables after entity creation. If creating your own requests:

    **Postman:**

    ```javascript theme={null}
    var jsonData = JSON.parse(responseBody);
    pm.environment.set("entityId", jsonData.individual.entityId);
    ```

    **Bruno:**

    ```javascript theme={null}
    const response = res.getBody();
    bru.setEnvVar("entityId", response.individual.entityId);
    ```

    Note: The entity ID is accessed at `individual.entityId` (nested under the `individual` object), not at the top level.
  </Accordion>
</AccordionGroup>

### FrankieOne-Specific

<AccordionGroup>
  <Accordion title="What's the difference between UAT and Production?">
    * **UAT:** Testing environment (`https://api.uat.frankie.one`) with testbed data, safe for experimentation
    * **Production:** Live environment (`https://api.frankie.one`) with real customers, use only after thorough testing

    Always test in UAT first.
  </Accordion>

  <Accordion title="What is Customer Child ID and do I need it?">
    **Customer Child ID** (`X-Frankie-CustomerChildID`) is for sub-account isolation within your main account.

    **You need it if:**

    * You have multiple brands or business units
    * You're a reseller with multiple clients
    * FrankieOne has configured sub-accounts for you

    **You don't need it if:**

    * You have a single, unified account
    * FrankieOne hasn't mentioned sub-accounts to you

    **How to know:** Contact your FrankieOne representative to confirm if you have CustomerChildID configured.

    **If you have it:** Include the header in all requests:

    ```
    X-Frankie-CustomerChildID: {{X-Frankie-CustomerChildID}}
    ```

    **If you don't:** Omit the header or leave the variable blank. In the Postman collection, this header is disabled by default.
  </Accordion>

  <Accordion title="How long do test entities stay in UAT?">
    Check with FrankieOne for specific retention policies. Generally, test data may be periodically cleaned.
  </Accordion>

  <Accordion title="What workflows are available?">
    Workflows are **configured by FrankieOne** based on your requirements. Contact your representative to:

    * See available workflows
    * Understand what each workflow does
    * Request custom workflows

    You can also retrieve available workflows via `GET /v2/workflows` (with optional `serviceName` query parameter).
  </Accordion>

  <Accordion title="Can I configure workflows via API?">
    **No.** Workflows are configured by FrankieOne. You can only **execute** workflows and **retrieve** workflow information via API.
  </Accordion>

  <Accordion title="What additional headers are available?">
    Beyond the required `api_key` and `X-Frankie-CustomerID`, the v2 API supports these optional headers:

    * `X-Frankie-CustomerChildID` — Sub-account isolation
    * `X-Frankie-Channel` — Channel identifier (e.g., `api`, `portal`, `smartui`). Can be used in routing and risk calculations.
    * `X-Frankie-Username` — Username of the API caller
    * `X-Frankie-Background` — Set to `1` for asynchronous processing (returns `202` instead of waiting)
  </Accordion>
</AccordionGroup>

***

## Summary

### Key Takeaways

| Principle                       | Details                                                                                              |
| ------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Use v2 for new integrations** | Current recommended version with better structure                                                    |
| **Use correct v2 format**       | Objects for dates, correct field names                                                               |
| **Use correct base URL**        | `https://api.{env}.frankie.one/v2/...` (no legacy `frankiefinancial.io` or `compliance/v1.2` prefix) |
| **Choose your tool**            | Postman for cloud sync; Bruno for Git integration                                                    |
| **Use testbed data**            | Pre-configured scenarios with predictable results                                                    |
| **Check both views**            | API response + Portal for complete understanding                                                     |
| **Test thoroughly**             | Various scenarios including edge cases                                                               |

### v2 Quick Reference

**Minimal v2 Individual:**

```json theme={null}
{
  "individual": {
    "name": {
      "givenName": "John",
      "familyName": "Smith"
    },
    "dateOfBirth": {
      "year": "1990",
      "month": "01",
      "day": "15"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "country": "AUS"
      }
    ],
    "consents": [
      {
        "type": "GENERAL"
      }
    ]
  }
}
```

### Getting Started Checklist

<Steps>
  <Step title="Install your tool">
    Install Postman or Bruno
  </Step>

  <Step title="Get the v2 collection">
    Download FrankieOne v2 API collection
  </Step>

  <Step title="Import">
    Import collection into your tool
  </Step>

  <Step title="Get credentials">
    Get API credentials from FrankieOne (UAT)
  </Step>

  <Step title="Configure environment">
    Set up environment variables (matching Postman environment)
  </Step>

  <Step title="Review v2 structure">
    Understand v2 payload format
  </Step>

  <Step title="First v2 API call">
    Create your first individual (v2)
  </Step>

  <Step title="Save entityId">
    Auto-save or manually save entity ID (from `individual.entityId`)
  </Step>

  <Step title="View in Portal">
    View results in Portal
  </Step>

  <Step title="Execute workflow">
    Test workflow execution
  </Step>

  <Step title="Test scenarios">
    Test different v2 scenarios
  </Step>

  <Step title="Document findings">
    Document your findings and questions
  </Step>

  <Step title="Plan integration">
    Plan your v2 API integration
  </Step>
</Steps>

***

## Additional Resources

### FrankieOne

| Resource             | URL                                                                                      |
| -------------------- | ---------------------------------------------------------------------------------------- |
| Website              | [https://frankieone.com](https://frankieone.com)                                         |
| v2 API Documentation | [https://docs.frankieone.com](https://docs.frankieone.com)                               |
| Testbed Data         | [https://docs.frankieone.com/docs/test-data](https://docs.frankieone.com/docs/test-data) |
| Support              | [help@frankieone.com](mailto:help@frankieone.com)                                        |

### Postman

| Resource        | URL                                                                    |
| --------------- | ---------------------------------------------------------------------- |
| Download        | [https://www.postman.com/downloads](https://www.postman.com/downloads) |
| Learning Center | [https://learning.postman.com](https://learning.postman.com)           |
| Documentation   | [https://learning.postman.com/docs](https://learning.postman.com/docs) |

### Bruno

| Resource      | URL                                                                      |
| ------------- | ------------------------------------------------------------------------ |
| Download      | [https://www.usebruno.com/downloads](https://www.usebruno.com/downloads) |
| Documentation | [https://docs.usebruno.com](https://docs.usebruno.com)                   |
| GitHub        | [https://github.com/usebruno/bruno](https://github.com/usebruno/bruno)   |

***

**Document Version:** 4.0 (v2 Corrected)\
**Last Updated:** February 2026\
**API Version:** v2\
**Audience:** Developers and technical teams evaluating or integrating FrankieOne v2 APIs


# API Versioning
Source: https://docs.frankieone.com/v2/api/introduction/api-versioning

How FrankieOne versions APIs and maintains backwards compatibility

## Specifying the Version

Include the version in the API path:

```text theme={null}
https://api.frankie.one/v2/individuals
```

<Note>
  Patch versions are applied automatically—you only specify the major version in requests.
</Note>

## Current Versions

| API                     | Version | Status     |
| ----------------------- | ------- | ---------- |
| KYC API (Individuals)   | v2      | Active     |
| KYB API (Organizations) | v2.1    | Active     |
| Legacy API              | v1      | Deprecated |

<Warning>
  v1 endpoints are legacy and should not be used for new integrations.
</Warning>

## Semantic Versioning

We use **Semantic Versioning** to label releases:

```text theme={null}
MAJOR.MINOR.PATCH
```

| Type      | When It Changes                     | Impact                   |
| --------- | ----------------------------------- | ------------------------ |
| **MAJOR** | Breaking changes                    | May require code updates |
| **MINOR** | New features (backwards-compatible) | No changes required      |
| **PATCH** | Bug fixes                           | No changes required      |

## Example: v1 vs v2

<Tabs>
  <Tab title="v1 (Legacy)">
    **Endpoint:**

    ```text theme={null}
    POST /v1/entity
    ```

    **Headers:**

    ```text theme={null}
    Authorization: Bearer YOUR_API_KEY
    ```

    **Request:**

    ```json theme={null}
    {
      "entity": {
        "entityType": "INDIVIDUAL",
        "givenName": "John",
        "familyName": "Doe",
        "dateOfBirth": "1990-03-27",
        "streetNumber": "525",
        "streetName": "Kent",
        "city": "Manhattan",
        "country": "USA"
      }
    }
    ```
  </Tab>

  <Tab title="v2 (Current)">
    **Endpoint:**

    ```text theme={null}
    POST /v2/individuals
    ```

    **Headers:**

    ```text theme={null}
    api_key: YOUR_API_KEY
    X-Frankie-CustomerID: YOUR_CUSTOMER_ID
    ```

    **Request:**

    ```json theme={null}
    {
      "individual": {
        "name": {
          "givenName": "John",
          "familyName": "Doe"
        },
        "dateOfBirth": {
          "year": "1990",
          "month": "03",
          "day": "27"
        },
        "addresses": [
          {
            "type": "RESIDENTIAL",
            "status": "CURRENT",
            "streetNumber": "525",
            "streetName": "Kent",
            "locality": "Manhattan",
            "subdivision": "NY",
            "country": "USA",
            "postalCode": "10037"
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

### Key Differences

| Change        | v1                               | v2                                                    |
| ------------- | -------------------------------- | ----------------------------------------------------- |
| Endpoint      | `/v1/entity`                     | `/v2/individuals`                                     |
| Auth header   | `Authorization: Bearer`          | `api_key` + `X-Frankie-CustomerID`                    |
| Root object   | `entity`                         | `individual`                                          |
| Name fields   | Flat (`givenName`, `familyName`) | Nested `name` object                                  |
| Date of birth | String `"1990-03-27"`            | Object with `year`, `month`, `day`                    |
| Address       | Flat fields                      | Structured `addresses` array with `type` and `status` |

## Backwards Compatibility

Within a major version, we guarantee:

* Existing endpoints continue to work
* Response fields won't be removed
* Required request fields won't be added

We may add:

* New optional request fields
* New response fields
* New endpoints

<Tip>
  Build your integration to ignore unknown fields in responses.
</Tip>

## Deprecation Policy

When we deprecate a version:

1. **Announcement** — Minimum 6 months notice
2. **Migration period** — Both versions run in parallel
3. **Sunset** — Old version retired

Deprecated endpoints return a `Deprecation` header:

```text theme={null}
Deprecation: true
Sunset: Sat, 01 Jan 2028 00:00:00 GMT
```

## Base URLs

| Environment | URL                           |
| ----------- | ----------------------------- |
| UAT         | `https://api.uat.frankie.one` |
| Production  | `https://api.frankie.one`     |

## Staying Informed

<CardGroup>
  <Card title="Release Notes" icon="list" href="/docs/releasenotes">
    View product changes
  </Card>

  <Card title="Status Page" icon="signal" href="https://status.frankieone.com">
    Subscribe to updates
  </Card>
</CardGroup>


# Introduction to FrankieOne API
Source: https://docs.frankieone.com/v2/api/introduction/introduction-to-frankie-one-api

Understand FrankieOne's core platform concepts, API architecture, and key resources to get started with your integration.

This page covers the core concepts that power the FrankieOne platform and the fundamentals of working with the API. Understanding these building blocks is the first step toward a successful integration.

## Platform Building Blocks

These are the fundamental concepts that power the FrankieOne platform.

### Entity

An **Entity** is the central object in the FrankieOne platform, representing a single customer you want to verify. All information, checks, and results are linked to an entity.

* An **Individual** is an entity type representing a single person.
* An **Organization** is an entity type representing a business or other non-individual entity.

### Workflow

A **Workflow** is a configurable, end-to-end process that runs a sequence of steps to verify an entity. You can design workflows to meet your specific risk and compliance requirements. A workflow is composed of steps such as KYC verifications, AML screening, IDV checks, and risk assessments.

###### Service Profile

A **Service Profile** provides an overview of an entity’s verification progress and risk status in the context of a specific product or service you offer. A single entity can have multiple service profiles, allowing you to apply different rules and risk policies for different products (e.g., a credit card vs. a home loan).

### Process Result

A **Process Result** is the raw, granular data returned from a single check against a third-party data source (e.g., a match for a name from a government database). A workflow step evaluates one or more process results to determine its outcome.

### Risk Assessment

FrankieOne uses granular **Risk** metrics to calculate a customer’s risk profile. During a workflow, an entity is scored against configurable risk factors (e.g., age, location, PEP status). The cumulative score determines the entity’s overall risk level, which can trigger different actions like Enhanced Due Diligence (EDD).

### Issue

An **Issue** is a problem raised during a workflow that requires manual review or intervention. Issues are created for significant events, such as a failed KYC check or a match on a sanctions watchlist, and provide clear guidance on the next steps.

### How The Concepts Connect

A typical verification process follows this logical flow:

1. You create an **Entity** representing your customer.
2. You assign a **Service Profile** to the Entity for the product they are accessing.
3. You trigger a **Workflow** to begin verification.
4. The Workflow runs checks, generating **Process Results** from data sources.
5. A **Risk Assessment** is performed based on the results.
6. If problems occur, an **Issue** is created for review.

***

## Technical Architecture

The FrankieOne API is built using the **REST (Representational State Transfer)** architectural style. This provides a simple, predictable, and scalable interface for interacting with all platform resources.

By adopting REST, FrankieOne ensures that its API is flexible and easy to learn. All communication is performed over secure HTTPS using standard HTTP methods (like `GET`, `POST`, `PATCH`) and clear, resource-oriented URLs. This unified approach allows you to interact with different parts of the platform in a consistent way, supporting robust automation and integration with your systems.

***

## Key Resources

<CardGroup>
  <Card title="KYC Swagger / OpenAPI definition" icon="file-code" href="https://drive.google.com/file/d/1gfo3MYKhCdPy2bffAoIyyX16U-VwZNHW/view?usp=drive_link">
    Download our latest Swagger / OpenAPI for KYC definition **here**.
  </Card>

  <Card title="KYB Swagger / OpenAPI definition" icon="file-code" href="https://raw.githubusercontent.com/frankieone/openapi/refs/heads/main/specs/frankieOneKYBV2.json">
    Download our latest Swagger / OpenAPI for KYB definition **here**.
  </Card>

  <Card title="Core Swagger / OpenAPI definition" icon="file-code" href="https://drive.google.com/file/d/12rfM85jHeRCWTBBhJIVEfb4uiCtKAmUP/view?usp=drive_link">
    Download our latest Swagger / OpenAPI for Core API definition **here**.
  </Card>

  <Card title="Postman Collection" icon="book" href="https://drive.google.com/file/d/103az4gnrGJhXTYlYaoIr7WWQ521RUBfN/view?usp=drive_link">
    Download our latest Postman collection **here**.
  </Card>

  <Card title="Transaction and Activity Monitoring Swagger / OpenAPI definition" icon="file-code" href="https://raw.githubusercontent.com/frankieone/openapi/refs/heads/main/specs/frankieOneTxAMV2.json">
    Download our latest Swagger / OpenAPI for Transaction and Activity Monitoring definition **here**
  </Card>
</CardGroup>


# Classify activities
Source: https://docs.frankieone.com/api-reference/activities/classify-activities

/specs/fc-act-bundled_generated.yaml post /v2/activities/classify
Classify one or more activities by applying tags and optionally sending feedback to the
originating provider.

Tags are applied to every activity specified in `activityIds`. All tag and activity validations are
atomic — if any ID is invalid or inaccessible, the entire request fails with no partial application.

**Tag constraints:**
- Tags must have domain `ACTIVITY`; any other domain results in error.
- Tags must not mix `FALSE_POSITIVE` category with other categories.
- Tags are re-applied if the activity was previously classified (idempotent update).




# Evaluate an activity
Source: https://docs.frankieone.com/api-reference/activities/evaluate-an-activity

/specs/fc-act-bundled_generated.yaml post /v2/activities
Evaluate an activity. This may be verification of a financial transaction such as a
deposit, withdrawal, etc or evaluating a platform level login or registration activities for example.

An entity must exist in the frankie system to tie the activity to.

This will return the immediate result of the activity, and then asynchronously the
activity will be processed in the FrankieOne platform.




# Get Individual Activities
Source: https://docs.frankieone.com/api-reference/activities/get-individual-activities

/specs/fc-act-bundled_generated.yaml get /v2/individuals/{entityId}/activities
Get a list of activities for an individual.



# Get Organization Activities
Source: https://docs.frankieone.com/api-reference/activities/get-organization-activities

/specs/fc-act-bundled_generated.yaml get /v2/organizations/{entityId}/activities
Get a list of activities for an organization.



# List audit events
Source: https://docs.frankieone.com/api-reference/audit/list-audit-events

/specs/fc-core-bundled_generated.yaml get /v2/audit
List all audit events with filtering.

Note that entityId and caseId is mutually exclusive and filtering for both at once will never return any results.




# Add a comment to an object
Source: https://docs.frankieone.com/api-reference/comments/add-a-comment-to-an-object

/specs/fc-core-bundled_generated.yaml post /v2/comments
Adds a comment to a specific entity or object, which is recorded in the audit log.
Please note that only adding comments to an entity is supported at this time so entityId and entityType are required.

Once created, comments are immutable and cannot be updated or deleted.




# Generate Hosted URL
Source: https://docs.frankieone.com/api-reference/hosted-url/generate-hosted-url

/specs/fc-kyb-facade-bundled_generated.yaml post /v2/organizations/hostedUrl
Generate a hosted URL for onboarding new organization.




# Provide hosted url for a hosted version of onesdk.
Source: https://docs.frankieone.com/api-reference/hostedurl/provide-hosted-url-for-a-hosted-version-of-onesdk

/specs/fc-kyc-bundled_generated.yaml post /v2/individuals/hostedurl
Hosted OneSDK URL Generation, used to request a hosted OneSDK URL with entity specific token for a customer to use a hosted OneSDK session to do an action. Examples of actions that may be done is to complete their onboarding process or to re-attempt IDV checks.  If sendSMS is true and a phone number is supplied, an SMS will be sent to the phone number with the generated URL.



# At the end of the IDV data capture process with all photos and videos captured, signal to IDV provider that check is ready to analyse and check.
Source: https://docs.frankieone.com/api-reference/idv/at-the-end-of-the-idv-data-capture-process-with-all-photos-and-videos-captured-signal-to-idv-provider-that-check-is-ready-to-analyse-and-check

/specs/fc-kyc-bundled_generated.yaml post /v2/individuals/{entityId}/actions/idv/process
At the end of the IDV data capture process with all photos and videos captured, signal to IDV provider
    that check is ready to analyse and check. If this call is successful, an entity
is populated with with any details supplied if it doesn't not already have a name.



# At the end of the IDV data capture process with all photos and videos captured, signal to IDV provider that check is ready to analyse and check.
Source: https://docs.frankieone.com/api-reference/idv/at-the-end-of-the-idv-data-capture-process-with-all-photos-and-videos-captured-signal-to-idv-provider-that-check-is-ready-to-analyse-and-check-1

/specs/fc-kyc-bundled_generated.yaml post /v2/individuals/{entityId}/actions/idv/checkstatus
At the end of the IDV data capture process with all photos and videos captured, signal to IDV provider
    that check is ready to analyse and check. If this call is successful, an entity
is populated with with any details supplied if it doesn't not already have a name.



# Get an IDV Token for the given individual.
Source: https://docs.frankieone.com/api-reference/idv/get-an-idv-token-for-the-given-individual

/specs/fc-kyc-bundled_generated.yaml post /v2/individuals/{entityId}/actions/idv/token
Queries the IDV provider for a token to be used with their sdk. This allows a provider SDK to be instantiated, this is to be called before starting the IDV or OCR process.



# Submit an identity document photo for ocr processing. Results will be in the form of an identity document with populated with ocr results.
Source: https://docs.frankieone.com/api-reference/idv/submit-an-identity-document-photo-for-ocr-processing-results-will-be-in-the-form-of-an-identity-document-with-populated-with-ocr-results

/specs/fc-kyc-bundled_generated.yaml post /v2/individuals/{entityId}/actions/idv/ocr
Submit an identity document photo for ocr processing. Results will be in the form of an identity document with populated with ocr results if successful. Status will be COMPLETE_OCR if OCR was successful and no further images are required. The image can be uploaded or captured via a vendor SDK after calling get IDV token, or can be submitted directly as a fileData.



# Create a new document for an individual.
Source: https://docs.frankieone.com/api-reference/individual-documents/create-a-new-document-for-an-individual

/specs/fc-kyc-bundled_generated.yaml post /v2/individuals/{entityId}/documents
Add a new document to an entity.



# Delete a document
Source: https://docs.frankieone.com/api-reference/individual-documents/delete-a-document

/specs/fc-kyc-bundled_generated.yaml delete /v2/individuals/{entityId}/documents/{documentId}
Delete a single document and all of it's attachments.



# Delete an attachment
Source: https://docs.frankieone.com/api-reference/individual-documents/delete-an-attachment

/specs/fc-kyc-bundled_generated.yaml delete /v2/individuals/{entityId}/documents/{documentId}/attachments/{attachmentId}
Delete an attachment from a given document.



# Get a single document by its id.
Source: https://docs.frankieone.com/api-reference/individual-documents/get-a-single-document-by-its-id

/specs/fc-kyc-bundled_generated.yaml get /v2/individuals/{entityId}/documents/{documentId}
Get a single document by its id.



# Get all documents for an entity
Source: https://docs.frankieone.com/api-reference/individual-documents/get-all-documents-for-an-entity

/specs/fc-kyc-bundled_generated.yaml get /v2/individuals/{entityId}/documents
Get all documents for an entity.



# Update a single document by its id.
Source: https://docs.frankieone.com/api-reference/individual-documents/update-a-single-document-by-its-id

/specs/fc-kyc-bundled_generated.yaml patch /v2/individuals/{entityId}/documents/{documentId}
Update document by id.



# Delete a date of birth
Source: https://docs.frankieone.com/api-reference/individual-entity-elements/delete-a-date-of-birth

/specs/fc-kyc-bundled_generated.yaml delete /v2/individuals/{entityId}/datesOfBirth/{dateOfBirthId}
Delete an individual's date of birth with the given id.



# Delete a name
Source: https://docs.frankieone.com/api-reference/individual-entity-elements/delete-a-name

/specs/fc-kyc-bundled_generated.yaml delete /v2/individuals/{entityId}/names/{nameId}
Delete an individual's name or alternateName with the given id.



# Delete an address
Source: https://docs.frankieone.com/api-reference/individual-entity-elements/delete-an-address

/specs/fc-kyc-bundled_generated.yaml delete /v2/individuals/{entityId}/addresses/{addressId}
Delete an individual's address with the given Id.



# Delete an email address
Source: https://docs.frankieone.com/api-reference/individual-entity-elements/delete-an-email-address

/specs/fc-kyc-bundled_generated.yaml delete /v2/individuals/{entityId}/emailaddresses/{emailAddressId}
Delete an individual's email address with the given id.



# Delete an external reference
Source: https://docs.frankieone.com/api-reference/individual-entity-elements/delete-an-external-reference

/specs/fc-kyc-bundled_generated.yaml delete /v2/individuals/{entityId}/externalreferences/{referenceId}
Delete an individual's external reference with the given id.



# Delete phone number
Source: https://docs.frankieone.com/api-reference/individual-entity-elements/delete-phone-number

/specs/fc-kyc-bundled_generated.yaml delete /v2/individuals/{entityId}/phonenumbers/{phoneNumberId}
Delete an individual's phone number with the given id.



# Get a list of external references
Source: https://docs.frankieone.com/api-reference/individual-entity-elements/get-a-list-of-external-references

/specs/fc-kyc-bundled_generated.yaml get /v2/individuals/{entityId}/externalreferences
Get a list of an individual's external references.



# Withdraw a previously provided consent
Source: https://docs.frankieone.com/api-reference/individual-entity-elements/withdraw-a-previously-provided-consent

/specs/fc-kyc-bundled_generated.yaml delete /v2/individuals/{entityId}/consents/{consentType}
Withdraw an individual's consent of a specific type.



# Get a service profile for a given individual entity.
Source: https://docs.frankieone.com/api-reference/individual-profiles/get-a-service-profile-for-a-given-individual-entity

/specs/fc-kyc-bundled_generated.yaml get /v2/individuals/{entityId}/serviceprofiles/{serviceName}
Get a profile for a given individual entity.



# Update a profile for a given individual entity.
Source: https://docs.frankieone.com/api-reference/individual-profiles/update-a-profile-for-a-given-individual-entity

/specs/fc-kyc-bundled_generated.yaml patch /v2/individuals/{entityId}/serviceprofiles/{serviceName}
Update a profile for a given individual entity.



# Approve Manual KYC for an individual
Source: https://docs.frankieone.com/api-reference/individual-results/approve-manual-kyc-for-an-individual

/specs/fc-kyc-bundled_generated.yaml post /v2/individuals/{entityId}/results/mkyc
Approve manual KYC (mKYC) for an individual as to allow them to pass all KYC workflow steps without performing eKYC. To ensure there is enough evidence for the mKYC process to be valid, the individual will need to have documents that match at least one of the following combinations:

1 Primary Photographic ID e.g. 
  - "DRIVERS_LICENSE": Driver's license.
  - "PASSPORT": Passport

2 Primary Non-Photographic IDs e.g.
  - "BIRTH_CERT": Birth certificate
  - "CITIZENSHIP": Citizenship certificate

1 Primary Non-Photographic ID AND 1 Secondary ID e.g.
  - "VISA": Visa document (not Visa payment card)
  - "IMMIGRATION": Immigration card
  - "NATIONAL_HEALTH_ID": Any national health program ID card (e.g. Medicare, NHS)
  - "NAME_CHANGE": Name change confirmation
  - "MARRIAGE_CERT": Marriage certificate




# Get a list of process results
Source: https://docs.frankieone.com/api-reference/individual-results/get-a-list-of-process-results

/specs/fc-kyc-bundled_generated.yaml get /v2/individuals/{entityId}/results
Get a list of process results for a given individual entity



# Get a process result
Source: https://docs.frankieone.com/api-reference/individual-results/get-a-process-result

/specs/fc-kyc-bundled_generated.yaml get /v2/individuals/{entityId}/results/{processResultId}
Get process result using process result id for a given individual entity



# Invalidate any Manual KYC evidences of an individual
Source: https://docs.frankieone.com/api-reference/individual-results/invalidate-any-manual-kyc-evidences-of-an-individual

/specs/fc-kyc-bundled_generated.yaml post /v2/individuals/{entityId}/results/mkyc/invalidate
Invalidate any Manual KYC evidences of an individual. This will force the entity to be verified by eKYC processes when KYC verification is next run. Only invalidate mKYC evidences if manual KYC evidences had previously been supplied for this entity.



# Update the status of a supporting document
Source: https://docs.frankieone.com/api-reference/individual-results/update-the-status-of-a-supporting-document

/specs/fc-kyc-bundled_generated.yaml patch /v2/individuals/{entityId}/documents/{documentId}/status
Update the status of a support document. This will create or update the process result for the given document. The given document must be a support document with an attachment, otherwise the request will fail with a 400 Bad Request error. Only support documents can currently be reviewed in this way.



# Update the status of AML process results
Source: https://docs.frankieone.com/api-reference/individual-results/update-the-status-of-aml-process-results

/specs/fc-kyc-bundled_generated.yaml patch /v2/individuals/{entityId}/results/aml
Update the status of a set of AML process results.



# Update the status of Duplicate process results
Source: https://docs.frankieone.com/api-reference/individual-results/update-the-status-of-duplicate-process-results

/specs/fc-kyc-bundled_generated.yaml patch /v2/individuals/{entityId}/results/duplicate
Update the status of a set of Duplicate process results.
The request body supports batch processing of duplicate results with the following components:
- processResults: Array of UUID strings identifying specific duplicate Process Results to update - manualStatus: The resolution status for the duplicates, which can be one of:
  * FALSE_POSITIVE: When the flagged entities are determined to be different individuals (both records should be kept)
  * TRUE_POSITIVE_ACCEPT: Keep the current entity as primary and mark the result entity as duplicate (use when current record is more complete/accurate)
  * TRUE_POSITIVE_REJECT: Keep the result entity as primary and mark the current entity as duplicate (use when duplicate record is more complete/accurate)
- comment: Optional documentation for the decision rationale, useful for audit trails and team communication



# Update the status of Fraud process results
Source: https://docs.frankieone.com/api-reference/individual-results/update-the-status-of-fraud-process-results

/specs/fc-kyc-bundled_generated.yaml patch /v2/individuals/{entityId}/results/fraud
Update the status of a set of Fraud process results.
The request body supports batch processing of fraud results with the following components:
- processResults: Array of UUID strings identifying specific fraud Process Results to update - manualStatus: The resolution status for the fraud, which can be one of:
  * FALSE_POSITIVE: When the result is determined to be false positive.
  * TRUE_POSITIVE: When the result is determined to be true positive.
  * UNKNOWN: When the result is still being evaluated and you do not yet want to resolve it.
- comment: Optional documentation for the decision rationale, useful for audit trails and team communication



# Update the status of IDV process results
Source: https://docs.frankieone.com/api-reference/individual-results/update-the-status-of-idv-process-results

/specs/fc-kyc-bundled_generated.yaml patch /v2/individuals/{entityId}/results/idv
Update the status of a set of IDV process results.



# Update the status of Matchlist process results
Source: https://docs.frankieone.com/api-reference/individual-results/update-the-status-of-matchlist-process-results

/specs/fc-kyc-bundled_generated.yaml patch /v2/individuals/{entityId}/results/matchlist
Update the status of a set of Matchlist process results.



# Update an individual entity's risk level for a service profile.
Source: https://docs.frankieone.com/api-reference/individual-risks/update-an-individual-entitys-risk-level-for-a-service-profile

/specs/fc-kyc-bundled_generated.yaml patch /v2/individuals/{entityId}/serviceprofiles/{serviceName}/risk
This endpoint allows you to override the calculated risk level for the last completed workflow of an individual entity's service profile.

Note:
- This operation will not trigger a new workflow but will be used in the next workflow execution unless risk factors change or results are invalidated.
- To execute the workflow, use the endpoint `POST /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/execute`.



# Override the status of a specific workflow execution.
Source: https://docs.frankieone.com/api-reference/individual-workflows/override-the-status-of-a-specific-workflow-execution

/specs/fc-kyc-bundled_generated.yaml patch /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions/{workflowExecutionId}
Override the result of a specific workflow execution by its id.



# Add an individual entity to a matchlist
Source: https://docs.frankieone.com/api-reference/matchlists/add-an-individual-entity-to-a-matchlist

/specs/fc-core-bundled_generated.yaml post /v2/matchlists/{matchlistName}/entries/addEntity
Creates an individual entity and its attributes as a new entry in an existing matchlist.



# Create one or more entries in a matchlist
Source: https://docs.frankieone.com/api-reference/matchlists/create-one-or-more-entries-in-a-matchlist

/specs/fc-core-bundled_generated.yaml post /v2/matchlists/{matchlistName}/entries
Create a new entry in an existing matchlist.
Entries must have at least one attribute and those attributes must be of valid types. Attribute values must have at least one non-whitespace character in their values.
Optionally a batch name can be provided in the request, which will be applied to all given entries. The batch name should reflect the source of the entry list, for example blocklist.csv. The entries can later be retrieved by batch name.
Optionally a reference can be provided for each entry in the request. The reference should be a unique name (but uniqueness is not required) from for example an externally sourced blocklist. The entries can later be retrieved by reference.
Optionally each entry can refer to an entity ID and type (both ID and type, or neither), to indicate that the entry is based on en existing entity.



# Get a list of matchlist entries
Source: https://docs.frankieone.com/api-reference/matchlists/get-a-list-of-matchlist-entries

/specs/fc-core-bundled_generated.yaml get /v2/matchlists/{matchlistName}/entries
The query parameter `entityId` can be used to filter the entries by entity ID. The entity UUID must be in lower case.
The query parameter `reference` can be used to filter the entries by reference.
The query parameter `batchName` can be used to filter the entries by batch name.
The query parameter `states` can be used to filter the entries by state. If set, the response will include only entries with the specified states. By default only `ACTIVE` entries are returned if the matchlist is `ACTIVE`. If the matchlist is `ARCHIVED` only `EXPIRED` entries will be returned. Possible values are: `ACTIVE`, `EXPIRED`, and `DELETED`. Multiple values can be provided as a comma-separated list. For example, `DELETED,EXPIRED`.
The query parameter `sortFields` (`createdAt`, `updatedAt` or `state`) can be set to one or more fields for sorting. The default is to use just `createdAt`.
The query parameter `sort` can set the sort order to ascending (`asc`) or descending (`desc`). The default is ascending.
The query parameters `limit` (default 10) and `page` (default 1) can be used to control paging of the returned entries. The values given must be positive.
If no matching entries are found, or the page is too large, then the entries array will be empty, but the result code is still 200.
In addition to the entries, the response will also include the basic details of the matchlist, including its state. This is important, since if a matchlist is `ARCHIVED`, all previously `ACTIVE` entries will be `EXPIRED`, and will only be seen in the response if the `states` includes `EXPIRED`. So the entries array will be blank for `ARCHIVED` matchlists if `states` is not given.



# Modify a matchlist entry
Source: https://docs.frankieone.com/api-reference/matchlists/modify-a-matchlist-entry

/specs/fc-core-bundled_generated.yaml patch /v2/matchlists/{matchlistName}/entries/{entryId}
This can be used in updating a matchlist entry's non-attribute fields such as `reference`, `state`, `reason`.

This endpoint can also be used to "delete" an entry by changing its state to `DELETED` and capturing comments.

NOTE: Updating `attributes` field of a matchlist entry is not allowed. An entry could be used in existing matches, and modifying attributes directly could lead to inconsistencies. 
As a workaround, retrieve the entry details, then create a new entry with the original and updated values. The old entry should have its state changed to `DELETED`.



# Remove an individual entity matchlist
Source: https://docs.frankieone.com/api-reference/matchlists/remove-an-individual-entity-matchlist

/specs/fc-core-bundled_generated.yaml patch /v2/matchlists/{matchlistName}/entries/removeEntity
Remove a matchlist entry's state using an entity ID. This automatically sets the state of the entry to `DELETED` .
- **Important**: Deletion cannot be undone.
- Delete a matchlist entry using the `entityId` associated with the entry.
- Deleted entries will not be used for screening.
- However, deleted entries can still be retrieved:
  - By `entityId`, using the multi-entry `GET` (list) API, by specifying an `includeStates` filter that includes `DELETED`.



# Retrieve a list of matchlist details
Source: https://docs.frankieone.com/api-reference/matchlists/retrieve-a-list-of-matchlist-details

/specs/fc-core-bundled_generated.yaml get /v2/matchlists
Retrieve a list of matchlists that new entries can be added or removed.



# Retrieve a matchlist entry
Source: https://docs.frankieone.com/api-reference/matchlists/retrieve-a-matchlist-entry

/specs/fc-core-bundled_generated.yaml get /v2/matchlists/{matchlistName}/entries/{entryId}
Retrieve a single matchlist entry using an entryId.



# Search for matchlist entries
Source: https://docs.frankieone.com/api-reference/matchlists/search-for-matchlist-entries

/specs/fc-core-bundled_generated.yaml post /v2/search/matchlists
Retrieve all matching entries for the search criteria.



# Turn on/off monitoring for a given entity
Source: https://docs.frankieone.com/api-reference/monitoring/turn-onoff-monitoring-for-a-given-entity

/specs/fc-kyc-bundled_generated.yaml patch /v2/individuals/{entityId}/monitor
Toggle monitoring on or off for for a given entity e.g. AML monitoring. Use this endpoint to either:
- Enable monitoring - System will start monitoring the entity for potential changes.
- Disable monitoring - System will no longer monitor the entity for new potential matches and will no longer send alerts.

The endpoint will effectively manage the monitoring status of the entity.
Having monitoring status of a type enabled means that the entity is being monitored for that type.
If the entity has several services under the entity, the endpoint will manage the subscription status of the entity for each service for the types requested.
Request:
The request object contains the `entityId` and list of `monitoring` that are about to toggle.
Also, the request body contains comment to be added to audit logs
Response:
The response object contains the `requestId` and the `subscriptions` that associated with the entity.
The subscriptions object contains the type of monitoring and the details of the subscriptions.
The details of the subscriptions includes:
  - service name
  - service profile ID
  - status of the subscription
  - the workflows that will be executed by the type for the service profile.



# Delete an address
Source: https://docs.frankieone.com/api-reference/organization-addresses/delete-an-address

/specs/fc-kyb-bundled_generated.yaml delete /v2/organizations/{entityId}/addresses/{addressId}
Delete a single organization address



# Delete a custom attribute
Source: https://docs.frankieone.com/api-reference/organization-custom-attributes/delete-a-custom-attribute

/specs/fc-kyb-bundled_generated.yaml delete /v2/organizations/{entityId}/customattributes/{key}
Delete a single organization custom attribute by key



# Confirm a trust analysis result for a document
Source: https://docs.frankieone.com/api-reference/organization-documents/confirm-a-trust-analysis-result-for-a-document

/specs/fc-kyb-bundled_generated.yaml post /v2/organizations/{entityId}/documents/{documentId}/analyses/{analysisId}/confirm
Submit a human-reviewed confirmation of a trust analysis result. The confirmation payload is the corrected `DocumentAnalysisInformationAndReferences`, which may be identical to the original analysis (confirm-as-is) or contain customer corrections. A new CONFIRMATION result is created with the confirmed payload. If a prior CONFIRMATION exists for the same analysis, it is marked STALE; the original ANALYSIS result is preserved as an audit trail. The response returns the confirmed analysis with `isConfirmed=true` and `status=VALID`, in the same shape as a single item from the GET analyses response.



# Create a new document for an organization.
Source: https://docs.frankieone.com/api-reference/organization-documents/create-a-new-document-for-an-organization

/specs/fc-kyb-bundled_generated.yaml post /v2/organizations/{entityId}/documents
Add a new document to an organization entity.



# Delete a document
Source: https://docs.frankieone.com/api-reference/organization-documents/delete-a-document

/specs/fc-kyb-bundled_generated.yaml delete /v2/organizations/{entityId}/documents/{documentId}
Delete a single document and all of it's attachments for an organization entity.



# Delete an attachment
Source: https://docs.frankieone.com/api-reference/organization-documents/delete-an-attachment

/specs/fc-kyb-bundled_generated.yaml delete /v2/organizations/{entityId}/documents/{documentId}/attachments/{attachmentId}
Delete an attachment from a given document.



# Get a single document by its id.
Source: https://docs.frankieone.com/api-reference/organization-documents/get-a-single-document-by-its-id

/specs/fc-kyb-bundled_generated.yaml get /v2/organizations/{entityId}/documents/{documentId}
Get a single document by its id for an organization entity.



# Get all documents for an organization entity
Source: https://docs.frankieone.com/api-reference/organization-documents/get-all-documents-for-an-organization-entity

/specs/fc-kyb-bundled_generated.yaml get /v2/organizations/{entityId}/documents
Get all documents for an organization entity.



# Get trust analyses results for a document
Source: https://docs.frankieone.com/api-reference/organization-documents/get-trust-analyses-results-for-a-document

/specs/fc-kyb-bundled_generated.yaml get /v2/organizations/{entityId}/documents/{documentId}/analyses
Retrieve all trust analyses results for a given document belonging to an organization entity. Both currently valid (VALID) and stale (STALE) analyses are returned so that consumers can display analysis history and detect invalidation. Consumers that only want current results can filter on `status=VALID`.



# Update a single document by its id.
Source: https://docs.frankieone.com/api-reference/organization-documents/update-a-single-document-by-its-id

/specs/fc-kyb-bundled_generated.yaml patch /v2/organizations/{entityId}/documents/{documentId}
Update a document by its id for an organization entity.



# Delete an organization external reference
Source: https://docs.frankieone.com/api-reference/organization-external-references/delete-an-organization-external-reference

/specs/fc-kyb-bundled_generated.yaml delete /v2/organizations/{entityId}/externalreferences/{referenceId}
Delete an organization's external reference with the given id.



# Turn on/off monitoring for a given organization
Source: https://docs.frankieone.com/api-reference/organization-monitoring/turn-onoff-monitoring-for-a-given-organization

/specs/fc-kyb-bundled_generated.yaml patch /v2/organizations/{entityId}/monitor
Toggle monitoring on or off for a given organization e.g. AML monitoring. Use this endpoint to either:
- Enable monitoring - System will start monitoring the organization for potential changes.
- Disable monitoring - System will no longer monitor the organization for new potential matches and will no longer send alerts.

The endpoint will effectively manage the monitoring status of the organization.
Having monitoring status of a type enabled means that the organization is being monitored for that type.
If the organization has several services under the entity, the endpoint will manage the subscription status of the organization for each service for the types requested.
Request:
The request object contains the `entityId` and list of `monitoring` that are about to toggle.
Also, the request body contains comment to be added to audit logs
Response:
The response object contains the `requestId` and the `subscriptions` that associated with the organization.
The subscriptions object contains the type of monitoring and the details of the subscriptions.
The details of the subscriptions includes:
  - service name
  - service profile ID
  - status of the subscription
  - the workflows that will be executed by the type for the service profile.



# Get a service profile for a given organization entity.
Source: https://docs.frankieone.com/api-reference/organization-profiles/get-a-service-profile-for-a-given-organization-entity

/specs/fc-kyb-bundled_generated.yaml get /v2/organizations/{entityId}/serviceprofiles/{serviceName}
Get a profile for a given organization entity.



# Update a profile for a given organization entity.
Source: https://docs.frankieone.com/api-reference/organization-profiles/update-a-profile-for-a-given-organization-entity

/specs/fc-kyb-bundled_generated.yaml patch /v2/organizations/{entityId}/serviceprofiles/{serviceName}
Update a profile for a given organization entity.



# Add or update relationships for an organization
Source: https://docs.frankieone.com/api-reference/organization-relationships/add-or-update-relationships-for-an-organization

/specs/fc-kyb-bundled_generated.yaml put /v2/organizations/{entityId}/relationships
Add or update a list of entity relationships for an organization. This will not modify any relationships (ie officials) from other (non-manual) sources. Relationships added with this operation can only be updated the same way.



# Delete relationships for an organization
Source: https://docs.frankieone.com/api-reference/organization-relationships/delete-relationships-for-an-organization

/specs/fc-kyb-bundled_generated.yaml delete /v2/organizations/{entityId}/relationships
Delete a list of entity relationships for an organization. Only relationships added via the relationship put operation can be deleted with this operation. Relationships (ie officials) from other sources cannot be deleted with this operation.



# Get all manually added relationships for organization
Source: https://docs.frankieone.com/api-reference/organization-relationships/get-all-manually-added-relationships-for-organization

/specs/fc-kyb-bundled_generated.yaml get /v2/organizations/{entityId}/relationships
Get all manually added relationships for an organization.



# Get a list of process results
Source: https://docs.frankieone.com/api-reference/organization-results/get-a-list-of-process-results

/specs/fc-kyb-bundled_generated.yaml get /v2/organizations/{entityId}/results
Get a list of process results for a given organization entity



# Get a process result
Source: https://docs.frankieone.com/api-reference/organization-results/get-a-process-result

/specs/fc-kyb-bundled_generated.yaml get /v2/organizations/{entityId}/results/{processResultId}
Get process result using process result id for a given organization entity



# Update the status of AML process results
Source: https://docs.frankieone.com/api-reference/organization-results/update-the-status-of-aml-process-results

/specs/fc-kyb-bundled_generated.yaml patch /v2/organizations/{entityId}/results/aml
Update the status of AML process results.



# Update an organization entity's risk level for a service profile.
Source: https://docs.frankieone.com/api-reference/organization-risks/update-an-organization-entitys-risk-level-for-a-service-profile

/specs/fc-kyb-bundled_generated.yaml patch /v2/organizations/{entityId}/serviceprofiles/{serviceName}/risk
This endpoint allows you to override the calculated risk level for the last completed workflow of an organization entity's service profile.

Note:
- This operation will not trigger a new workflow but will be used in the next workflow execution unless risk factors change or results are invalidated.
- To execute the workflow, use the endpoint `POST /v2/organizations/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/execute`.



# Evaluate a workflow for the given organization entityId using existing results
Source: https://docs.frankieone.com/api-reference/organization-workflows/evaluate-a-workflow-for-the-given-organization-entityid-using-existing-results

/specs/fc-kyb-bundled_generated.yaml post /v2/organizations/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/evaluate
Re-evaluate a workflow for the given organization entityId and service profile using only the current set of results, without gathering any new data.



# Execute a workflow for the given orgnaization entityId
Source: https://docs.frankieone.com/api-reference/organization-workflows/execute-a-workflow-for-the-given-orgnaization-entityid

/specs/fc-kyb-bundled_generated.yaml post /v2/organizations/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/execute
Execute a workflow for the given organization entityId and service profile.



# Execute a workflow with organization details
Source: https://docs.frankieone.com/api-reference/organization-workflows/execute-a-workflow-with-organization-details

/specs/fc-kyb-bundled_generated.yaml post /v2/organizations/workflows/{workflowName}/execute
Execute a workflow for the supplied organization details. If no matching organization is found for the provided details, a new organization will be created. The request body includes entityID, organizationToken and organization. Only one of these should be provided per request. Providing more than one will result in an error. Additionally you can also specify a serviceName to execute a workflow for a specific service profile of the organization.



# Get a list of executions and their results
Source: https://docs.frankieone.com/api-reference/organization-workflows/get-a-list-of-executions-and-their-results

/specs/fc-kyb-bundled_generated.yaml get /v2/organizations/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions
Get a list of entity results. Always sorted in reverse chrono order



# Get the result of a specific execution by its executionId
Source: https://docs.frankieone.com/api-reference/organization-workflows/get-the-result-of-a-specific-execution-by-its-executionid

/specs/fc-kyb-bundled_generated.yaml get /v2/organizations/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions/{workflowExecutionId}
Retrieves the result of a specific workflow execution by its executionId. The organization in the response reflects the state of the organization at the time this endpoint is called, not the state at the point of the workflow execution.



# Create an organization entity
Source: https://docs.frankieone.com/api-reference/organizations/create-an-organization-entity

/specs/fc-kyb-bundled_generated.yaml post /v2/organizations
Creates an Organization entity object which can be used to store data about an organization. You can optionally include documents, attachments, references etc. to the entity.



# Delete an organization entity
Source: https://docs.frankieone.com/api-reference/organizations/delete-an-organization-entity

/specs/fc-kyb-bundled_generated.yaml delete /v2/organizations/{entityId}
Delete an organization entity with the matching entity ID.



# Get an organization entity
Source: https://docs.frankieone.com/api-reference/organizations/get-an-organization-entity

/specs/fc-kyb-bundled_generated.yaml get /v2/organizations/{entityId}
Retrieve all the information of the Organization with the matching entity ID.



# Lookup organizations
Source: https://docs.frankieone.com/api-reference/organizations/lookup-organizations

/specs/fc-kyb-bundled_generated.yaml post /v2/organizations/lookup
Lookup for a given business name or business number across business registries.

The lookup will return a list of matching companies that you can then
potentially run workflows on.

Each lookup result will have a organizationToken that you can use to create an organization or run workflows on

Note: This process will not save any details from the lookup results.



# Update basic attributes of an organization entity
Source: https://docs.frankieone.com/api-reference/organizations/update-basic-attributes-of-an-organization-entity

/specs/fc-kyb-bundled_generated.yaml patch /v2/organizations/{entityId}
Update just the basic organization attributes: address, custom attributes, primary name and taxpayer identification number.



# Download Extract PII files
Source: https://docs.frankieone.com/api-reference/reports/download-extract-pii-files

/specs/fc-core-bundled_generated.yaml post /v2/report/extractPII/download
Download extracted PII CSV files as a ZIP archive. The backend retrieves the job details using the provided jobId and authentication headers, fetches all associated CSV files from S3, compresses them into a ZIP file, and optionally applies password protection if a password is provided. The backend validates that the requesting user has access to the specified job.



# Extract PII report
Source: https://docs.frankieone.com/api-reference/reports/extract-pii-report

/specs/fc-core-bundled_generated.yaml post /v2/report/extractPII
Create a request for extract PII report.



# List Extract PII jobs
Source: https://docs.frankieone.com/api-reference/reports/list-extract-pii-jobs

/specs/fc-core-bundled_generated.yaml get /v2/report/extractPII
Retrieve a list of Extract PII jobs for a customer with optional filtering by status and pagination support.



# Redact Process Result
Source: https://docs.frankieone.com/api-reference/results/redact-process-result

/specs/fc-core-bundled_generated.yaml post /v2/results/{entityId}/processes/{processResultId}/redact
Redact the process result object with the matching ID. The process result is redacted regardless of its current state. All PII data in the process result will be replaced with "*" or dropped.



# Update Organization Results
Source: https://docs.frankieone.com/api-reference/results/update-organization-results

/specs/fc-act-bundled_generated.yaml patch /v2/organizations/{entityId}/results/activity
Update the status of activity process results for an organization.



# Update Results
Source: https://docs.frankieone.com/api-reference/results/update-results

/specs/fc-act-bundled_generated.yaml patch /v2/individuals/{entityId}/results/activity
Update the status of activity process results.



# Search for individual profiles
Source: https://docs.frankieone.com/api-reference/search/search-for-individual-profiles

/specs/fc-kyc-bundled_generated.yaml post /v2/search/serviceprofiles
Search for Individuals that match the provided search parameters.  Search parameters are supplied in the form of an entity object, similar to how you would create an individual.



# Search for profiles
Source: https://docs.frankieone.com/api-reference/search/search-for-profiles

/specs/fc-core-bundled_generated.yaml post /v2/search/serviceprofiles
Search for Individuals and Organizations that match the provided search parameters.  Search parameters are supplied in the form of an entity object.



# Create Individual Session.

Source: https://docs.frankieone.com/api-reference/sessions/create-individual-session

/specs/fc-act-bundled_generated.yaml post /v2/individuals/{entityId}/sessions
Create a new session for an individual. This is only required for onboarding fraud checks where device data is required and at this stage 
it is NOT specifically needed for Transaction and Activity monitoring.




# List tags
Source: https://docs.frankieone.com/api-reference/tags/list-tags

/specs/fc-core-bundled_generated.yaml get /v2/tags
Retrieve all tags matching the optional filter criteria. Results are scoped to the customer
context provided in the request headers — including the customer's own tags, parent customer
tags, and all SYSTEM tags. Sibling customer tags are excluded.

Results are sorted in descending order by `updatedAt`.

Filtering within a single parameter applies **OR** logic (e.g. `categories=FRAUD,SCAM` returns
tags in either category). Filtering across different parameters applies **AND** logic
(e.g. `categories=FRAUD&domains=ONBOARDING` returns tags that are both FRAUD and ONBOARDING).




# List tags objects
Source: https://docs.frankieone.com/api-reference/tags/list-tags-objects

/specs/fc-core-bundled_generated.yaml get /v2/tags/objects
Retrieve tag mappings for objects in the FrankieOne ecosystem. Results are scoped to the
customer context provided in the request headers. Child organisations cannot access mappings
belonging to sibling organisations.

Objects with no tag mappings are excluded from the response.

When no filters are provided, all tag mappings within the customer and child scope are returned,
paginated and sorted by the object mapping's `updatedAt` descending (most recently updated first).
Within each object, tags are sorted by their mapping `createdAt` descending (newest first).

Filtering within a single parameter applies **OR** logic (e.g. `objectTypes=ENTITY,TRANSACTION`
returns mappings for either type). Filtering across different parameters applies **AND** logic
(e.g. `objectTypes=ENTITY&objectIds=abc,def` returns ENTITY mappings only for those IDs).

Duplicate `objectIds` are de-duplicated before processing.




# Remove tag objects
Source: https://docs.frankieone.com/api-reference/tags/remove-tag-objects

/specs/fc-core-bundled_generated.yaml post /v2/tags/objects/remove
Remove tag mappings for the specified tags and objects.

Tag IDs are validated against the customer's accessible tags. If any tag ID does not exist or
belongs to a different customer, the entire request fails.

If an object has no mappings for the given tags, the operation succeeds and that object appears
in the response with an empty `tags` array.

Duplicate `tagIds` or `objects` in the request are deduplicated before processing.

An optional `comment` can be included.




# Create or update a workflow definition
Source: https://docs.frankieone.com/api-reference/workflow-definitions/create-or-update-a-workflow-definition

/specs/fc-core-bundled_generated.yaml put /v2/workflowDefinitions/{workflowDefinitionId}
Forwards the request to the FLOW Workflow Engine to create or update a workflow definition. The request body and headers are forwarded as-is to the upstream service. When isDraft is true, the definition is saved as a draft (version -1). When isDraft is false, a new published version is created.



# Get a list of executable workflows
Source: https://docs.frankieone.com/api-reference/workflows/get-a-list-of-executable-workflows

/specs/fc-core-bundled_generated.yaml get /v2/workflows
Get a list of workflows that can be executed



# Update Workflow Information
Source: https://docs.frankieone.com/api-reference/workflows/update-workflow-information

/specs/fc-core-bundled_generated.yaml patch /v2/workflows/{workflowId}
Update Workflow Information



# FrankieOne Identity Verification Guide
Source: https://docs.frankieone.com/v2/api/developers/frankie-one-key-terms

Understanding Key Terms for Customer Onboarding

## What is FrankieOne?

FrankieOne is a comprehensive identity verification and compliance platform that helps businesses verify customer identities, prevent fraud, and meet regulatory requirements. Through a single integration, you can access hundreds of global data sources and verification tools to onboard customers securely and efficiently.

***

## Core Verification Services

### Know Your Customer (KYC)

The mandatory process of identifying and verifying the identity of customers to prevent fraud and financial crime. KYC checks verify customer information such as name, date of birth, and address against trusted data sources including government databases, credit bureaus, and utility providers.

**Why it matters:**\
KYC is a legal requirement for regulated businesses to prevent money laundering and terrorist financing.

***

### Identity Verification (IDV)

The process of confirming that a person is genuinely who they claim to be. IDV commonly involves document scans, facial comparison, and liveness checks. It combines document verification with biometric authentication to establish trust and enhance security.

**Why it matters:**\
IDV prevents identity fraud by ensuring the person onboarding is the legitimate document holder.

***

### Anti-Money Laundering (AML) Screening

The process of checking individuals and businesses against global watchlists, sanctions lists, and Politically Exposed Persons (PEPs) lists. AML screening helps identify potential risks and ensures compliance with financial crime prevention regulations.

**Why it matters:**\
AML screening protects your business from engaging with high-risk individuals or sanctioned entities.

***

## Document Verification

### Government ID Verification

Verification of government-issued documents such as passports, driver’s licenses, and national ID cards against official records. This confirms the document’s authenticity and validates information including name, date of birth, and document details.

***

### Optical Character Recognition (OCR)

Technology that automatically extracts text and data from identity documents. OCR reduces manual data entry, minimizes errors, and speeds up the onboarding process.

**Why it matters:**\
OCR makes onboarding faster and more accurate by automatically capturing customer information from identity documents.

***

### Document Authenticity Checks

Advanced analysis used to determine whether an identity document is genuine or has been tampered with. This includes checks for alterations, forgeries, photocopies, and screen replays.

***

## Biometric Verification

### Biometrics

Technology that uses unique physical characteristics to verify identity. In customer onboarding, this typically includes facial recognition and liveness detection.

***

### Facial Comparison (Face Match)

The process of comparing a live selfie or video with the photo on an identity document to confirm they match. This ensures the person presenting the ID is the legitimate document holder.

**Why it matters:**\
Face matching prevents fraudsters from using stolen or borrowed identity documents.

***

### Liveness Detection

Technology that confirms a real person is physically present during verification, rather than a photo, video, or mask. Liveness checks detect spoofing attempts and prevent fraud from replays or deepfakes.

**Why it matters:**\
Liveness detection prevents fraudsters from bypassing verification using photos or pre-recorded videos.

***

## Risk & Compliance Terms

### Politically Exposed Person (PEP)

An individual with a prominent public function who may present higher risk for potential bribery or corruption. Examples include government officials, senior executives of state-owned companies, and their close associates.

***

### Sanctions

Economic or trade restrictions imposed on specific individuals, entities, or countries by governments or international bodies. Businesses must screen customers against sanctions lists to ensure compliance.

***

### Watchlists

Lists of individuals or entities subject to scrutiny under AML and sanctions regulations. These include sanctions lists, PEP lists, and adverse media sources.

***

### Adverse Media

Negative news or information about an individual or entity found in reputable media sources. Adverse media screening helps identify potential reputational or financial crime risks.

***

## Verification Process Terms

### Workflow

A customizable, end-to-end process consisting of a series of verification steps. Workflows can include KYC checks, AML screening, document verification, biometric checks, and fraud controls tailored to your compliance requirements.

***

### Service Profile

An overview of a customer’s verification progress for a specific product or service. This includes applied workflows, risk levels, and current verification status.

***

### Decision

The outcome of a verification workflow that determines whether a customer can proceed.

**Possible decisions include:**

* **PASS** – Customer successfully verified and can proceed
* **FAIL** – Verification unsuccessful and the customer cannot proceed
* **REVIEW** – Manual review is required before a final decision is made

***

## Entity Types

### Individual

A single person who can be verified within the platform. Individuals have service profiles, workflows, and risk assessments related to their identity.

***

### Organization

A business or non-individual entity, such as a company or partnership, that can be verified within the platform.

***

## Additional Verification Features

### Duplicate Detection

Technology that identifies and flags linked or duplicate accounts to maintain a single customer view and prevent fraud.

***

### Blocklist Management

Internal lists of known high-risk individuals or entities that your business chooses not to engage with. Blocklists help proactively prevent fraud by rejecting bad actors.

***

### Risk Assessment

A calculated score that evaluates a customer’s potential risk based on configured rules, verification outcomes, and real-time data. Risk scores help determine the appropriate level of verification.

***

## Getting Started

FrankieOne’s platform is designed to be flexible and easy to integrate. You can customize verification workflows to match your business needs and risk appetite while maintaining compliance with regulatory requirements.

### Key Benefits

* **Single Integration** – Access hundreds of global data sources through one platform
* **Automated Workflows** – Reduce manual effort and speed up customer onboarding
* **Global Coverage** – Verify customers from around the world
* **Always Compliant** – Stay current with changing regulatory requirements


# How FrankieOne Selects Vendors and Data Sources
Source: https://docs.frankieone.com/v2/api/developers/how-frankie-one-selects-vendors-and-data-sources

Conceptual Guide (Platform Capabilities) for vendors and datasources

**Audience:** Pre-sales, Product Managers, Compliance Teams

***

## Important Disclaimers

### This is NOT API Documentation

This document describes **FrankieOne's platform capabilities** for vendor and data source management. It does **not** describe API-controllable features.

**What customers CANNOT do via API:**

* Select specific vendors
* Configure routing rules
* Define fallback logic
* Control data source cascade
* Modify vendor selection strategies

**What customers CAN do:**

* Submit verification requests via FrankieOne's API
* Receive verification results
* Work with FrankieOne to **request configuration changes** to vendor setup

### Pricing Disclaimer

All pricing examples are illustrative only. Actual costs vary based on requirements, volumes, geographic coverage, vendor selection, contract terms, and custom configurations. Contact your FrankieOne representative for accurate pricing.

***

## Table of Contents

1. [Understanding FrankieOne's Orchestration Platform](#understanding-frankieones-orchestration-platform)
2. [Types of Vendors and Data Sources](#types-of-vendors-and-data-sources)
3. [How FrankieOne Configures Vendor Selection](#how-frankieone-configures-vendor-selection)
4. [Data Source Selection Strategies](#data-source-selection-strategies)
5. [Vendor Routing and Fallback](#vendor-routing-and-fallback)
6. [Optimizing Pass Rates](#optimizing-pass-rates)
7. [Working with FrankieOne](#working-with-frankieone)
8. [Common Scenarios](#common-scenarios)
9. [FAQs](#faqs)

***

## Understanding FrankieOne's Orchestration Platform

### What is FrankieOne?

FrankieOne is an **orchestration platform** that connects you to a global ecosystem of verification vendors and data sources through a single API integration. FrankieOne manages all vendor relationships, routing logic, and data source selection on your behalf.

**Architecture Overview:**

**WITHOUT FRANKIEONE:**

```mermaid theme={null}
graph LR
    A[Your System] --> B[Vendor 1<br/>separate integration]
    A --> C[Vendor 2<br/>separate integration]
    A --> D[Vendor 3<br/>separate integration]
    A --> E[Data Source 1<br/>separate integration]
    A --> F[Data Source 2<br/>separate integration]
    A --> G[Data Source 3<br/>separate integration]
    
    style A fill:#e1f5ff,stroke:#333,stroke-width:2px
    style B fill:#ffe1e1,stroke:#333,stroke-width:1px
    style C fill:#ffe1e1,stroke:#333,stroke-width:1px
    style D fill:#ffe1e1,stroke:#333,stroke-width:1px
    style E fill:#ffe1e1,stroke:#333,stroke-width:1px
    style F fill:#ffe1e1,stroke:#333,stroke-width:1px
    style G fill:#ffe1e1,stroke:#333,stroke-width:1px
```

*= 6 separate integrations to build and maintain*

**WITH FRANKIEONE:**

```mermaid theme={null}
graph LR
    A[Your System] --> B[FrankieOne API<br/>single integration]
    B --> C[FrankieOne Platform<br/>manages routing]
    C --> D[Vendor 1]
    C --> E[Vendor 2]
    C --> F[Vendor 3]
    C --> G[Data Source 1]
    C --> H[Data Source 2]
    C --> I[Data Source 3]
    
    style A fill:#e1f5ff,stroke:#333,stroke-width:2px
    style B fill:#d4edda,stroke:#333,stroke-width:2px
    style C fill:#d4edda,stroke:#333,stroke-width:2px
    style D fill:#f0f0f0,stroke:#333,stroke-width:1px
    style E fill:#f0f0f0,stroke:#333,stroke-width:1px
    style F fill:#f0f0f0,stroke:#333,stroke-width:1px
    style G fill:#f0f0f0,stroke:#333,stroke-width:1px
    style H fill:#f0f0f0,stroke:#333,stroke-width:1px
    style I fill:#f0f0f0,stroke:#333,stroke-width:1px
```

*= 1 API integration, FrankieOne manages 350+ sources*

### Key Platform Capabilities

**1. Single API Integration**

* One API integration to FrankieOne
* FrankieOne maintains connections to 350+ data sources globally
* Coverage in 195+ countries
* No need to integrate with each vendor separately

**2. FrankieOne-Managed Vendor Selection**

* FrankieOne configures which vendors are used for your verifications
* Routing rules are set by FrankieOne based on your requirements
* Changes to vendor configuration require coordination with FrankieOne

**3. Vendor Flexibility**

* FrankieOne can change underlying vendors without requiring changes to your API integration
* No vendor lock-in at the integration level
* Ability to adapt to changing requirements through FrankieOne configuration

**4. Simplified Management**

* Single contract with FrankieOne
* Consolidated billing
* Unified support
* Consistent API response format across all vendors

***

## Types of Vendors and Data Sources

FrankieOne connects to vendors across multiple verification categories. The specific vendors used for your account are **configured by FrankieOne** based on your requirements.

### 1. KYC (Know Your Customer) Vendors

**Purpose:** Verify identity details against authoritative data sources

**Capabilities May Include:**

* Electronic verification (e.g., 2+2 rule compliance)
* Credit bureau checks
* Electoral roll verification
* Government database checks
* Utility record verification

**Use Cases:**

* Standard customer onboarding
* Electronic verification
* Address verification
* Identity confirmation

### 2. IDV (Identity Verification) Vendors

**Purpose:** Verify documents and biometrics

**Capabilities May Include:**

* Document authenticity verification
* OCR (data extraction from documents)
* Liveness detection
* Face matching (biometrics)
* Forgery detection

**Use Cases:**

* Document verification
* Remote identity verification
* Biometric verification
* High-assurance verification

### 3. AML (Anti-Money Laundering) Vendors

**Purpose:** Screen against watchlists and sanctions

**Capabilities May Include:**

* PEP (Politically Exposed Persons) screening
* Sanctions list screening
* Watchlist screening
* Adverse media screening
* Ongoing monitoring

**Use Cases:**

* Compliance screening
* Risk assessment
* Ongoing monitoring
* Enhanced due diligence

### 4. Fraud Detection Vendors

**Purpose:** Detect fraud signals and risk

**Capabilities May Include:**

* Device intelligence
* Email risk assessment
* Phone risk assessment
* IP address analysis
* Behavioral analytics

**Use Cases:**

* Fraud prevention
* Risk scoring
* Account takeover prevention
* Transaction monitoring

### 5. KYB (Know Your Business) Vendors

**Purpose:** Verify business entities

**Capabilities May Include:**

* Company registry searches
* Beneficial ownership verification
* Business verification
* Corporate structure analysis
* Director verification

**Use Cases:**

* Business onboarding
* Corporate verification
* UBO (Ultimate Beneficial Owner) verification
* Corporate due diligence

### Data Source Types

Within each vendor category, different types of data sources may be available:

**Government Data Sources:**

* Passport databases
* Driver license databases
* National ID databases
* Birth/death registries
* Electoral rolls

**Commercial Data Sources:**

* Credit bureaus
* Utility providers
* Telecommunications providers
* Financial institutions
* Property records

**Watchlist Data Sources:**

* OFAC (US sanctions)
* UN sanctions lists
* EU sanctions lists
* PEP databases
* Adverse media databases

**Proprietary Data Sources:**

* Vendor-specific databases
* Consortium data
* Historical verification data
* Fraud intelligence networks

***

## How FrankieOne Configures Vendor Selection

### The Configuration Process

**Important:** Vendor selection and routing are **configured by FrankieOne**, not controlled by API parameters.

```mermaid theme={null}
flowchart TD
    A[Step 1: Customer Defines Requirements] --> A1["• What countries do you operate in?<br/>• What verification types do you need?<br/>• What are your pass rate requirements?<br/>• What is your budget?<br/>• What are your regulatory requirements?"]
    A1 --> B[Step 2: FrankieOne Recommends Vendors]
    B --> B1["• Based on customer requirements<br/>• Considering coverage and capabilities<br/>• Factoring in cost and performance<br/>• Aligned with use cases"]
    B1 --> C[Step 3: Customer Reviews and Approves]
    C --> C1["• Reviews FrankieOne's recommendations<br/>• Understands trade-offs<br/>• Approves vendor selection<br/>• Approves fallback options"]
    C1 --> D[Step 4: FrankieOne Configures Platform]
    D --> D1["• Sets up vendor connections<br/>• Configures routing rules<br/>• Implements fallback logic<br/>• Tests in UAT environment"]
    D1 --> E[Step 5: Customer Tests]
    E --> E1["• Tests with real data via API<br/>• Monitors pass rates<br/>• Reviews results<br/>• Requests adjustments if needed"]
    E1 --> F[Step 6: Production Deployment]
    F --> F1["• FrankieOne activates configuration<br/>• Customer begins sending production traffic<br/>• Ongoing monitoring and optimization"]
    
    style A fill:#e1f5ff,stroke:#333,stroke-width:2px
    style B fill:#d4edda,stroke:#333,stroke-width:2px
    style C fill:#e1f5ff,stroke:#333,stroke-width:2px
    style D fill:#d4edda,stroke:#333,stroke-width:2px
    style E fill:#e1f5ff,stroke:#333,stroke-width:2px
    style F fill:#d4edda,stroke:#333,stroke-width:2px
    style A1 fill:#f8f9fa,stroke:#333,stroke-width:1px
    style B1 fill:#f8f9fa,stroke:#333,stroke-width:1px
    style C1 fill:#f8f9fa,stroke:#333,stroke-width:1px
    style D1 fill:#f8f9fa,stroke:#333,stroke-width:1px
    style E1 fill:#f8f9fa,stroke:#333,stroke-width:1px
    style F1 fill:#f8f9fa,stroke:#333,stroke-width:1px
```

### Configuration Factors

FrankieOne considers multiple factors when configuring vendor selection:

**Geographic Coverage:**

* Which countries/regions need coverage
* Local vs international data sources
* Regional regulatory requirements

**Verification Requirements:**

* Type of verification needed (KYC, IDV, AML, etc.)
* Required data points
* Regulatory compliance needs
* Industry-specific requirements

**Performance Requirements:**

* Pass rate targets
* Response time requirements
* Availability requirements

**Cost Constraints:**

* Budget per verification
* Volume projections
* Cost vs pass rate trade-offs

**Regulatory Compliance:**

* Industry regulations (financial services, gaming, etc.)
* Regional requirements (GDPR, CCPA, etc.)
* Audit requirements

***

## Data Source Selection Strategies

FrankieOne can configure your account with different data source selection strategies. The strategy used is **set by FrankieOne**, not controlled via API.

### Strategy 1: Single Data Source

**How It Works:**

* FrankieOne configures a single primary data source for verifications
* All verification requests are processed using this configured source

**When FrankieOne May Configure This:**

* High-quality single source available
* Cost optimization priority
* Regulatory requirement for specific source
* Simple use case with good baseline pass rates

**Characteristics:**

* Simplest configuration
* Lowest cost per verification
* Pass rate dependent on single source quality
* No redundancy if source is unavailable

**Example Scenario:**
Customer operates only in Australia and has regulatory requirement to use specific government data source.

### Strategy 2: Cascade (Sequential Fallback)

**How It Works:**

* FrankieOne configures a primary data source
* If primary source returns no match, FrankieOne's platform automatically attempts secondary source
* Process continues through configured sources until match is found or all sources exhausted

**When FrankieOne May Configure This:**

* Need for higher pass rates
* Coverage gaps in primary source
* Multiple complementary data sources available

**Characteristics:**

* Higher pass rates than single source
* Incremental cost (only pay for sources actually used)
* Automatic fallback on no-match
* Sequential processing may increase latency

**Example Configuration:**

```mermaid theme={null}
graph TD
    A[Verification Request] --> B[Primary Source<br/>Credit Bureau]
    B -->|No Match| C[Secondary Source<br/>Electoral Roll]
    C -->|No Match| D[Tertiary Source<br/>Utility Records]
    B -->|Match Found| E[Return Result]
    C -->|Match Found| E
    D -->|Match Found| E
    D -->|No Match| F[Return No Match]
    
    style A fill:#e1f5ff,stroke:#333,stroke-width:2px
    style B fill:#fff3cd,stroke:#333,stroke-width:2px
    style C fill:#fff3cd,stroke:#333,stroke-width:2px
    style D fill:#fff3cd,stroke:#333,stroke-width:2px
    style E fill:#d4edda,stroke:#333,stroke-width:2px
    style F fill:#f8d7da,stroke:#333,stroke-width:2px
```

### Strategy 3: Parallel Verification (coming soon)

This feature is under assessment if interested in Parallel verification please reach out as we have this planned; however, require customer interest. Due to the cost many customers select alternate options.

**How It Works:**

* FrankieOne configures multiple data sources to be queried simultaneously
* Results from all sources are aggregated
* Higher confidence through multiple confirmations

**When FrankieOne May Configure This:**

* High-assurance verification needed
* Fraud prevention priority
* Regulatory requirement for multiple independent checks

**Characteristics:**

* Highest confidence
* Best for high-risk scenarios
* Higher cost (pay for all parallel sources)
* Fastest response time (parallel execution)

**Example Configuration:**

```mermaid theme={null}
graph TD
    A[Verification Request] --> B[Source 1<br/>Credit Bureau]
    A --> C[Source 2<br/>Electoral Roll]
    A --> D[Source 3<br/>Utility Records]
    B --> E[Aggregate Results]
    C --> E
    D --> E
    E --> F[Return Combined Result]
    
    style A fill:#e1f5ff,stroke:#333,stroke-width:2px
    style B fill:#fff3cd,stroke:#333,stroke-width:2px
    style C fill:#fff3cd,stroke:#333,stroke-width:2px
    style D fill:#fff3cd,stroke:#333,stroke-width:2px
    style E fill:#d1ecf1,stroke:#333,stroke-width:2px
    style F fill:#d4edda,stroke:#333,stroke-width:2px
```

### Strategy 4: Conditional Routing

**How It Works:**

* FrankieOne configures different data sources for different scenarios
* Routing rules based on entity attributes, risk signals, or geographic location

**When FrankieOne May Configure This:**

* Different requirements for different customer segments
* Geographic optimization needed
* Risk-based verification strategies

**Characteristics:**

* Optimized for specific scenarios
* Cost-effective for diverse use cases
* Complex configuration
* Requires clear segmentation logic

**Example Configuration:**

```mermaid theme={null}
graph TD
    A[Verification Request] --> B{Risk Level?}
    B -->|High Risk| C[Parallel Verification<br/>3 sources]
    B -->|Medium Risk| D[Cascade<br/>2 sources]
    B -->|Low Risk| E[Single Source]
    C --> F[Return Result]
    D --> F
    E --> F
    
    style A fill:#e1f5ff,stroke:#333,stroke-width:2px
    style B fill:#d1ecf1,stroke:#333,stroke-width:2px
    style C fill:#f8d7da,stroke:#333,stroke-width:2px
    style D fill:#fff3cd,stroke:#333,stroke-width:2px
    style E fill:#d4edda,stroke:#333,stroke-width:2px
    style F fill:#e1f5ff,stroke:#333,stroke-width:2px
```

### Strategy 5: Geographic Routing

**How It Works:**

* FrankieOne configures different data sources for different countries/regions
* Requests are routed based on customer's declared country

**When FrankieOne May Configure This:**

* Multi-country operations
* Regional data sources perform better locally
* Regulatory requirements vary by region

**Characteristics:**

* Optimized for geographic coverage
* Addresses regional data availability
* May use different strategies per region

**Example Configuration:**

```mermaid theme={null}
graph TD
    A[Verification Request] --> B{Customer Country?}
    B -->|Australia| C[Australian Credit Bureau]
    C -->|No Match| D[Electoral Roll]
    B -->|UK| E[UK Credit Reference Agency]
    E -->|No Match| F[Electoral Roll]
    B -->|US| G[US Credit Bureau]
    G -->|No Match| H[Utility Database]
    D --> I[Return Result]
    C --> I
    E --> I
    F --> I
    G --> I
    H --> I
    
    style A fill:#e1f5ff,stroke:#333,stroke-width:2px
    style B fill:#d1ecf1,stroke:#333,stroke-width:2px
    style C fill:#fff3cd,stroke:#333,stroke-width:1px
    style D fill:#fff3cd,stroke:#333,stroke-width:1px
    style E fill:#ffe1e1,stroke:#333,stroke-width:1px
    style F fill:#ffe1e1,stroke:#333,stroke-width:1px
    style G fill:#e1ffe1,stroke:#333,stroke-width:1px
    style H fill:#e1ffe1,stroke:#333,stroke-width:1px
    style I fill:#d4edda,stroke:#333,stroke-width:2px
```

***

## Vendor Routing and Fallback

### How Routing Works

**Important:** All routing logic is **configured and managed by FrankieOne**, not controlled by API parameters submitted by customers.

### Routing Configuration Types

**1. Geographic Routing**

* FrankieOne configures routing based on customer's country
* Example: Australian customers → Australian data sources
* Ensures local data coverage and compliance

**2. Document-Type Routing**

* For IDV checks, FrankieOne may configure different vendors for different document types
* Example: Passport checks → Vendor A, Driver License checks → Vendor B
* Optimizes for vendor strengths

**3. Risk-Based Routing**

* FrankieOne may configure routing based on risk signals
* Example: High-risk → Enhanced verification path, Low-risk → Standard path
* Requires risk scoring configuration

**4. Performance-Based Routing**

* FrankieOne may configure routing to optimize for pass rates
* Example: If Vendor A pass rate drops, route to Vendor B
* Requires monitoring and dynamic configuration

### Fallback Configuration

**Automatic Fallback:**
FrankieOne can configure automatic fallback in several scenarios:

1. **No Match Fallback**
   * Primary source returns no match
   * System automatically tries configured secondary source
   * Continues through fallback chain if configured

2. **Vendor Unavailability Fallback**
   * Primary vendor is unavailable or times out
   * System automatically routes to configured backup vendor
   * Ensures service continuity

3. **Error Fallback**
   * Vendor returns error response
   * System may retry with alternate vendor if configured
   * Depends on error type and configuration

**Example Fallback Configuration:**

```mermaid theme={null}
flowchart TD
    A[Verification Request] --> B[Try Primary Vendor<br/>Vendor A]
    B --> C{Successful?}
    C -->|Yes| D[Return Result]
    C -->|No| E[Try Secondary Vendor<br/>Vendor B]
    E --> F{Successful?}
    F -->|Yes| D
    F -->|No| G[Return No Match]
    
    style A fill:#e1f5ff,stroke:#333,stroke-width:2px
    style B fill:#fff3cd,stroke:#333,stroke-width:2px
    style C fill:#d1ecf1,stroke:#333,stroke-width:2px
    style E fill:#fff3cd,stroke:#333,stroke-width:2px
    style F fill:#d1ecf1,stroke:#333,stroke-width:2px
    style D fill:#d4edda,stroke:#333,stroke-width:2px
    style G fill:#f8d7da,stroke:#333,stroke-width:2px
```

### Resilience Features

FrankieOne's platform includes resilience features (configuration dependent):

* **Timeout Handling:** Configured timeouts for vendor responses
* **Retry Logic:** May retry requests on transient failures
* **Circuit Breakers:** May temporarily disable failing vendors
* **Monitoring:** Tracks vendor performance and availability

**Note:** Specific resilience configurations are managed by FrankieOne based on your SLA requirements.

***

## Optimizing Pass Rates

Pass rate optimization is achieved through **FrankieOne configuration changes**, not API controls.

### What Affects Pass Rates

**Data Quality:**

* Accuracy of customer data submitted via API
* Completeness of required fields
* Data formatting and standardization

**Data Source Coverage:**

* Whether configured data sources have records for your customer demographics
* Geographic coverage of configured sources
* Recency of data in configured sources

**Configuration Strategy:**

* Single source vs cascade vs parallel (configured by FrankieOne)
* Number of fallback sources configured
* Match criteria sensitivity (configured by FrankieOne)

### How to Request Pass Rate Improvements

**1. Review Current Performance**

* Analyze pass rate data from FrankieOne reporting
* Identify patterns in failures
* Understand failure reasons

**2. Contact FrankieOne**

* Provide pass rate data and failure analysis
* Discuss your target pass rates
* Share any constraints (budget, latency, etc.)

**3. FrankieOne Recommends Configuration Changes**
Options may include:

* Adding fallback data sources
* Switching primary data source
* Adjusting match criteria
* Implementing cascade strategy
* Geographic routing optimization

**4. Test in UAT**

* FrankieOne implements proposed changes in UAT
* Customer tests with real data via API
* Measure pass rate improvements
* Evaluate cost impact

**5. Production Deployment**

* Once approved, FrankieOne deploys to production
* Monitor ongoing pass rates
* Iterate if needed

### Pass Rate Improvement Strategies

**Strategy 1: Add Fallback Sources**

* **Configuration Change:** FrankieOne adds secondary/tertiary sources
* **Impact:** Higher pass rates, incremental cost
* **Best For:** Cases with clear coverage gaps

**Strategy 2: Switch Primary Source**

* **Configuration Change:** FrankieOne changes which source is tried first
* **Impact:** Different coverage, may affect cost
* **Best For:** When alternative source has better coverage for your demographics

**Strategy 3: Parallel Verification**

* **Configuration Change:** FrankieOne configures multiple sources to run in parallel
* **Impact:** Highest pass rates, highest cost
* **Best For:** High-value customers or regulatory requirements

**Strategy 4: Optimize Data Quality**

* **Customer Action:** Improve data submitted via API (not a configuration change)
* **Impact:** Better matching across all sources
* **Best For:** When data quality is identified as primary issue

**Strategy 5: Geographic Routing**

* **Configuration Change:** FrankieOne implements region-specific source routing
* **Impact:** Optimized pass rates per region
* **Best For:** Multi-country operations

### Cost vs Pass Rate Trade-offs

FrankieOne helps you balance cost and pass rates:

```mermaid theme={null}
graph LR
    A[Single Source] -->|"Lower Cost<br/>~70-80% Pass Rate"| B[Cascade<br/>2-3 Sources]
    B -->|"Medium Cost<br/>~80-90% Pass Rate"| C[Parallel<br/>3+ Sources]
    C -->|"Higher Cost<br/>~90-100% Pass Rate"| D[ ]
    
    style A fill:#d4edda,stroke:#333,stroke-width:2px
    style B fill:#fff3cd,stroke:#333,stroke-width:2px
    style C fill:#f8d7da,stroke:#333,stroke-width:2px
    style D fill:none,stroke:none
```

*Pass rates and costs are illustrative - actual results vary by configuration and data quality*

**Work with FrankieOne to:**

* Define your acceptable pass rate
* Understand your cost constraints
* Find optimal configuration
* Test and validate trade-offs

***

## Working with FrankieOne

### Initial Setup Process

**1. Requirements Gathering**

Contact FrankieOne with:

* Geographic coverage needs
* Verification types required
* Expected volumes
* Pass rate targets
* Budget constraints
* Regulatory requirements
* Timeline for deployment

**2. FrankieOne Provides Recommendations**

FrankieOne will:

* Recommend specific vendors for your use cases
* Propose routing and fallback strategy
* Provide estimated pass rates
* Share pricing proposal
* Explain configuration rationale

**3. Customer Review and Approval**

You will:

* Review vendor recommendations
* Understand trade-offs
* Ask questions
* Approve proposed configuration
* Sign contracts if needed

**4. FrankieOne Configuration**

FrankieOne will:

* Set up vendor connections
* Configure routing rules
* Implement fallback logic
* Prepare UAT environment
* Provide API credentials

**5. UAT Testing**

Customer will:

* Test verification API with sample data
* Validate pass rates
* Check response formats
* Test error scenarios
* Measure latency

**6. Production Deployment**

FrankieOne will:

* Deploy approved configuration to production
* Monitor initial traffic
* Provide go-live support

### Ongoing Optimization

**Monthly/Quarterly Reviews**

FrankieOne can provide:

* Pass rate reports
* Cost analysis
* Vendor performance metrics
* Failure reason analysis
* Optimization recommendations

**Configuration Changes**

To request configuration changes:

1. Contact your FrankieOne representative
2. Explain what you want to change and why
3. FrankieOne provides options and impact analysis
4. Test changes in UAT
5. Deploy to production once approved

**Common Change Requests:**

* Add new verification types
* Expand to new countries
* Adjust pass rate vs cost balance
* Add fallback sources
* Change routing strategy

### Support and SLAs

**Support Channels:**

* Your FrankieOne account representative
* Technical support (for API integration questions)
* Configuration requests (for routing/vendor changes)

**SLA Considerations:**

* API availability SLAs
* Response time SLAs
* Support response times
* Configuration change timelines

Contact FrankieOne to discuss specific SLA requirements.

***

## Common Scenarios

### Scenario 1: Starting with Single Country

**Situation:**

* New business, operating only in Australia
* Need standard KYC verification
* Limited budget, volume under 1000/month

**FrankieOne May Configure:**

* Single Australian KYC vendor
* One fallback source
* Standard match criteria

**Why This Configuration:**

* Cost-effective for low volumes
* Adequate pass rates for single market
* Simple to test and deploy
* Room to expand later

**Customer Experience:**

* Submit verification via API
* Receive pass/fail response
* No API changes needed if vendors change

***

### Scenario 2: Multi-Country Expansion

**Situation:**

* Established business expanding from Australia to UK and Singapore
* Need consistent verification across regions
* Volume: 5,000/month split across countries

**FrankieOne May Configure:**

* Geographic routing:
  * Australia → Australian KYC vendor + fallback
  * UK → UK KYC vendor + fallback
  * Singapore → APAC KYC vendor + fallback
* Consistent fallback strategy across regions
* Unified reporting

**Why This Configuration:**

* Optimized for local data coverage
* Regulatory compliance per region
* Consistent customer experience
* Centralized management

**Customer Experience:**

* Same API integration for all countries
* Submit country in API request
* FrankieOne routes to appropriate vendors
* Consistent response format

***

### Scenario 3: High-Risk Vertical (Crypto Exchange)

**Situation:**

* Cryptocurrency exchange
* High regulatory scrutiny
* Need enhanced due diligence
* Fraud prevention critical
* Budget allows for comprehensive verification

**FrankieOne May Configure:**

* Parallel KYC verification (2-3 sources)
* Enhanced IDV with liveness and biometrics
* AML screening (PEP + sanctions)
* Fraud signals (device, email, phone)
* Ongoing monitoring

**Why This Configuration:**

* High-assurance verification
* Multiple independent confirmations
* Comprehensive risk assessment
* Regulatory compliance

**Customer Experience:**

* Submit verification via API
* FrankieOne orchestrates multiple checks
* Receive aggregated pass/fail result
* Access to detailed check results if needed

***

### Scenario 4: Optimizing for Pass Rates

**Situation:**

* Existing customer with 75% pass rate
* Want to improve to 85%
* Currently using single KYC source

**FrankieOne May Recommend:**

1. Analysis of failure reasons
2. Add cascade fallback source
3. Test in UAT
4. Measure pass rate improvement
5. Evaluate cost increase

**Potential Outcome:**

* Pass rate improves to 83%
* Cost per verification increases 15%
* Customer approves change
* FrankieOne deploys to production

**Customer Experience:**

* No API changes required
* Improved pass rates
* Transparent cost increase
* Better customer conversion

***

### Scenario 5: Adding New Verification Type

**Situation:**

* Customer currently doing KYC only
* Want to add document verification (IDV)
* Same API integration preferred

**FrankieOne May Configure:**

1. Add IDV vendor to customer's configuration
2. Configure document routing (passport vs license)
3. Set up liveness detection
4. Configure OCR extraction
5. Test in UAT

**Customer Experience:**

* Same API integration
* New endpoints for IDV (as per OpenAPI spec)
* Consistent authentication
* Unified reporting across KYC and IDV

***

## FAQs

### General

**Q: Can I choose which specific vendor is used for my verifications?**

A: Vendor selection is **configured by FrankieOne** based on your requirements. You cannot select vendors dynamically via API parameters. However, you can work with FrankieOne to:

* Request specific vendors during initial setup
* Understand which vendors are configured for your account
* Request vendor changes if needed

**Q: Can I change vendors after going live?**

A: Yes, but vendor changes are configuration changes managed by FrankieOne:

1. Contact your FrankieOne representative
2. Explain why you want to change vendors
3. FrankieOne will recommend alternatives
4. Test in UAT
5. Deploy to production

Your API integration does not need to change.

**Q: Do I need a separate contract with each vendor?**

A: No:

* Single contract with FrankieOne
* FrankieOne manages all vendor relationships
* Consolidated billing through FrankieOne
* Unified support

**Q: What happens if a vendor has an outage?**

A: Depends on your configuration:

* If fallback is configured, FrankieOne automatically routes to backup vendor
* If no fallback configured, requests may fail
* Discuss resilience requirements with FrankieOne

**Q: How do I know which vendor was used for a specific verification?**

A: FrankieOne can provide:

* Vendor information in API responses (if configured)
* Detailed reporting showing vendor usage
* Audit logs

Check with FrankieOne about available reporting options.

***

### Coverage and Capabilities

**Q: What countries does FrankieOne support?**

A: FrankieOne provides access to data sources in 195+ countries. Specific coverage for your account depends on:

* Which vendors are configured for you
* The verification types you need
* Your budget and volume

Contact FrankieOne to discuss coverage for your target markets.

**Q: Can FrankieOne verify all document types?**

A: FrankieOne connects to IDV vendors that support multiple document types:

* Passports
* Driver licenses
* National ID cards
* Residence permits
* Other government-issued documents

Specific document support depends on:

* Configured vendors
* Country of document issuance
* Document type

**Q: Does FrankieOne support biometric verification?**

A: Yes, FrankieOne connects to IDV vendors that offer:

* Liveness detection
* Face matching
* Document-to-selfie matching

This requires appropriate vendor configuration.

***

### Pricing

**Q: How does FrankieOne pricing work?**

A: **All pricing is determined by your FrankieOne representative** and is customized based on:

* Your specific requirements
* Verification types and volumes
* Geographic coverage needed
* Selected vendors (configured by FrankieOne)
* Contract terms

FrankieOne cannot provide standardized pricing because configurations vary significantly. Contact FrankieOne for accurate pricing.

**Q: Do I pay for failed verifications?**

A: Depends on the vendor and your agreement:

* Some vendors charge for all attempts
* Some vendors charge only for successful matches
* Pricing models vary

Your FrankieOne representative will explain the pricing model for your configured vendors.

**Q: Are there volume discounts?**

A: Yes, volume discounts are typically available:

* Higher volumes generally receive better per-unit pricing
* Discount tiers vary by vendor and contract
* Commitments may unlock better pricing

Contact FrankieOne to discuss volume discounts.

**Q: What if my volume changes?**

A: FrankieOne offers flexible options:

**Volume Increases:**

* May qualify for better pricing tiers
* Can adjust contract terms
* Discuss with your representative

**Volume Decreases:**

* Depends on contract terms
* May need to adjust commitments
* FrankieOne works with you to find solutions

**Best Practice:**

* Provide realistic volume estimates
* Include growth projections
* Discuss flexibility needs upfront

**Q: Are there setup fees?**

A: Depends on configuration complexity:

* Standard configurations may have no setup fees
* Complex custom configurations may have setup fees
* Professional services may be available

Your FrankieOne representative will provide transparent pricing.

***

### Technical

**Q: Do I need to integrate with each vendor separately?**

A: No:

* Single API integration to FrankieOne
* FrankieOne handles all vendor integrations
* Consistent API across all vendors
* No code changes needed when FrankieOne changes your vendor configuration

**Q: How long does vendor configuration take?**

A: Typical timeline:

* Simple: 1-2 weeks
* Standard: 2-4 weeks
* Complex: 4-8 weeks

Depends on:

* Number of vendors
* Complexity of routing
* Testing requirements
* Vendor onboarding needs

**Q: Can I test vendors before committing?**

A: Yes:

* Test in UAT environment
* Use test data via API
* Measure pass rates and performance
* Make informed decision

FrankieOne provides UAT access for testing.

**Q: Can I control routing via API parameters?**

A: No. Routing logic is **configured by FrankieOne**, not controlled via API parameters. To change routing:

1. Contact FrankieOne
2. Request routing changes
3. FrankieOne implements in UAT
4. Test and approve
5. Deploy to production

**Q: What data do I need to provide in the API request?**

A: Required data depends on verification type. Refer to:

* FrankieOne OpenAPI specification for required fields
* Postman collection for example requests
* API documentation at [https://docs.frankieone.com](https://docs.frankieone.com)

Common fields include:

* Entity type (person, organization)
* Name fields
* Address fields
* Date of birth
* Document details (for IDV)

***

### Vendor Selection

**Q: How does FrankieOne recommend vendors?**

A: FrankieOne considers:

**Your Requirements:**

* Geographic coverage
* Verification types
* Pass rate targets
* Budget constraints
* Regulatory requirements

**Vendor Capabilities:**

* Data source coverage
* Verification accuracy
* Response times
* Reliability
* Pricing

**FrankieOne's Experience:**

* Vendor performance data
* Coverage analysis
* Cost benchmarking
* Best practices

**Q: Can I request specific vendors?**

A: Yes:

* Share preferences during requirements gathering
* FrankieOne will evaluate feasibility
* May recommend alternatives if better suited
* Final decision requires FrankieOne approval

**Q: What if I'm already using a specific vendor directly?**

A: FrankieOne may be able to:

* Connect to your existing vendor account
* Or configure FrankieOne's connection to same vendor
* Maintain continuity while adding flexibility

Discuss with FrankieOne during setup.

***

### Pass Rates and Optimization

**Q: What pass rate can I expect?**

A: Pass rates vary based on:

* Data quality you submit via API
* Configured vendors and data sources
* Your customer demographics
* Geographic market
* Verification type

FrankieOne can provide:

* Benchmark pass rates for similar customers
* Estimated pass rates during vendor recommendation
* Actual pass rates during UAT testing
* Ongoing pass rate reporting

**Q: How can I improve my pass rates?**

A: Two approaches:

**1. Improve Data Quality (Customer Action):**

* Submit complete, accurate data via API
* Ensure proper formatting
* Include all available data points
* Standardize address formats

**2. Configuration Changes (FrankieOne Action):**

* Add fallback sources
* Switch primary vendor
* Implement cascade strategy
* Optimize match criteria

Contact FrankieOne to analyze pass rates and discuss optimization options.

**Q: What causes verification failures?**

A: Common reasons:

* No match in configured data sources
* Incomplete data submitted via API
* Data formatting issues
* Customer not in vendor databases
* Vendor service issues

FrankieOne reporting can break down failure reasons.

***

## Summary

### Key Takeaways

**FrankieOne is an Orchestration Platform**

* Single API integration
* Access to 350+ data sources
* Coverage in 195+ countries
* Vendor-agnostic integration

**Vendor Selection is Configured by FrankieOne**

* Not controllable via API parameters
* Based on your requirements
* Considering coverage, cost, and performance
* Customer approves final configuration

**Flexibility Without Code Changes**

* Switch vendors without changing your integration
* Add new verification types
* Expand to new countries
* Optimize based on performance

**Pricing is Customized**

* Determined by FrankieOne representative
* Based on specific requirements
* Varies by volume, coverage, vendors
* Contact FrankieOne for accurate pricing

**Multiple Configuration Strategies**

* Single source (simple, cost-effective)
* Cascade (higher pass rates)
* Parallel (highest confidence)
* Conditional routing (optimized)
* Geographic routing (regional optimization)

**Continuous Optimization**

* Monitor performance through reporting
* Request configuration adjustments
* Test changes in UAT
* Deploy approved changes to production

***

## Next Steps

### 1. Define Your Requirements

Prepare the following information:

* **Geographic coverage:** Which countries?
* **Verification types:** KYC, IDV, AML, KYB, Fraud?
* **Volume:** Expected verifications per month
* **Pass rate targets:** What success rate do you need?
* **Budget:** Cost constraints
* **Regulatory:** Compliance requirements
* **Timeline:** When do you need to go live?

### 2. Contact FrankieOne

Schedule consultation to:

* Discuss your requirements
* Receive vendor recommendations
* Understand routing strategy options
* Get customized pricing proposal
* Plan implementation timeline

### 3. Review Recommendations

FrankieOne will provide:

* Recommended vendors
* Proposed configuration strategy
* Estimated pass rates
* Pricing details
* Implementation plan

### 4. Test in UAT

Once configured:

* Test verification API
* Use real sample data
* Measure actual pass rates
* Validate response formats
* Test error scenarios

### 5. Deploy to Production

After UAT approval:

* FrankieOne activates production configuration
* Begin sending production traffic via API
* Monitor pass rates and costs
* Request optimizations as needed

***

## Resources

**FrankieOne Documentation:**

* API Documentation: [https://docs.frankieone.com](https://docs.frankieone.com)
* OpenAPI Specification: Available from FrankieOne
* Postman Collections: Available from FrankieOne

**Support:**

* Contact your FrankieOne representative
* Technical support for API integration questions
* Configuration change requests

**What to Prepare for Your FrankieOne Call:**

* Your requirements (see "Define Your Requirements" above)
* Target markets / countries
* Expected verification volumes
* Budget constraints
* Current challenges or pain points
* Timeline and go-live date

***

## Final Reminders

### This Document Describes Platform Capabilities

This is a **conceptual guide** explaining how FrankieOne's platform works. It does **not** describe API-controllable features.

**For API Documentation:**

* See FrankieOne's OpenAPI specification
* See API documentation at [https://docs.frankieone.com](https://docs.frankieone.com)
* Use Postman collections for example requests

### Vendor Selection is Configuration, Not API Control

You **cannot** control vendor selection, routing, fallback, or data source cascade through API parameters. These are configured by FrankieOne based on your requirements.

### All Pricing is Customized

Examples in this document are illustrative only. Contact your FrankieOne representative for accurate pricing based on your specific situation.

***

**Document Version:** 1.0\
**Last Updated:** February 2026\
**Document Type:** Conceptual Guide (Non-API)


# KYC IDV and AML Exceptions Guide
Source: https://docs.frankieone.com/v2/api/developers/idv-exceptions

Detailed information on exceptions for IDV, AML and KYC

This guide covers exceptions that can occur during IDV, AML, KYC, and Biometric processes. Use this reference to plan your internal processes for handling these scenarios.

> **Note:** IDV vendors (Daon, Incode, Onfido) have built-in quality gates that prevent submission of poor quality images or fraudulent documents at capture stage. Many technical errors are handled by vendor SDKs before reaching FrankieOne.

***

## Summary

### Primary Resolution Approaches

Before diving into specific exceptions, these are the standard fallback approaches:

| Approach                   | When to Use                                          | Process                                                                                                    |
| -------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Request Alternative ID** | Customer unable to verify with current document      | Direct customer to provide different government-issued ID (e.g., if Passport failed, try Driver's License) |
| **Manual KYC Fallback**    | Automated verification failed after multiple retries | Collect document images via secure upload; process via manual KYC in FrankieOne portal                     |
| **eKYC Form Fallback**     | Biometric/OCR automated flow failed                  | Direct customer to eKYC manual form to enter details and upload documents                                  |

### Workflow Status Values

Understanding the workflow result statuses:

| Status       | Meaning                                            | Typical Action               |
| ------------ | -------------------------------------------------- | ---------------------------- |
| `PASS`       | Successfully completed with passing recommendation | Proceed with onboarding      |
| `REVIEW`     | Results require manual examination                 | Check risks and step details |
| `FAIL`       | Finished with failing recommendation               | Reject or request retry      |
| `INCOMPLETE` | Finished but results are partial                   | May need additional steps    |
| `BLOCKED`    | Cannot complete; manual review needed              | Escalate to operations       |

### Exception Categories at a Glance

| Category          | Typical Handler             | Severity   |
| ----------------- | --------------------------- | ---------- |
| Access Issues     | Customer Support            | Low        |
| Document Issues   | Customer Support            | Low-Medium |
| OCR/Data Mismatch | Customer Support            | Low-Medium |
| Biometric Issues  | Customer Support/Operations | Medium     |
| Technical Issues  | Customer Support/TechOps    | Low-Medium |
| KYC Failures      | Customer Support            | Medium     |
| AML Matches       | Compliance/Operations       | High       |
| Blocklist Matches | Compliance/Operations       | High       |

### Handler Reference

| Handler              | Description                                  |
| -------------------- | -------------------------------------------- |
| **Customer Support** | Your customer-facing support/compliance team |
| **Operations**       | Back-office operations team                  |
| **Compliance**       | Compliance/risk team for regulatory matters  |
| **TechOps**          | Technical operations team                    |
| **FrankieOne**       | Escalate to FrankieOne support               |

***

## IDV - Access Issues

Exceptions related to customers accessing the verification flow.

### URL Access

| Exception            | Description                                             | Handler          | Suggested Approach                                                                                                             |
| -------------------- | ------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Link Expired**     | Customer accessed verification link after expiry period | Customer Support | Generate and send new verification link; adjust expiry time if needed for customer's use case                                  |
| **Link Not Working** | Customer cannot access hosted verification URL          | Customer Support | Verify stable internet connection; try different browser; send new link; provide alternative verification method if persistent |

### Browser Issues

| Exception                 | Description                                     | Handler          | Suggested Approach                                                                                              |
| ------------------------- | ----------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------- |
| **Browser Not Supported** | Customer using outdated or incompatible browser | Customer Support | Direct customer to use Chrome, Safari, Firefox, or Edge (latest versions); provide mobile option as alternative |

### Network Issues

| Exception                      | Description                                       | Handler          | Suggested Approach                                                                                                                          |
| ------------------------------ | ------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Corporate Network Blocking** | Customer's workplace firewall blocking FrankieOne | Customer Support | Ask customer to try from personal device/network; coordinate with customer's IT to whitelist FrankieOne domains; provide alternative method |

***

## IDV - Document Issues

Exceptions related to document capture and validation.

### Document Quality

| Exception                 | Description                                       | Handler          | Suggested Approach                                                                                                              |
| ------------------------- | ------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Poor Image Quality**    | Document image too dark, blurry, or unclear       | Customer Support | Instruct customer to: use good lighting; hold camera steady; ensure document fills frame; place on plain surface; retry capture |
| **Glare or Shadows**      | Reflections or shadows obscuring document details | Customer Support | Instruct customer to: avoid direct overhead lighting; adjust angle; place document flat on dark surface; retry capture          |
| **Document Not Detected** | System cannot recognize document in image         | Customer Support | Instruct customer to: ensure entire document visible in frame; use plain background; avoid hands in frame; retry capture        |

### Document Type

| Exception                   | Description                                              | Handler          | Suggested Approach                                                                                                |
| --------------------------- | -------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Wrong Document Provided** | Customer uploaded different document type than requested | Customer Support | Clarify which document types are accepted; request correct document type; provide list of acceptable alternatives |
| **Document Not Accepted**   | Document type not supported for customer's country       | Customer Support | Explain which documents are accepted for their country; request alternative accepted document type                |

### Document Validity

| Exception            | Description                     | Handler          | Suggested Approach                                                                                                      |
| -------------------- | ------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Expired Document** | Document has passed expiry date | Customer Support | Request current valid (non-expired) document; if customer has no valid ID, escalate to manual KYC with manager approval |

### Document Authenticity (IDV\_DOCUMENT)

IDV document checks validate visual authenticity, image integrity, data validation, and document compromise status.

| Exception                         | Description                                                                               | Handler               | Suggested Approach                                                                                                                        |
| --------------------------------- | ----------------------------------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Suspected Fraudulent Document** | System detected potential document fraud or tampering (status: `SUSPECTED` or `REJECTED`) | Compliance/Operations | Reject application; flag for investigation; request alternative document; escalate to compliance team; may require in-person verification |
| **Photocopied Document**          | Document appears to be photocopy, not original                                            | Customer Support      | Request photo of original physical document; explain requirement for genuine ID; may require manual review                                |

***

## IDV - OCR Issues

Exceptions related to data extraction and matching. OCR extracts data from documents (`IDV_OCR`), then comparison checks this against entity information (`IDV_OCR_COMPARISON`), flagging discrepancies via a `mismatchMap`.

> **Note:** The system uses fuzzy matching logic (Levenshtein distance) to tolerate minor OCR errors before flagging mismatches.

### Data Mismatch

| Exception                         | Description                                           | Handler          | Suggested Approach                                                                                                                                            |
| --------------------------------- | ----------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name Doesn't Match**            | Name on document doesn't match entered information    | Customer Support | Ask customer to verify spelling; check for legal name vs nickname; check for name changes (marriage, maiden name); request correction or alternative document |
| **Date of Birth Doesn't Match**   | DOB on document doesn't match entered information     | Customer Support | Verify DOB format (DD/MM/YYYY vs MM/DD/YYYY); check for typos; request customer verify and correct; may require manual review                                 |
| **Address Doesn't Match**         | Address on document doesn't match entered information | Customer Support | Check for abbreviations (St vs Street); verify current vs previous address; request customer update to match document; may need previous address              |
| **Document Number Doesn't Match** | ID number doesn't match entered information           | Customer Support | Verify document number entry; check for common errors (O vs 0, I vs 1); request customer re-enter carefully                                                   |

### Data Extraction

| Exception                | Description                                       | Handler          | Suggested Approach                                                                                                                |
| ------------------------ | ------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Cannot Read Document** | System unable to extract data from document image | Customer Support | Request better quality image with clear readable text; ensure good lighting and focus; fallback to eKYC manual form if persistent |

***

## IDV - Biometric Issues

Exceptions related to liveness checks and facial matching. IDV results use statuses: `CLEAR`, `SUSPECTED`, or `REJECTED`.

### Liveness Failed (IDV\_FACIAL\_LIVENESS)

| Exception                      | Description                                                          | Handler               | Suggested Approach                                                                                                                         |
| ------------------------------ | -------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Liveness Check Failed**      | System could not verify customer is live person (status: `REJECTED`) | Customer Support      | Instruct customer to: ensure good lighting; look directly at camera; follow on-screen prompts; remove glasses/hat if needed; retry capture |
| **Suspected Fraud - Liveness** | System detected potential spoofing attempt (status: `SUSPECTED`)     | Compliance/Operations | Reject application; flag for fraud investigation; do not proceed with automated verification; escalate to compliance                       |

### Face Match (IDV\_FACIAL\_COMPARISON)

| Exception                       | Description                                                 | Handler                     | Suggested Approach                                                                                                                               |
| ------------------------------- | ----------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Face Doesn't Match Document** | Selfie doesn't match photo on document (status: `REJECTED`) | Customer Support/Operations | Verify customer using correct document; check for significant appearance changes; may require manual review; request more recent ID if available |
| **Low Match Confidence**        | Insufficient confidence in face match (status: `SUSPECTED`) | Customer Support            | Request better quality selfie with good lighting; ensure face clearly visible; retry capture; may require manual review                          |

### Image Quality

| Exception               | Description                               | Handler          | Suggested Approach                                                                                                           |
| ----------------------- | ----------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Poor Selfie Quality** | Selfie image too dark, blurry, or unclear | Customer Support | Instruct customer to: use good lighting; hold camera steady; look directly at camera; ensure face fills frame; retry capture |

### Obstruction

| Exception         | Description                                           | Handler          | Suggested Approach                                                                                        |
| ----------------- | ----------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
| **Face Obscured** | Face partially covered by glasses, hat, mask, or hair | Customer Support | Request customer remove obstructions (sunglasses, hat, scarf); ensure face clearly visible; retry capture |

### Detection

| Exception             | Description                        | Handler          | Suggested Approach                                                                                                       |
| --------------------- | ---------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Face Not Detected** | System cannot detect face in image | Customer Support | Instruct customer to: position face in frame; ensure adequate lighting; look at camera; be alone in frame; retry capture |

### Appearance Change

| Exception                         | Description                                       | Handler    | Suggested Approach                                                                                                           |
| --------------------------------- | ------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Significant Appearance Change** | Customer looks very different from document photo | Operations | May be acceptable if due to aging, weight change, or styling; requires manual review by operator; may request more recent ID |

***

## IDV - Technical Issues

Technical exceptions during the verification process.

### Camera Access

| Exception                    | Description                              | Handler          | Suggested Approach                                                                                                                |
| ---------------------------- | ---------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Camera Permission Denied** | Customer denied camera access in browser | Customer Support | Instruct customer to enable camera permission in browser settings; provide step-by-step guide; fallback to document upload option |
| **No Camera Available**      | Customer's device has no camera          | Customer Support | Provide document upload option; suggest using device with camera (smartphone); fallback to eKYC manual form                       |

### Upload

| Exception         | Description                      | Handler          | Suggested Approach                                                                                                       |
| ----------------- | -------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Upload Failed** | Document or selfie upload failed | Customer Support | Check customer's internet connection; try smaller file size; retry upload; try different browser; escalate if persistent |

### Processing

| Exception                        | Description                                 | Handler                     | Suggested Approach                                                                                                                 |
| -------------------------------- | ------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Verification Taking Too Long** | Processing stuck or timing out              | Customer Support/FrankieOne | Ask customer to wait and retry; check system status; escalate to FrankieOne if widespread; provide alternative verification method |
| **System Error**                 | Generic technical error during verification | FrankieOne                  | Check system health and vendor status; retry; escalate to FrankieOne; provide alternative verification method to customer          |

***

## KYC Exceptions

Exceptions during electronic KYC verification.

### Verification Failed

| Exception                              | Description                                                 | Handler          | Suggested Approach                                                                                                                              |
| -------------------------------------- | ----------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **KYC Failed - No Matches**            | Customer details don't match any data sources               | Customer Support | Verify customer entered correct details (spelling, DOB, address); request previous address; try alternative ID document; escalate to manual KYC |
| **KYC Partial - Insufficient Matches** | Some details matched but not enough for recipe requirements | Customer Support | Request previous address; verify all details correct; try alternative ID document; may require manual KYC                                       |
| **Government ID Verification Failed**  | ID document failed DVS or government verification           | Customer Support | Verify document details entered correctly; check document is current and valid; try alternative government ID; escalate to manual KYC           |

### Data Issues

| Exception                          | Description                                             | Handler          | Suggested Approach                                                                                                                |
| ---------------------------------- | ------------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Name Not Found in Databases**    | Customer's name not found in credit/electoral databases | Customer Support | Verify name spelling and format; check for recent name changes; request previous name; try alternative ID; may require manual KYC |
| **Address Not Found in Databases** | Customer's address not found in databases               | Customer Support | Request previous address; verify address format; check for recent moves; try alternative address; may require manual KYC          |
| **Date of Birth Not Found**        | Customer's DOB not matching records                     | Customer Support | Verify DOB format and accuracy; check for typos; confirm with customer; may indicate data quality issue requiring manual KYC      |

### Credit Header

| Exception                | Description                                        | Handler          | Suggested Approach                                                                                                                                              |
| ------------------------ | -------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Credit Header Failed** | Customer details don't match credit bureau records | Customer Support | Inform customer this doesn't affect credit score; verify details correct; request previous address; try alternative verification method; escalate to manual KYC |

### Technical

| Exception                   | Description                                      | Handler    | Suggested Approach                                                                                                                    |
| --------------------------- | ------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Data Source Unavailable** | Verification data source temporarily unavailable | FrankieOne | Check vendor status; retry when available; use backup data source if configured; notify customer of delay; provide alternative method |

***

## AML Exceptions

Exceptions from Anti-Money Laundering screening. AML screening checks against four categories: PEPs, Sanctions, Adverse Media, and Regulatory/Law Enforcement Watchlists.

### Screening Hits

When AML returns a `HIT` result, compliance teams must classify the match.

| Exception                    | Description                                                      | Handler               | Suggested Approach                                                                                                                                                     |
| ---------------------------- | ---------------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **PEP Match Detected**       | Customer matched to Politically Exposed Person list              | Compliance/Operations | Flag for compliance review; gather additional information; conduct enhanced due diligence; classify via API as `TRUE_POSITIVE_ACCEPT` or `TRUE_POSITIVE_REJECT`        |
| **Sanctions Match Detected** | Customer matched to sanctions list (OFAC, UN, EU, DFAT, etc.)    | Compliance/Operations | Immediate escalation to compliance; do not proceed with onboarding; conduct thorough investigation; classify as `TRUE_POSITIVE_REJECT` unless confirmed false positive |
| **Adverse Media Match**      | Customer matched to negative news (financial crime, fraud, etc.) | Compliance/Operations | Flag for compliance review; investigate media reports; assess risk level; classify appropriately                                                                       |
| **Watchlist Match**          | Customer matched to law enforcement or regulatory watchlist      | Compliance/Operations | Escalate to compliance immediately; conduct investigation; gather additional information; classify based on risk assessment                                            |

### AML Hit Classification

Use the PATCH `/v2/individuals/{entityId}/results/aml` endpoint to classify matches:

| Status                 | When to Use                         |
| ---------------------- | ----------------------------------- |
| `FALSE_POSITIVE`       | Match is a different person         |
| `TRUE_POSITIVE_ACCEPT` | Confirmed match; risk acceptable    |
| `TRUE_POSITIVE_REJECT` | Confirmed match; reject applicant   |
| `UNKNOWN_ACCEPT`       | Identity unclear; proceeding anyway |
| `UNKNOWN_REJECT`       | Identity unclear; declining         |

> **Note:** Re-run the workflow after classification as statuses may change.

### Review Required

| Exception                                | Description                                               | Handler               | Suggested Approach                                                                                                                                                     |
| ---------------------------------------- | --------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Potential AML Match - Low Confidence** | Possible match but low confidence (likely false positive) | Compliance/Operations | Review match details; compare customer information using DOB, nationality, country; classify as `FALSE_POSITIVE` if confirmed; document decision                       |
| **Multiple AML Hits**                    | Customer matched multiple screening lists                 | Compliance/Operations | High priority escalation to compliance; conduct comprehensive investigation; enhanced due diligence required; senior approval needed; classify each match individually |

### Technical

| Exception                | Description                          | Handler    | Suggested Approach                                                                                        |
| ------------------------ | ------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------- |
| **AML Screening Failed** | Technical error during AML screening | FrankieOne | Check AML vendor status; retry screening; escalate if persistent; do not proceed until screening complete |

### Ongoing Monitoring

AML Ongoing Monitoring continuously screens entities after onboarding. When risk status changes, alerts are triggered requiring review.

***

## Blocklist & Duplicate Exceptions

Exceptions from internal matchlist/blocklist and duplicate detection.

### Matchlist/Blocklist Matches

When a matchlist check returns a `HIT`, a `BLOCKLISTED` issue is generated.

| Exception                    | Description                                      | Handler               | Suggested Approach                                                                                                         |
| ---------------------------- | ------------------------------------------------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Blocklist Match Detected** | Customer matched to internal matchlist/blocklist | Compliance/Operations | Review blocklist reason; verify match accuracy; classify as `FALSE_POSITIVE` or `TRUE_POSITIVE_REJECT` via API             |
| **Fraud Blocklist Match**    | Customer matched to known fraudster list         | Compliance/Operations | Reject application immediately; classify as `TRUE_POSITIVE_REJECT`; flag for investigation; do not proceed with onboarding |

**Classification Options:**

* `FALSE_POSITIVE` - Match is incorrect, no risk
* `TRUE_POSITIVE_REJECT` - Match confirmed, reject entity

> **Note:** After classification, re-run the workflow. If all hits are marked `FALSE_POSITIVE`, the step changes to `CLEARED` and the `BLOCKLISTED` issue is removed.

### Duplicate Detection

When the DUPLICATE step finds a match, a `DUPLICATE` issue is generated and the workflow typically goes to `REVIEW`.

| Exception                     | Description                                 | Handler    | Suggested Approach                                                                                       |
| ----------------------------- | ------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------- |
| **Duplicate Entity Detected** | Customer appears to already exist in system | Operations | Review potential duplicate; compare matched fields (name, DOB, document numbers); classify appropriately |

**Classification Options:**

* `FALSE_POSITIVE` - Not a duplicate, no relationship created
* `TRUE_POSITIVE_ACCEPT` - Confirmed duplicate; marks the older entity as duplicate
* `TRUE_POSITIVE_REJECT` - Confirmed duplicate; marks the newer entity as duplicate

> **Note:** After classification, re-run the workflow so the DUPLICATE step can reassess and update the overall status.

***

## Fraud Check Exceptions

Exceptions from the FRAUD workflow step, which evaluates email, phone, device, and IP risk.

### Fraud Hits

When fraud checks return a `HIT` result, issues are generated with `category: FRAUD`.

| Exception               | Type                  | Handler                     | Suggested Approach                                                                                            |
| ----------------------- | --------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Risky Email Address** | `FRAUD_EMAIL_ADDRESS` | Customer Support/Operations | Review email indicators (disposable domain, age, reputation); may request alternative email; classify via API |
| **Risky Phone Number**  | `FRAUD_PHONE_NUMBER`  | Customer Support/Operations | Review phone indicators (VoIP, carrier risk); may request alternative number; classify via API                |
| **Risky Device**        | `FRAUD_DEVICE`        | Operations/Compliance       | Review device signals (emulation, characteristics); higher risk—may require manual review                     |
| **Risky IP Address**    | `FRAUD_IP_ADDRESS`    | Operations/Compliance       | Review IP indicators (VPN, geolocation mismatch); assess if legitimate use case                               |

### Risk Levels

Fraud checks return risk levels: `LOW`, `MEDIUM`, `HIGH`, or `UNACCEPTABLE`.

### Fraud Hit Classification

Use the PATCH `/v2/individuals/{entityId}/results/fraud` endpoint to classify fraud detections:

| Status                 | When to Use                          |
| ---------------------- | ------------------------------------ |
| `FALSE_POSITIVE`       | Signal is incorrect                  |
| `TRUE_POSITIVE_ACCEPT` | Risk acceptable despite fraud signal |
| `TRUE_POSITIVE_REJECT` | Applicant rejection warranted        |

> **Note:** Results automatically become `MARKED_INVALID` or `STALE` when associated data (email/phone) is modified or deleted.

***

## Biometrics - Vendor Specific

Vendor-specific biometric exceptions.

| Exception                         | Description                              | Handler          | Suggested Approach                                                                                                                      |
| --------------------------------- | ---------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Biometric Verification Failed** | Generic biometric failure from vendor    | Customer Support | Request customer retry with better lighting and positioning; try alternative ID document; escalate to manual KYC if persistent failures |
| **Vendor Service Unavailable**    | Biometric vendor temporarily unavailable | TechOps          | Check vendor status page; retry when available; use backup vendor if configured; notify customer of delay; provide alternative method   |

### Manual Override

IDV results can be manually overridden via `PATCH /v2/individuals/{entityId}/results/idv` by updating the `manualStatus` field. Results automatically invalidate (`STALE` or `MARKED_INVALID`) when underlying entity data changes post-verification.

***

## Quick Reference: Escalation Paths

```mermaid theme={null}
flowchart TD
    A["Exception Occurs"] --> B{Exception Type}
    B -->|Access/Technical| C["Customer Support"]
    B -->|Document/OCR| D["Customer Support"]
    B -->|Biometric| E["Customer Support/Operations"]
    B -->|KYC Failed| F["Customer Support → Manual KYC"]
    B -->|AML Match| G["Compliance Team"]
    B -->|Fraud/Blocklist| H["Compliance/Fraud Team"]
    B -->|System Error| I["FrankieOne Support"]

    C --> J{Resolved?}
    D --> J
    E --> J
    J -->|No| K["Escalate to Operations/Manual KYC"]
    J -->|Yes| L["Continue Onboarding"]

    G --> M["Enhanced Due Diligence"]
    H --> N["Reject/Investigate"]
```

***

## Support

* **Documentation**: [docs.frankieone.com](https://docs.frankieone.com)
* **Support**: Contact your FrankieOne representative


# Predefined Workflows
Source: https://docs.frankieone.com/v2/api/developers/predefined-workflows

This guide provides a reference to FrankieOne's standard workflow bundles — pre-configured verification workflows designed to meet common compliance requirements across different regions and risk levels.

## Document Overview

**What You'll Learn:**

* Available standard workflow bundles and their intended use cases
* Workflow IDs and naming conventions
* How workflows are configured and customised
* Differences between V2 workflows and V1 entity profiles (recipes)

**Who Should Read This:**

* Developers implementing FrankieOne
* Compliance teams selecting appropriate workflows
* Product managers planning verification requirements

> **Note:** This guide covers V2 workflows (current standard). V1 references are included for context. See [V1 Entity Profiles (Recipes)](#v1-entity-profiles-recipes) for legacy details.

***

## Table of Contents

1. [Understanding Workflow Bundles](#understanding-workflow-bundles)
2. [Workflow ID Naming Convention](#workflow-id-naming-convention)
3. [Discovering Available Workflows](#discovering-available-workflows)
4. [Australian (AU) Workflows](#australian-au-workflows)
5. [New Zealand (NZ) Workflows](#new-zealand-nz-workflows)
6. [United States (US) Workflows](#united-states-us-workflows)
7. [United Kingdom (UK) Workflows](#united-kingdom-uk-workflows)
8. [Specialised Workflows](#specialised-workflows)
9. [Choosing the Right Workflow](#choosing-the-right-workflow)
10. [How Workflows Are Configured](#how-workflows-are-configured)
11. [V1 Entity Profiles (Recipes)](#v1-entity-profiles-recipes)
12. [FAQs](#faqs)

***

## Understanding Workflow Bundles

### What is a Workflow Bundle?

A workflow bundle is a pre-configured verification workflow that combines multiple checks in a specific order to meet common compliance requirements. Workflow bundles are configured and managed by FrankieOne — they are not self-service editable via the API or Portal.

### Bundle Categories

FrankieOne organises workflow bundles into two main categories:

**Essential Bundles** — Standard customer due diligence for low-to-medium risk scenarios.

* Foundational identity verification
* Standard AML screening (PEP & Sanctions)
* Electronic verification (KYC checks)
* Optional document verification
* Suitable for high-volume operations

**Enhanced Bundles** — For higher-risk environments requiring stronger identity assurance.

* Mandatory document verification (IDV)
* Biometric checks (liveness, face match)
* Enhanced AML screening (includes Adverse Media)
* Multiple data source verification

### Workflow Components

Every workflow bundle contains a combination of these check types:

| Check Type          | Description                                    | Essential | Enhanced  |
| ------------------- | ---------------------------------------------- | --------- | --------- |
| **Blocklist**       | Checks against your internal blocklist         | ✓         | ✓         |
| **KYC**             | Verifies identity details against data sources | ✓         | ✓         |
| **Government ID**   | Verifies government-issued ID number           | Optional  | ✓         |
| **IDV**             | Validates document authenticity & biometrics   | Optional  | Mandatory |
| **AML (Standard)**  | Screens PEP & Sanctions lists                  | ✓         | —         |
| **AML (Enhanced)**  | Screens PEP, Sanctions & Adverse Media         | —         | ✓         |
| **Risk Assessment** | Calculates overall risk score                  | ✓         | ✓         |

> **Note:** The specific checks, data sources, and routing within a workflow are configured by FrankieOne. These are not dynamically controlled via the API. Contact your FrankieOne representative to discuss workflow composition.

***

## Workflow ID Naming Convention

All standard workflow IDs follow a consistent structure:

```
{COUNTRY}-{TIER}{SOURCES}V-{TYPE}
```

| Component    | Values                                        | Description                    |
| ------------ | --------------------------------------------- | ------------------------------ |
| `{COUNTRY}`  | `AUS`, `NZL`, `USA`, `GBR`                    | Three-letter country code      |
| `{TIER}`     | `Basic`, `Advanced`                           | Essential or Enhanced tier     |
| `{SOURCES}V` | `1V`, `2V`, `3V`                              | Number of verification sources |
| `{TYPE}`     | `IDOnly`, `TwoPlus`, `TwoPlusID`, `AgeVerify` | Verification method            |

**Examples:**

| Workflow ID             | Meaning                                                                   |
| ----------------------- | ------------------------------------------------------------------------- |
| `AUS-Basic2V-TwoPlus`   | Australia, Essential tier, two sources, electronic verification           |
| `USA-Advanced1V-IDOnly` | United States, Enhanced tier, one source, ID + biometric verification     |
| `GBR-Basic2V-TwoPlusID` | United Kingdom, Essential tier, two sources, electronic + ID verification |

***

## Discovering Available Workflows

You can retrieve the list of workflows available to your account using the V2 API.

**Endpoint:**

```
GET /v2/workflows
```

**Required Headers:**

| Header                 | Required | Description                             |
| ---------------------- | -------- | --------------------------------------- |
| `api_key`              | Yes      | Your API key provided by FrankieOne     |
| `X-Frankie-CustomerID` | Yes      | Your Customer ID provided by FrankieOne |

**Optional Headers:**

| Header                      | Description                                           |
| --------------------------- | ----------------------------------------------------- |
| `X-Frankie-CustomerChildID` | Child account identifier for multi-tenant setups      |
| `X-Frankie-Channel`         | Channel identifier (e.g., `api`, `portal`, `smartui`) |
| `X-Frankie-Username`        | Username of the API caller                            |

**Optional Query Parameters:**

| Parameter     | Description                                              |
| ------------- | -------------------------------------------------------- |
| `serviceName` | Filter workflows by service name                         |
| `include`     | Include additional detail; supports `workflowDefinition` |

The response returns an array of workflow objects, each containing `serviceName`, `workflowId`, `workflowName`, `type`, and `lifecyclePhase`.

> **Note:** The workflows available to your account depend on your FrankieOne configuration. Not all workflow IDs listed in this guide may be available. Use this endpoint to confirm which workflows are configured for your account.

***

## Australian (AU) Workflows

Australia has the most comprehensive range of workflow bundles, designed to meet Australian AML/CTF requirements.

### Essential AU Bundles

#### 1. AU Essential Identity (ID Only)

|                 |                                            |
| --------------- | ------------------------------------------ |
| **Workflow ID** | `AUS-Basic1V-IDOnly`                       |
| **Common Name** | Basic ID Check, Government ID Verification |

**What It Does:** Verifies a single government-issued ID against the Document Verification Service (DVS). Performs standard AML screening (PEP & Sanctions) and calculates a risk assessment.

**Checks Included:** Blocklist, Government ID verification (DVS), AML screening (PEP & Sanctions), Risk assessment.

**Typical Use Cases:** Low-risk digital onboarding, e-commerce platforms, digital service sign-ups.

***

#### 2. AU Essential Identity — Two Sources

|                 |                                           |
| --------------- | ----------------------------------------- |
| **Workflow ID** | `AUS-Basic2V-TwoPlus`                     |
| **Common Name** | 2+2 Verification, Electronic Verification |

**What It Does:** Matches customer data against two independent electronic data sources to meet standard 2+2 verification requirements. No document scanning required. Performs standard AML screening.

**Checks Included:** Blocklist, KYC check (2+2 rule — verifies against 2 data sources), AML screening (PEP & Sanctions), Risk assessment.

**Typical Use Cases:** Standard bank account opening, credit applications, insurance onboarding, utility account setup.

> **Note:** The specific data sources used (e.g., credit bureaus, electoral rolls) are configured by FrankieOne and may vary by customer.

***

#### 3. AU Essential Identity — Two Sources & ID

|                 |                                               |
| --------------- | --------------------------------------------- |
| **Workflow ID** | `AUS-Basic2V-TwoPlusID`                       |
| **Common Name** | 2+2 Plus ID, Enhanced Electronic Verification |

**What It Does:** Combines 2+2 electronic verification with a government ID check for a higher level of assurance.

**Checks Included:** Blocklist, Government ID verification (DVS), KYC check (2+2 rule), AML screening (PEP & Sanctions), Risk assessment.

**Typical Use Cases:** Mortgage applications, investment accounts, higher-value transactions, regulated financial products.

***

#### 4. AU Essential Identity — Three Sources

|                 |                                         |
| --------------- | --------------------------------------- |
| **Workflow ID** | `AUS-Basic3V-TwoPlus`                   |
| **Common Name** | Extended 2+2, Three Source Verification |

**What It Does:** Uses three independent data sources for verification. Provides a fallback when initial two sources don't yield results. Useful for customers with thin credit files.

**Checks Included:** Blocklist, KYC check (2+2 rule with 3 sources), AML screening (PEP & Sanctions), Risk assessment.

**Typical Use Cases:** First-time credit applicants, customers with thin credit files, recent immigrants, fallback verification.

***

### Enhanced AU Bundles

#### 5. AU Enhanced Identity (ID Only)

|                 |                                                  |
| --------------- | ------------------------------------------------ |
| **Workflow ID** | `AUS-Advanced1V-IDOnly`                          |
| **Common Name** | Enhanced ID Verification, Biometric Verification |

**What It Does:** Mandatory government ID verification and IDV (document authenticity + biometric checks). Enhanced AML screening including Adverse Media.

**Checks Included:** Blocklist, Government ID verification (DVS), IDV (document authenticity, liveness detection, face match), Enhanced AML screening (PEP, Sanctions, Adverse Media), Risk assessment.

**Typical Use Cases:** Cryptocurrency exchanges, high-value lending, wealth management, international money transfers.

***

#### 6. AU Enhanced Identity — Three Sources & ID

|                 |                                                   |
| --------------- | ------------------------------------------------- |
| **Workflow ID** | `AUS-Advanced3V-TwoPlusID`                        |
| **Common Name** | Maximum Verification, Comprehensive Due Diligence |

**What It Does:** The most thorough verification bundle available. Combines government ID, biometrics, enhanced AML, and three data sources.

**Checks Included:** Blocklist, Government ID verification (DVS), KYC check (2+2 rule with 3 sources), IDV (document authenticity, liveness, face match), Enhanced AML screening (PEP, Sanctions, Adverse Media), Risk assessment.

**Typical Use Cases:** Private banking, high-net-worth individuals, large cryptocurrency transactions.

***

### Specialised AU Bundles

#### 7. AU Age Verification

|                 |                             |
| --------------- | --------------------------- |
| **Workflow ID** | `AUS-Basic3V-AgeVerify`     |
| **Common Name** | Age Check, 18+ Verification |

**What It Does:** Specialised workflow for age verification. Confirms the customer is above a specified age. Verifies date of birth against multiple data sources. Does not perform full identity verification.

**Checks Included:** Blocklist, KYC check (age verification focus), AML screening (PEP & Sanctions), Risk assessment.

**Typical Use Cases:** Online gambling, alcohol delivery, tobacco e-commerce, age-restricted digital services.

***

## New Zealand (NZ) Workflows

New Zealand bundles are similar to Australian bundles but use NZ-specific data sources.

| Workflow ID                | Type      | Description                     |
| -------------------------- | --------- | ------------------------------- |
| `NZL-Basic1V-IDOnly`       | Essential | Government ID verification only |
| `NZL-Basic2V-TwoPlus`      | Essential | Electronic 2+2 verification     |
| `NZL-Basic2V-TwoPlusID`    | Essential | Electronic + ID verification    |
| `NZL-Advanced1V-IDOnly`    | Enhanced  | ID + biometric verification     |
| `NZL-Advanced3V-TwoPlusID` | Enhanced  | Maximum verification            |

Check composition follows the same pattern as the equivalent AU workflows. Data sources are NZ-specific and configured by FrankieOne.

***

## United States (US) Workflows

US bundles are designed to meet US regulatory requirements and use US-specific data sources.

| Workflow ID                | Type        | Description                                              |
| -------------------------- | ----------- | -------------------------------------------------------- |
| `USA-Basic1V-IDOnly`       | Essential   | Government ID verification only                          |
| `USA-Basic2V-TwoPlus`      | Essential   | Electronic verification                                  |
| `USA-Basic2V-TwoPlusID`    | Essential   | Electronic + ID verification                             |
| `USA-Advanced1V-IDOnly`    | Enhanced    | ID + biometric verification (may include OFAC screening) |
| `USA-Advanced3V-TwoPlusID` | Enhanced    | Maximum verification                                     |
| `USA-eID-Express`          | Specialised | Identity verification with prefilled data                |

### US eID Express (Prefill)

|                 |                                            |
| --------------- | ------------------------------------------ |
| **Workflow ID** | `USA-eID-Express`                          |
| **Common Name** | Instant Verification, Prefill Verification |

**What It Does:** Provides identity verification with prefilled data. Given minimal input (e.g., mobile number and date of birth), FrankieOne can retrieve and prefill additional identity fields such as name and SSN from verified data sources, reducing friction in the onboarding flow.

**Checks Included:** Blocklist, eID verification (prefill), AML screening (PEP & Sanctions), Risk assessment.

**How It Works:** The customer provides minimal identifying information. FrankieOne retrieves and prefills additional identity data from verified sources. The customer confirms or corrects the prefilled information. Identity verification and AML screening are then performed.

**Typical Use Cases:** FinTech applications, digital wallets, instant account opening, low-friction onboarding flows.

> **Note:** The specific data sources and fields available for prefill are configured by FrankieOne and may vary. Contact your representative for details.

***

## United Kingdom (UK) Workflows

UK bundles are designed to meet UK regulatory requirements, including FCA requirements for customer due diligence.

| Workflow ID                | Type      | Description                     |
| -------------------------- | --------- | ------------------------------- |
| `GBR-Basic1V-IDOnly`       | Essential | Government ID verification only |
| `GBR-Basic2V-TwoPlus`      | Essential | Electronic verification         |
| `GBR-Basic2V-TwoPlusID`    | Essential | Electronic + ID verification    |
| `GBR-Advanced1V-IDOnly`    | Enhanced  | ID + biometric verification     |
| `GBR-Advanced3V-TwoPlusID` | Enhanced  | Maximum verification            |

Check composition follows the same pattern as AU workflows. Data sources are UK-specific and configured by FrankieOne.

***

## Specialised Workflows

### AML-Only Workflows

| Workflow ID         | Description                                                                       |
| ------------------- | --------------------------------------------------------------------------------- |
| `AML-Only-Standard` | AML screening only (PEP & Sanctions). No identity verification.                   |
| `AML-Only-Enhanced` | Enhanced AML screening (PEP, Sanctions, Adverse Media). No identity verification. |

Use these for re-screening existing customers or performing standalone AML checks on already-verified entities.

### Ongoing Monitoring

FrankieOne supports ongoing AML monitoring. Once enabled for an entity, FrankieOne automatically screens the entity periodically and can send alerts on status changes (e.g., if the entity is added to a sanctions list).

Monitoring is managed via the V2 API:

```
PATCH /v2/individuals/{entityId}/monitor?enabled={true|false}&monitoringTypes={AML|ACTIVITY}
```

The `enabled` query parameter (required) toggles monitoring on or off. The `monitoringTypes` query parameter specifies the type of monitoring (`AML`, `ACTIVITY`, or omit to apply to all types). The request body accepts an optional `comment` object.

> **Note:** Monitoring configuration (frequency, alert thresholds) is managed by FrankieOne, not controlled via the API.

### Re-Verification

**Workflow ID pattern:** `Refresh-KYC-{Country}`

Re-verifies existing customers by running updated KYC and AML checks. Use for periodic re-verification or when customer information has changed.

> **Note:** The specific workflow IDs listed in this section (AML-Only, Monitoring, Refresh-KYC) are representative. Use `GET /v2/workflows` to confirm which workflows are configured for your account.

***

## Choosing the Right Workflow

### Decision Framework

**Step 1: Identify Your Region**

| Region         | Workflow Prefix |
| -------------- | --------------- |
| Australia      | `AUS-`          |
| New Zealand    | `NZL-`          |
| United States  | `USA-`          |
| United Kingdom | `GBR-`          |

**Step 2: Determine Risk Level**

| Risk Level | Bundle Type                    | When to Use                                               |
| ---------- | ------------------------------ | --------------------------------------------------------- |
| Low        | Essential                      | Standard customers, low-value transactions                |
| Medium     | Essential with ID              | Medium-value transactions, regulatory requirements for ID |
| High       | Enhanced                       | High-value transactions, regulated industries             |
| Very High  | Enhanced with multiple sources | Maximum due diligence, highest-risk scenarios             |

**Step 3: Choose Verification Method**

| Method           | Workflow Type        | Pros                          | Cons                           |
| ---------------- | -------------------- | ----------------------------- | ------------------------------ |
| ID Only          | `{TIER}1V-IDOnly`    | Fast, simple                  | Requires government ID         |
| Electronic (2+2) | `{TIER}2V-TwoPlus`   | No document needed            | May not work for all customers |
| Electronic + ID  | `{TIER}2V-TwoPlusID` | Higher assurance              | Requires ID and data match     |
| Extended         | `{TIER}3V-TwoPlusID` | Works for thin-file customers | Higher cost                    |

**Step 4: Consider Special Requirements**

| Requirement               | Workflow                                              |
| ------------------------- | ----------------------------------------------------- |
| Age verification only     | `AUS-Basic3V-AgeVerify`                               |
| Instant verification (US) | `USA-eID-Express`                                     |
| AML screening only        | `AML-Only-Standard` or `AML-Only-Enhanced`            |
| Ongoing monitoring        | Enable via `PATCH /v2/individuals/{entityId}/monitor` |
| Re-verification           | `Refresh-KYC-{Country}`                               |

### Example Scenarios

**Australian E-Commerce (age-gated products):** `AUS-Basic3V-AgeVerify` — designed for age verification, no document upload, suitable for high volume.

**US Cryptocurrency Exchange:** `USA-Advanced1V-IDOnly` or `USA-Advanced3V-TwoPlusID` — mandatory document and biometric verification, enhanced AML screening.

**Australian Digital Bank:** `AUS-Basic2V-TwoPlus` as primary, with `AUS-Basic2V-TwoPlusID` as a fallback — meets 2+2 requirements, electronic verification for most customers.

**UK Wealth Management:** `GBR-Advanced3V-TwoPlusID` — maximum verification, enhanced AML, designed for FCA enhanced due diligence.

**US FinTech App:** `USA-eID-Express` — prefill-based verification, no document upload, low-friction onboarding.

***

## How Workflows Are Configured

Workflows in V2 are configured and managed by FrankieOne. They are **not self-service editable** via the API or Portal.

**To customise a workflow:**

1. Contact your FrankieOne representative.
2. Discuss your requirements (checks needed, risk thresholds, data sources, regulatory obligations).
3. FrankieOne configures or modifies the workflow.
4. Test in UAT, then deploy to production.

**What can be customised:**

* Add or remove checks
* Change check order
* Adjust pass/fail thresholds
* Modify data sources
* Create custom workflows
* Clone and modify standard bundles

**Timelines:**

* Simple changes: 1–2 business days
* Standard customisations: 3–5 business days
* Complex customisations: 5–10 business days

***

## V1 Entity Profiles (Recipes)

> **Note:** V1 is the legacy API. V2 is recommended for all new integrations. Both remain supported.

### Key Differences

| Aspect                   | V1 (Legacy)                   | V2 (Current)                   |
| ------------------------ | ----------------------------- | ------------------------------ |
| **Terminology**          | Entity Profiles / Recipes     | Workflows / Workflow Bundles   |
| **Self-Service Editing** | No — configured by FrankieOne | No — configured by FrankieOne  |
| **Naming**               | Custom names per customer     | Standardised naming convention |
| **Execution**            | Assign profile to entity      | Execute workflow on entity     |
| **Portal**               | View profiles in Portal       | View workflows in Portal       |

### V1 Portal Access

| Environment | Portal URL                             |
| ----------- | -------------------------------------- |
| Production  | `https://portal.frankie.one/login`     |
| UAT         | `https://portal.uat.frankie.one/login` |

In V1, you can view your entity profiles (recipes) in the Portal under **Settings → Workflow Builder**. Profiles are configured by FrankieOne — contact your representative for any changes.

### V1 API Base URLs

| Environment | Base URL                                                  |
| ----------- | --------------------------------------------------------- |
| Production  | `https://api.kycaml.frankiefinancial.io/compliance/v1.2/` |
| UAT         | `https://api.kycaml.uat.frankiefinancial.io/`             |

### Should You Migrate to V2?

V2 is the current standard. Benefits include standardised naming, improved documentation, and a more consistent structure. Migration is available — contact your FrankieOne representative to plan the process.

***

## FAQs

**Can I use multiple workflows for different customer types?**
Yes. You can configure different workflows for different customer segments, products, or risk levels. Each workflow execution is independent.

**Can I run multiple workflows on the same entity?**
Yes. You can execute different workflows on the same entity — for example, an onboarding workflow followed by a monitoring workflow. Each execution is independent.

**Can I edit workflows myself?**
No. Workflows are configured by FrankieOne in both V1 and V2. Contact your FrankieOne representative to request changes.

**How do I know which workflows are available to my account?**
Use the `GET /v2/workflows` endpoint. This returns the list of workflows configured for your account.

**What if I need a workflow for a country not listed here?**
FrankieOne supports verification in 200+ countries. Contact your representative to discuss country-specific workflow configuration.

**Can I test workflows before production?**
Yes. Always test in the UAT environment first. V2 UAT base URL: `https://api.uat.frankie.one`. V2 UAT Portal: `https://portal.uat.frankie.one/login`.

**How much do different workflows cost?**
Pricing varies by workflow and check composition. Contact your FrankieOne representative for specific pricing.

***

## Environments

### V2 (Current)

| Environment | API Base URL                  | Portal URL                             |
| ----------- | ----------------------------- | -------------------------------------- |
| Production  | `https://api.frankie.one`     | `https://portal.frankie.one/login`     |
| UAT         | `https://api.uat.frankie.one` | `https://portal.uat.frankie.one/login` |

### V1 (Legacy)

| Environment | API Base URL                                              | Portal URL                             |
| ----------- | --------------------------------------------------------- | -------------------------------------- |
| Production  | `https://api.kycaml.frankiefinancial.io/compliance/v1.2/` | `https://portal.frankie.one/login`     |
| UAT         | `https://api.kycaml.uat.frankiefinancial.io/`             | `https://portal.uat.frankie.one/login` |

***

## Getting Help

**Contact:** Email [help@frankieone.com](mailto:help@frankieone.com) or your FrankieOne representative.

When contacting support, include your Customer ID (`X-Frankie-CustomerID`), the workflow ID in question, and a description of what you're trying to achieve.

**Resources:**

* API Documentation: [https://docs.frankieone.com](https://docs.frankieone.com)
* V2 Production Portal: [https://portal.frankie.one/login](https://portal.frankie.one/login)
* V2 UAT Portal: [https://portal.uat.frankie.one/login](https://portal.uat.frankie.one/login)


# Troubleshooting Environment Access
Source: https://docs.frankieone.com/v2/api/developers/troubleshoot

Resolve common issues when accessing FrankieOne environments and making API calls.

## Getting Your Credentials

When you start working with FrankieOne, you receive your credentials via a secure 1Password link. This package includes the following for each environment (UAT and Production):

* **Customer ID** — your primary account identifier (UUID format)
* **API Key** — your secret authentication token
* **Child ID** (if applicable) — issued when your account uses child entities
* **Portal URL**
* **API Base URL**

<Note>
  FrankieOne typically sets up the UAT environment first. The UAT environment is not connected to real production data or live data sources — mock sources such as testbed are used for testing purposes.
</Note>

## Understanding Your Credentials

### Customer ID (Required)

Your primary account identifier. Required for all API calls.

**Format:** UUID (e.g., `12345678-1234-1234-1234-123456789012`)

### API Key (Required)

Your secret authentication token. Keep this secure and never share it publicly.

**Format:** Long alphanumeric string (e.g., `245c765b124a098d09ef8765....`)

### Child ID (Optional)

Only required if your account uses child entities. A Child ID is issued when:

* You are accessing the service as part of an organisational division (e.g., regional or country division).
* You are acting as an agent of a service that uses FrankieOne for their KYC/AML needs.

**Format:** UUID (e.g., `87654321-4321-4321-4321-210987654321`)

## Setting Up API Authentication

### Required Headers

All API requests must include these headers:

```
X-Frankie-CustomerID: YOUR_CUSTOMER_ID
api_key: YOUR_API_KEY
```

### If You Have a Child Account

If you have been provided with a Child ID, you must also include it:

```
X-Frankie-CustomerID: YOUR_CUSTOMER_ID
X-Frankie-CustomerChildID: YOUR_CHILD_ID
api_key: YOUR_API_KEY
```

### Header Format Requirements

<Warning>
  Headers are case-sensitive and must be formatted exactly as shown.
</Warning>

**Correct:**

| Header                      | Notes                         |
| --------------------------- | ----------------------------- |
| `X-Frankie-CustomerID`      | Uppercase `ID` at the end     |
| `X-Frankie-CustomerChildID` | Uppercase `ID` at the end     |
| `api_key`                   | All lowercase with underscore |

**Incorrect (common mistakes):**

| Incorrect Header        | Issue                            |
| ----------------------- | -------------------------------- |
| `X-Frankie-CustomerId`  | Wrong case — `Id` should be `ID` |
| `X-Frankie-Customer-ID` | Extra hyphen                     |
| `api-key`               | Hyphen instead of underscore     |
| `API_KEY`               | Wrong case                       |

## Environment URLs

Ensure you are using the correct URLs for your environment.

### UAT Environment

| Resource     | URL                              |
| ------------ | -------------------------------- |
| API Base URL | `https://api.uat.frankie.one`    |
| Portal URL   | `https://portal.uat.frankie.one` |

### Production Environment

| Resource     | URL                                |
| ------------ | ---------------------------------- |
| API Base URL | `https://api.frankie.one`          |
| Portal URL   | `https://portal.frankie.one/login` |

All V2 API paths are prefixed with `/v2` (e.g., `https://api.uat.frankie.one/v2/individuals`).

<Warning>
  Using UAT credentials with Production URLs (or vice versa) causes authentication failures. Always ensure your credentials match your environment.
</Warning>

## Common Authentication Issues

### Issue 1: Unauthorized (401)

**Error codes:** `AUTH-0002` or `AUTH-0401`

**Possible causes:**

* Incorrect API key or Customer ID
* Missing Child ID when one is required
* Wrong environment (UAT credentials sent to Production, or vice versa)
* Case sensitivity errors in header names

**Troubleshooting steps:**

1. **Verify header names** — check that header names are exactly correct with proper capitalisation: `X-Frankie-CustomerID` (not `X-Frankie-CustomerId`), `api_key` (not `API_KEY` or `api-key`).
2. **Check for extra spaces** — ensure there are no leading or trailing spaces in your credentials.
3. **Verify complete credentials** — make sure you have copied the entire API key. These are long strings and can be accidentally truncated.
4. **Confirm environment match** — UAT credentials must be used with the UAT URL, and Production credentials with the Production URL.
5. **Check Child ID requirement** — if you have a Child ID, you must include the `X-Frankie-CustomerChildID` header.

### Issue 2: Bad Request (400)

**Error code:** `API-0400`

**Possible causes:**

* Malformed UUID format
* Special characters in credentials
* Incorrect header format

**Troubleshooting steps:**

1. **Validate UUID format** — Customer IDs and Child IDs should be in standard UUID format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` (lowercase hexadecimal characters with hyphens in specific positions).
2. **Check for copy-paste issues** — when copying from 1Password or email, do not include surrounding quotes, line breaks, or hidden characters.

### Issue 3: Forbidden (403)

**Possible causes:**

* Attempting to access a child account's data from a parent account without proper permissions
* Attempting unauthorised operations
* Account permissions not properly configured

**Solution:** Contact FrankieOne support to verify your account permissions and access levels.

### Issue 4: Not Seeing Entities in Portal

**Scenario:** You have made API calls successfully but do not see the entities in the Portal.

**Possible causes:**

* If your API calls include a Child ID, you need to be viewing the child account in the Portal — not the parent account.
* Parent accounts can view child account data, but child accounts cannot view parent account data or other child accounts' data.

**Solution:**

1. Check the account dropdown in the top-right corner of the Portal.
2. If your API calls use a Child ID, switch to that child account view. If your API calls use only the Customer ID (parent), ensure you are in the parent account view.
3. Verify the entity was created by checking the API response for the entity ID and searching for it in the Portal.

## Portal Access

### Requesting Portal Access

If you have not been provided with Portal access, contact FrankieOne support at [help@frankieone.com](mailto:help@frankieone.com) with:

* Your name and email address
* The environment you need access to (UAT, Production, or both)
* Whether you need parent or child account access

### Parent and Child Accounts in the Portal

**Parent Account:**

* Can view all child account data
* Can act as a child account
* Has administrative capabilities and can manage users across all accounts

**Child Account:**

* Has its own API key
* Cannot see parent account data or other child accounts' data
* Can have separate billing
* Restricted to its own data view

<Note>
  For security, users in a child account cannot view or assign users from the parent account by default.
</Note>

## Testing Your Connection

Use this API call to verify your credentials are working:

```bash theme={null}
curl --location 'https://api.uat.frankie.one/v2/kyc/ruok' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerID: YOUR_CUSTOMER_ID'
```

**Expected response (HTTP 200):**

```json theme={null}
{
  "status": "ok"
}
```

If you receive this response, your credentials are correctly configured.

<Note>
  The `/v2/kyc/ruok` endpoint is a convenience health-check endpoint. It may not appear in the OpenAPI specification.
</Note>

## Troubleshooting Checklist

When experiencing access issues, check these items in order:

1. Are you using the correct environment URL (UAT vs Production)?
2. Are your header names exactly correct (case-sensitive)?
3. Have you copied the complete API key without truncation?
4. Are there any extra spaces in your credentials?
5. If you have a Child ID, are you including it in the `X-Frankie-CustomerChildID` header?
6. Are your credentials for the correct environment?
7. If using the Portal, are you viewing the correct account (parent vs child)?
8. Have you been granted Portal access for the environment you are trying to access?

## Understanding API Error Responses

### Error Response Structure

FrankieOne API errors follow this structure:

```json theme={null}
{
  "requestId": "0123456789ABCDEFGHIJKLMNOP",
  "errorCode": "AUTH-0002",
  "errorMsg": "Unauthorized",
  "details": [
    {
      "issue": "Invalid Authentication provided. Access denied.",
      "issueLocation": "request"
    }
  ]
}
```

The `details` array provides additional diagnostic information. Each entry includes an `issue` description and an `issueLocation` indicating where the problem was detected.

### Error Code Prefixes

The prefix of an error code indicates the domain of the issue:

| Prefix | Meaning                                             |
| ------ | --------------------------------------------------- |
| `AUTH` | Authorisation and security related errors           |
| `API`  | Errors in the API request (incorrectly constructed) |
| `VAL`  | API data validation errors                          |
| `SYS`  | System-level errors                                 |
| `ENT`  | Errors related to entity functions                  |
| `DOC`  | Errors related to document functions                |

### Common Authentication Error Codes

| Error Code  | HTTP Status | Description                                     |
| ----------- | ----------- | ----------------------------------------------- |
| `AUTH-0002` | 401         | Invalid authentication provided. Access denied. |
| `AUTH-0401` | 401         | No API key provided. Access denied.             |
| `API-0400`  | 400         | Parsing credentials failed — invalid format     |
| `ENT-1029`  | 401         | Attempt to access unauthorised data             |

For a complete list of error codes, see the [Error Codes reference](https://docs.frankieone.com/reference/error-codes).

## Getting Help

### When to Contact FrankieOne Support

Contact [help@frankieone.com](mailto:help@frankieone.com) if:

* You have not received your credentials.
* You need Portal access.
* You are consistently getting authentication errors after verifying all credentials.
* You need to confirm whether you should have a Child ID.
* You need to verify your account configuration.
* You need parent/child account permissions adjusted.

### Information to Provide

When contacting support about access issues, include:

* The environment you are trying to access (UAT or Production)
* The error message you are receiving (including the error code)
* Whether you are trying to access via API or Portal
* Your Customer ID (safe to share)
* Whether you have a Child ID
* The exact headers you are using (**without** the actual API key value)
* A sample `curl` command or API request (with credentials redacted)

<Warning>
  Do **not** share your actual API key or password.
</Warning>

## Best Practices

* **Store credentials securely** — use environment variables or a secure credential management system.
* **Never commit credentials** — do not commit API keys to version control.
* **Use environment-specific credentials** — keep UAT and Production credentials separate.
* **Test in UAT first** — always test your integration in UAT before moving to Production.
* **Verify environment URLs** — double-check you are using the correct URL for your environment.
* **Keep credentials updated** — if credentials are rotated, update them immediately in all systems.

## Additional Resources

* [API Authentication Documentation](https://docs.frankieone.com/reference/authentication)
* [Getting Started Guide](https://docs.frankieone.com/docs/getting-started)
* [API Error Codes](https://docs.frankieone.com/reference/error-codes)
* [Support Portal](https://frankieone.atlassian.net/servicedesk/customer/portal/3)


# FrankieOne Release Approach
Source: https://docs.frankieone.com/docs/frankies-release-process

How FrankieOne goes about updating our product and what that means for you.

Our service is designed in such a way that we can push out updates to the service as needed with zero downtime. However, we also respect the fact that our customers need stability & sustainability, and so we generally only push updates during quiet periods.

FrankieOne generally has a policy of fail-forward. But in the unlikely event of a potential service disruption, we will roll back to a previous deployment to not impact on our customers. To do so, we make use of the same process for the deployment of new services, except we simply push the previous revision of the system, thus restoring the service to previous levels.


# FrankieOne Release Notes
Source: https://docs.frankieone.com/docs/release-notes



<Update label="07 Sep 2026">
  **OneSDK**

  * **\[v1.9.40] Dynamic Review Screen Forms:**  Underlying updates to prepare support for Kenya, Ghana, South Africa, Singapore and Malaysia country fields in the review screen and future OneSDK versions.
  * **\[v1.9.40] Review screen:** Improved review screen by handling multi-doc and non-multi-doc flows correctly. This provides more focused information during the review process.
  * **\[v1.9.40] Review Screen for Thailand:** Review Screen for Thailand: Addressed issue where the address & postcode are empty in the review screen.

  **KYB**

  * **International Ownership Report:**

  We've introduced a new International Ownership Report for non-Australian organizations, allowing officers and API consumers to evidence beneficial ownership chains without AU-specific sections. This report retains the domestic layout while suppressing Australian content, providing a clear and concise overview of international ownership structures.
</Update>

<Update label="04 Sep 2026">
  **KYC**

  * **KYC Failure Reasons:**  KYC results now provide more detailed failure reasons, such as 'GovID required but no match' or 'Name insufficient matches', along with required versus actual counts. This helps users quickly identify and fix data issues, speeding up the resolution of failed entities.
</Update>

<Update label="03 Sep 2026">
  **IDV**

  * **Security Signals:**  Injection attack signals for face and document scans are now visible on the portal, providing consistent security insights that match backend data.
</Update>

<Update label="02 Sep 2026">
  **AML**

  * **AML Alert Display:**  Resolved an issue where the 'Associates' section on AML alerts for Politically Exposed Persons (PEPs) incorrectly displayed a blank dash. Now, the system accurately shows the related PEP's name and connection, improving clarity for reviewers and applying to both new and historical alerts.

  **KYC**

  * **Data Source Expansion:** Enabled Singapore data sources for the datazoo connector, enhancing data retrieval capabilities for our users.

  **OneSDK**

  * **\[v1.9.40] Dynamic Review Screen Forms:**  Underlying updates to prepare support for Kenya country fields in the review screenp: enabling applicants to provide necessary details like names, date of birth, National ID number, and address information.  This update improves the onboarding experience for Kenyan users by supporting their specific data requirements and ensuring accurate data capture.
</Update>

<Update label="31 Aug 2026">
  **OneSDK**

  * **\[v1.9.39] Daon Face Capture Instruction Screen:**  Resolved an issue where an unnecessary face capture instruction screen was displayed during the biometric verification flow for certain customers, ensuring a smoother user experience.
  * **\[v1.9.39] Dynamic Review Screen Forms:**  Underlying updates to prepare support for Thailand country fields in review screen:  Thai script for names and addresses, and accurately captures specific national ID details like the 13-digit citizen ID and laser code.

  **IDV**

  * **Daon Connector:**  Handled a scenario where the document expiry check result from the Daon connector was not being correctly processed, ensuring that document expiry information is now accurately reflected.
</Update>

<Update label="27 Aug 2026">
  **KYB**

  * **Organisation Search Enhancements:**

  Officers can now configure the country dropdown in international organisation search to display only enabled countries, preventing lookups outside configured coverage. Additionally, expanded lookup results now show full registry details, allowing officers to confirm the correct organisation before creating a profile.
</Update>

<Update label="24 Aug 2026">
  **KYB**

  * **Trust Analyzer is now generally available:** Trust Analyzer is now available end-to-end through both the Portal and the API, for all V2 KYB customers with Trust Analyzer enabled. It covers Australian trust deeds only; international coverage is not yet supported. This builds on the Trust Analyser tab introduced 16 Jul 2026 and the inline review/correction editor released 28 Jul 2026. See [Trust Analyzer](/docs/kyb/trust-analyzer) and the [Trust Analyzer Implementation Guide](/docs/kyb/trust-analyzer-implementation).
  * **Full Portal workflow:** Upload a trust deed, track analysis progress, review and correct extracted fields inline, and confirm — all from the organization's Trust Analyser tab, now a complete, generally available workflow.
  * **Workflow status now reflects sign-off:** Once you confirm an analysis, the workflow execution updates from `REVIEW` to `COMPLETE`, rather than remaining in `REVIEW` indefinitely.
  * **Supported trust types and limits:** Discretionary (family) trusts, unit trusts, and self-managed superannuation funds (SMSFs) are supported. A deed that can't be classified is shown as unclassified, with the reasons why, and a type must be identified before the analysis can be confirmed. Deeds must be text-based PDFs up to 100 pages and 20MB.
  * **No concurrent-analysis blocking:** Running more than one analysis on the same document at the same time isn't currently blocked, so we'd recommend against it for direct API integrations. This isn't something you'll encounter through the Portal, since each upload is treated as a new document.
</Update>

<Update label="21 Aug 2026">
  **IDV**

  * **Incode Anti-Fraud Module:**  The Incode Anti-Fraud module data is now mapped within the portal, allowing users to view Anti-Fraud results, including both passing and flagged statuses, alongside existing Age Verification data.

  **KYB**

  * **Ownership Tree PDF Highlighting:** Fixed an issue where the ownership tree in PDF reports incorrectly highlighted beneficial owners as non-beneficial, ensuring accurate visual representation of ownership status.
</Update>

<Update label="20 Aug 2026">
  **IDV**

  * **Improved Mexico Driver's License Verification:**  We have updated the Incode mapping for Mexico Driver's Licenses to include the CURP number, significantly improving the pass rate for identity verification and ensuring compliance with GDC requirements.
  * **Verification Step Monitoring:**  We've implemented a new system that automatically notifies customers via webhook if a user completes biometric or OCR verification but does not proceed to the final verification step within a configurable timeframe. This helps ensure that all necessary verification steps are completed.

  **KYC**

  * **Surname Mapping:** We have improved the accuracy of surname mapping for specific countries by using pre-parsed paternal and maternal surname data from identity documents when available. This ensures more precise data submission to external systems.
</Update>

<Update label="19 Aug 2026">
  **OneSDK**

  * **\[v1.9.38] Onfido Biometrics Module:**  Resolved an issue where the exit button was not displayed in the biometrics module, preventing users from easily exiting the flow. Users can now close the biometrics screen as intended.
  * **\[v1.9.38] Biometrics Camera Access Warnings:**  OneSDK now emits detailed warning events when a user encounters camera permission issues during biometrics capture, providing better visibility into user journey blockers. These warnings are integrated into existing event channels for easier tracking without requiring new subscriptions.
  * **\[v1.9.38] Onfido Mobile Biometrics Loading State:**  Resolved an issue where a loading state obscured the biometrics widget during the transition from OCR to biometrics on mobile devices, ensuring a smoother user experience during identity verification.

  **AML**

  * **AML Screening Workflow:** Resolved an issue where AML screening workflows would fail to finalize due to false positive adverse media hits. The system now correctly preserves false positive hits, allowing workflows to complete successfully.

  **KYC**

  * **Clearer failure reasons for KYC checks:**  Failed KYC checks in the Portal now present their reasons in plain English. Field names appear as readable labels rather than raw system paths, provider messages are normalised for consistency, and issues are grouped under the provider that reported them. Fields that passed validation are no longer listed as issues, so compliance operators can distinguish a data problem from a provider error or a genuine verification failure without interpreting raw system output.

  * **Duplicate Workflow Event Display:** Duplicate checks are now enabled for all V2 customers, allowing users to view matched entities and resolve duplicates directly from workflow events.
</Update>

<Update label="13 Aug 2026">
  **IDV**

  * **Improved first-name matching for multi-part given names:** We’ve enhanced how our ID OCR verification handles compound or multi-word first names (e.g., cases where an ID’s given name is split between “First” and “Middle,” or only partially captured). This reduces false first-name mismatches and helps prevent unnecessary manual reviews.
  * **IDV Link Expiry:**  We've updated the IDV link expiry logic to ensure links only expire after a biometric check is completed AND the KYC check is triggered, preventing issues where users abandon a session before review.

  **OneSDK**

  * **\[v1.9.37] Manual KYC Field Rendering:**  Fixed a regression where customized fields in the manual KYC flow were not rendering correctly, ensuring all fields now display as expected.
  * **\[v1.9.37] User Interface in Review Screen:**  The maternal last name field on the OCR review screen is now optional for users in Mexico, Spain, and Colombia, allowing for greater flexibility in data entry.
  * **\[v1.9.37] Country of Residence Update:**  Resolved an issue where the country of residence was incorrectly updated during identity verification, ensuring that the initial country selection is preserved and preventing applications from being approved under restricted or incorrect regions.
  * **\[v1.9.37] Dynamic Review Screen Forms:**  Underlying updates to prepare support for Mexico, Colombia, Canada, India and Spain country fields in the review screen and future OneSDK versions.
</Update>

<Update label="11 Aug 2026">
  **KYC**

  * **Reseller support for Experian AU credit header checks:** Customers who run Experian AU credit header checks on behalf of another reporting entity can now supply that entity's ABN with each check. Set the `CustomerChannelReferenceIdentifier` custom attribute on the individual and FrankieOne forwards it to Experian as `AMLObligatedEntityABN`. This is enabled per-configuration and off by default. See [Reseller Checks (Experian AU)](/docs/kyc-v2/implementation-guide/experian-reseller-abn).
</Update>

<Update label="10 Aug 2026">
  **OneSDK**

  * **\[v1.9.36] Expiry Date in eKYC flow:** We’ve enhanced the manual eKYC ID entry flow by adding an optional “Date of Expiry” field when customers select Passport, aligning the experience with the existing Driver’s Licence flow.
  * **\[v1.9.36] Form Validation:** Improved form validation on the 'Are your details correct?' page. When submitting the form with missing or invalid information, specific error messages and visual cues will now appear next to the affected fields, making it easier to identify and correct errors.
  * **\[v1.9.36] Onfido OCR Module Event Ordering:** Resolved a race condition in some Onfido OCR flows that could end the session before OCR results were received. We now deliver OCR results before closing the session, improving speed and consistency of results availability.
  * **\[v1.9.36] OneSDK Credit-check messaging improvement:** We fixed an issue where the OneSDK could display a credit-check related notice even when no credit check was actually performed (e.g., ID-only verification flows). With this update, credit-check messaging is now shown only when a credit check is genuinely applicable based on the check results.
  * **\[v1.9.36] User Interface:** Resolved an issue where scrolling on the desktop success page would incorrectly display both success and loading screens simultaneously, improving the user experience.
  * \**\[v1.9.36] Incode Consent API:* We've enhanced the API to allow passing user consent directly to Incode, supporting both mandatory and optional consent types for biometric data use and system enhancement. This streamlines the consent process for custom consent screens.

  **IDV**

  * **Document Check Status Clarity:**  Improved clarity for document checks where a workflow-level override changes the overall status to 'Needs Attention'. The individual document check step will now correctly reflect the reason for needing attention, providing a clearer explanation for operational teams.
</Update>

<Update label="04 Aug 2026">
  **AML**

  * **AML False Positive Resolution:** Resolved an issue where previously marked false-positive AML hits were not preserved upon re-running an entity's AML check, preventing unnecessary re-evaluation and workflow failures.
</Update>

<Update label="03 Aug 2026">
  **OneSDK**

  * **SMS Sender ID Compliance:**  We've updated our SMS sending configuration to comply with new regulations, allowing key customers to use their own Twilio API keys and ensuring all other SMS messages are sent from a generic phone number by default.
</Update>

<Update label="30 Jul 2026">
  **OneSDK**

  * **\[v1.9.35] Maintenance & dependency housekeeping:** removes an unused internal dependency as part of routine maintenance. There is no change to SDK functionality, behaviour, or public API — no action is required to upgrade. This update also streamlines the SDK's  dependency footprint, which may reduce noise in downstream dependency scans.
</Update>

<Update label="29 Jul 2026">
  **KYC**

  * **Portal Audit Tab:**  The Portal V2 Audit tab has been revamped to provide a more scannable and filterable timeline of audit events. Users can now quickly find relevant audit information, troubleshoot, and diagnose entity issues more efficiently.

  **OneSDK**

  * **\[v1.9.35] Form field Validation:**  The  review screen now correctly handles spaces in address fields, preventing validation errors for valid addresses and automatically trimming leading or trailing spaces upon submission. This ensures a smoother user experience when entering address details.

  - **\[v1.9.35] Maintenance & dependency housekeeping:** removes an unused internal dependency as part of routine maintenance. There is no change to SDK functionality, behaviour, or public API — no action is required to upgrade. This update also streamlines the SDK's  dependency footprint, which may reduce noise

  **IDV**

  * **Enhanced address extraction for Onfido document OCR:** We’ve improved how we capture and return address information extracted from Onfido document OCR. When enabled, this update allows us to surface more detailed, structured address data—including individual address lines—so you can more easily display, store, or validate addresses downstream.

  **KYB**

  * **UAT Environment Data Update:** New test data has been added to the UAT environment to support comprehensive testing of various scenarios, enhancing our ability to validate system behavior.
</Update>

<Update label="28 Jul 2026">
  **KYB**

  * **Trust Analysis Review:**  Compliance officers can now review, correct, and approve extracted trust details within the portal. This enhancement provides an inline editor for extracted fields, an entity-associations view, and page bookmarks to source pages in the trust deed PDF, ensuring accurate trust structures.
</Update>

<Update label="24 Jul 2026">
  **KYB**

  * **Duplicate Entity Creation:**
    We have fixed an issue where associating parties could inadvertently create duplicate entities, ensuring that only one record is created per party.

  **Portal**

  * **Audit Report:**  The audit report now includes masked mobile numbers, providing more comprehensive data while maintaining privacy.
</Update>

<Update label="23 Jul 2026">
  **Portal**

  * **IDV Portal Display Improvements:**  The IDV Portal now features enhanced document check displays including updated headings and new modals for detailed document validation, improving the clarity and accessibility of identity verification data.
</Update>

<Update label="22 Jul 2026">
  **OneSDK**

  * **\[v1.9.34] International Address Support:** The OCR review screen now supports selecting Italian provinces for residential addresses and document regions, improving international address data capture. This enhancement also lays the groundwork for adding subdivision support for other countries in the future OneSDK versions.

  **AML**

  * **Risk Edit Feature:** Resolved an issue where the risk policy screen did not display the complete list of countries for certain risk factors, ensuring all countries are now visible and editable.

  **Platform**

  * **SMS Sender ID Compliance:**  We've updated our SMS sending configuration to comply with new regulations, allowing key customers to use their own Twilio API keys and ensuring all other SMS messages are sent from a generic phone number by default.

  **KYC**

  * **Entity List Management:**
    Users can now customize the Entities table in Portal V2 by selecting which data columns to display and arranging their order, making it easier to review entity information.
</Update>

<Update label="21 Jul 2026">
  **KYB**

  * **KYB Workflow:**
    Resolved an issue where the KYB workflow would fail due to an organization deduplication error during the persist step, preventing the completion of the process.

  * **Credit Limit Display:**
    Fixed an issue where the credit limit banner was not consistently displayed on account overview pages, ensuring users now see accurate credit limit information.
</Update>

<Update label="16 Jul 2026">
  **KYB**

  * **Trust Analysis Workflow:**
    We have enhanced the Trust Analysis workflow by displaying its lifecycle events (started, completed, failed, approved) on the Workflow events page, providing better visibility into the analysis process. Additionally, the Trust Analysis workflow can no longer be directly selected from the generic workflow picker, ensuring it is initiated only in the correct context.
  * **Trust Analysis:**
    Compliance officers can now access a new Trust Analyser tab from the organization Overview to upload trust deeds, track their analysis status, and initiate analysis for organizations. This enhancement streamlines the process of managing and reviewing trust documents.
</Update>

<Update label="14 Jul 2026">
  **IDV**

  * **Document Verification:** Handle address fields containing ^ (caret) characters as separators from Daon  provider.

  **KYC**

  * **Audit Report Alert ID Hyperlink:** Fixed an issue where the 'Alert ID' hyperlink in the Audit Report incorrectly directed users to the development environment, ensuring analysts can now access the correct production alert page directly.
</Update>

<Update label="13 Jul 2026">
  **Transaction Monitoring**

  * **Organization entity monitoring in the Portal**: Fraud and Compliance Officers can now view, investigate, and resolve Transaction Monitoring alerts for organization entities directly in the FrankieOne portal. Alert lists, detail drawers, activity tables, risk assessment panels, and monitoring status banners are all available for organization entities.

  * **Alert classification with Reasons**: When resolving an alert, officers can now select one or more Reasons to classify the decision via the Portal— for example, marking an alert as a true positive or false positive. At least one Reason is required for resolutions in the portal.

  * **Activity classification with Reasons**: Officers can tag non-alerting activities with a Reason to capture false negatives and send feedback to the monitoring provider via the Portal. The Reason is visible in the Activity drawer after submission.

  * **Organization entity activity evaluation**: Activities for organization entities can now be evaluated via `POST /v2/organizations/{entityId}/activities`. The system enriches organization entity data — including registration name, registration number, address, and contact details — before forwarding to the configured monitoring provider for risk scoring. Results are returned asynchronously via webhook.

  * **Webhook: ActivityAlertCreated and ActivityAlertUpdated for organization entities**: The existing `ActivityAlertCreated` webhook event now fires for organization entity alerts in addition to individual entity alerts. Alerts for organization entities can be resolved via `PATCH /v2/organizations/{entityId}/results/activity`. On resolution, FrankieOne dispatches an `ActivityAlertUpdated` webhook to your registered endpoint containing the updated `manualStatus`.

  * **Tags and Classifications**: FrankieOne introduces a Tags framework — a general-purpose system for defining and managing labels across the platform. For Transaction and Activity Monitoring, Tags are surfaced as Reasons that officers select when resolving alerts or classifying activities. Tags are FrankieOne-defined and can be grouped by `category` (for example, `FRAUD`, `MONEY_LAUNDERING`, `FALSE_POSITIVE`) and `domain` (for example, `ACTIVITY`). When a Reason is selected, a Classification is recorded against the alert or activity. Activities can be independently classified via `POST /v2/activities/classify`.

  **KYB**

  * **KYB Request Processing:**
    Resolved an issue where KYB requests for certain organizations would get stuck in processing and return a 500 error, preventing the completion of verification workflows.
</Update>

<Update label="13 Jul 2026">
  **IDV**

  * **Hosted OneSDK Onboarding:** We’ve resolved an issue that was keeping some new users from starting their onboarding flow. You can now successfully kick off your setup without any hiccups!
</Update>

<Update label="08 Jul 2026">
  **IDV**

  * **Data Mapping:** Updated data mapping for the Incode connector to correctly process CURP numbers for Mexican voter identification cards, improving the pass rate for identity verification.
</Update>

<Update label="07 Jul 2026">
  **OneSDK**

  * **\[v1.9.33] Daon Address Field Handling:**  Address fields returned from OCR or stored in the backend will now automatically trim leading/trailing whitespace, preventing validation errors and ensuring clean data display and submission.
  * **\[v1.9.33] Truuth User Experience:**  When a user chooses to return later, the system now directly redirects them, skipping an unnecessary intermediate page for a smoother experience in Truuth integration.
</Update>

<Update label="06 Jul 2026">
  **IDV**

  * **Daon Document Capture for Learner’s DL:**  Improved document type recognition for identity verification, ensuring that Australian Learner's Driver's Licences and similar documents are correctly processed through the appropriate verification channels.
</Update>

<Update label="02 Jul 2026">
  **OneSDK**

  * **\[v1.9.32] Credit Bureau Header Notifications:**  OneSDK now displays a notification when a credit bureau header data source fails to find a match during a KYC check, ensuring compliance with regulatory requirements and informing users of the mismatch.
  * **\[v1.9.32] Language Control:** Added capability to programmatically set the language for Onfido and Incode within OneSDK, providing insights into the level of control available for displayed languages.
  * **\[v1.9.32] Review Screen Submissions:**  Disabled address and document fields on review and personal details screens are now preserved upon submission, preventing accidental data loss.
  * **\[v1.9.32] Hosted Review Screen:** Resolved an issue where submitting the hosted review screen incorrectly cleared name fields and where the IDV completion webhook fired prematurely. Name fields will now persist correctly, and the webhook will fire only after the review screen is submitted, ensuring reliable signal for review completion.

  **IDV**

  * **Daon Error Codes:**  Improved the handling of error codes from backend services, ensuring that the OneSDK consistently receives and displays accurate failure messages to users, even when the backend provides them in a different format.

  **Fraud**

  * **Monitoring Workflow Trigger:** Resolved an issue where monitoring workflows were triggered multiple times for entities with multiple subscriptions. Workflows will now trigger only once, respecting the specified monitoring type in the inbound message.
</Update>

<Update label="22 Jun 2026">
  **IDV**

  * **Mexico ID mapping:**  Updated the Incode integration for improved identity verification in Mexico by correctly mapping the CURP number to the ID number field, which will increase the success rate of identity checks.
  * **Enhanced Family Name Support for Global Identity Verification:** We have updated our document scanning and OCR (Optical Character Recognition) engine to better handle diverse naming conventions across different countries and cultures.
  * **Document Type Mapping - Brazil National ID:**  Updated the mapping for Brazilian ID cards to correctly identify them as 'National ID' instead of 'Other' when processing documents from a third-party vendor. This ensures accurate document classification and processing.
</Update>

<Update label="17 Jun 2026">
  **KYB**

  * **Core Onboarding Journey:** The core onboarding journey has been updated to use the new v2 platform, allowing applicants to complete the flow more efficiently from providing details to linking organizations, reviewing, and submitting their applications.
</Update>

<Update label="12 Jun 2026">
  **KYB**

  * **UBO Reporting:** Resolved an issue where Ultimate Beneficial Owner (UBO) information was not appearing in reports for certain entities, ensuring all relevant relationships are now correctly displayed.
  * **AML Check Timeout Error:** Resolved a potential timing issue with the integration with World-Check re-running screening.
</Update>

<Update label="10 Jun 2026">
  **KYB**

  * **Core Onboarding Journey:** The core onboarding journey has been updated to a new platform, allowing applicants to complete the entire flow from providing details to submitting their application more efficiently.
</Update>

<Update label="09 Jun 2026">
  **Transaction and Activity Monitoring**

  **Service and Integration**

  * **Counterparty identifier — external reference support**: When evaluating an activity, the counterparty identifier sent to the monitoring provider can now be set via `counterparty.externalReference.value`. This enables rule-building against counterparties that are not registered as FrankieOne entities. When a `counterparty.entityId` is provided it takes precedence; `externalReference` is used only when `entityId` is absent.
  * **Party and counterparty custom attributes**: The Activity API now accepts a `customAttributes` map on both `party` and `counterparty` in the activity evaluation request. Custom attributes are forwarded to the monitoring provider as persistent tags, enabling rule evaluation against entity-level signals that persist between evaluations. Custom attributes provided at evaluation time are not written back to the FrankieOne entity record.
  * **Address country enrichment**: FrankieOne now automatically includes two additional attributes on activity evaluation calls: `partyEntityResidentialCountry` and `partyEntityPostalCountry`. These are derived from the most recently updated residential and postal addresses on the entity record and are sent regardless of any address values supplied in the evaluation request. This supports address-based rule writing where historical address data would otherwise be unavailable.
  * **Alert risk level flexibility**: Improved how non-real-time alerts can specify the risk level of associated alerts, giving customers more flexibility to determine how risk levels are represented when different offline alert types are processed across the wider FrankieOne platform.

  **KYB**

  * **Onboarding Link Generation:** Operators can now generate onboarding links directly within the Portal v2, providing applicants with a seamless entry into the new experience.

  **IDV**

  * **Daon Document Processing:** Improved the accuracy of document country identification by using more reliable data fields from the document provider, resolving issues with certain document types.
  * **Chilean ID Verification:** We've corrected an issue where Chilean identification numbers were incorrectly mapped, ensuring accurate verification and improving the success rate for identity checks.
  * **Columbia Name Field Capture:** We've resolved an issue where some components of a customer's full name, specifically secondary surnames, were not consistently displayed in the last name field, ensuring all provided name information is now correctly captured and visible.
</Update>

<Update label="04 Jun 2026">
  **OneSDK**

  * **\[v1.9.30] Biometric Page Extraction:** Resolved an issue where users could get stuck on the page extraction screen after completing biometrics, ensuring a smoother transition to the next step.
  * **\[v1.9.30] Daon Error Handling:** Error codes and messages from the Daon Process Definition (PD) flow are now displayed in the portal, allowing for quicker diagnosis and resolution of issues.

  **KYB**

  * **Risk Factors:** We've added three new risk factors to improve the accuracy of KYB risk assessments. These factors include company ownership structure, industry risk, and country risk.
</Update>

<Update label="01 Jun 2026">
  **KYC**

  * **Equifax Canada Credit Lock Handling:** The system now correctly recognizes and processes Equifax Canada's Hit Code 7 (Credit Lock - Report Unavailable) response, ensuring compliance with Ontario's Bill 142. This update prevents cascading to secondary bureaus when a credit lock is detected, accurately reflecting consumer intent.

  **IDV**

  * **Daon Portal Display:**  We've updated the Portal to ensure report statuses display correctly for match document.
  * **Structured Address Populating from OCR Results:** We have introduced an optional mechanism to populate structured address details directly from OCR provider results. This is an optional feature. When enabled, the system parses the OCR output to isolate specific address fields, improving downstream data quality and reducing the need for manual data cleaning.
</Update>

<Update label="28 May 2026">
  **OneSDK**

  * **\[v1.9.29] Improved User Guidance:**  We have updated the helper text for Australian driver's license card numbers during manual verification to accurately guide users on where to find the card number for each state, especially for Victorian licenses where it is now correctly stated to be on the back of the card.
  * **\[v1.9.29] Document Upload:**  OneSDK can now handle multiple document upload of the same type, improving flexibility and efficiency when submitting required information.
</Update>

<Update label="27 May 2026">
  **Edit your Risk Policy in the Portal**

  **Available to:** All v2 KYC Portal customers.

  You can now edit your live risk policy directly in the Portal. Adjust factor scores, tune risk-level thresholds, and publish changes in minutes. No more tickets to change a score or recalibrate a threshold.

  **What's new**

  **Edit factor scores** — Update the score for any KYC risk factor directly in the Portal. Live score is shown side-by-side as you edit, so you always know what's currently active versus what you're proposing. Set any score to **0** to exclude a factor from the assessment entirely. For range-based factors (e.g. Age of Entity, PEP Count), you can also modify the max value for each range.

  <Frame>
    <img alt="Image2 Risk V2" />
  </Frame>

  **Edit risk-level thresholds** — Drag the slider or type the values to set the max threshold for each level (Low / Medium / High / Unacceptable). Automatic validation prevents gaps or overlaps between levels.

  <Frame>
    <img alt="Image Risk V2" />
  </Frame>

  **Draft and publish workflow, with safeguards** — Save changes as a draft, reset back to live values, or publish to production. An authorisation acknowledgement is required at the start of every edit session, and a confirmation step (with optional comment) is required before publish.

  **Permission-gated editing** — Only users with the **Risk & Compliance Officer** role can publish changes. Administrators, Super Admins, and Compliance Officers can view but not edit. Permissions are managed by your tenant administrator.

  **Important behaviours**

  **Changes apply to future entities only** — Published changes do not re-assess existing entities. New onboardings from the moment of publish onwards use the new policy.

  **Allow 15–30 minutes for changes to take effect** — Once a change is published, propagation through the system is fast but not instantaneous.

  **Child accounts inherit your published version** — Any child account without its own risk policy will pick up the parent account's published version.

  **Learn more**

  For more information, see [Managing your risk configuration](https://docs.frankieone.com/docs/manage-risk-config).

  ***

  **View your KYC rulesets in the Portal**

  **Available to:** All v2 KYC Portal customers

  You can now see the KYC verification rulesets configured for your account directly in the Portal, and view a per-entity ruleset breakdown showing exactly which rules ran, what matched, and which data sources confirmed each match. No more emails to answer "what runs on this workflow?" or "why did this entity pass?".

  **What's new**

  **Rulesets page** — A new **Rulesets** section under **Risk and rules** lists every KYC ruleset configured for your account, with match requirements (name, address, date of birth, government ID) shown at a glance.

  <Frame>
    <img alt="Ruleset 1" />
  </Frame>

  **Per-entity ruleset breakdown** — Every entity profile now displays the applied ruleset, its match requirements, the matches found, and the data sources that confirmed each match. Use it for audit responses, internal training, or troubleshooting failed verifications.

  <Frame>
    <img alt="Ruleset 2" />
  </Frame>

  **Optional check badge** — appears next to checks that didn't match but weren't required for the verification to pass (for example, an address that didn't match when the ruleset only needed address OR date of birth)

  <Frame>
    <img alt="Ruleset 3" />
  </Frame>

  ## Learn more

  For more information, see [here](https://docs.frankieone.com/docs/view-kyc-ruleset).
</Update>

<Update label="28 May 2026">
  **KYB**

  * **Risk Scoring:** We fixed an issue where KYC custom risks were incorrectly included in the overall KYB risk calculation, ensuring more accurate KYB risk scores.
</Update>

<Update label="28 May 2026">
  **KYB**

  * **KYB v2 Entity Age and Residential Address:** Fixed an issue in KYB v2 where 'Age of Entity' and 'Residential Address Country Risk' were incorrectly applied to business records; these checks now correctly apply only to individual records.
</Update>

<Update label="25 May 2026">
  **OneSDK**

  * **\[v1.9.28] Daon Session Timeout Handling:**  We've introduced a new screen for Daon biometric sessions that have timed out due to inactivity, providing a clear visual indication to users and allowing for better handling of these scenarios by developers.
  * **\[v1.9.28] OCR Review Screen Improvements:**  The OCR review screen has been updated to improve clarity and consistency, including corrected spelling, adjusted field labels, and reordered document information for a more intuitive user experience.
  * **\[v1.9.28] Result Screen Customization:**  OneSDK now allows developers to customize the result screen with their own images, either by providing a base64 encoded image or a URL to an image, enhancing the visual experience.
  * **\[v1.9.28] Address Field Improvements:**  We've enhanced the review screen to correctly display full address details, including unit numbers and proper separation of suburb and town. Additionally, address pre-fill now supports state acronyms, and the name field accepts hyphens, preventing previous submission errors.
</Update>

<Update label="21 May 2026">
  **IDV**

  * **Daon Authenticity Checks:**  The portal now displays available Daon authenticity check options and their mapping to the FrankieOne platform, providing transparency into configured checks and result interpretations.
</Update>

<Update label="20 May 2026">
  **KYB**

  * **Security:** We have strengthened Content Security Policy rules to enhance security, resolving potential weaknesses related to iframes, Thoughtspot, and Frankie AI Chatbot integrations.
</Update>

<Update label="18 May 2026">
  **OneSDK**

  * **\[v1.9.27] Result Screen Descriptions:**  The result screen description field now supports rendering HTML elements, allowing for richer text formatting like bold and italics to improve clarity and user experience.
  * **\[v1.9.27] Biometric Review Screen:**  OneSDk review screen now accepts and displays hyphenated names properly allowing users with such names from completing the submission process.
  * **\[v1.9.27] Document Identification UI:**  Enable configuration of field labels for document identification to clearly indicate the source of information (e.g., "From your driver's licence" or "From your passport") and to display the expiry date for passports, improving clarity and compliance.
  * **\[v1.9.27] OneSDK Forms:**  Resolved an issue where overriding form field configurations with partial objects caused dropdowns to display "No records"; dropdown options will now correctly fall back to default values if not explicitly provided in the override.

  **IDV**

  * **OCR Comparison:** Handled a specific customer flow scenario where the OCR comparison was displaying data from a Passport instead of the Driver's License, ensuring accurate document data comparison.
</Update>

<Update label="13 May 2026">
  **IDV**

  * **Portal State Consistency from OneSDK KYC Flow:** Handled a scenario where failed ID uploads in the KYC flow would lead to inconsistent portal states and prevent successful completion. The system now gracefully handles failed ID uploads, preventing further processing until a valid ID is provided.
</Update>

<Update label="12 May 2026">
  **OneSDK**

  * **\[v1.9.26] Review Screen Updates:**  The review Screen in OneSDK has been updated to include a header sentence and a checkbox, providing clearer instructions and improved user interaction.
  * **\[v1.9.26] Multi-Document Review Screen:**  The review screen now supports displaying information from multiple documents, such as a Driver's License and Passport, in a single view, providing a more comprehensive and dynamic review experience.
  * **\[v1.9.26] Result Screen Accuracy:**  Resolved an issue where a 'Verification Complete / You're all set' message could appear even when verification had not succeeded; the final result screen now reflects the true processing state, preventing misleading completion messaging.
</Update>

<Update label="08 May 2026">
  **KYC**

  * **Portal Display:** Resolved an issue where an internal IDV check ID was incorrectly displayed on the portal, ensuring only relevant information is visible to users.
</Update>

<Update label="07 May 2026">
  **IDV**

  * **OCR Output in V2:**  Handled a scenario where expiry and/or issuing dates were missing from the OCR Output column in Portal v2, ensuring complete and accurate data display.
</Update>

<Update label="06 May 2026">
  **OneSDK**

  * **\[v1.9.25] Library Update:** We have addressed dependency issue with the lodash library in the OneSDK package.

  **IDV**

  * **Daon Portal Display:** Fixed an issue where expiry dates extracted by OCR were not consistently visible in the Frankie Portal for various document types, ensuring all extracted data is now correctly displayed.
  * **Audit Logging:** Improved audit logging for v2 processes now provides clearer messages when a face image does not match the driver's license, helping to diagnose issues more effectively.
</Update>

<Update label="04 May 2026">
  **IDV**

  * **Document Scanning:** Handle a scenario where scanning Australian Driver's Licenses from Victoria incorrectly returned an 'Invalid document type' error, ensuring accurate document processing.
</Update>

<Update label="29 Apr 2026">
  **OneSDK**

  * **\[v1.9.24] Daon IDV Processing:**  The Daon identity verification process now emits a 'loading' event, providing clearer status updates for embedded customers during check processing.
</Update>

<Update label="28 Apr 2026">
  **KYB**

  * **AML Monitoring Event Section:** The KYB Portal now includes a dedicated AML Monitoring Event section, providing a comprehensive view of monitoring status, search details, and summary counts. Users can also filter, select, and bulk update alerts directly within the results table.
  * **AML Monitoring:** The AML Monitoring section in the Portal has been updated to reflect the current state of monitoring for an entity, including an 'Unchecked' status when no monitoring has occurred. You can now easily enable or disable AML monitoring with clear feedback, provided an AML screening subscription is active.
</Update>

<Update label="27 Apr 2026">
  **IDV**

  * **Onfido Document Display:** Resolved an issue where outdated Onfido session document images were displayed in the portal, ensuring that the latest document details and OCR data are now correctly shown.

  **KYB**

  * **Custom Attributes:** The KYB Controller can now delete custom attributes from organization entities, allowing for more flexible management of organization metadata.
  * **Organisation Custom Attributes:** We've added new capabilities to manage custom attributes for organisations, allowing you to create, update, and list key/value metadata associated with an organisation.
</Update>

<Update label="24 Apr 2026">
  **Transaction and Activity Monitoring**

  **Portal**

  * **Faster investigations with richer context**: Activity and monitoring views now surface more relevant details to help Fraud and Compliance teams triage and resolve cases more quickly such as alerts associated to other activities, custom attributes, and device indicators.

  **Service and Integration**

  * **Fraud detection feedback loop (FrankieOne → Provider)**: FrankieOne alert outcomes are now forwarded to the provider as "decisions", enabling provider services (e.g., analytics) to learn from real outcomes, improve detection quality over time, and keep the system alerts in sync
  * **More intelligent data point selection, timely evaluation inputs**: Evaluation now supports better data point selection (including `updatedAt` timestamps) to reduce reliance on stale information.
  * **More configurable risk management**: Support for entity custom attribute mappings and additional risk handlers gives more granular control over what signals drive risk outcomes.
  * **Audit and compliance alignment**: Audit reporting improvements align monitoring behaviour more closely with audit report expectations, improving traceability.
</Update>

<Update label="22 Apr 2026">
  **OneSDK**

  * **\[v1.9.23] Daon Error Events:**  Daon error codes and messages are now surfaced to embedded customers through OneSDK events, providing clearer, more actionable insight into why an identity verification attempt failed during the IDV flow.
  * **\[v1.9.23] Configurable 'No Documents' Redirect:**  When a user selects 'I have none of these documents', OneSDK can now be configured to redirect them to a provided link instead of proceeding to the liveness check, giving customers control over alternative onboarding paths.
  * **\[v1.9.23] Dependency Update:**  Upgraded the axios library to 1.15.0, keeping the SDK's dependencies current and secure.
</Update>

<Update label="20 Apr 2026">
  **IDV**

  * **Biometrics Check:**  Enhanced the biometric verification process to ensure accurate results by requiring a valid image upload for all portal checks.
</Update>

<Update label="16 Apr 2026">
  **OneSDK**

  * **\[v1.9.22] Onboarding Journey Event Logging:**  The entity audit report now captures detailed event logging across the onboarding journey, giving customers visibility into which screens an end user reached and where they dropped off, rather than only recording that the onboarding link was generated.
  * **\[v1.9.22] Review Screen Edits Persist:**  Fixed an issue in the hosted eKYC flow where edits made on the review screen were not saved, ensuring user changes are now correctly retained on submission.
  * **\[v1.9.22] Review Screen Loading:**  Resolved a regression where the review screen could fail to load (appearing as a blank screen) after document and selfie capture on some mobile devices, ensuring the review and result screens display reliably.
</Update>

<Update label="09 Apr 2026">
  **OneSDK**

  * **\[v1.9.21] Review Screen 'Other Names' Field:**  The review screen can now be configured to include an 'Other names known by' field, allowing customers to capture alternate or additional names (such as middle names) during onboarding.
  * **\[v1.9.21] Document Upload Visibility:**  Resolved an issue where documents captured through the OneSDK flow did not consistently appear in the Portal, ensuring uploaded documents and their OCR results are now reliably available for review.
</Update>

<Update label="08 Apr 2026">
  **KYC**

  * **AI Entity Summary:**  Resolved an issue where the AI entity summary was sometimes not displaying in the portal, ensuring that all generated summaries are now visible.
</Update>

<Update label="06 Apr 2026">
  **KYB**

  * **Workflow Status Display:** We've corrected the display of workflow status badges on the Entities table and Workflow events page to ensure consistency and accuracy. The 'Unchecked' status on the Workflow events page now correctly displays as 'Incomplete'.
</Update>

<Update label="02 Apr 2026">
  **IDV**

  * **IDV Webhooks:** Fixed an issue where the customer reference was missing from the ONB\_URL\_GENERATED event payload for IDV webhooks, ensuring all relevant customer data is now included.
</Update>

<Update label="01 Apr 2026">
  **Transaction and Activity Monitoring**

  **Portal**

  * **Custom attributes visible for Individuals**<br />The Portal now surfaces custom attributes for individual entities, so operators can view client-specific or use-case-specific fields without switching context.
    * **Entity profile view** (Entity view – Profile)
    * **Activity monitoring views** (Activity drawer)<br />This gives investigators more context about the party involved in a transaction or activity, giving investigators more context about the party involved in a transaction or activity.
  * **View accounts linked to an entity**<br />Operators can now see all accounts associated with an entity directly in the Portal. This makes it easier to understand which accounts are tied to the party being assessed, and to review account‑level behavior and related activities in one place.
  * **Usability improvements in monitoring views**<br />We have made incremental UX refinements across the Portal, including layout adjustments and clearer labels in monitoring sections. These changes are designed to make navigation between entities, activities, and related context more intuitive for day‑to‑day investigations.

  **Services and Integrations**

  * **Support for new activity event types**<br />Backend services have been updated to accept additional activity event types used by ingestion and evaluation flows for transaction and activity monitoring. This allows the platform to handle a broader set of activity signals in a consistent way, paving the way for richer monitoring scenarios.
  * **Account‑enriched activity evaluation**<br />During evaluation, activities can now be automatically enriched with account information. This gives rules, decisions and the UI more complete context, enabling more precise monitoring logic and clearer explanations for operators reviewing activity.
  * **Improved external reference traceability**<br />During activity evaluation, the party's external reference (for example, the CUSTOMER-REFERENCE external reference set on the individual entity) is now consistently populated on the resulting activity record and related process results. This change applies to activities evaluated after this release. No changes to your integration are required.

  **KYC**

  * **KYC Issue Reporting:**  The v2 Entity Profile API now provides detailed KYC issue codes alongside summary codes. This enhancement allows platform operators and integration partners to understand specific verification failure reasons, enabling them to guide end-users more effectively on necessary corrections.

  **OneSDK**

  * **\[v1.9.20] Build Fix:**  Resolved an issue where the SDK prevented Next.js 15+ applications from building when Turbopack was enabled, ensuring smoother development for users leveraging modern build tools.
  * **\[v1.9.20] Lodash Build Fix:**  Resolved an issue where a hidden lodash dependency in the SDK could cause application builds to fail when lodash was not separately installed, ensuring projects build successfully with only the OneSDK package.
</Update>

<Update label="24 Mar 2026">
  **IDV**

  * **Daon Error and Events:** We have significantly improved how we communicate IDV results. By introducing more granular error codes and descriptive messages, we are providing clearer insights into why a verification attempt might have failed, allowing for faster resolution and a smoother customer experience.
</Update>

<Update label="23 Mar 2026">
  **KYC**

  * **Netherlands Postcode Enrichment:**  Improved the accuracy of Netherlands postcodes by automatically correcting missing characters or formatting issues, ensuring more reliable address data.
</Update>

<Update label="19 Mar 2026">
  **KYC**

  * **Individual Report Generation:**  Individual PDF reports now include dedicated sections for IDV and AML checks, providing a more comprehensive overview of an entity's verification status.
</Update>

<Update label="18 Mar 2026">
  **OneSDK**

  * **\[v1.9.19] Incode translation feature:** You can now customize translations for the Incode biometrics and identity verification provider, allowing you to tailor the user experience to your preferred language. This enhancement gives you greater control over how verification prompts and messages appear to your end users.
  * **\[v1.9.19] Incode SDK Integration:**  We've enhanced the Incode SDK integration to allow passing additional options to the renderCamera method, providing more flexibility for OCR and biometrics flows.
  * **\[v1.9.19] Flexible Identity Verification Flows:** You can now customize your Incode verification by choosing between standalone document scanning or document scanning with biometrics, providing more control over your identity verification process.
  * **\[v1.9.19] Review Screen Layout**:\*\* The ‘Address search’ option on the review screen can now be configured to change its position through this setting addressSearchPosition. This provides flexibility to adjust to the UI to customers’ preference.

  **KYC**

  * **KYC CTA Banner:**  The KYC Call to Action banner will no longer display for workflows that do not include a KYC step, preventing irrelevant verification messages.
</Update>

<Update label="04 Mar 2026">
  **KYC**

  * **Individual v2 PDF Report:**  Compliance officers and operators can now generate a comprehensive PDF report for v2 individuals directly from the portal, providing essential evidence for auditors.
  * **PII Retention:** We've introduced a new feature that allows for the immediate deletion of Personally Identifiable Information (PII) after workflow execution, ensuring enhanced data privacy and compliance.
  * **Watchlist and Comply Advantage Updates:**  We've updated the Comply Advantage connector to use different fuzziness levels for PEP and PEP Media checks, improving the accuracy of AML screenings by minimizing false positives for PEP and broadening matches for PEP Media.
</Update>

<Update label="03 Mar 2026">
  **IDV**

  * **Document Capture:**  Resolved an issue where the system incorrectly defaulted the country of issue to Afghanistan during document capture, ensuring only relevant country options are displayed for Driver's License selections.
</Update>

<Update label="27 Feb 2026">
  **IDV**

  * **Stability:** Addressed an issue where the IDV service was restarting due to a model converter panic, improving service stability and reliability.
</Update>

<Update label="25 Feb 2026">
  **Transaction and Activity Monitoring**

  **TM Portal**

  * **View all alerts, including historical decisions**: You can now see all alerts for an entity in the Portal ' including those that have already been resolved so investigators always have the full decision history when reviewing a case.
  * **Richer alert and activity context**: Alert detail views now expose more of the underlying activity information, making it easier to understand *why* an alert was raised and what happened before/after.
  * **UX polish for alert investigations**: We've addressed UI issues where some expanded details or alerts were not visible in certain states, making the alert timeline more predictable and easier to navigate. The monitoring flow summary now correctly shows “No issues” when all steps are clear, and reruns behave consistently for non-final resolutions, reducing confusion during reviews.
  * **Alert lifecycle stability**: Fixed cases where alerts could be incorrectly invalidated when entity details were updated, ensuring investigations aren't disrupted by background changes.

  **TM API and Integrations**

  * **Provider alert ingestion pipeline**: FrankieOne now supports end-to-end ingestion of routine alerts from the provider, including:
    * Webhook intake
    * Asynchronous processing
    * Creation of TM activities and results from incoming alerts<br />This gives customers access to the provider's ongoing fraud and AML signals directly within TM.
  * **Additional provider risk signals**: Expanded set of the provider's risk signals that can be ingested (including device and behavioral signals)
  * **Device and IP data for TM Introduced device**: and IP-level data ingestion to enrich TM activities, enabling more granular and context-rich fraud and AML rules.
  * **Risk level mapping and data quality**: Corrected the mapping of provider's VERY\_HIGH risk level to FrankieOne's UNACCEPTABLE outcome and tightened validation around external references and enums, to avoid losing high-risk signals
  * **Stability of TM workflows and APIs**: Fixed a range of issues across activity fetching, result updates, and workflow triggers to ensure consistent behavior for both synchronous and asynchronous monitoring flows.
</Update>

<Update label="25 Feb 2026">
  **KYC**

  * **Country Risk Factors:** The system now supports multiple country-based risk factors for different address types, such as residential and postal, allowing for more granular risk assessment. It can also handle multiple addresses per type and calculate maximum, minimum, and average risk scores.
</Update>

<Update label="24 Feb 2026">
  **IDV**

  * **Webhook Notifications:** Fixed an issue where webhooks were not consistently triggered when manually updating workflow statuses, ensuring accurate database synchronization for status changes.
</Update>

<Update label="18 Feb 2026">
  **IDV**

  * **Send Link:** Resolved an issue where SMS messages could not be sent if the entity did not have a name, ensuring smoother communication workflows.

  **KYB**

  * **AML Summary:** Resolved an issue where the AML Summary was not updating correctly, ensuring accurate display of potential matches after resolving hits.
</Update>

<Update label="17 Feb 2026">
  **KYC**

  * **Experian Checks:**  Experian checks for v2 customers now include Illion data, improving verification success rates without requiring any changes to your existing integration.
</Update>

<Update label="16 Feb 2026">
  **OneSDK**

  * **\[v1.9.16] Daon Event Handling:**  The system now correctly processes events from Daon for IDV, OCR, and Biometrics modules, ensuring proper workflow completion, error handling, and event emission for both scenarios with and without a redirect URL.
  * **\[v1.9.16] React Version Support:**  The OneSDK now officially supports React 19, and React has been updated to a peer dependency. This change improves compatibility and simplifies dependency management for applications integrating with the SDK.

  **IDV**

  * **Selfie Capture on iPhone Safari:**  Resolved an issue preventing users from completing the Daon selfie capture process on iPhone Safari due to a JavaScript error, ensuring a smooth biometric verification experience.

  **KYC**

  * **Global Address Validation:**  The KYC validation system now normalizes and validates customer-provided address information by mapping state or province names to their correct ISO state codes for an expanded list of countries, ensuring consistent data across integrations. Missing state mappings will now be logged for easier identification and resolution.
</Update>

<Update label="13 Feb 2026">
  **KYC**

  * **Portal Customer Records Extract, Individual PDF Report:** We've enhanced the  Portal with new permission-based reporting features. Authorized users can now generate detailed PDF reports for individual entities and customer records, providing essential evidence for audits and case management. Please contact support to learn more about these reports.

  **IDV**

  * **Truuth IDV Results Enhancement:**  Enhanced the FrankieOne Portal to provide complete visibility of Truuth IDV verification results including Document Authenticity and Face Match data, enabling more thorough identity verification review and decision-making.
</Update>

<Update label="11 Feb 2026">
  **KYC**

  * **Report Management:** We've enhanced report management improving performance and data handling. Additionally, the search filter has been removed to streamline the user interface.
</Update>

<Update label="10 Feb 2026">
  **KYC**

  * **Customer Records PII Extract:**  Admin users with the 'Customer Records Report' permission can now generate and download password-protected PII extracts with date range filtering from the portal, allowing for efficient access to customer data for compliance, auditing, or analysis.

  **IDV**

  * **Internationalization:**  The system now correctly recognizes and processes the Republic of Kosovo as a valid country, resolving previous errors related to invalid country codes.

  **Portal**

  * **Login:**  Usernames are now case-insensitive, so you can sign in successfully regardless of how your email address or username is capitalised at account creation. This reduces failed login attempts and makes access more reliable and user-friendly.
</Update>

<Update label="09 Feb 2026">
  **KYB**

  * **SLBO Report Generation:** Resolved an issue preventing the generation of Single Level Beneficial Ownership (SLBO) reports, ensuring users can now successfully create these reports.
</Update>

<Update label="05 Feb 2026">
  **IDV**

  * **KYC Database Check Failure:** We have investigated and resolved an issue where KYC database checks were failing due to discrepancies in country name formatting and missing date of expiry data during OCR processing.
</Update>

<Update label="26 Jan 2026">
  **KYC**

  * **AI Entity Summaries:**  We've enhanced the AI entity summary feature for v2 customers in the portal, providing clear, concise explanations of why an entity failed or needs attention, along with actionable insights and exportable reports.
</Update>

<Update label="30 Jan 2026">
  **KYC**

  * **IDV Result Status Update:**  The IDV result now displays who updated its status and when, providing clarity on changes to the verification outcome.
</Update>

<Update label="26 Jan 2026">
  **OneSDK**

  * **\[v1.9.15] Daon Brand-specific styling:**  The OneSDK now supports passing brand information to Daon, enabling brand-specific styling for Customer's different brands within Daon-hosted web pages for a more consistent user experience.
  * **\[v1.9.15] Daon Document Selection:**  The SDK can now bypass the document selection screen, allowing clients to pre-select a document type and streamline the capture process for users.
  * **\[v1.9.15] OneSDK Event Handling and Teardown:**  Addressed issues with OneSDK event relay for Onfido, improved teardown functionality to ensure proper cleanup, and enhanced handling of expired tokens for a more robust integration.
</Update>

<Update label="26 Jan 2026">
  **OneSDK**

  * **\[v1.9.14] Document Processing:**  Resolved an issue where processing large base64 encoded documents could cause a system error, improving the stability of document handling.
  * **\[v1.9.14] Incode Language Parameter:**  The Incode integration  now supports a language parameter, allowing the Incode page to load in Spanish by default for an improved user experience.
  * **\[v1.9.14] Selfie Flow:**  Resolved an issue where the selfie capture flow would crash and get stuck in an infinite loop due to repeated API calls and SDK events, preventing users from completing the selfie verification process.
</Update>

<Update label="22 Jan 2026">
  **KYC**

  * **GDC Netherlands Address Verification:**  Improved address verification for Netherlands by automatically enriching 4-digit postal codes to the full 6-character format and ensuring province fields are accurately populated, leading to better data quality and increased pass rates.
</Update>

<Update label="21 Jan 2026">
  **Portal**

  **Product roadmap now availa/2ble in the Portal**

  We’ve added our **Product roadmap** page directly inside the Portal, giving you a single, always up-to-date view of what we’re working on and what’s coming next.

  **Why this matters**

  Until now, roadmap updates lived across slides and documents, which meant duplication and outdated information. This change gives you a single source of truth that’s easy to access and always current.

  **What’s new**

  * **New Portal page**: A dedicated **Product roadmap** item is now available in the left-hand navigation.
  * **Live updates**: The roadmap is powered directly from our planning system, so changes are reflected automatically.
  * **Interactive view**: You can scroll, filter, and explore upcoming initiatives at a high level.

  **What you’ll see**

  The roadmap provides a current and forward-looking view of:

  * What’s recently **launched**
  * What’s **in discovery**
  * What’s **in progress**
  * What’s **coming up next**

    <img alt="" />

  **IDV**

  * **OCR Checks:**  Resolved an issue where OCR checks were not consistently identifying mismatches in Date of Birth, improving the accuracy of identity verification and reducing manual review efforts.
</Update>

<Update label="20 Jan 2026">
  **KYC**

  * **Document Download Security:** We've enhanced document downloads to validate the base64 data of attachments, preventing downloads of invalid files and returning clear error messages for improved security and reliability.
</Update>

<Update label="19 Jan 2026">
  **KYC**

  * **Webhook Customer Reference:** We've handled a scenario where webhook payloads were using an incorrect customer reference, ensuring that service profile updates, individual risk updates, and workflow overrides now correctly identify the customer.
</Update>

<Update label="15 Jan 2026">
  **KYC**

  * **Risk Override:** Fixed an issue where manually overridden risk scores were incorrectly removed after re-running a workflow, ensuring that manual overrides are now retained as expected unless new risk scores are calculated or existing scores change.
  * **Risk Step Response:** Resolved an issue where the risk step response was no longer returning the 'risk.factor' object, ensuring that risk factors are now correctly included in the response for technical users.
  * **Risk Factor Calculation:** Fixed an issue where risk factors were not being recalculated after AML results were updated to false positive, ensuring accurate risk assessments.
</Update>

<Update label="14 Jan 2026">
  **KYC**

  * **Data Submission for Brazil:** We've improved data processing for Brazilian state information by ensuring that state values are correctly formatted, preventing them from being ignored during searches and improving data accuracy.
  * **Country Code Mapping:** Resolved an issue where the issuing country was not correctly mapped to its country name, ensuring accurate country identification.
</Update>

<Update label="12 Jan 2026">
  **KYC**

  * **AML Monitoring:**  Handle an issue where the v2 AML monitor toggle failed when an entity had an email address, ensuring that ongoing monitoring requests now process correctly without validation errors related to missing country information.
</Update>

<Update label="09 Jan 2026">
  **OneSDK**

  * **\[v1.9.13] Camera Management for Incode:**  We've added a manual teardown function to ensure the camera properly turns off when a user leaves a page, preventing the camera from remaining active unexpectedly.
  * **\[v1.9.13] Document Upload:** Improved OneSDK flow to correctly display document types during the KYC document upload flow, ensuring a consistent user experience regardless of how the flow is initiated.
  * **\[v1.9.13] Onfido Integration Improvements:**   Enhanced the Onfido IDV module within OneSDK to better respect recipe configurations for the useOneStep flow. It introduces the ability to configure an exit button and refines how document types and biometric options are passed to the Onfido SDK, addressing a client's need for flexible IDV processes.
</Update>

<Update label="08 Jan 2026">
  **Portal**

  * **Role Permissions:**  Resolved an issue on F1 where role permissions does not hide the PII on CSV export. only admin users that can see the PII on CSV export other roles will be redacted

  **KYC**

  * **Risk Management:**  Platform users can now standardize the flagging of risk failures with category and issue metadata, enabling reliable triage, routing, and auditing of all risk-based outcomes.
</Update>

<Update label="07 Jan 2026">
  **KYC**

  * **Improved AML Updates:** We've enhanced the bulk update feature in the FrankieOne portal, allowing users to streamline the process of handling large volumes of data by pre-marking true positive cases and enabling 'select all' to target only remaining false positives, with up to 100 selections per page.
</Update>

<Update label="05 Jan 2026">
  **OneSDK** **Middle Name Validation:** We've fixed an issue where middle name mismatches were not being flagged correctly in the onboarding process in some scenarios. This enhancement ensures that discrepancies between declared middle names and ID documents are now properly identified, improving data accuracy and compliance.
</Update>

<Update label="02 Jan 2026">
  **OneSDK**

  * **OCR Mapping for Passports:** We have resolved an issue where the issuing country for passports was not correctly included in the OCR results from OneSDK. This fix ensures that the `issuingCountry` field is now populated for passports, improving data accuracy for document verification.
</Update>

<Update label="18 Dec 2025">
  **KYC**

  * **Risk Profile in Portal Page:** Users can now view detailed KYC risk policies, including configured risk thresholds and how associated risk factors are calculated, in a new read-only portal page.
</Update>

<Update label="16 Dec 2025">
  **OneSDK** **\[v1.9.12] Critical Error Fix:**  Added telemetry to detect critical error that occasionally prevented OneSDK from loading individual details, ensuring a more stable and reliable experience.
</Update>

<Update label="15 Dec 2025">
  **New product: Transaction and Activity Monitoring via Portal**

  **Overview**

  We’re excited to introduce Transaction and Activity Monitoring, a crucial component in detecting and preventing financial crime and fraud beyond initial onboarding.

  FrankieOne's Transaction Monitoring actively oversees all end-customer fiat and crypto transaction activities, as well as non-financial activities like logins and password changes, to identify suspicious patterns that may indicate money laundering, terrorism financing, or various forms of fraud.

  **What’s New**

  Ensure your teams have accurate, real-time information to make informed decisions by using the Transaction and Activity Monitoring in both Portal and API.

  **Key Capabilities**

  **Centralized Alert Management**: Provides a unified view in the FrankieOne Portal for officers to review, investigate, and resolve alerts, with the ability to add comments and track resolution statuses.

  **Benefits**

  * **Stronger Fraud and AML Transaction Monitoring**: Proactively detects various fraud types (synthetic identity, account takeover, payment fraud) and money laundering patterns (structuring, high-risk jurisdictions), reducing financial losses and reputational damage.
  * **Increased Operational Efficiency**: Streamlined alert management and clearer information reduce the time and effort required for officers to investigate and resolve cases, allowing them to focus on true risks.
  * **Enhanced Compliance**: Supports regulatory requirements for AML and fraud detection by providing a robust, auditable system for monitoring and reporting suspicious activities.
  * **Adaptive Risk-Based Approach**: Our continuous monitoring, combined with dynamic risk scoring, ensures that appropriate scrutiny is applied where it's needed most, without impeding legitimate customer activity.

  **Availability**

  Transaction Monitoring is live and can be configured via FrankieOne workflows or integrated through [Transaction Monitoring API](https://docs.frankieone.com/docs/implementation-guide-transaction-monitoring).

  [Click here for more info](https://docs.frankieone.com/docs/overview-transaction-monitoring)

  <Note>
    Contact your Customer Success Manager if you are interested in learning more about Transaction and Activity Monitoring, or implementing it for your organisation.
  </Note>
</Update>

<Update label="11 Dec 2025">
  **KYC**

  * **Single Name Handling:**  Resolved an issue where users with a single legal name were unable to complete KYC checks, ensuring successful verification for all customers.

  **OneSDK**

  * **\[v1.9.11] Process Initialization for Daon Provider:**  Enhanced the status polling mechanism for process initialization to improve reliability and provide a smoother user experience during critical operations.
</Update>

<Update label="07 Dec 2025">
  **KYC**

  * **Address Matching:**  We've improved address matching accuracy for the Netherlands and other European countries by enabling a new feature that better handles street numbers embedded within street names.
</Update>

<Update label="04 Dec 2025">
  **OneSDK**

  * **Data Mapping:** Resolved an issue where Daon data was not correctly mapping to the V2 Portal, ensuring all entity details and images are now displayed accurately and consistently.
  * **IDV Service Stability:** A critical bug causing the IDV service to crash when attempting to find a selfie ID for entities without an ID document has been resolved, improving system stability and reliability.
  * **\[v1.9.10]  Driver's License Expiry Date:**  The eKYC form now includes an 'Expiry Date' field for Driver's Licenses, allowing customers to capture this information during onboarding and improving data completeness for connectors.
  * **\[v1.9.10] IDV Review:**  Fixed an issue where the IDV Review was not displaying document fields correctly when identity documents contained a self-image without an OCR run date, ensuring all relevant document information is now visible.
  * **\[v1.9.10] Biometric Review Page:**  The biometric review page now correctly accepts apostrophes in name fields, resolving an issue that previously caused Know Your Customer (KYC) checks to fail for users with apostrophes in their legal names.
  * **\[v1.9.10] Performance Improvement for Truuth IDV vendor:** We've significantly improved the loading speed of identity verification screens, reducing load times to under 5 seconds for a smoother user experience.
  * **\[v1.9.10] Date of Birth Input:**  The Date of Birth field in OneSDK screens now accurately validates month entries, displaying error messages only after all DOB fields are completed.
</Update>

<Update label="03 Dec 2025">
  **KYC**

  * **IDV Checks:**  Improved IDV checks by excluding phone numbers longer than 10 digits, which previously caused validation failures. This enhances efficiency by preventing invalid inputs.
  * **Aristotle Integration:**  When integrating with Aristotle, the system now accurately displays the Date of Birth (DOB) as 'Unchecked' for match code 98, preventing misleading 'No Match' representations.
</Update>

<Update label="02 Dec 2025">
  **KYC**

  * **Document Display:** Fixed an issue where document images in the Portal incorrectly displayed the same filename for all images. Each image now shows its correct filename, improving clarity and accuracy.
  * **Risk Manual Override:** Fixed an issue where the risk manual override modal was not accessible in the Portal, ensuring users can now properly interact with it.
  * **API Stability:** Resolved an intermittent issue where the `CreateVerify` endpoint would fail due to a service profile not being immediately available after entity creation, improving the reliability of the workflow execution.
  * **Refinitiv AML Reports:** Compliance officers can now generate Refinitiv AML reports that only include true positive matches after all AML hits have been resolved (configurable), streamlining the verification process and reducing manual errors.
  * **Automated Refinitiv Report Generation:** Compliance officers will now automatically receive an updated Refinitiv AML report after resolving all open hits, ensuring a complete and accurate record without manual intervention.
</Update>

<Update label="01 Dec 2025">
  **KYC**

  * **Refinitiv AML Workflow:**  Handled an error when requesting for Refinitiv report that may cause AML step to fail, ensuring that AML workflow results are now accurately determined.

  **OneSDK**

  * **\[v1.9.9] IDV Processing for Daon:** OneSDK now includes a new feature to poll the status of identity verification (IDV) requests when the initial process indicates 'CHECK\_PROCESSING'. This enhancement ensures that users are informed about the ongoing processing of their IDV requests, preventing indefinite waiting times.
</Update>

<Update label="27 Nov 2025">
  **KYC**

  **New product: Transaction and Activity Monitoring V2 API**

  **Overview**

  We’re excited to introduce the Transaction and Activity Monitoring V2 API, a crucial component in detecting and preventing financial crime and fraud beyond initial onboarding.

  FrankieOne's Transaction and Activity Monitoring actively oversees all end-customer fiat and crypto transaction activities, as well as non-financial activities like logins and password changes, to identify suspicious patterns that may indicate money laundering, terrorism financing, or various forms of fraud and scams.

  **What’s new**

  The Transaction and Activity Monitoring V2 API provides a powerful set of endpoints to manage the full lifecycle of activity monitoring:

  * **Evaluate an Activity** (`POST /v2/activities`): Send detailed financial transaction (e.g. deposit, withdrawal) and non-financial activity (e.g. login, registration) data for evaluation against configured rules and models.
  * **Get Individual Activities** (`GET /v2/individuals/:entityId/activities`): Programmatically retrieve a comprehensive list of historical activity data for analysis and integration with internal systems.
  * **Update Results** (`PATCH /v2/individuals/:entityId/results/activity`): Programmatically update the status of activity process results (alerts) within FrankieOne, enabling seamless integration with external case management systems.
  * **Create Individual Session** (`POST /v2/sessions`): Register user sessions in FrankieOne, linking activities to individuals and enabling enforcement of session ownership for enhanced security.

  **Key capabilities**

  * **Real-time monitoring of activities**: Continuously monitors both financial (e.g. deposits, withdrawals, transfers) and non-financial (e.g. logins, password changes) events against predefined rules and models.
  * **Advanced risk signal collection**: Leverages device intelligence, behavioral biometrics, email and phone risk assessment, and IP and location intelligence to enrich decisioning.
    * **Device intelligence**: Detects emulators, VPNs, proxies, and remote desktops, flagging suspicious devices and sessions.
    * **Behavioral biometrics**: Identifies intrinsic fraud behaviors such as unusual copy-paste patterns, typing speed anomalies, or straight-line mouse movements.
    * **IP and location intelligence**: Identifies inconsistencies between IP address location, declared address, and country of origin, detecting suspicious geolocation patterns.
  * **Historical activities**: Historical activity data for context and detailed analysis.

  **Benefits**

  * **End-to-end activity lifecycle management**: From initiating activity evaluations to retrieving detailed results and updating their resolution status.
  * **Deeper insights**: Access to rich, granular data empowers your analysts to perform more thorough investigations and identify emerging fraud patterns.
  * **Greater flexibility and control**: Programmatic control over activity and alert management allows you to tailor FrankieOne's capabilities to your specific operational needs.

  **Availability**

  Transaction and Activity Monitoring is live and can be configured via FrankieOne workflows or integrated through Transaction and Activity Monitoring V2 API.

  <Note>
    Contact your Customer Success Manager if you are interested in learning more about Transaction and Activity Monitoring, or implementing it for your organisation.
  </Note>

  [Click here for more information](https://docs.frankieone.com/docs/transaction-and-activity-monitoring-v-2-api-preview/activities/evaluate-activity)
</Update>

<Update label="26 Nov 2025">
  **OneSDK**

  * \*\*\[v1.9.8] **Biometric SMS Links:**  Fixed an issue where biometric SMS links failed to send to New Zealand phone numbers with non-standard digit lengths (9 or 11 digits), ensuring all valid NZ phone numbers can now successfully receive these links.
  * **\[v1.9.8] OnFido Configuration:**  OneSDK now supports configuring Onfido to enforce mobile-only ID verification, allowing users to seamlessly complete the process on their mobile devices via QR code or link.
  * **\[v1.9.8] User Interface Consistency for Incode:** Resolved an issue where font sizing on message displays was inconsistent, ensuring a uniform and polished appearance for users.
</Update>

<Update label="18 Nov 2025">
  **KYC**

  * **ComplyAdvantage AML Check Failure:** Resolved an issue where malformed place of birth data from ComplyAdvantage caused AML checks to fail. This fix ensures that AML checks are processed correctly, improving the reliability of our compliance procedures.
  * **Audit Event Payload for Supporting Documents:** The audit event payload for newly created supporting documents now includes the processing result status, providing clearer insight into the document’s initial state.
</Update>

<Update label="13 Nov 2025">
  **OneSDK**

  **FrankieOne Unveils Enhanced Document Management for Compliance Teams**

  FrankieOne introduces a new feature designed to streamline manual reviews for compliance officers, enhancing document management efficiency.

  **Key Features** :

  * **Simplified Review Process** : Documents can be quickly assigned an APPROVED or REJECTED status, expediting compliance checks.
  * **Secure Storage** : All documents are securely stored using FrankieOne’s robust infrastructure, ensuring stringent security and access controls.
  * **User-Friendly Portal** : A new Documents tab in the Entity View allows easy upload and management of SUPPORTING documents. Users can select types, review statuses, and add comments via a modal interface.

  This enhancement underscores FrankieOne’s commitment to pioneering secure, efficient compliance solutions in the fintech and regtech sectors.
</Update>

<Update label="17 Nov 2025">
  **KYC**

  * **Aristotle Connector Configuration:** The Aristotle connector now supports country-based tenant configurations and country-based match code mapping, allowing for more flexible and accurate address, date of birth, and ID matching based on specific country requirements.
</Update>

<Update label="12 Nov 2025">
  **KYC**

  * **Alternative address matching rules:** The system now supports alternative address matching rule configurations, allowing for more flexible and robust address verification, particularly for regions like France Residential. This enhancement improves the accuracy of both full and partial address matches.
</Update>

<Update label="12 Nov 2025">
  **OneSDK**

  * **\[v.1.9.7] Additional Document Collection:** The OneSDK now supports a standardized flow for collecting additional identification documents (Passport and Driver’s License) via Daon, ensuring consistent processing and improved user experience.
</Update>

<Update label="11 Nov 2025">
  **KYC**

  * **Refinitiv AML Report Automation:** The system now automatically fetches and attaches Refinitiv AML PDF reports to individual entities after a screening. This provides customers with a comprehensive audit trail for compliance records without manual intervention.
  * **Configurable Address Matching for Socure KYC:** The Socure Know Your Customer (KYC) check now allows for country-specific configuration of address matching criteria. This enhancement enables more comprehensive address verification for USA addresses by utilizing all address elements, while maintaining streamlined matching for other countries based on their specific requirements. This provides greater flexibility and accuracy in address verification.
  * **Enhanced KYC Verification for Europe:** We’ve implemented new configurations for KYC verification in Europe, enabling split recipes for basic and advanced accounts. Basic accounts can now use green and yellow data sources for onboarding up to a 1,000 EUR limit, while advanced accounts require Proof of Address verification using only green (government) sources. This update supports upcoming go-lives in the Netherlands and Italy, and will be extended to other European countries.
  * **Audit Events for Risk Factor Generation:** The system now generates detailed audit events for every risk factor evaluated during workflow execution, providing Compliance Officers with a comprehensive and traceable record of how final risk scores are derived. This enhancement includes new fields within the audit event’s risk factor objects to capture aggregation methods, inputs considered, matched rules, and data sources.
</Update>

<Update label="02 Nov 2025">
  \*\*KYC \*\*

  * **Enhanced Chinese Customer Verification:** We’ve expanded our KYC capabilities for Chinese customers by integrating with Datazoo. This enables verification using China National ID, Passport, and Phone, ensuring comprehensive compliance and a smoother onboarding experience for users.
</Update>

<Update label="30 Oct 2025">
  **KYC**

  * **AML Check Failure:** Handle the scenario where business entities incorrectly showed a ‘Failed’ status due to Anti-Money Laundering (AML) check errors with Refinitiv, even after associated individuals were successfully screened. This fix ensures accurate onboarding status for entities.
</Update>

<Update label="29 Oct 2025">
  **KYC**

  * **Risk Factors Portal:** The Risk Factors Portal now allows scrolling, improving usability for viewing comprehensive risk information.
  * **Combined Endpoint Improvement:** We’ve enhanced the combined endpoint for creating entities and executing workflows, streamlining the process and improving audit logging for clearer tracking of these operations.
  * **Additional Datazoo Rules** : Allow for additional rules for address matching per country when using datazoo data sources
</Update>

<Update label="28 Oct 2025">
  **KYB**

  * **Error Handling:** Improved the system’s resilience when retrieving entity details, ensuring a smoother experience even if underlying APIs or services are temporarily unavailable.
</Update>

<Update label="28 Oct 2025">
  **KYC**

  * **User Permissions:** Fixed an issue where users with the Operator role could not filter entities based on the ‘Assigned To’ field, improving their ability to manage and review assigned entities.
</Update>

<Update label="27 Oct 2025">
  **KYC**

  * **Address Field Logic:** Improved portal where address fields were not clearing correctly when the country was changed, preventing incorrect address data from being stored. This ensures that only relevant address fields for the selected country are saved.
</Update>

<Update label="26 Oct 2025">
  **IDV**

  * **SMS Recipient Name Validation:** Enhanced validation for SMS recipient names to prevent the inclusion of suspicious text or URLs, improving security for both API and Portal users.
</Update>

<Update label="24 Oct 2025">
  **IDV**

  * **Daon Biometrics Portal Display:** Biometric verification results were not appearing in the portal, ensuring all IDV flow outcomes are now correctly displayed for manual review.
  * **Truuth Results Handling:** Improved the Truuth integration to automatically retry retrieving results when they are not immediately available, preventing unnecessary errors and ensuring a smoother data retrieval process. **Platform**
  * **Security:** We have fixed an HTML injection vulnerability in entity audit report generation, preventing unauthorized modification of audit reports and enhancing data integrity.
</Update>

<Update label="23 Oct 2025">
  **KYC**

  * **AML Adverse Media and Other Data Sources:** Improved the display of ‘Other Data Sources’ in AML v2 with Refinitiv by showing the link name and date, and addressed repetitive information in the ‘Adverse Media’ tab for a clearer user experience.
  * **AML Screening:** AML screening in the Portal now includes Gender and Place of Birth as searchable criteria and displays this information in both the Workflow Events tab and AML alerts, improving the accuracy and detail of your AML checks.
  * **Jurisdiction Country Risk Scoring:** Risk Policy Managers can now configure granular jurisdictional risk profiles based on country codes from an individual’s address, place of birth, and documents, allowing for more precise risk assessments during onboarding.
</Update>

<Update label="21 Oct 2025">
  **KYC**

  * **Handle IDV Truuth vendor Session:** Truuth sessions can now be initiated even if no phone number or email is provided, by utilizing a configurable placeholder email address.
</Update>

<Update label="19 Oct 2025">
  **KYC**

  * **OCR Data Capture:** We’ve enhanced the IDV service to allow date of birth information to be populated via OCR even when the name field is already filled, improving the efficiency of data capture.
</Update>

<Update label="17 Oct 2025">
  **KYC / IDV**

  * **Poland Socure Integration:** The Poland Socure system now correctly processes state codes as numerical values, improving data accuracy and integration for Polish entities.
</Update>

<Update label="16 Oct 2025">
  **KYC**

  * **KYC Routing:** We’ve enhanced KYC routing for European entities by integrating Socure in a cascade with DataZoo and GDC, improving customer onboarding pass rates in key regions like Germany, France, and Spain.
</Update>

<Update label="15 Oct 2025">
  **KYC**

  * **Risk Profile Scoring:** Handle scenario where a default risk score of 0 was not being correctly processed, ensuring accurate risk assessments in workflows.
  * **IDV Text Message Update:** The IDV text message has been updated to display days instead of hours providing clearer and more user-friendly information.
  * **Equifax Process Results:** Handle a scenario where the Equifax connector was returning duplicate process results, ensuring accurate and singular data outputs.
</Update>

<Update label="13 Oct 2025">
  **OneSDK**

  * **\[v1.9.5] Performance Monitoring:** We’ve added an event to detect when memory limits are reached due to multiple browser tabs, helping us improve system stability and performance. **KYC / IDV**
  * **API Error Handling:** The Get Hosted URL API now provides detailed error messages in its response when an invalid request field is submitted. This enhancement helps developers quickly identify and resolve issues with their API calls.
</Update>

<Update label="09 Oct 2025">
  **KYC**

  * **Module Configuration:** We’ve added a new configuration that allows different modules to be used based on the country, resolving an error where specific modules were unavailable for certain regions.
  * **Tax ID Document Support:** Users can now add and store Tax ID details for entities within FrankieOne v2, providing a more comprehensive record of identification documents for KYC and IDV checks. This enhancement ensures existing connectors function correctly with the updated data schema.
  * **KYC for Italy:** We’ve enabled Socure KYC checks for individuals in Italy, allowing for compliant onboarding and leveraging Socure’s risk and identity verification capabilities with configurable address verification rules.
</Update>

<Update label="08 Oct 2025">
  **KYC / IDV**

  * **Flexible Risk Factor Aggregation Methods:** Risk Configuration Administrators can now define how multiple scores from a single risk factor are combined, choosing from sum, max, min, average, or count, to precisely control risk assessment calculations.
  * **Risk Factor Configuration:** Risk Policy Managers can now configure a new risk factor that automatically calculates an individual’s age from their date of birth and applies a score based on defined age ranges, enabling more precise age-related risk assessments.
  * **Name Transliteration Verification:** We’ve enhanced our identity verification process to accurately cross-reference names provided in Latin characters with native script names (e.g., Chinese characters) using a specialized service. This ensures more precise KYC checks for international identities and helps reduce identity fraud.
  * **KYC Ruleset Configuration:** We have enhanced our KYC rulesets to support multiple distinct verification requirements within a single ruleset, ensuring comprehensive and flexible KYC processes are maintained and accurately tested during the transition to FrankieOne v2.
</Update>

<Update label="03 Oct 2025">
  **KYC**

  * **DVS Visa Checks:** Our DVS Visa Check functionality now supports ‘VISA’ document types in addition to ‘PASSPORT’ documents, allowing for more comprehensive and accurate verification of entity visa requirements.
  * **VEVO Visa Checks:** VEVO Visa Checks now support ‘VISA’ document types in addition to ‘PASSPORT’ documents, ensuring comprehensive visa verification for all relevant entities.
  * **Custom Risk Attributes:** Onboarding Rules Owners can now pass custom data attributes into FrankieOne to apply risk scores, allowing for seamless integration of proprietary business logic and internal scoring models into a unified risk assessment. This feature leverages the individual.customAttributes map in the API request payload.
  * **Risk Factor Configuration:** Risk analysts can now assign specific risk scores based on ‘product type’ values within an entity’s custom attributes, allowing risk assessments to automatically adapt to the inherent risk of different transaction channels.
  * **Risk Factor Configuration:** Risk Policy Managers can now configure risk factors that assign scores based on the type of document provided in an individual’s profile, allowing for more granular risk modeling based on identification data.
</Update>

<Update label="30 Sep 2025">
  **OneSDK**

  * **\[v1.9.4] Address Form** : Resolved an issue where the address state field was not correctly reset when changing the country in the review form, ensuring accurate address data entry.
  * **\[v1.9.4] Review Screen Prepopulation** : Fixed an issue where the phone number was not prepopulated on the 1SDK review screen, ensuring a smoother user experience when completing IDV flows.
</Update>

<Update label="26 Sep 2025">
  **Portal**

  * **Risk Score Display:** The risk score button on the entity profile now correctly displays the risk factors screen, ensuring users can access detailed risk information. **KYC**
  * **DVS Passport Checks:** Improve handling of DVS passport checks failed for single-name applicants using special characters like dots or hyphens. The system now correctly processes these names by sending a blank given name to the DVS, improving verification success rates.
</Update>

<Update label="25 Sep 2025">
  **OneSDK**

  * **\[v1.9.3] Incode SDK Integration:** Capability to configure Incode SDK to expose a option within the settings, allowing for a tutorial screen to be displayed before document scanning on both desktop and mobile devices.
  * **\[v1.9.3] Address Input:** When a quota error occurs during address input via Google API, users can now manually enter their address details, ensuring a smoother onboarding experience.

  **KYC**

  * **Data Mapping:** The system now automatically maps the best-matched entity data (name and date of birth) from KYC Plus into key-value pairs, improving data consistency and integration for downstream systems.
  * **Refinitiv AML Screening:** We’ve enhanced Refinitiv AML screening by adding the ability to send an individual’s gender and country of birth, improving match accuracy and reducing false positives. This also includes an update to the AML PRO schema to store matched gender information.
</Update>

<Update label="23 Sep 2025">
  **KYC**

  * **Integration and Support for Birth Certificate Verification in Global KYC.** The Birth Certificate verification feature has been fully integrated and tested within the Global KYC initiative. This update ensures that Birth Certificates are now a supported document type, ready for inclusion in future product demonstrations, with comprehensive validation of end-to-end functionality.
</Update>

<Update label="22 Sep 2025">
  **KYC**

  * **HostedUrl API customerRef mapping:** External references created via hosted link api will now be saved under external references instead of custom attributes
</Update>

<Update label="19 Sep 2025">
  <Icon icon="sparkles" /> **Onboarding Fraud**

  **Overview**

  We're excited to introduce Onboarding Fraud, a smarter way to detect and block fraudulent activity at the very first step of the customer journey. This feature helps businesses reduce risk, comply with AML regulations, and onboard trusted customers faster with minimal friction.

  **What's New**

  Onboarding Fraud enhances our Graduated Onboarding framework, empowering you to design an adaptive and intelligent sign-up process. By assigning a real-time risk score to each customer based on your configured rules, you can dynamically tailor the entire user journey.

  * **For Lower-Risk Users** : Automatically fast-track them through a seamless, low-friction flow to get them started faster.
  * **For Higher-Risk Users** : Automatically trigger your chosen due diligence steps—such as ID verification, biometrics, or sanctions screening—in response to specific risk signals.

  This adaptive approach ensures you can welcome genuine customers effortlessly while applying robust security where it matters most, all according to your unique risk appetite.

  <img alt="" />

  **Key Capabilities**

  * **Device Intelligence** : Detects emulators, VPNs, proxies, and remote desktops through cookies and fingerprinting.
  * **Behavioural Biometrics** : Flags suspicious behaviour like copy-paste banking details, unnatural typing, or straight-line mouse movements.
  * **Email & Phone Risk Assessment**: Evaluates email age, domain, and unusual activity across multiple accounts.
  * **IP & Location Intelligence**: Identifies mismatches between IP, phone, and country of origin.
  * **Dynamic Risk Scoring** : Instantly categorises users into risk tiers for tailored verification steps.

  **Benefits**

  * **Faster Onboarding** : Genuine customers experience less friction, reducing drop-offs and improving conversion rates.
  * **Stronger Fraud Prevention** : Detect and block synthetic IDs, bots, and repeat fraud rings before they reach account creation.
  * **Cost Efficiency** : Reduce reliance on expensive checks by only applying them where risk is high.
  * **Regulatory Compliance** : Stay aligned with AML requirements using risk-based onboarding practices

  **Availability**

  Onboarding Fraud is live and can be configured via FrankieOne workflows or integrated through OneSDK.

  [Watch the video](/docs/fraud-checks#video-guide)

  [Click here for more info](/docs/fraud-prevention-risk-based-onboarding-1)

  Contact your Customer Success team member if you are interested to learn more.
</Update>

<Update label="19 Sep 2025">
  **KYC**

  * **Country of Issue Mapping:** Handled a scenario when ‘Country of Issue’ for foreign passports was incorrectly mapped in entity data, preventing correct DVS checks and causing verification failures for customers.
</Update>

<Update label="16 Sep 2025">
  **KYC**

  * **Equifax Connector Error:** Resolved an issue where the Equifax connector would return a 500 error when processing certain results due to a logging failure. The connector now handles these cases gracefully, preventing system errors.
</Update>

<Update label="15 Sep 2025">
  **OneSDK**

  * **\[v1.9.2] OCR-only Flow Process:** Integrates support for Incode’s combined consent and document selector features, providing enhanced flexibility and control over the user onboarding flow within OCR-only processes.
  * **\[v1.9.2] IDV Workflow:** Improve behavior of confirmation checkbox in the IDV workflow, ensuring users must now check the box to proceed and complete the process.
  * **\[v1.9.2] Incode SDK Integration:** Capability to configure Incode SDK to expose a option within the settings, allowing for a tutorial screen to be displayed before document scanning on both desktop and mobile devices.
</Update>

<Update label="12 Sep 2025">
  **OneSDK**

  * **\[v1.9.1] Onfido biometric variants in OneSDK :** OneSDK now supports exposing different Onfido ‘requestedVariant’ configurations, allowing for more flexible integration with Onfido’s biometric verification options (video, motion, and standard).
</Update>

<Update label="11 Sep 2025">
  <Icon icon="sparkles" /> **New Feature:**

  **Workflow Viewer – Full Transparency for Your Compliance Workflows**

  Workflow Viewer is a new capability in the FrankieOne V2 Portal that brings total transparency to your onboarding and compliance processes. This feature will be enabled for **all V2 Portal customers** as part of the general release.

  Until now, customers had to rely on technical support to understand how their workflows were configured. This slowed training, complicated audits, and made it difficult to validate recent changes. Workflow Viewer removes this friction by putting visibility and control back into your hands.

  <img alt="" />

  **Key Benefits**

  * **Complete Visibility** – instantly view and explore every verification step, condition, and action in your workflows
  * **Simplified Compliance** – quickly validate configurations for audits and regulators
  * **Faster Training** – onboard new staff with confidence using clear, visual workflow diagrams
  * **Insights** – click on any component to see configuration details

  **Coming Soon**

  In this release, Workflow Viewer is **read-only**. Editing, deleting, or deploying workflows, as well as access to historical versions, will be delivered in future updates.

  [Watch the video](/docs/fraud-checks#video-guide)

  [Click here for more info](/docs/fraud-prevention-risk-based-onboarding-1)
</Update>

<Update label="09 Sep 2025">
  **OneSDK**

  * **\[v1.9.0] Start Screen Image Display:** The start screen now correctly maintains the aspect ratio of images, ensuring they display as intended without distortion.
  * **\[v1.9.0] Document Upload:** We are thrilled to announce this new feature where customers can now seamlessly generate secure, standalone links that allow users to upload their ID documents safely. This cutting-edge solution drastically minimizes the risks associated with insecure email submissions, ensuring both new and existing entities enjoy a safer, more efficient process. Learn more [here](/docs/using-hosted-onesdk#document-collection)
</Update>

<Update label="10 Sep 2025">
  **KYC**

  * **Phone Ownership Verification:** We’ve enhanced our identity verification capabilities to include phone ownership checks for Rest of World non-document verifications, allowing for more robust identity matching.
</Update>

<Update label="09 Sep 2025">
  **Portal**

  * **Global KYC Document Management:** National ID is now the default document type for all countries in Global KYC, replacing the Pan Card label for India and ensuring consistent document options globally.
</Update>

<Update label="09 Sep 2025">
  **KYC**

  * **Data Source Mapping:** Enhanced the mapping of Australian Driver’s License data sources to ensure accurate name and date of birth verification within the API response, and allowing ore comprehensive data reporting through configuration.
</Update>

<Update label="10 Sep 2025">
  **KYC**

  * **API Endpoint for Comments:** A new API endpoint has been created to allow client applications to add auditable comments to any entity, providing important context for manual actions.
</Update>

<Update label="08 Sep 2025">
  **KYC**

  * **Document Generation:** Fixed an issue for certain custom flow where the ID number was not being populated in documents generated after biometric capture, ensuring complete document details from the IDV provider.
</Update>

<Update label="03 Sep 2025">
  **OneSDK**

  * **\[v1.8.16] Form Review:** The form review screen now improved submission email and phone number fields, ensuring all user-provided contact information is captured.
</Update>

<Update label="03 Sep 2025">
  **OneSDK**

  * **\[v1.8.16] Embedded IDV Flow Styling and Performance:** We’ve enhanced the Embedded IDV flow to allow for custom styling, providing greater flexibility in user interface design. Additionally, improvements have been made to optimize data handling, preventing app crashes during repeated use of the IDV flow.
</Update>

<Update label="01 Sep 2025">
  **KYC / IDV**

  * **Global KYC Checks:** We have enhanced our system to validate Global Data Consortium (GDC) KYC checks for individual entities, ensuring accurate processing of results. This improvement helps maintain regulatory compliance, prevent fraud, and streamline customer onboarding.
</Update>

<Update label="28 Aug 2025">
  **KYC**

  * **Better Handling of Resolved AML Issues:** Resolved an issue where the issue banner was incorrectly removed for AML failures when marking process results as ‘true\_positive\_reject’. The banner will now persist as expected, ensuring proper visibility of AML-related issues.
  * **Data Zoo Connector:** The Data Zoo connector for France has been updated to no longer require address element 4 (state), improving flexibility for address validation in France.
</Update>

<Update label="27 Aug 2025">
  **KYC**

  * **Added Support for Name Change Certificates:** This enhancement allows users to efficiently add and manage Name Change Certificate details for entities, providing a comprehensive record of identification documents for improved KYC and IDV checks.
</Update>

<Update label="27 Aug 2025">
  **OneSDK**

  * **\[v.18.15] Daon Initialisation Improvement:** We have resolved an issue where the Daon IDV process was not correctly initializing, ensuring smoother identity verification workflows.
  * **\[v.1.8.15] Improved Performance on Handling Multiple Attachments:** Resolved an issue where the OneSDK would crash or slow down significantly when handling multiple attachments, particularly during biometric flows. This fix prevents crashes and improves performance by optimizing how image data is handled, ensuring a smoother user experience during retries.
</Update>

<Update label="26 Aug 2025">
  **KYC**

  * **ID Number Verification:** The system now accurately compares ID numbers for individuals even when different document types (e.g., Passport and Driver’s License) are used for KYC and biometric verification, improving matching accuracy. Please contact support to enable this capability.
</Update>

<Update label="21 Aug 2025">
  **\[v1.8.14] IDVerse Error Handling:** Improved error handling for IDVerse scans by introducing a new error type, “IDVerseScanFailedAndDestroyed”, which is triggered after multiple failed OCR or biometric attempts. This provides clearer feedback when an IDVerse scan cannot be completed.

  **\[v1.8.14] IDVerse Biometric Workflow:** The system now prevents users from starting biometric verification for a new transaction if OCR has not been completed, ensuring a more streamlined and correct workflow.

  **\[v.1.8.14] Additional Error Tracking:** The SDK now captures and externalizes ‘out of bounds memory’ errors from the Incode OCR component, improving error handling and stability.
</Update>

<Update label="20 Aug 2025">
  **KYC**

  * **API Document Updates:** Fixed an issue where document object fields and supplementary data could not be updated or cleared via the API, ensuring that document information can now be correctly modified and persisted.
  * **Incode Verification Process.** The system now correctly handles cases where a user has not uploaded any images during the Incode verification process, ensuring the applicant’s session is appropriately failed and marked as complete from the Incode side.
</Update>

<Update label="18 Aug 2025">
  **Portal**

  **Global KYC on V2**

  <img alt="" />

  We’re excited to announce a significant enhancement to our platform that will revolutionize your global Know Your Customer (KYC) process: Global KYC Expansion!

  This enhancement is designed to simplify and broaden your ability to onboard clients from around the world, offering a more robust and efficient KYC experience.

  *What’s New?*

  We’ve expanded our KYC capabilities to include a wider range of countries and document types, allowing you to seamlessly verify international clients. This means:

  **Broader Country Coverage** : We now support a comprehensive list of countries, including Canada, United Kingdom, and Hong Kong, with ongoing expansion to regions like France, Netherlands, Italy, Germany, Spain, Belgium, and Brazil.

  **Enhanced Document Support** : We’ve added crucial document types such as National IDs, Passports, Driver’s Licence and Tax IDs for various countries, ensuring you have the flexibility you need.

  **Improved Address Handling** : Benefit from enhanced address capture, including specialized structures for countries like Great Britain and Singapore.

  **Seamless User Experience** : We’ve prioritized a user-friendly interface, ensuring that the process remains straightforward and efficient for your team.

  *Why is this important for you?*

  The Global KYC Expansion is built to directly address your needs for:

  **Expanded Market Reach** : Onboard clients from more regions with confidence and ease.

  **Increased Efficiency** : Reduce manual effort and streamline your verification processes with our dynamic and intelligent system.

  **Greater Compliance** : Stay ahead of evolving regulatory requirements with our continuously updated KYC framework.

  **Reduced Risk** : Enhance your due diligence with comprehensive and accurate identity verification.

  *Enhancements*

  **Improved Display of Pending IDV Checks** : For workflows awaiting IDV results, the status is now clearly displayed as `'UNCHECKED'` instead of `'FAIL'`. A banner has been added to prompt operators on the next steps, such as sending a biometrics link to the customer.
</Update>

<Update label="19 Aug 2025">
  **KYC**

  * **Integration and Support for Birth Certificate Verification in Global KYC.** The Birth Certificate verification feature has been fully integrated and tested within the Global KYC initiative. This update ensures that Birth Certificates are now a supported document type, ready for inclusion in future product demonstrations, with comprehensive validation of end-to-end functionality.
</Update>

<Update label="18 Aug 2025">
  **KYC**

  * **Enhanced Attachment Date Display.** Improved the attachment displays with its unique created date, enhancing clarity and organization for users.
  * **Improved Consistency in Workflow Execution Responses.** We have made an important update to enhance the consistency of responses from our workflow execution endpoints. Both `{{result}}` and `{{status}}` fields are now included in the response, providing a complete picture of the workflow execution. You can rely on the `{{status}}` field as the definitive source for the current state of the workflow, without needing additional API calls.
  * **Enhanced Logging Features.** This update introduces additional logging capabilities for improved tracking and auditing. It includes logs for OCR comparison, specifically addressing cases where values may be blank, and audit logs for onboarding URL errors to ensure attempts are documented.
</Update>

<Update label="15 Aug 2025">
  **OneSDK**

  * **\[v1.8.13] Enhanced Network Failure Handling in OneSDK** : In this update, OneSDK improves the IDV review flow by gracefully handling network failures during the KYC process. Users are now given the opportunity to retry submissions up to three times, with clear error messages guiding them through network issues, ensuring a smoother and more transparent user experience.
  * **\[v1.8.13] Enhance User Experience with Start Screen** : The new start screen now dynamically renders the logo and call-to-action (CTA) based on provided configurations, ensuring a tailored user experience. It emits specific events upon loading, CTA interaction, and error occurrences, enhancing responsiveness and feedback mechanisms. [Read more…](/docs/implementation-guide/module/ekyc/start)
</Update>

<Update label="07 Aug 2025">
  **KYC**

  * **Enhanced Verification Process** : We have improved the verification process to ensure more accurate results. A recent update ensures that when a full match is achieved through our primary verification system, additional partial matches from secondary sources are minimized to prevent confusion.
  * **Added Support for International Passport through GDC** : This enhancement allows users to efficiently add and manage International Passport details, streamlining KYC and IDV processes
  * **Enhanced Socure Audit Log** : This update adds extra audit logs for error scenarios and includes reason codes in the API response, improving debugging and providing more context for KYC check results.
</Update>

<Update label="05 Aug 2025">
  **Portal**

  What’s new in this release?

  * **Collapsible Profile Summary in Entity Header** : For quicker access to key information, a profile summary (including Date of Birth, Address, and Latest Workflow) is now displayed in the header of the entity page. This summary can be expanded to show more details like email and phone.
  * **Improved SMS Message for ‘Send Link’** : When using the ‘Send Link’ feature without providing an applicant’s name, the SMS message sent will now use the generic term ‘customer’ instead of showing an unpolished placeholder variable, ensuring a more professional experience.
  * **Corrected Audit Report for Data Modifications** : Fixed an issue where the audit report would incorrectly include unmodified document information when only other fields (like Customer Reference) were updated. The audit report now accurately logs only the fields that were actually changed.

  **KYC**

  * **Enhanced OCR Comparison for Issuing Country** : Add new config for mismatches between the issuing country extracted from OCR and the issuing country provided in the user’s identity document. This aims to improve the accuracy of identity verification.
  * **Added Support for National ID through Socure.** This enhancement allows users to efficiently add and manage National ID details, streamlining KYC and IDV processes.
  * **Added Support for Marriage Certificate document type.** FrankieOne v2 now supports the addition and storage of Marriage Certificate details for entities. This enhancement allows users to maintain a comprehensive record of identification documents, streamlining KYC and IDV checks.
  * **Added Support for National ID through Netbay.** This enhancement allows users to efficiently add and manage National ID details, streamlining KYC and IDV processes
  * **Added Support for National ID through Advance AI.** This enhancement allows users to efficiently add and manage National ID details, streamlining KYC and IDV processes.
  * **Duplicate Name Check Stripping.** This update introduces the ability to automatically strip duplicate name checks from entity check responses. Enabled via the configuration flag, this feature significantly reduces redundancy by consolidating checks originating from the same source.
  * **Enhanced OCR Comparison for Issuing Country.** Add new config for mismatches between the issuing country extracted from OCR and the issuing country provided in the user’s identity document. This aims to improve the accuracy of identity verification.

  **OneSDK**

  * **Latest Version** : 1.8.12
  * **Support Biometrics and OCR Split flow with Daon** : We are now supporting Daon,a new IDV vendor to perform split flow for OCR extraction and Biometrics. This update ensures seamless handling of verifications across diverse document types and countries, providing a secure onboarding experience.
  * **Support OCR-only flow with Daon** : We are now supporting Daon,a new IDV vendor to perform OCR-only extraction on document uploads.
  * **Support IDV Flow with Daon** : Implement Headed IDV flow with OCR extraction and Biometrics. This update ensures seamless onboarding experience using the Daon’s interface.
  * **Phone Number Field Enhancement** : This update improves the handling of phone numbers in fields with available code options, ensuring correct separation of area codes and numbers. It addresses various formats, including those with and without the ’+’ sign and ’-’ separators, enhancing data submission accuracy.
</Update>

<Update label="04 Aug 2025">
  What’s new in this release?

  **KYC**

  What’s new in this release?

  * **Enhanced Centrix Result Filtering** : This update introduces the ability to ignore NotSearched and NA results from Centrix, controlled by a new configuration option. Response handling has been updated to accommodate this filtering, and CI scripts have been refined for more efficient testing.
</Update>

<Update label="30 Jul 2025">
  What’s new in this release?

  **KYC**

  * **Enhanced Document Type Support for Onfido Integration** : This release introduces expanded document type support for the Onfido integration, significantly improving ID verification. A new configuration option now allows the system to recognize a wider array of national identity documents. This enhancement provides greater flexibility and comprehensive coverage for user verification processes.
  * **Enhanced Data Access for Socure Connector** : We are excited to announce an update to the Socure connector. With this enhancement, our customers will now have access to a broader set of enriched data provided by Socure’s verifyPlus service. This includes detailed information such as addresses, phone numbers, and email addresses, enabling more comprehensive identity verification and user insights.
</Update>

<Update label="29 Jul 2025">
  What’s new in this release?

  **OneSDK**

  * **Enhanced Success Screen** : Use the customisable success screen so that customers can make configuration changes to it such as title and description.
  * **Support IDV Flow with Daon** : Implement Headed IDV flow with OCR extraction and Biometrics. This update ensures seamless onboarding experience using the Daon’s interface.
</Update>

<Update label="21 July 2025">
  What’s new in this release?

  **OneSDK**

  * **Latest version** : 1.8.11

  ***IDVerse Updates***

  * **Improved Handling of Multiple Document Attempts** : This update addresses issues related to multiple document submission attempts, enhancing the overall user experience and stability.
  * **Enabled Skip Face Scan Intro Option** : You now have the option to skip the introductory screen for face scans.
  * **`ExposedscanFail Error Events`**: We have exposed `scanFail` error events, providing more detailed feedback and enabling better error handling within your applications.

  <Callout icon="thumbtack">
    ##### Important Notes

    * **IDVerse Integration** : This release utilises the IDVerse release version from July 9, 2025.
    * `skipFaceScanIntro` **Flag** : The `skipFaceScanIntro` flag is set to `FALSE` by default. To enable this feature and set it to TRUE, you can include the `skipFaceScanIntro` flag within the `biometrics` component configuration, either on the `OneSdk` instance or directly on the biometrics component.

    ```javascript Example Usage theme={null}
    // On OneSDK Instance
    const oneSdk = await OneSdk({
      session: sessionObjectFromBackend,
      mode: "production",
      recipe: {
        ocr: {
          provideReviewScreen: false,
          provider: {
            name: "idverse",
          }
        },
        biometrics: {
          provider: {
            name: "idverse",
            skipFaceScanIntro: true, // Set to true to skip the intro
          }
        }
      }
    });

    // OR on biometrics component
    const biometrics = oneSdk.component('biometrics', {
      provider: {
        name: 'idverse',
        skipFaceScanIntro: true, // Set to true to skip the intro
      }
    });
    ```
  </Callout>

  <Callout icon="bell">
    ##### Known Issues

    * **Biometrics Screen Stuck on Phone (with** `skipFaceScanIntro` **enabled)** : When `skipFaceScanIntro` is enabled and the user’s journey begins on a mobile phone, we have identified an issue where the user may get stuck on the biometrics screen and cannot proceed. This issue is **not observed** when the journey starts from a desktop device. We are actively investigating this and will provide a fix in a future release.
  </Callout>

  ***Hosted OneSDK***

  * **Enhanced Success Screen:** Use the customisable success screen so that customers can make configuration changes to it such as title and description

  ***

  **Portal**

  * **Improved Handling of Blocklisted ‘Unchecked’ Entities** : Enhanced the user experience for entities that are blocklisted before any checks are run. The ‘Edit profile’ and ‘Verify profile’ actions are now correctly disabled, and a clear banner explains that no further checks can be run.
  * **Improved Duplicate Resolution User Flow** : Redesigned the duplicate resolution process to be more intuitive. Entity updates are now triggered only after a user clicks the **Confirm** button on the match summary page, rather than during intermediate steps.
  * **Global Comments for Duplicates** : Enabled the use of a global comment field within the duplicate resolution workflow, improving communication and context for resolution decisions.
  * **Improved Blocklist Error Messaging** : Replaced a technical error message with a more clear messge (“Unable to process blocklist. Please check provided data”) when an invalid attribute (e.g., a duplicate or incorrectly formatted value) is added to a blocklist entry.
  * **Enhanced UI for Duplicates Comparison Screen** : Improved the user interface on the duplicates comparison screen with better padding and styling for highlighted fields, a more balanced side-by-side layout for comments, and ensuring matching fields remain vertically aligned.
  * **Corrected Workflow ‘Attempts’ Count in Duplicates** : Fixed a bug where the ‘Attempts’ count for a workflow would incorrectly jump by multiple numbers after resolving duplicate entities. The count now accurately reflects the number of workflow runs.
  * **Fixed Auto-Scroll for Visa Check Summary** : Corrected an issue where clicking the Visa Check icon in the workflow summary did not automatically scroll the page down to the corresponding Visa Check details section. The link now navigates as expected.
  * **Improved Error State UI** : Implemented a more user-friendly error fallback page. Instead of a blank page, users who encounter a system error will now see a helpful UI with clear information.
  * **Enabled Searchable Dropdowns Across the Portal** : Improved usability by making dropdown fields searchable across the Portal, including in the Entity form (Workflow, Country, ID Type), Blocklist modals, and Settings.

  ***
</Update>

<Update label="17 July 2025">
  What’s new in this release?

  **KYC**

  * **Automatic Blocklist Creation (v2):** Blocklist in v2 now automatically creates a default blocklist if none is available when the scope is set to ALL or DEFAULT.
  * **National ID Integration (AsiaVerify):** FrankieOne v2 now supports adding and managing National ID details for enhanced identity verification through AsiaVerify.
  * **KYC Address Submission Enhancement:** We’re enhancing KYC efficiency by enabling the submission of both Current and Previous addresses in a single request. This update will streamline processes across supported connectors.

  ***
</Update>

<Update label="15 July 2025">
  What’s new in this release?

  **OneSDK**

  * **Latest Version** : 1.8.10
  * **Enhanced Result Screen Flow** : In the hosted OneSDK versions v1 and v2, for both IDV review and KYC fraud processes, the success screen now consistently displays a success message with only one full stop for better user experience.
  * **Safari Cookie Blocking Causes LocalStorage SecurityError** : In Safari on macOS, enabling “Block all cookies” in Preferences -> Privacy results in a SecurityError when websites attempt to use localStorage. Consider using SessionStorage as a fallback or advise users not to block all cookies.
  * **Customizable Checkbox Colors in OneSDK/HostedOneSDK V2** : FrankieOne now offers enhanced customization in its OneSDK/HostedOneSDK V2, allowing businesses to tailor checkbox colors to match their brand themes.

  ***
</Update>

<Update label="14 July 2025">
  What’s new in this release?

  * Custom Views
  * Send IDV Link via SMS
  * Risk Overrides
  * Duplicate Checks
  * Matchlist
  * AML Monitoring

  **Custom Views** : ***Tailor Your Data, Your Way!***

  Elevate your workflow efficiency with Custom Views, a powerful new feature designed to give you unparalleled control over how you see and interact with your data. No more sifting through irrelevant information – now you can personalise your view to focus on what matters most.

  <img alt="" />

  **What’s New & Why You’ll Love It:**

  **Personalised Data Display** : Easily apply filters to your Entities table and save those exact configurations as a custom view. Quickly access highly relevant customer data, tailored precisely to your tasks and analysis needs.

  **Instant Access** : Navigate effortlessly between your saved custom views. Each view remembers your preferred filters, allowing you to instantly load the data you need for specific workflows or compliance checks.

  **Streamlined Organisation** : Create up to 5 unique custom views to manage different aspects of your operations. Keep your workspace clean and organised by editing or deleting views as your priorities change.

  Ready to revolutionise your data experience? Explore the new Custom Views capabilities today! [Learn more about Custom Views in our Public Docs](/docs/custom-views).

  ***

  **Send IDV Link via SMS** : ***Accelerate Your KYC Process!***

  Streamline your customer onboarding and identity verification (IDV) with the new Send IDV Link via SMS feature. This secure and convenient method allows you to instantly reach customers on their mobile devices, significantly speeding up the collection of crucial information.

  <img alt="" />

  **What’s New & Why You’ll Love It**:

  **Rapid Customer Engagement** : Send secure links directly to your customers’ mobile phones via SMS for swift document and biometric collection. Reduce friction and delays in the onboarding journey.

  **Enhanced Convenience** : Empower your customers to complete necessary IDV steps at their convenience, from anywhere, directly from their mobile device. This improves completion rates and customer satisfaction.

  **Efficient KYC Workflows** : Automate the process of sending IDV requests, freeing up your team to focus on more complex tasks. This feature is integrated to ensure a seamless flow from request to successful verification.

  Ready to accelerate your onboarding? Discover how to send IDV links via SMS! [Learn more about Send IDV Link via SMS in our Public Docs](/docs/create-a-new-profile-via-the-portal).

  ***

  **Risk Overrides** : ***Gain Granular Control Over Risk Assessments!***

  Introducing Risk Overrides, a critical enhancement that provides your team with the flexibility and precision needed for managing complex risk profiles. Now, you can manually adjust overall risk scores, ensuring that your assessments truly reflect unique operational insights and circumstances.

  <img alt="" />

  **What’s New & Why You’ll Love It**:

  **Tailored Risk Management** : Manually override system-calculated risk scores for specific entities. This allows you to factor in external information or unique scenarios that the automated system might not capture.

  **Maintain Accurate Profiles** : Ensure that every entity’s risk level is precisely aligned with your internal policies and expert judgment. This flexibility prevents misclassification and supports more informed decision-making.

  **Full Transparency & Auditability**: All risk score overrides are meticulously logged, including the previous and new scores, the user who made the change, and the reason. Maintain complete audit trails for compliance and internal review.

  Ready for more precise risk management? Explore the capabilities of Risk Overrides! [Learn more about Risk Overrides in our Public Docs](/docs/risk-assessment-v2#overriding-risk-score).

  ***

  **Duplicate Checks** : ***Optimise Data Integrity and Prevent Fraud!***

  Fortify your customer data and enhance onboarding efficiency with our new Duplicate Checks functionality. This intelligent feature automatically identifies and flags potential duplicate entities, helping you maintain a clean, consistent database and prevent fraudulent activities.

  <img alt="" />

  **What’s New & Why You’ll Love It:**

  **Automated Duplicate Detection** : Proactively identify duplicate customer records during the onboarding process. This significantly reduces the need for costly, repetitive KYC checks and streamlines operations.

  **Superior Data Quality** : Ensure the accuracy and consistency of your entity data. By preventing conflicting records, you minimise data redundancy and improve overall data governance.

  **Fraud Prevention** : Effectively detect and block repeat actors attempting to create multiple accounts. This adds a crucial layer of security, protects your platform, and reinforces compliance.

  **Streamlined Resolution** : Easily filter entities with duplicate issues, view detailed potential matches, and quickly resolve discrepancies. The system guides you through marking, resolving, or consolidating records.

  Ready for smarter data management? Discover how Duplicate Checks can transform your operations! [Learn more about Duplicate Checks in our Public Docs](/docs/managing-duplicates).

  ***

  **Matchlist** : ***Proactive Risk Identification and Control!***

  Enhance your defence against high-risk entities with the introduction of Matchlist (Blocklist Management). This new module empowers your investigators to manage and utilise blocklists effectively, providing immediate insights into flagged entities and the reasons behind their inclusion.

  <img alt="" />

  **What’s New & Why You’ll Love It:**

  **Centralised Blocklist Control** : Easily add and remove individual entities from your blocklists. Maintain precise control over who is flagged, ensuring your risk management is always up-to-date.

  **Instant Risk Identification** : When an entity matches a blocklist entry, it is immediately flagged, prompting your team to investigate. This proactive approach helps prevent high-risk individuals from proceeding through your workflows.

  **Transparent Decision-Making** : Apply distinct reason codes to each blocklisted entry, providing clear context for all decisions. This transparency supports internal reviews and regulatory compliance.

  **Comprehensive Audit Trails** : All actions related to blocklist management—including additions, removals, and associated reasons—are logged, providing a clear history for audit and compliance purposes.

  Ready to elevate your risk strategy? Explore the power of Matchlist (Blocklist Management) today! [Learn more about Matchlist (Blocklist Management) in our Public Docs](/docs/blocklists-overview).

  ***

  **AML Monitoring** : ***Continuous Vigilance for Ongoing Compliance!***

  Ensure continuous compliance and robust risk management with our new Ongoing AML Monitoring workflow. This dedicated feature within the portal allows you to proactively track entities for Anti-Money Laundering (AML) risks, transforming how you manage regulatory obligations.

  <img alt="" />

  **What’s New & Why You’ll Love It**:

  **Proactive AML Oversight** : Automatically monitor entities for ongoing AML risks after their initial onboarding. This ensures that changes in an entity’s risk profile are immediately detected and addressed.

  **Intelligent Alert Management** : View, prioritise, and resolve AML alerts directly within the portal. The system helps you focus on new or critical issues, streamlining the review process and reducing manual effort.

  **Flexible Monitoring Controls** : Gain granular control over AML monitoring with options to manually or automatically enable and disable it based on workflow outcomes (e.g., passed onboarding, archived status).

  **Comprehensive History & Audit**: Access detailed audit logs of all monitoring status changes and AML alerts. Understand when an entity was flagged, why action was taken, and by whom, ensuring full transparency and compliance.

  **Support for Multiple Workflows & Providers**: Our system seamlessly integrates with leading AML service providers, giving you a unified view across various workflows and data sources.

  Ready to enhance your AML compliance? Dive into the features of Ongoing AML Monitoring! [Learn more about AML Monitoring in our Public Docs](/docs/review-and-resolve-potential-aml-matches).

  ***

  **KYC**

  * **International Passports** : Full support for creating, updating, retrieving, and deleting international passport details, including enhanced connector compatibility for seamless KYC and IDV checks.
  * **Citizenship Certificates** : Now fully supported for robust identity verification and record-keeping.
  * **ImmiCards** : Added support for Immigration Card documents, further extending our document verification capabilities.
  * **Detailed Audit Events for AML Monitoring** : Audit events are now logged whenever AML monitoring updates are triggered. This provides detailed tracking of successful and failed updates, ensuring better compliance oversight.
  * **Resolved Manual KYC Update Error** : Improved error messaging, which ensures a more reliable manual verification process.
  * **Improved Duplicate Check Performance** : Addressed an issue causing duplicate check steps to time out in, leading to faster and more reliable duplicate detection.
  * **Corrected Multi-List Match Resolution** : Fixed a bug where multi-list match results were not correctly clearing after being manually resolved. Blocklist resolutions will now consistently reflect the correct status.
  * **Restored Missing AML Audit Log** : Fixed an issue where the audit log for “AML check was initiated” was not being generated. This restores crucial visibility for AML initiation steps.

  **Portal**

  * **Improved Address Search Validation** : The address search field now requires a minimum of three non-whitespace characters before initiating a search. This prevents premature or empty search results and improves the address selection experience.
  * **“Unchecked” Badge for ID Only Address Checks with No Results** : To improve clarity, an “Unchecked” badge will now be displayed when an “ID Only residential address” check returns no meaningful results, differentiating it from a “No Match” result.
  * **Resolved Address Field Entity Submission** : Fixed an issue where submitting an entity creation form too quickly after selecting an address could cause KYC checks to fail. The form now correctly waits for all address details to be fully populated before submission.
  * **Email and Phone Fields Now Visible on “Resolve Entity” Screen** : The “Resolve Entity” screen, which can appear when editing an entity created via Send Link before the flow is completed, will now correctly display the Email and Phone fields for editing.
  * **Removed Confusing Red Dots from Biometric Scores** : To avoid confusion, the red dots that weredisplayed next to biometric scores have been removed. This styling change ensures scores are not incorrectly interpreted as failures.
  * **SMS Message Preview** : Corrected an issue where the SMS message preview in the “Send Link” feature did not match the content of the SMS. The preview is now accurate.
  * **Provider Session IDs Now Available in Audit Logs** : To assist with support and debugging with external partners, provider-specific session IDs (e.g., Incode session ID) are now visible in the audit logs for connector events.
</Update>

<Update label="11 Jul 2025">
  What’s new in this release?

  ***OneSDK***

  * **Customizable Branding in HostedOneSDK** : This feature allows customers to customize and add their company logo. This enhancement enables seamless alignment with your company’s branding, providing a more personalized and cohesive user experience.
</Update>

<Update label="10 Jul 2025">
  What’s new in this release?

  **KYC**

  * **Issues are now generated for some KYC Failures** : Issues are not being generated properly for some KYC checks and this caused some incomplete information when looking at entity state in Portal.

  ***
</Update>

<Update label="09 July 2025">
  What’s new in this release?

  **OneSDK**

  * **Latest Version** : 1.8.9
  * **Customizable Branding in HostedOneSDK** : This feature allows customers to customize and add their company logo. This enhancement enables seamless alignment with your company's branding, providing a more personalized and cohesive user experience.
  * **Enhanced OCR Review Page Stability** : Users can now set the document type to “Driver License” and select “NZL” as the country without the country field disappearing.
  * **`[Hosted] Better handling ofocr_only flow in Hosted OneSDK`**:Improved the user experience by addressing issues that occur when starting the OCR-only flow with Incode, preventing users from being redirected to an error page.

  ***
</Update>

<Update label="10 Jul 2025">
  What’s new in this release?

  **KYC**

  * **Issues are now generated for some KYC Failures:** Issues are not being generated properly for some KYC checks and this caused some incomplete information when looking at entity state in Portal.

  ***
</Update>

<Update label="30 June 2025">
  What’s new in this release?

  **OneSDK**

  * **Latest Version** : 1.8.8
  * **FrankieOne Enhances Onboarding with New Consent Flow**. FrankieOne introduces a Welcome & Consent screen for new entities without prior consent across OCR-only, IDV, and IDV-review flows. This update ensures compliance and a seamless onboarding experience, reinforcing FrankieOne’s commitment to user-friendly and secure identity verification solutions.
  * **FrankieOne Introduces Enhanced Vendor Switching in OneSDK for Seamless Identity Verification** : We have updated our OneSDK platform, enabling seamless switching between identity verification vendors like Incode, Onfido, and Sumsub within the embedded environment. This enhancement offers businesses greater flexibility and efficiency with real-time results displayed in the portal. Ideal for fintech and regtech sectors, this update streamlines compliance and optimizes customer onboarding.
  * **Enhanced Error Logging for failure to load external script** : In the event of network issues preventing the loading of Incode scripts for OCR and Biometrics components, error messages will now be logged on Cloudwatch. This ensures prompt identification and resolution of script load errors, enhancing system reliability and user experience.
  * **Handle empty phone number country code** : Since V2 now requires phone number country code, handle empty value instead of returning an error

  ***
</Update>

<Update label="24 June 2025">
  What’s new in this release?

  **OneSDK**

  * **Latest Version** : 1.8.7
  * **SDK Memory Usage:** Reduce the OneSDK memory usage during code build
  * **Enhances Date Input Validation:** Defer the input validation when user has completed all the date components. If date is prefilled, validate the input promptly to alert users of any discrepancies.
  * **Better user experience when unable to fetch Onfido SDK:** We’ve improved the user experience by addressing the issue where a blank screen appeared when OneSDK was unable to load the Onfido SDK. This update ensures seamless continuity, providing users with a more intuitive interaction.
  * **IDVerse Engine 5 Support**

  We’re introducing support for split OCR + Biometrics workflows powered by IDVerse Engine 5.

  ✅ **Verified Scenarios** :

  * **Passport-based flows** successfully tested with documents from:
  * New Zealand 🇳🇿
  * Australia 🇦🇺
  * India 🇮🇳
  * Canada 🇨🇦
  * **Australian Driver’s License-based flows** validated as part of our UAT testing efforts.

  ⚠️ **Known Issues**

  * **Front/Back scan inconsistency** — failures common in NT, WA, TAS, QLD (likely due to fake IDs)
  * **OCR issues for DOB/Expiry** — affects ACT, NSW, SA, VIC; under investigation (likely due to fake IDs)
  * This enhancement improves flexibility and future-proofs biometric verification flows for evolving compliance needs and document formats.
</Update>

<Update label="04 June 2025">
  What’s new in this release?

  **OneSDK**

  * **Latest Version** : 1.8.6
  * **Sumsub as new additional IDV partner** : We’ve added Sumsub as an IDV partner, to provide additional options for customers especially for cryptocurrency companies. Contact your Customer Success team member if you are interested learn more.
  * **Eliminate separate calls for OCR and Biometrics** : We’ve improved how we process results from Onfido. Now, a single API call handles both OCR and Biometrics, eliminating the need for separate calls. This update simplifies the process and enhances reliability, ensuring you receive accurate results more efficiently.
  * **Telemetry improvements** : The OCR, Biometrics, and IDV modules now emit more granular events, giving you richer insights for monitoring and troubleshooting.

  ***
</Update>

<Update label="23 May 2025">
  What’s new in this release?

  **OneSDK**

  * **Latest version** : 1.8.5
  * **Update for error screen:** Show error screen and ask customer to try again later system temporarily unavailable
  * **Enhanced Tracking** : Hosted OneSDK (using iframe) will now send a notification to our event system when they receive a “window unload” message from the parent window. This helps us track when the application is being closed or navigated away from.
  * **Custom Retry Pages and Outage for DVS** : Introduced a feature to customize retry pages based on specific field errors during verification or front-end validation processes. This allows users to focus on correcting only the necessary fields rather than all fields. This covers Personal Information Errors and Document Errors. Display an error screen advising customers to try again later due to system unavailability (500 - timeout).
  * **Handle invalid document type event** : Emit appropriate event: `input_required` when we received invalid document type from backend.
</Update>

<Update label="19 May 2025">
  What’s new in this release?

  **Portal**

  * **Clearer OCR Failure Explanations and More Consistent Report Status Icons** : OCR reports now provide more direct explanations when document checks fail, aiding quicker understanding. Status icons in Document and Biometrics Check reports now consistently and accurately show check results.
  * **Corrected Analytics Tracking** : Ensured ‘Send Link’ and key IDV (Resolve document/biometrics) events are accurately tracked for better analytics.
  * **Proper Redirection Post-Check Resolution** : Users are now correctly redirected to the Workflow Events page after resolving Document or Biometrics checks.
  * **Refined Action Menu for Compliance Officers** : The ‘Add to Blocklist’ option is now correctly hidden from the action menu for Compliance Officer roles.

  **KYC**

  * \[NEW]**Visa (VEVO) Checks Now Available in V2 KYC Workflow** : You can now perform Visa (VEVO) Checks as part of the V2 KYC workflow to verify visa entitlements for non-Australian passports.

  This includes extracting and validating passport details via OCR, secure integration with the VEVO API, and comprehensive processing of VEVO response data (including visa class, subclass, status, expiry).

  Support added for allow/deny lists for visa class/subclass.

  Detailed audit events, workflow step results, and summaries for VEVO checks are now available, ensuring better tracking and portal interpretation. This also includes notes for visa denied class/subclasses. Contact your CSM for more details.

  **Important** : Ensure your workflow includes a Visa step. If you use **Standard Bundles** , this step is already included by default.

  * **Blocklist Checks Now Available in V2 KYC Workflow** : FrankieOne now supports Blocklist (Match List) functionality in V2 workflows, enabling you to automatically block individuals or businesses from being onboarded.
  * A default Blocklist is available out of the box—no setup required.
  * Entities can be matched based on name, email, date of birth, business name, ABN, and more.
  * Blocklist checks run automatically within the onboarding workflow.
  * Self-manage your list via API or through the FrankieOne portal.
  * When a match is found, the entity will be marked in your workflow execution results as `status = FAIL`, `issues= BLOCKLISTED`

  **Important** : Ensure your workflow includes a Blocklist step. If you are using **Standard Bundles** , this step is already included by default

  * **Default OCR Comparison Fuzziness Applied** : FrankieOne now applies default fuzziness (Levenshtein distance) to OCR field comparisons for customers using IDV checks. Previously, exact match was used unless fuzziness was explicitly configured. ***When It Applies*** OCR comparison is triggered:
  * When the applicant **manually enters data before OCR** , or
  * When the applicant **reviews and updates OCR-extracted information**

  ***New Default Matching Rules***

  | Field          | Default Distance | Outcome if Exceeded |
  | :------------- | :--------------- | :------------------ |
  | First Name     | 2                | SUSPECTED           |
  | Last Name      | 2                | SUSPECTED           |
  | DOB            | 1                | SUSPECTED           |
  | ID Number      | 2                | SUSPECTED           |
  | Max Mismatches | 2 total          | SUSPECTED           |

  Settings are configurable per customer. Contact your Customer Success Manager to adjust.

  **KYB**

  * **KYB Channel Data and Billing Codes Fix** : An issue affecting KYB channel data and billing codes has been resolved. This ensures accurate data capture and billing information for KYB workflows.

  **OneSDK**

  * **Latest version** : v1.8.4
  * **Window Unload Event Tracking** We’ve added tracking to identify when users leave the biometric verification process early. This helps distinguish between system issues and user-initiated page closure. This is applicable to embedded and non iframe hosted.

  ***
</Update>

<Update label="13 May 2025">
  What’s new in this release?

  ***OneSDK***

  * **Latest version** : v1.8.3
  * **Manual Flow DL Country Filtering:** Allow AUS only country to be filtered in manual driver’s licence screen

  ***
</Update>

<Update label="07 May 2025">
  What's new in this release?

  **Portal**

  * **Simplified onboarding link** : You can now start an onboarding flow with only a name and mobile number.
  * **Supplementary data – profile updates** : Audit logs capture previous and current values when a profile changes.
  * **Supplementary data – audit report error events** : A generic error template now displays error details inside audit reports.
  * **Supplementary data – AML step** : AML-related audit events now include contextual data for quicker investigation.
  * **Supplementary data – workflow status change** : `WORKFLOW_STATUS_CHANGE` events now record additional context.
  * **Custom view assignee filter** : Selecting an assignee in Custom Views now returns accurate results.
  * **Step summary accuracy** : The Step Summary shows only the steps configured for the workflow.
  * **Support for other addresses** : The profile tab now supports additional address types beyond residential and mailing.
  * **Double country code display** : Fixed an issue where the country code appeared twice in some views.
  * **Phone number country code in Send SMS** : The country code field in the Send SMS modal now populates correctly.

  ***
</Update>

<Update label="30 Apr 2025">
  What’s New in This Release?

  **OneSDK**

  * **Latest version** : v1.8.2
  * **Date-of-birth validation fix** : Eliminated the false “Enter a valid date of birth” error that appeared even when the format and value were correct.
  * **Hosted OneSDK runtime error screen** : Added a dedicated error screen that appears if a problem is encountered during Hosted OneSDK execution, giving users a clear recovery path.
  * **Device-permission logging** : Implemented an event handler that records Incode device-permission requests, helping developers diagnose camera and microphone access issues faster.
  * **New Zealand passport expiry validation fix** : Corrected a defect that incorrectly flagged valid NZ passport expiry dates.
</Update>

<Update label="16 Apr 2025">
  What’s new in this release?

  **Platform**

  **FrankieOne Portal URL Update** : We’re making it easier to access our platform by updating our portal URLs to a new domain: **`*.frankie.one`**.

  ***What’s Changing?***

  * Our portal URLs are moving to **`*.frankie.one`**. The new production URL will be: `https://portal.frankie.one`.
  * Old URLs will remain accessible during the transition.

  ***Timeline***

  * **Q1 2025** – Both old and new URLs will work.
  * **Q2 2025** – Old URLs will start redirecting to the new ones.

  ***What You Need to Know***

  * **No impact on portal access** : Both URLs (old and new Portal URLs) will function during the transition.
  * No action needed for most users.
  * **SSO users** : You may need to update configurations once redirection starts.

  **Portal**

  * **“Saving Changes” Spinner** : Fixed a persistent “Saving changes” loading spinner that occurred when selecting a new entity. This improvement enhances workflow efficiency and user satisfaction by reducing unnecessary waiting time.

  ***
</Update>

<Update label="10 Apr 2025">
  What’s New in This Release?

  **OneSDK**

  * **Latest version** : v1.8.1
  * **Handling Consent** : Fixed an issue where consent from manual forms was not passed correctly in a specific customer scenario.
  * **Hosted OneSDK Success Event Format** : Corrected the format of the Hosted OneSDK `idv:success` event.
  * **Phone Number Validation** : Addressed a problem where phone number validation failed despite the correct format.
  * **General Improvement** : Enhanced security by updating the system to prevent request headers from being logged.

  ***
</Update>

<Update label="09 Apr 2025">
  What’s New in This Release?

  **KYC**

  * **Webhooks for IDV Biometrics v2** : We’ve introduced several new webhooks for the IDV Biometrics flow to streamline your verification processes:
  * **`TOKEN_REQUESTED`** : Triggered when an IDV session begins.
  * **`TOKEN_ERROR`** : Indicates a failure in creating or starting a session.
  * **`RESULTS_RETRIEVED`** : Notifies that verification results have been successfully received.
  * **`RESULTS_ERROR`** : Signals an error in retrieving results.
  * **`EXPIRED`** : The session expired before it could be completed.
  * **`CANCELLED`** : The session was manually cancelled.
  * **`OCR_PROCESSED`** : Confirms successful OCR data extraction.
  * **`OCR_ERROR`** : Denotes an OCR failure, often due to poor image quality.
  * **`ONB_URL_ERROR`** : Indicates a failure to generate the onboarding URL.

  **Portal**

  * **KYC Step Supplementary Data in Audit Logs** : The audit logs now include supplementary data for KYC steps, providing richer context for audit events.
  * **Supplementary Data in Audit Logs** : Audit logs for entity creation and updates now include supplementary data, capturing details of added and modified fields.
  * **Audit Report Enhancements** : The Audit report now displays the Execution ID for improved tracking and debugging of workflows.
  * **Entity Error and Permission Handling** : Improved handling of entity errors and permissions.
  * **Date Validation** : Enhanced date validation to ensure data integrity across the platform. Resolved an issue where users were unable to edit the residential state address in the Portal.

  ***
</Update>

<Update label="07 Apr 2025">
  What’s New in This Release?

  **OneSDK**

  * **Latest version** : v1.8.0
  * **Expanded Onfido Support** : We’ve added support for Onfido version 14 in OneSDK. To take advantage of the latest improvements, please contact our customer support team to update your configuration.
</Update>

<Update label="24 Mar 2025">
  What's new in this release?

  **Portal**

  * **Inconsistent Document Order** : Addressed an inconsistency in the order of documents displayed for Passports and Medicare cards.
  * **AML Alert Display Issues** : Resolved several issues with the display of AML alerts, including inconsistent country display and missing separators.
  * **IDV OCR Check Results** : Improved the accuracy of IDV OCR check results to ensure consistency between different views of the data.
  * **Tooltip Modal in KYB Documents Tab** : Addressed an issue with a tooltip modal in the KYB documents tab.
  * **Chinese Documents Improvements** : Improved the handling of Chinese characters in various fields related to document processing.
  * **Audit Log for AML Status Change** : Clarified the audit log entries for AML status changes to reduce confusion
  * **Missing Country Flags in IKYB** : Added missing country flags for various countries in the IKYB section.
  * **Document Attachment Handling** : Improved the handling of document attachments to prevent crashes when attachment data is null.

  ***
</Update>

<Update label="11 Mar 2025">
  What’s New in This Release?

  **KYC**

  **DVS Retry Mechanism Implemented** : We’ve introduced a configurable retry mechanism for our DVS connector to handle non-2xx responses, S codes, and timeouts. This improvement helps reduce failures due to transient issues, improving the reliability of identity verification checks. Currently, this has been tested and is available upon request for our V2 customers.

  **Portal**

  * **Implemented New Permissions** : The “Modify risk level” permission has been added to control access to manually overriding entity risk levels, and it is enabled by default for Admins and Operators.
  * **Risk Override Function** : Risk scores have been introduced for the risk override function to allow more granular risk management.
  * **Phone Number Support** : Phone number support has been expanded to additional regions to improve global reach in F2.
  * **Error Messaging** : Proper error messaging has been added for invalid phone numbers to enhance user understanding and reduce confusion.
  * **Form Validation** : Validation has been implemented for incorrect years in the Date of Expiry field to ensure accurate data entry.
  * **Profile Risk Button** : The Profile Risk button now redirects users efficiently to the last workflow with a comprehensive risk assessment.
  * **Bug Fixes** : Duplicate entries when creating new entities have been resolved to ensure data integrity. Phone number validation for AU, NZ, and US has been enhanced, and the US phone number placeholder has been updated to improve user experience. Audit logs incorrectly showing “Anonymous” entries have been fixed to improve audit trail accuracy.

  ***
</Update>

<Update label="24 Feb 2025">
  What’s New in This Release?

  **KYC**

  **Webhook notifications:** Webhooks will now be sent when a workflow is completed.

  **Portal**

  * Enhanced support for new report identifiers for registry documents, ensuring seamless transition and backward compatibility with backend changes.
  * Fixed an issue with the step summary for document checks, ensuring correct pass/fail status is displayed
  * Corrected an issue related to the liveness checks.
  * Fixed issues related to the ‘Assigned to me’ link duplication and the ‘x’ icon behavior in the Search user field.
  * Corrected an issue where special characters (’ and &) were incorrectly encoded in the Audit Log.
  * Resolved a bug preventing entity information from displaying in the portal before execution in V2.

  ***
</Update>

<Update label="10 Feb 2025">
  What’s New in This Release?

  **Portal**

  * **Improved Comment Display** : Only comments relevant to the selected workflow are shown. Comments are now collapsible.
  * **Enhanced Navigation** : Smoother animation for expanding and collapsing navigation in the Workflows and Profile sections.
  * **Send Link Functionality** : The Send Link button’s visibility is now correctly managed based on IDV verification status and configuration settings. A liveness detection checkbox has been added for specific providers.
  * **Entity Assignment Filtering** : Users can now filter entities based on assignment status to manage unassigned resources more efficiently.
  * **AML Match Country Filters** : Added an “All” option to provide comprehensive search capabilities.
  * **Workflow Comments** : Users can now add comments when re-running workflows, improving transparency and traceability.
  * **KYC Database Check Improvements** : Enhanced data mapping ensures only relevant results are displayed.
  * Resolved a critical bug causing unexpected application errors in the Entity Detail View.

  ***
</Update>

<Update label="13 Jan 2025">
  What’s New in This Release?

  **KYC**

  * Updated endpoints /v2/individuals/entityId/actions/idv/token, /v2/individuals/entityId/actions/idv/ocr and /v2/individuals/entityId/actions/idv/process for IDV actions.
  * Endpoints have been added for maintaining IDV and match list results
  * Endpoints have been added for managing subscriptions per entity

  ***
</Update>

<Update label="19 Aug 2024">
  What’s New in This Release?

  **KYC**

  * Create document, update document and update service profile endpoints now have a separate field for comment, which changes the body of the request.
  * Process result objects now have an object for confidence and fuzziness levels.
  * Endpoints for Hosted Url and IDV have been introduced, these aren’t available at the moment for use in UAT.
  * Audit events now have more detail in the supplementary data for result summaries.
</Update>


# Version History
Source: https://docs.frankieone.com/docs/v1/onesdk/oneSDK/sdk-version-log



## v1.9.40

**07 Sep 2026**

* **Dynamic Review Screen Forms:**  Underlying updates to prepare support for Kenya, Ghana, South Africa, Singapore and Malaysia country fields in the review screen and future OneSDK versions.
* **Review screen:** Improved review screen by handling multi-doc and non-multi-doc flows correctly. This provides more focused information during the review process.

## v1.9.39

**31 Aug 2026**

* **Dynamic Review Screen Forms:**  Underlying updates to prepare support for UK, HK, Philippines, Taiwan and Thailand  country fields in the review screen and future OneSDK versions.
* **Daon Face Capture Instruction Screen:** Resolved an issue where an unnecessary face capture instruction screen was displayed during the biometric verification flow for certain customers, ensuring a smoother user experience.

## v1.9.38

**19 Aug 2026**

* **Biometrics Camera Access Warnings:**  OneSDK now emits detailed warning events when a user encounters camera permission issues during biometrics capture, providing better visibility into user journey blockers. These warnings are integrated into existing event channels for easier tracking without requiring new subscriptions.
* **Onfido Mobile Biometrics Loading State:**  Resolved an issue where a loading state obscured the biometrics widget during the transition from OCR to biometrics on mobile devices, ensuring a smoother user experience during identity verification.
* **Biometrics Module:**  Resolved an issue where the exit button was not displayed in the biometrics module, preventing users from easily exiting the flow. Users can now close the biometrics screen as intended.

## v1.9.37

**13 Aug 2026**

* **Manual KYC Field Rendering:**  Fixed a regression where customized fields in the manual KYC flow were not rendering correctly, ensuring all fields now display as expected.
* **User Interface in Review Screen:**  The maternal last name field on the OCR review screen is now optional for users in Mexico, Spain, and Colombia, allowing for greater flexibility in data entry.
* **Country of Residence Update:** Resolved an issue where the country of residence was incorrectly updated during identity verification, ensuring that the initial country selection is preserved and preventing applications from being approved under restricted or incorrect regions.
* **Dynamic Review Screen Forms:**  Underlying updates to prepare support for Mexico, Colombia, Canada, India and Spain country fields in the review screen and future OneSDK versions.

## v1.9.36

**10 Aug 2026**

* **Incode Consent API:**  We've enhanced the API to allow passing user consent directly to Incode, supporting both mandatory and optional consent types for biometric data use and system enhancement. This streamlines the consent process for custom consent screens.
* **Expiry Date in eKYC flow:** We’ve enhanced the manual eKYC ID entry flow by adding an optional “Date of Expiry” field when customers select Passport, aligning the experience with the existing Driver’s Licence flow.
* **Onfido OCR Module Event Ordering:** Resolved a race condition in some Onfido OCR flows that could end the session before OCR results were received. We now deliver OCR results before closing the session, improving speed and consistency of results availability.
* **OneSDK Credit-check messaging improvement:** We fixed an issue where the OneSDK could display a credit-check related notice even when no credit check was actually performed (e.g., ID-only verification flows). With this update, credit-check messaging is now shown only when a credit check is genuinely applicable based on the check results.
* **Form Validation:**  Improved form validation on the 'Are your details correct?' page. When submitting the form with missing or invalid information, specific error messages and visual cues will now appear next to the affected fields, making it easier to identify and correct errors.

## v1.9.35

**30 July 2026**

* **Form field Validation:**  The  review screen now correctly handles spaces in address fields, preventing validation errors for valid addresses and automatically trimming leading or trailing spaces upon submission. This ensures a smoother user experience when entering address details.
* **Maintenance & dependency housekeeping:** removes an unused internal dependency as part of routine maintenance. There is no change to SDK functionality, behaviour, or public API — no action is required to upgrade. This update also streamlines the SDK's  dependency footprint, which may reduce noise in downstream dependency scans.

## v1.9.34

**22 July 2026**

* **International Address Support:** The OCR review screen now supports selecting Italian provinces for residential addresses and document regions, improving international address data capture. This enhancement also lays the groundwork for adding subdivision support for other countries in the future OneSDK versions.

## v1.9.33

**07 July 2026**

* **RDaon Address Field Handling:** Address fields returned from OCR or stored in the backend will now automatically trim leading/trailing whitespace, preventing validation errors and ensuring clean data display and submission.
* **RTruuth User Experience:** When a user chooses to return later, the system now directly redirects them, skipping an unnecessary intermediate page for a smoother experience in Truuth integration.

## v1.9.32

**02 July 2026**

* **Review Screen Submissions:**  Disabled address and document fields on review and personal details screens are now preserved upon submission, preventing accidental data loss.
* **Hosted Review Screen:** Resolved an issue where submitting the hosted review screen incorrectly cleared name fields and where the IDV completion webhook fired prematurely. Name fields will now persist correctly, and the webhook will fire only after the review screen is submitted, ensuring reliable signal for review completion.
* **Language Control:**  Added capability to programmatically set the language for Onfido and Incode within OneSDK, providing insights into the level of control available for displayed languages.
* **Credit Bureau Header Notifications:**  OneSDK now displays a notification when a credit bureau header data source fails to find a match during a KYC check, ensuring compliance with regulatory requirements and informing users of the mismatch.

## v1.9.30

**04 June 2026**

* **Biometric Page Extraction:** Resolved an issue where users could get stuck on the page extraction screen after completing biometrics, ensuring a smoother transition to the next step.
* **Daon Error Handling:** Error codes and messages from the Daon Process Definition (PD) flow are now displayed in the portal, allowing for quicker diagnosis and resolution of issues.

## v1.9.29

**28 May 2026**

* **Improved User Guidance:**  We have updated the helper text for Australian driver's license card numbers during manual verification to accurately guide users on where to find the card number for each state, especially for Victorian licenses where it is now correctly stated to be on the back of the card.
* **Document Upload:** OneSDK can now handle multiple document upload of the same type, improving flexibility and efficiency when submitting required information.

## v1.9.28

**25 May 2026**

* **Daon Session Timeout Handling:** We’ve introduced a new screen for Daon biometric sessions that have timed out due to inactivity, providing a clear visual indication to users and allowing for better handling of these scenarios by developers.
* **OCR Review Screen Improvements:** The OCR review screen has been updated to improve clarity and consistency, including corrected spelling, adjusted field labels, and reordered document information for a more intuitive user experience.
* **Result Screen Customization:** OneSDK now allows developers to customize the result screen with their own images, either by providing a base64 encoded image or a URL to an image, enhancing the visual experience.
* **Address Field Improvements:** We’ve enhanced the review screen to correctly display full address details, including unit numbers and proper separation of suburb and town. Additionally, address pre-fill now supports state acronyms, and the name field accepts hyphens, preventing previous submission errors.

## v1.9.27

**18 May 2026**

* **Result Screen Descriptions:**  The result screen description field now supports rendering HTML elements, allowing for richer text formatting like bold and italics to improve clarity and user experience.
* **Document Identification UI:**  Enable configuration of field labels for document identification to clearly indicate the source of information (e.g., "From your driver's licence" or "From your passport") and to display the expiry date for passports, improving clarity and compliance.
* **Biometric Review Screen:**  OneSDk review screen now accepts and displays hyphenated names properly allowing users with such names from completing the submission process.
* **OneSDK Forms:**  Resolved an issue where overriding form field configurations with partial objects caused dropdowns to display "No records"; dropdown options will now correctly fall back to default values if not explicitly provided in the override.

## v1.9.26

**12 May 2026**

* **Multi-Document Review Screen:** The review screen now supports displaying information from multiple documents, such as a Driver's License and Passport, in a single view, providing a more comprehensive and dynamic review experience.

## v1.9.25

**6 May 2026**

* **Library Update::** We have addressed dependency issue with the lodash library in the OneSDK package.

## v1.9.24

**29 April 2026**

* **Daon IDV Processing:** The Daon identity verification process now emits a 'loading' event, providing clearer status updates for embedded customers during check processing.

## v1.9.23

**22 April 2026**

* **Daon Error and Events:** We have significantly improved how we communicate IDV results. By introducing more granular error codes and descriptive messages, we are providing clearer insights into why a verification attempt might have failed, allowing for faster resolution and a smoother customer experience.

## v1.9.22

**16 April 2026**

* **Onboarding Journey Logging:**  We've enhanced event logging for the onboarding journey, providing customers with detailed visibility into end-user progress and drop-off points within the onboarding flow.
* **eKYC Hosted OneSDK Flow:**  Resolved an issue where changes made on the eKYC hosted OneSDK flow review page were not being saved, ensuring all user inputs are now correctly reflected.

## v1.9.21

**9 April 2026**

* **Hosted OneSDK Review Screen:**  The Hosted OneSDK Review screen now includes an 'Other names known by' field, allowing for the capture of additional name details such as middle names.
* **Onfido Document Visibility:** Resolved an issue where documents submitted during VOI were not appearing in Frankie for certain profiles, ensuring all uploaded documents are now correctly displayed.

## v1.9.20

**1 April 2026**

* **Build Fix:**  Resolved an issue where the SDK prevented Next.js 15+ applications from building when Turbopack was enabled, ensuring smoother development for users leveraging modern build tools.

## v1.9.19

**18 March 2026**

* **Incode Translation Feature:** You can now customize translations for the Incode biometrics and identity verification provider, allowing you to tailor the user experience to your preferred language. This enhancement gives you greater control over how verification prompts and messages appear to your end users.
* **Review Screen Layout:**  The ‘Address search' option on the review screen can now be configured to change its position through this setting addressSearchPosition. This provides flexibility to adjust to the UI to customers' preference.
* **Incode SDK Integration:**  We've enhanced the Incode SDK integration to allow passing additional options to the renderCamera method, providing more flexibility for OCR and biometrics flows.
* **Flexible Identity Verification Flows:** You can now customize your Incode verification by choosing between standalone document scanning or document scanning with biometrics, providing more control over your identity verification process

## v1.9.18

**10 March 2026**

* **OneSDK Form Validation:**  Improved data validation and form-saving reliability within the OneSDK for a more seamless user experience.
* **Onfido Integration:**  A new `hideCountrySelection` option is now available for Onfido integrations, allowing the country selection step to be hidden during identity verification and optical character recognition processes when not required.
* **Individual Module Document:** Improved submission reliability by ensuring document modifications are processed correctly regardless of the underlying object instance.

## v1.9.17

**2 March 2026**

* **Session Error Handling:**  Fixed an issue where session error events for iframe integrations had an empty payload, ensuring consistent error data for developers.
* **Onfido Event Standardisation:** We have standardised event emissions across all Onfido modules, ensuring consistent and reliable event tracking for user interactions, including successful completions and user-initiated exits.

## v1.9.16

**16 February 2026**

* **Daon Event Handling:**  The system now correctly processes events from Daon for IDV, OCR, and Biometrics modules, ensuring proper workflow completion, error handling, and event emission for both scenarios with and without a redirect URL.
* **React Version Support:**  The OneSDK now officially supports React 19, and React has been updated to a peer dependency. This change improves compatibility and simplifies dependency management for applications integrating with the SDK.

## v1.9.15

**5 February 2026**

* **Daon Brand-specific styling:**  The OneSDK now supports passing brand information to Daon, enabling brand-specific styling for Customer’s different brands within Daon-hosted web pages for a more consistent user experience.
* **Daon Document Selection:**  The SDK can now bypass the document selection screen, allowing clients to pre-select a document type and streamline the capture process for users.
* **OneSDK Event Handling and Teardown:** Addressed issues with OneSDK event relay for Onfido, improved teardown functionality to ensure proper cleanup, and enhanced handling of expired tokens for a more robust integration.

## v1.9.14

**26 January 2026**

* **Incode Language Parameter:**  The Incode integration now supports a language parameter, allowing the Incode page to load in Spanish by default for an improved user experience.
* **Daon Selfie Flow:**  Resolved an issue where the selfie capture flow would crash and get stuck in an infinite loop due to incorrect iframe message handling, preventing users from completing the selfie verification process.
* **Document Processing:**  Resolved an issue where processing large base64 encoded documents could cause a system error, improving the stability of document handling.

## v1.9.13

**12 January 2026**

* **Status Polling Configuration:** Apply polling configuration for Daon standard flow.
* **Document Upload:** Improved OneSDK flow to correctly display document types during the KYC document upload flow, ensuring a consistent user experience regardless of how the flow is initiated.
* **Onfido Integration Improvements:**   Enhanced the Onfido IDV module within OneSDK to better respect recipe configurations for the useOneStep flow. It introduces the ability to configure an exit button and refines how document types and biometric options are passed to the Onfido SDK, addressing a client's need for flexible IDV processes.
* **Camera Management for Incode:**  We've added a manual teardown function to ensure the camera properly turns off when a user leaves a page, preventing the camera from remaining active unexpectedly.

## v1.9.12

**16 Dec 2025**

* **Critical Error Fix:**  Added telemetry to detect critical error that occasionally prevented OneSDK from loading individual details, ensuring a more stable and reliable experience.

## v1.9.11

**11 Dec 2025**

* **Process Initialization for Daon Provider:**  Enhanced the status polling mechanism for process initialization to improve reliability and provide a smoother user experience during critical operations.

## v1.9.10

**04 Dec 2025**

* **Data Mapping:** Resolved an issue where Daon data was not correctly mapping to the V2 Portal, ensuring all entity details and images are now displayed accurately and consistently.
* **IDV Service Stability:** A critical bug causing the IDV service to crash when attempting to find a selfie ID for entities without an ID document has been resolved, improving system stability and reliability.
* **Driver's License Expiry Date:**  The eKYC form now includes an 'Expiry Date' field for Driver's Licenses, allowing customers to capture this information during onboarding and improving data completeness for connectors.
* **IDV Review:**  Fixed an issue where the IDV Review was not displaying document fields correctly when identity documents contained a self-image without an OCR run date, ensuring all relevant document information is now visible.
* **Biometric Review Page:**  The biometric review page now correctly accepts apostrophes in name fields, resolving an issue that previously caused Know Your Customer (KYC) checks to fail for users with apostrophes in their legal names.
* **Performance Improvement for Truuth IDV vendor:** We've significantly improved the loading speed of identity verification screens, reducing load times to under 5 seconds for a smoother user experience.
* **Date of Birth Input:**  The Date of Birth field in OneSDK screens now accurately validates month entries, displaying error messages only after all DOB fields are completed.

## v1.9.9

**01 Dec 2025**

* **IDV Processing for Daon:** OneSDK now includes a new feature to poll the status of identity verification (IDV) requests when the initial process indicates 'CHECK\_PROCESSING'. This enhancement ensures that users are informed about the ongoing processing of their IDV requests, preventing indefinite waiting times.

## v1.9.8

**26 Nov 2025**

* **Biometric SMS Links:**  Fixed an issue where biometric SMS links failed to send to New Zealand phone numbers with non-standard digit lengths (9 or 11 digits), ensuring all valid NZ phone numbers can now successfully receive these links.
* **OnFido Configuration:**  OneSDK now supports configuring Onfido to enforce mobile-only ID verification, allowing users to seamlessly complete the process on their mobile devices via QR code or link.
* **User Interface Consistency for Incode:** Resolved an issue where font sizing on message displays was inconsistent, ensuring a uniform and polished appearance for users.

## v1.9.7

**12 November 2025**

* **Additional Document Collection:**  The OneSDK now supports a standardized flow for collecting additional identification documents (Passport and Driver's License) via Daon, ensuring consistent processing and improved user experience.

## v1.9.6

**30 October 2025**

* **IDVerse Image Assets**: Resolved an issue where SVG image assets were failing to load correctly, particularly impacting the selfie modal. This fix ensures all images display as intended.
* **IDVerse SDK Asset Loading**: Fixed an issue where the SDK was incorrectly attempting to load image assets from the local file system, which caused icons to be missing in dialogs for some users. This update ensures all icons display correctly

## v1.9.13

**23 Jan 2026**

* **Status Polling Configuration:** Apply polling configuration for Daon standard flow.
* **Document Upload:** Improved OneSDK flow to correctly display document types during the KYC document upload flow, ensuring a consistent user experience regardless of how the flow is initiated.
* **Onfido Integration Improvements:**   Enhanced the Onfido IDV module within OneSDK to better respect recipe configurations for the useOneStep flow. It introduces the ability to configure an exit button and refines how document types and biometric options are passed to the Onfido SDK, addressing a client's need for flexible IDV processes.
* **Camera Management for Incode:**  We've added a manual teardown function to ensure the camera properly turns off when a user leaves a page, preventing the camera from remaining active unexpectedly.

***

## v1.9.12

**16 Dec 2025**

* **Critical Error Fix:**  Added telemetry to detect critical error that occasionally prevented OneSDK from loading individual details, ensuring a more stable and reliable experience.

***

## v1.9.11

**11 Dec 2025**

* **Process Initialization for Daon Provider:**  Enhanced the status polling mechanism for process initialization to improve reliability and provide a smoother user experience during critical operations.

***

## v1.9.10

**04 Dec 2025**

* **Data Mapping:** Resolved an issue where Daon data was not correctly mapping to the V2 Portal, ensuring all entity details and images are now displayed accurately and consistently.
* **IDV Service Stability:** A critical bug causing the IDV service to crash when attempting to find a selfie ID for entities without an ID document has been resolved, improving system stability and reliability.
* **Driver's License Expiry Date:**  The eKYC form now includes an 'Expiry Date' field for Driver's Licenses, allowing customers to capture this information during onboarding and improving data completeness for connectors.
* **IDV Review:**  Fixed an issue where the IDV Review was not displaying document fields correctly when identity documents contained a self-image without an OCR run date, ensuring all relevant document information is now visible.
* **Biometric Review Page:**  The biometric review page now correctly accepts apostrophes in name fields, resolving an issue that previously caused Know Your Customer (KYC) checks to fail for users with apostrophes in their legal names.
* **Performance Improvement for Truuth IDV vendor:** We've significantly improved the loading speed of identity verification screens, reducing load times to under 5 seconds for a smoother user experience.
* **\[v1.9.10] Date of Birth Input:**  The Date of Birth field in OneSDK screens now accurately validates month entries, displaying error messages only after all DOB fields are completed.

***

## v1.9.9

**01 Dec 2025**

* **IDV Processing for Daon:** OneSDK now includes a new feature to poll the status of identity verification (IDV) requests when the initial process indicates 'CHECK\_PROCESSING'. This enhancement ensures that users are informed about the ongoing processing of their IDV requests, preventing indefinite waiting times.

\---=

## v1.9.8

**26 Nov 2025**

* **Biometric SMS Links:**  Fixed an issue where biometric SMS links failed to send to New Zealand phone numbers with non-standard digit lengths (9 or 11 digits), ensuring all valid NZ phone numbers can now successfully receive these links.
* OnFido Configuration:\*\*  OneSDK now supports configuring Onfido to enforce mobile-only ID verification, allowing users to seamlessly complete the process on their mobile devices via QR code or link.
* User Interface Consistency for Incode:\*\* Resolved an issue where font sizing on message displays was inconsistent, ensuring a uniform and polished appearance for users.

***

## v1.9.7

**12 November 2025**

**Additional Document Collection:**  The OneSDK now supports a standardized flow for collecting additional identification documents (Passport and Driver's License) via Daon, ensuring consistent processing and improved user experience.

***

## v1.9.6

**30 October 2025**

* **IDVerse Image Assets**: Resolved an issue where SVG image assets were failing to load correctly, particularly impacting the selfie modal. This fix ensures all images display as intended.
* **IDVerse SDK Asset Loading**: Fixed an issue where the SDK was incorrectly attempting to load image assets from the local file system, which caused icons to be missing in dialogs for some users. This update ensures all icons display correctly

***

## v1.9.5

**17 October 2025**

* **Performance Monitoring:**  We've added an event to detect when memory limits are reached due to multiple browser tabs, helping us improve system stability and performance.
* **Driver's Licence Expiry Date:**  The Driver's Licence form in OneSDK now supports the expiry date as an optional field by default, ensuring compliance with FrankieOne's updated identity checks and preventing failed verifications.
* **IDVerse Event Handling:**  The `supportConfirm` event has been renamed to `validDocumentConfirmed` in the SDK to provide clearer insight into document validation outcomes, allowing for more precise handling of user responses to ID document validity.
* **OCR Endpoint:**  The OCR endpoint now supports an optional token for enhanced session management and authentication when attaching OCR documents.

***

## v1.9.4

**1 October 2025**

* **Address Form**: Improve behavior of address state field reset when changing the country in the review form, ensuring accurate address data entry
* **Review Screen Pre-population**: Fixed an issue where the phone number was not prepopulated on the 1SDK review screen, ensuring a smoother user experience when completing IDV flows.

***

## v1.9.3

**15 September 2025**

* **Incode SDK Integration**: Capability to configure Incode SDK to expose a option within the settings, allowing for a tutorial screen to be displayed before document scanning on both desktop and mobile devices.
* **Address Input**: When a quota error occurs during address input via Google API, users can now manually enter their address details, ensuring a smoother onboarding experience.

***

## v1.9.2

**15 September 2025**

* **IDV Workflow**:  Improve behavior of confirmation checkbox in the IDV workflow, ensuring users must now check the box to proceed and complete the process.
* **OCR-only Flow Process**: Integrates support for Incode’s combined consent and document selector features, providing enhanced flexibility and control over the user onboarding flow within OCR-only processes.

***

## v1.9.1

**12 September 2025**

* **Support IDV Flow with Truuth**: We are now supporting Truuth, a new IDV vendor to perform IDV flow with OCR extraction and Biometrics. This update ensures seamless onboarding experience using the Truuth’s interface.
* **Onfido biometric variants in OneSDK**: OneSDK now supports exposing different Onfido ‘requestedVariant’ configurations, allowing for more flexible integration with Onfido’s biometric verification options (video, motion, and standard).

***

## v1.9.0

**09 September 2025**

* **Start Screen Image Display:**  The start screen now correctly maintains the aspect ratio of images, ensuring they display as intended without distortion.
* **Document Upload:**  We have added a latest feature enhancement to Hosted OneSDK. Users can now seamlessly generate secure, standalone links that allow their customers to upload their ID documents safely. This solution drastically minimizes the risks associated with insecure email submissions, ensuring both new and existing entities enjoy a safer, more efficient process. [Learn more here](https://docs.frankieone.com/docs/using-hosted-onesdk#document-collection)

***

## v1.8.16

**02 September 2025**

* **Form Review**: The form review screen now improved submission email and phone number fields, ensuring all user-provided contact information is captured.
* **IDVerse Integration**: OneSDK has been updated to use a new IDVerse build, improving the reliability and accuracy of identity verification processes for passports and driver's licenses.
* **Embedded IDV Flow Styling and Performance**: We've enhanced the Embedded IDV flow to allow for custom styling, providing greater flexibility in user interface design. Additionally, improvements have been made to optimize data handling, preventing app crashes during repeated use of the IDV flow.

***

## v1.8.15

**28 August 2025**

* **Improved Performance on Handling Multiple Attachments**: Resolved an issue where the OneSDK would crash or slow down significantly when handling multiple attachments, particularly during biometric flows. This fix prevents crashes and improves performance by optimizing how image data is handled, ensuring a smoother user experience during retries.
* **Daon Initialisation Improvement**: We have resolved an issue where the Daon IDV process was not correctly initializing, ensuring smoother identity verification workflows.

***

## v1.8.14

**21 August 2025**

* **IDVerse Error Handling:**  Improved error handling for IDVerse scans by introducing a new error type, `IDVerseScanFailedAndDestroyed`, which is triggered after multiple failed OCR or biometric attempts. This provides clearer feedback when an IDVerse scan cannot be completed.
* **IDVerse Biometric Workflow:**  The system now prevents users from starting biometric verification for a new transaction if OCR has not been completed, ensuring a more streamlined and correct workflow.
* **Additional Error Tracking:**  The SDK now captures and externalizes `out of bounds memory` errors from the Incode OCR component, improving error handling and stability.

***

## v1.8.13

**20 August 2025**

* **Enhance User Experience with Start Screen.** The new start screen now dynamically renders the logo and call-to-action (CTA) based on provided configurations, ensuring a tailored user experience. It emits specific events upon loading, CTA interaction, and error occurrences, enhancing responsiveness and feedback mechanisms. [Read more…](https://docs.frankieone.com/docs/implementation-guide/module/ekyc/start)
* **Enhanced Network Failure Handling in OneSDK.** In this update, OneSDK improves the IDV review flow by gracefully handling network failures during the KYC process. Users are now given the opportunity to retry submissions up to three times, with clear error messages guiding them through network issues, ensuring a smoother and more transparent user experience.

***

## v1.8.12

**05 August 2025**

* **Support OCR-only flow with Daon**: We are now supporting Daon, a new IDV vendor to perform OCR-only extraction on document uploads.
* **Support Biometrics and OCR Split flow with Daon**: We are now supporting Daon, a new IDV vendor to perform split flow for OCR extraction and Biometrics. This update ensures seamless handling of verifications across diverse document types and countries, providing a secure onboarding experience.
* **Support IDV Flow with Daon**: Implement Headed IDV flow with OCR extraction and Biometrics. This update ensures seamless onboarding experience using the Daon’s interface.
* **Phone Number Field Enhancement**: This update improves the handling of phone numbers in fields with available code options, ensuring correct separation of area codes and numbers. It addresses various formats, including those with and without the '+' sign and '-' separators, enhancing data submission accuracy.

***

## v1.8.11

**21 July 2025**

***IDVerse Updates***

* **Improved Handling of Multiple Document Attempts**: This update addresses issues related to multiple document submission attempts, enhancing the overall user experience and stability.
* **Enabled Skip Face Scan Intro Option**: You now have the option to skip the introductory screen for face scans.
* **Exposed `scanFail` Error Events**: We have exposed `scanFail` error events, providing more detailed feedback and enabling better error handling within your applications.

<Note>
  - **IDVerse Integration**: This release utilises the IDVerse release version from July 9, 2025.
  - `skipFaceScanIntro` **Flag**: The `skipFaceScanIntro` flag is set to `FALSE` by default. To enable this feature and set it to TRUE, you can include the `skipFaceScanIntro` flag within the `biometrics` component configuration, either on the `OneSdk` instance or directly on the biometrics component.

  ```js Example Usage theme={null}
  // On OneSDK Instance
  const oneSdk = await OneSdk({
      session: sessionObjectFromBackend,
      mode: "production",
      recipe: {
          ocr: {
              provideReviewScreen: false,
              provider: {
                  name: "idverse",
              }
          },
          biometrics: {
              provider: {
                  name: "idverse",
                  skipFaceScanIntro: true, // Set to true to skip the intro
              }
          }
      }
  });

  // OR on biometrics component
  const biometrics = oneSdk.component('biometrics', {
      provider: {
          name: 'idverse',
          skipFaceScanIntro: true, // Set to true to skip the intro
      }
  }); 
  ```
</Note>

<Warning>
  * **Biometrics Screen Stuck on Phone (with** `skipFaceScanIntro` **enabled)**: When `skipFaceScanIntro` is enabled and the user's journey begins on a mobile phone, we have identified an issue where the user may get stuck on the biometrics screen and cannot proceed. This issue is **not observed** when the journey starts from a desktop device. We are actively investigating this and will provide a fix in a future release.
</Warning>

***Hosted OneSDK***

* **Enhanced Success Screen:** Use the customisable success screen so that customers can make configuration changes to it such as title and description.

***

## v1.8.10

**15 July 2025**

The following changes are included in this release:

* **Enhanced Result Screen Flow**: In the hosted OneSDK versions v1 and v2, for both IDV review and KYC fraud processes, the success screen now consistently displays a success message with only one full stop for better user experience.
* **Safari Cookie Blocking Causes LocalStorage SecurityError**: In Safari on macOS, enabling "Block all cookies" in Preferences -> Privacy results in a SecurityError when websites attempt to use localStorage. Consider using SessionStorage as a fallback or advise users not to block all cookies.
* **Customizable Checkbox Colors in OneSDK/HostedOneSDK V2**: FrankieOne now offers enhanced customization in its OneSDK/HostedOneSDK V2, allowing businesses to tailor checkbox colors to match their brand themes.

***

## v1.8.9

**09 July 2025**

The following changes are included in this release:

* **Customizable Branding in HostedOneSDK**: This feature allows customers to customize and add their company logo. This enhancement enables seamless alignment with your company’s branding, providing a more personalized and cohesive user experience.
* **Enhanced OCR Review Page Stability**: Users can now set the document type to "Driver License" and select "NZL" as the country without the country field disappearing.
* **\[Hosted] Better handling of ocr\_only flow in Hosted OneSDK**:  Improved the user experience by addressing issues that occur when starting the OCR-only flow with Incode, preventing users from being redirected to an error page.

***

## v1.8.8

**30 June 2025**

The following changes are included in this release:

* **FrankieOne Enhances Onboarding with New Consent Flow**. FrankieOne introduces a Welcome & Consent screen for new entities without prior consent across OCR-only, IDV, and IDV-review flows. This update ensures compliance and a seamless onboarding experience, reinforcing FrankieOne's commitment to user-friendly and secure identity verification solutions.
* **FrankieOne Introduces Enhanced Vendor Switching in OneSDK for Seamless Identity Verification**: We have updated our OneSDK platform, enabling seamless switching between identity verification vendors like Incode, Onfido, and Sumsub within the embedded environment. This enhancement offers businesses greater flexibility and efficiency with real-time results displayed in the portal. Ideal for fintech and regtech sectors, this update streamlines compliance and optimizes customer onboarding.
* **Enhanced Error Logging for failure to load external script**: In the event of network issues preventing the loading of Incode scripts for OCR and Biometrics components, error messages will now be logged on Cloudwatch. This ensures prompt identification and resolution of script load errors, enhancing system reliability and user experience.
* **Handle empty phone number country code**: Since V2 now requires phone number country code, handle empty value instead of returning an error

***

## v.1.8.7

**24 June 2025**

The following changes are included in this release:

* **SDK Memory Usage:** Reduce the OneSDK memory usage during code build
* **Enhances Date Input Validation:** Defer the input validation when user has completed all the date components. If date is prefilled, validate the input promptly to alert users of any discrepancies.
* **Better user experience when unable to fetch Onfido SDK:** We've improved the user experience by addressing the issue where a blank screen appeared when OneSDK was unable to load the Onfido SDK. This update ensures seamless continuity, providing users with a more intuitive interaction.
* **IDVerse Engine 5 Support**
  We're introducing support for split OCR + Biometrics workflows powered by IDVerse Engine 5.
  ✅ **Verified Scenarios**:
  * **Passport-based flows** successfully tested with documents from:
    * New Zealand 🇳🇿
    * Australia 🇦🇺
    * India 🇮🇳
    * Canada 🇨🇦
  * **Australian Driver’s License-based flows** validated as part of our UAT testing efforts.
    ⚠️ **Known Issues**
  * **Front/Back scan inconsistency** — failures common in NT, WA, TAS, QLD (likely due to fake IDs)
  * **OCR issues for DOB/Expiry** — affects ACT, NSW, SA, VIC; under investigation (likely due to fake IDs)
  * This enhancement improves flexibility and future-proofs biometric verification flows for evolving compliance needs and document formats.

***

## v1.8.6

**04 June 2025**

The following changes are included in this release:

* **Sumsub as new additional IDV partner**: We've added Sumsub as an IDV partner, to provide additional options for customers especially for cryptocurrency companies. Contact your Customer Success team member if you are interested learn more.
* **Eliminate separate calls for OCR and Biometrics**: We've improved how we process results from Onfido. Now, a single API call handles both OCR and Biometrics, eliminating the need for separate calls. This update simplifies the process and enhances reliability, ensuring you receive accurate results more efficiently.
* **Telemetry improvements**: The OCR, Biometrics, and IDV modules now emit more granular events, giving you richer insights for monitoring and troubleshooting.

***

## v1.8.5

**23 May 2025**

The following changes are included in this release:

* **Enhanced Tracking**: Hosted OneSDK (using iframe) will now send a notification to our event system when they receive a "window unload" message from the parent window. This helps us track when the application is being closed or navigated away from.
* **Custom Retry Pages and Outage for DVS**: Introduced a feature to customize retry pages based on specific field errors during verification or front-end validation processes. This allows users to focus on correcting only the necessary fields rather than all fields. This covers Personal Information Errors and Document Errors. Display an error screen advising customers to try again later due to system unavailability (500 - timeout).
* **Handle invalid document type event**: Emit appropriate `event: input_required` when we received invalid document type from backend.

***

## v1.8.4

**19 May 2025**

The following changes are included in this release:

* **Window Unload Event Tracking** We've added tracking to identify when users leave the biometric verification process early. This helps distinguish between system issues and user-initiated page closure. This is applicable to embedded and non iframe hosted.

***

## v1.8.3

**13 May 2025**

The following change is included in this release:

* **Country filter on manual driver’s licence screen**: Resolved an issue that prevented the manual driver’s licence screen from limiting the country selector to Australia. The screen now reliably displays only “Australia (AUS).”

***

## v1.8.2

**28 Apr 2025**

The following changes are included in this release:

* **Date-of-birth validation fix**: Eliminated the false “Enter a valid date of birth” error that appeared even when the format and value were correct.
* **Hosted OneSDK runtime error screen**: Added a dedicated error screen that appears if a problem is encountered during Hosted OneSDK execution, giving users a clear recovery path.
* **Device-permission logging**: Implemented an event handler that records Incode device-permission requests, helping developers diagnose camera and microphone access issues faster.
* **New Zealand passport expiry validation fix**: Corrected a defect that incorrectly flagged valid NZ passport expiry dates.

***

## v1.8.1

**10 Apr 2025**

The following changes are included in this release:

* **Handling Consent**: \[Fixed] Consent from manual forms not passed correctly for a specific customer scenario
* **Hosted OneSDK Success Event Format**: \[Fixed] Incorrect format of Hosted OneSDK `idv:success event`
* **Phone Number Validation**: \[Fixed] Phone number validation failed despite correct format
* **General Improvement**: \[Fixed] To improve security, we've updated our system to prevent the header from request being logged, ensuring a safer experience for users.

***

## v1.8.0

**07 Apr 2025**

The following changes are included in this release:

* **Expanded Onfido Support**: We’ve added support for Onfido version 14.\* in OneSDK. To take advantage of the latest improvements, please contact our customer support team to update your configuration.

***

## v1.7.21

**26 Mar 2025**

The following changes are included in this release:

* **Display Name Update Issue Resolved**: Fixed an issue where the DisplayName was being incorrectly updated upon verification, leading to invalidation and a suspected status.
* **OCR Component Failure Screen**: Addressed a bug that now correctly shows a failure screen if the OCR (Object Character Recognition) component fails during processing.

***

## v1.7.20

**19 Mar 2025**

The following changes are included in this release:

* **Order Fields in Personal Details**: You can now customize the order of fields when entering personal details, enhancing the flexibility and organization of your data input.
* **Fixed Loading Issue**: Resolved an issue where OneSDK would fail to load if the entity had a customer reference set. This fix ensures smoother initialization and operation.
* **Onfido Modal Enhancement**: The Onfido modal now includes a confirmation dialog to prevent users from accidentally closing it by clicking the overlay. This enhancement prevents unintended session termination.
* **OneSDK CLI Customizations**: Apply customizations more effectively in IDV + Review through the OneSDK command-line interface, providing more control and efficiency in operations.

***

## v1.7.19

**07 Mar 2025**

The following changes are included in this release:

* **Fixed Retry Screen Issue**: Resolved the problem where the Retry screen persistently asked for additional ID verification. This fix ensures a smoother user experience without repetitive requests for identification.
* **Improved Redirect Links**: Enhanced the handling of redirect links, ensuring they are correctly applied across various flow IDs<br />This update applies to:
* IDV + Review
* IDV + KYC
* Manual + KYC
* OCR Only

***

## v1.7.18

**27 Feb 2025**

The following changes are included in this release:

* **Edit Button Customization**: You can now customize the edit button on the review screen, enhancing the user interface according to your brand needs.
* **Disabled Button Background Color**: Customize the background color of disabled buttons to match your application's aesthetic.
* **Credit Header Description Customization**: Tailor the `credit_header_description` to provide clearer guidance and context to users.
* **Multiple IDs/Retry Flow Text Customization**: Modify the text displayed during multiple ID submissions or retry flows to improve user understanding and reduce errors.
* **Address Search Label Update**: For address searches, the label now uses the value from `formatted_address` from the Google Search API, replacing the previous use of `description` from Google Predictions API. This change aims to provide more accurate and user-friendly address suggestions.

**Fixes**

* **Project Build Issue**: Resolved an issue where projects could not be built using the latest version of OneSDK. Ensure seamless integration and deployment with this fix.

***

## v1.7.17

**24 Feb 2025**

The following updates are included in this version:

* Improve OCR module to read expiry date when switching between different ID types.
* The OCR module's events have been updated to match the order and format of the Biometrics module.
* Previously, OCR vendor loaded event is only emitted when OCR is done. Now, vendor loaded event is emitted before ready event regardless if OCR is done or not.
* Adjusted the credit header text for passed KYC checks.
* Trigger Google API requests when typing is complete. This optimization reduces the number of API calls and associated costs.

**Additional configurable components**:

* HTML link tags: Updated the HTML sanitization logic to allow the `<a target="_blank">` tag. This allows customers to include links that open in a new tab within consent screens, enhancing user experience.
* Checkbox colors: Added the ability to customize the color of checkboxes using the .ff-checkbox CSS class and the accent-color property. This allows for greater flexibility in styling consent screens.

***

## v1.7.16

**17 Feb 2025**

This version of the OneSDK includes the latest enhancements and updates that we’ve made to improve your experience with our platform. It also fixes issues previously encountered.

***

## v1.7.15

**27 Jan 2025**

The following changes have been implemented in this version:

* General improvements, including improved logic for handling entity information updates and status flagging.
* Resolved an issue where the UI was not visible in dark mode.
* Updated the messaging on the result screen for KYC check results.

***

## v1.7.13

**13 Jan 2025**

The following updates are included in this version:

* **Enhanced OCR Review with Manual Address Input**: The OCR review screen now defaults to manual address input, ensuring accurate and complete address information by requiring users to fill in individual address fields.
* **Configurable OCR Field Extraction**: Customers can now configure which specific fields should be pre-filled after OCR extraction, providing greater control over the data review process.
* **Rate Limit Investigation for OneSDK Calls**: We've implemented measures to investigate and potentially rate-limit critical calls within the OneSDK to ensure stability and prevent rapid successive executions.
* **Additional Error Handling**:

1. We've addressed several scenarios to provide clearer error messages and a smoother user experience, particularly when encountering issues with OCR or missing permissions.
2. **Improved error Response of OCR Failures**. When it fails or an invalid document is provided, system now returns a more informative error code (not a generic 500), allowing for better error handling.

* **Incode version 1.75.2 support is now available**. For those using embedded, you may update sdkversion to point this while customers using Hosted OneSDK will automatically fetch this version

***

## v1.7.12

**16 Dec 2024**

The following updates have been implemented in OneSDK:

* UI issue on Driver’s Licence button text misalignment and instruction text during selfie capture
* Missing middle name initial option for Medicare Card in eKYC form and requirement config not working
* Unable to override Labels for Personal details in Review screen
* Update Address breakdown issue
* Added ability to view and non-editable personal information (Name + DOB + Address) in the review screen and generic document screen

***

## v1.7.11

**26 Nov 2024**

* Improvements on phone, email and device information for fraud check

***

## v1.7.10

**22 Nov 2024**

The following updates are included in this version:

* The review screen is skipped when an Incomplete status is received from the backend.
* Document Restrictions Not Working for Passports
* Navigation not clearing the form
* Mounting of result screen
* Document configuration for passport and driver’s licence
* Document configuration for passport and driver’s licence
* Ability to disable edit button on review screen
* Prevent OneSDK’s styling from overriding customer's styling

***

## v1.7.7

**21 Oct 2024**

Allow retries after partial error before directing

**Fixes**

* Issue with phone number not updating individual module
* ID expiry date allows date prior to current date
* Cosmetic issue with field borders

***

## v1.7.6

**26 Sept 2024**

OneSDK now emits a clear event when the Onfido modal is closed, ensuring seamless integration and improved user experience.

***

## v1.7.5

**19 Sept 2024**

Added the new Hosted OneSDK flow, `idv_kyc`. This new flow provides a complete end-to-end flow, including IDV and KYC

***

## v1.7.4

**16 Sept 2024**

We've introduced the ability to set and remove key-value pairs (KVPs) on an entity. This enhancement enables customers to add extra information, such as a preferred name `preferredName`, to the entity using OneSDK.

***

## v1.7.3

**03 Sept 2024**

* We've added Webpack Support to expand the compatibility of OneSDK with build tools.

**Fixes**

* The ID Type wasn't being highlighted when a document was already added. This is now fixed.
* The timestamp in the Portal now correctly shows the submission time of the entity details.
* Previously, it displayed the time when OneSDK was initialized.
* Fixed a bug where a duplicate screen appeared when the back button was disabled in a single-page customer implementation.
* An error has been fixed where it was mistakenly showing up in headless OCR.
* The biometric instructions text for users has been fixed to ensure it doesn't appear too low on the screen.

***

## v1.7.2

**01 Aug 2024**

Onboarding Forms: New onboarding forms extracted address mapping.<br />Onboarding Forms: Fix issue with country address mapped to Passport issuing country

***

## v1.7.1

**15 July 2024**

New Onboarding Forms: Fix Review screen input configuration

***

## v1.7.0

**27 June 2024**

**Introducing OneSDK Onboarding Forms**

We're thrilled to announce that in 2024 we're launching our new OneSDK Onboarding Forms, to replace Smart UI.

OneSDK Onboarding Forms was developed through insight and feedback from valued clients, like yourself. We're confident that it ill yield substantial benefits for both your organisation and your end-users, delivering a faster experience that isn't only superior but also more cost-effective, and enables:

**Better outcomes**

* Improved Pass Rates (5-10%+ uplift)
* 2X Faster Onboarding with Biometrics-first
* Capability to conduct A/B testing of screens
* OneSDK Analytics to track user behaviour**More flexibility**
* Modular forms for easy UX optimisation, facilitating rapid deployment of new designs in less than a day
* Availability of our Hosted OneSDK, managed by FrankieOne, facilitating seamless improvements and patches directly to you without involving your engineers
* Future access to our Business Onboarding Forms

***

## v1.6.1-beta

**30 May 2024**

**OneSDK Enhancements**<br />*Updates:*<br />Onfido: You can now limit the country and document type in the OCR header.<br />Onfido: Custom UI is now exposed for easier customization.<br />Individual Module: The entityProfile is now accessible for use.

*Fixed*<br />Mock Mode: Issues with exit/error functionality have been resolved.

**Hosted OneSDK Updates**<br />*FIxed*<br />Loading Spinner: The problem with the loading spinner not working has been fixed.

***

## v1.5.0-beta

**30 April 2024**

**Introducing OneSDK Onboarding Forms**<br />We're thrilled to announce that in 2024 we're launching our new OneSDK Onboarding Forms, to replace Smart UI.

OneSDK Onboarding Forms was developed through insight and feedback from valued clients, like yourself. We're confident that it will yield substantial benefits for both your organisation and your end-users, delivering a faster experience that isn't only superior but also more cost-effective, and enables:

**Better outcomes**

* Improved Pass Rates (5-10%+ uplift)
* 2X Faster Onboarding with Biometrics-first
* Capability to conduct A/B testing of screens
* OneSDK Analytics to track user behaviour<br />**More flexibility**
* Modular forms for easy UX optimisation, facilitating rapid deployment of new designs in less than a day
* Availability of our Hosted OneSDK, managed by FrankieOne, facilitating seamless improvements and patches directly to you without involving your engineers
* Future access to our Business Onboarding Forms

***

## v1.4.4-beta

**11 April 2024**

This version of the OneSDK contains the following updates:

* For Incode, we’ve added the ability to force a specific document type for OCR processing.
* Handling of CSS within the OneSDK has also been improved.
* We’ve introduced support for DigitalID in OCRLabs
* Our team also resolved issues related to the NPM package.

***

## v.1.4.3-beta

**28 March 2024**

This version of the OneSDK contains the following updates:

* Added the full Smart UI configuration in the Form component in OneSDK.
* Additional changes to implement Smart UI into OneSDK

***

## v.1.3.2-beta

**19 March 2024**

This version of the OneSDK contains the following update:<br />A hotfix was implemented to address an issue related to capturing driver’s license information using Incode SDK 1.66.0.<br />To address this issue, the default version was reverted to 1.59.0, and dynamic version selection in the recipe now permits using an alternative version.

***

## v.1.3.1-beta

**08 March 2024**

This version of the OneSDK contains the following update:<br />A **hotfix** was applied to resolve an issue where iOS users encounter an error related to screen orientation.

***

## v1.3.0-beta

**05 March 2024**

This version of the OneSDK contains the following update:<br />To align with Incode's new policy, we've enabled the option to re-use the token from the IDV service.

***

## v1.2.0-beta

**23 January 2024**

This version of the OneSDK contains the following update:<br />**Onfido IDV flow into OneSDK (OCR + Biometrics)**

***

## v1.1.0-beta

**05 December 2023**

This version of the OneSDK contains the following update:<br />**OCR with review screen**<br />**SmartUI within OneSDK**

* Minor fixes and updates

***

## v1.0.0-beta

**01 November 2023**

This version of the OneSDK contains the following update:<br />**Incode for OCR and Biometrics**

***

## v0.8.6-alpha

**17 October 2023**

This version of the OneSDK contains the following update:<br />**Hotfix for Onfido Motion**<br />A fix was implemented to prevent the issue where the user isn't able to proceed to OCR flow due to an infinite loop.

***

## v0.8.3-alpha

**19 September 2023**

This version of the OneSDK contains the following update:

**Onfido for OCR and Biometrics (Motion)**

***

## v0.8.0-alpha

**01 August 2023**

This version of the OneSDK contains the following update:

**Addition of IDV flow**

***

## v0.7.4-alpha

**28 July 2023**

This version of the OneSDK contains the following features:

**Capture details from an individual**<br />Use the IDV component to capture and verify the details of an individual

**Document OCR flow**<br />The OCR component provided by OneSDK to extract document details from a document images supplied by the user

**Biometrics (selfie and liveliness)**<br />Leverage the Biometrics component or the OCR component via the OneSDK.

**Device characteristics and behavioral biometrics** Evaluate potential fraud indicators from the characteristics of their device as well as al their form-filling behavior using OneSDK

**Support Federated Identity**<br />Use OneSDK's Federation component to import data from various Identity Providers (**IdP**s) that support OpenID Connect or OAuth2.

Additional features help developers build and test the OneSDK:

**Test mode**<br />Use mock data during development to accelerate integration by enabling your frontend and backend teams to work parallel

**Headless UI**<br />Integrate seamlessly into your existing design system to match yhour application's look and feel

**Install via CDN or npm**<br />Choose how to integrate into your codebase.

**RX.JSObservable support**<br />Integrate into popular frontend frameworks such as Vue, Angular, or React with support for RXKS.Observable

***


# MCP Server
Source: https://docs.frankieone.com/v2/api/developers/frankie-one-mcp-server

Connect your AI coding assistant directly to FrankieOne documentation

## Overview

FrankieOne provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives AI coding assistants direct access to our documentation, API references, and integration guides.

This means you can ask your AI assistant questions about FrankieOne — like how to structure API payloads, configure webhooks, or implement KYC checks — and get answers sourced directly from our docs, without leaving your IDE.

<Note>
  No authentication is required. The MCP server is a public endpoint available to all FrankieOne customers and developers.
</Note>

## Quick setup

Add the following to your MCP client configuration:

```json theme={null}
{
  "mcpServers": {
    "frankieone": {
      "type": "url",
      "url": "https://docs.frankieone.com/mcp"
    }
  }
}
```

## Setup by tool

<AccordionGroup>
  <Accordion title="Claude Code">
    Add to your `~/.mcp.json` file:

    ```json theme={null}
    {
      "mcpServers": {
        "frankieone": {
          "type": "url",
          "url": "https://docs.frankieone.com/mcp"
        }
      }
    }
    ```

    Restart Claude Code to activate the server.
  </Accordion>

  <Accordion title="Claude Desktop">
    Open **Settings > Developer > Edit Config** and add to your `claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "frankieone": {
          "type": "url",
          "url": "https://docs.frankieone.com/mcp"
        }
      }
    }
    ```

    Restart Claude Desktop to activate.
  </Accordion>

  <Accordion title="Cursor">
    Go to **Settings > MCP Servers > Add Server** and configure:

    * **Name:** `frankieone`
    * **Type:** `url`
    * **URL:** `https://docs.frankieone.com/mcp`
  </Accordion>

  <Accordion title="Windsurf">
    Go to **Settings > MCP Servers** and add:

    ```json theme={null}
    {
      "mcpServers": {
        "frankieone": {
          "type": "url",
          "url": "https://docs.frankieone.com/mcp"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Any MCP-compatible client">
    The FrankieOne MCP server is available at:

    ```
    https://docs.frankieone.com/mcp
    ```

    Add this as a remote URL-based MCP server in your client's configuration. No API key or authentication is needed.
  </Accordion>
</AccordionGroup>

## Available tools

| Tool                 | Description                                                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **SearchFrankieone** | Search across the FrankieOne knowledge base to find documentation, code examples, API references, and integration guides. |

### SearchFrankieone parameters

| Parameter          | Type    | Required | Description                                                             |
| ------------------ | ------- | -------- | ----------------------------------------------------------------------- |
| `query`            | string  | Yes      | A query to search the content with                                      |
| `version`          | string  | No       | Filter to a specific API version (e.g., `v2.0.0`)                       |
| `language`         | string  | No       | Filter to a specific language code (e.g., `en`, `zh`). Defaults to `en` |
| `apiReferenceOnly` | boolean | No       | Only return API reference documentation                                 |
| `codeOnly`         | boolean | No       | Only return code snippets                                               |

## Example queries

Once connected, try asking your AI assistant:

* "How do I create an individual entity using the FrankieOne v2 API?"
* "What fields are required for a Brazilian KYC check?"
* "Show me the webhook payload format for check completion"
* "How does forceRefresh work when re-running a verification?"
* "What are the available recipe types for international checks?"
* "How do I configure OneSDK for document capture?"

## How it works

The MCP server connects your AI assistant to FrankieOne's documentation in real time. When you ask a question:

1. Your AI assistant sends the query to the FrankieOne MCP server
2. The server searches across all published documentation
3. Relevant content — including code examples, API references, and guides — is returned
4. Your AI assistant uses this context to provide an accurate, up-to-date answer

<Tip>
  The MCP server always returns content from the latest published documentation, so you'll always get current information about FrankieOne's APIs and features.
</Tip>

## Requirements

* An MCP-compatible AI tool (Claude Code, Claude Desktop, Cursor, Windsurf, or similar)
* Internet connectivity to reach `docs.frankieone.com`
* No API key, authentication, or FrankieOne account required


# How to Get Portal Access to FrankieOne
Source: https://docs.frankieone.com/v2/api/developers/how-to-get-portal-access

Detailed information on how to access FrankieOne's portal

## Overview

Getting access to the FrankieOne Portal is a straightforward process. FrankieOne provisions your organisation's initial portal access, and from there, authorised Administrators can invite and manage additional team members independently. This guide covers how access is granted and what you need to know about user roles and permissions.

***

## Portal Environments and URLs

FrankieOne provides two separate environments for your organisation:

| Environment | Purpose                     | Portal URL                     |
| ----------- | --------------------------- | ------------------------------ |
| UAT         | Testing & training          | `portal.uat.frankie.one/login` |
| Production  | Live customer verifications | `portal.frankie.one/login`     |

> **Best practice:** Always test new configurations and workflows in UAT before implementing them in Production. Never use Production credentials in a UAT environment, or vice versa.

***

## Getting Your Initial Portal Access

### Step 1 — FrankieOne sets up your account

When you become a FrankieOne customer, your Customer Success Manager or Implementation Team will:

* Create your organisation's account in both UAT and Production environments
* Set up an initial Administrator user (typically your primary contact)
* Provide login credentials and environment details
* Send a welcome email with instructions to set your password

This initial setup is handled entirely by FrankieOne to ensure your account is properly configured.

### Step 2 — First Administrator logs in

The initial Administrator will:

* Receive an email from FrankieOne with login instructions
* Click the link to set their password
* Log in using the appropriate environment URL above
* Verify access to both UAT and Production environments

### Step 3 — Administrator invites additional users

Once the first Administrator has access, they can invite additional team members without requiring further assistance from FrankieOne.

***

## Adding New Users to Your Portal

### For Administrators: How to add new users

1. Navigate to Profile menu → Settings → User Management
2. Click **Add new user**
3. Enter the user's full name and email address
4. Assign at least one role (required for portal access)
5. Click **Add user** to create the account

### For new users: Activating your account

Once an Administrator creates your account:

* Check your email for an automated message from FrankieOne
* Click the link in the email to set your password
* Log in using the appropriate environment URL
* Familiarise yourself with your assigned permissions

***

## Requesting Portal Access

### If you are a new team member

1. **Identify your organisation's Administrator** — typically someone in compliance, operations, or IT
2. **Request access** — provide them with your full name, work email address, the role(s) you need, and which environment(s) you require (UAT, Production, or both)
3. **Wait for the invitation email** — your Administrator will create your account and you will receive setup instructions

### If you are the first user at your organisation

Contact your FrankieOne Customer Success Manager or Implementation Team to initiate the account setup process. They will create your initial Administrator account and provide all necessary credentials and documentation.

***

## Default User Roles and Permissions

The FrankieOne Portal includes three default roles. Your Administrator will assign one or more roles based on your responsibilities.

### Default roles

* **Administrator** — Full access to all portal features
* **Operator** — Can manage entities and perform verifications
* **Compliance Officer** — Read and reporting access; cannot create or modify entities or settings

### Baseline permissions (all roles)

Regardless of assigned role, all portal users can:

* View entities and their audit reports
* Search and filter entities
* View workflow event details (check results, risk level)
* View entity profile information (personal information, identity documents)
* Create and manage custom views
* View and add comments

### Role-specific permissions

| Permission                            | Administrator | Operator | Compliance Officer |
| ------------------------------------- | :-----------: | :------: | :----------------: |
| **Create, Edit, and Download Access** |               |          |                    |
| Download reports                      |       ✅       |     ✅    |          ✅         |
| Create and edit entities              |       ✅       |     ✅    |          ❌         |
| Modify entity monitoring              |       ✅       |     ✅    |          ❌         |
| Manage blocklists                     |       ✅       |     ✅    |          ❌         |
| Manage duplicates                     |       ✅       |     ✅    |          ❌         |
| Modify risk level                     |       ✅       |     ✅    |          ❌         |
| **Settings**                          |               |          |                    |
| Users and permissions                 |       ✅       |     ❌    |          ❌         |
| Account settings                      |       ✅       |     ❌    |          ❌         |

### Detailed permission breakdown

**Administrator** can:

* Manage all user accounts (create, edit, delete, lock users)
* Configure role permissions
* Manage all account settings
* Perform all entity management tasks
* Override verification results
* Manage blocklists and duplicates

**Operator** can:

* Create and verify new entities
* Update and verify existing entities
* Perform manual and electronic KYC
* Override workflow event status
* Retrigger checks
* Update AML alert status
* Override document and biometrics check results
* Download entity data as CSV
* Leave comments on manual review actions

**Compliance Officer** can:

* View all entity information
* Generate and download audit reports as PDF
* Monitor compliance status
* View check results and risk assessments

***

## Custom Roles

Your organisation can create custom roles with specific permission combinations to match your internal workflows and compliance requirements. To create a custom role, an Administrator should navigate to the Role Management section in Settings.

***

## Important Security Notes

### Parent-child account structure

If your organisation uses a parent-child account structure, users in a child account cannot view or assign users from the parent account by default. This restriction is enabled by default for security purposes. If your business requires parent-level user management from a child account, contact FrankieOne Support to discuss enabling this feature.

### Password management

If you are locked out of the portal or need to reset your password:

* Click the **Reset password** button on the portal login page — you will receive an email with a reset link
* Alternatively, contact your Administrator, who can send a password reset link through the portal

### Account locking

If your account is locked, you will not be able to access the portal. Your profile remains in the system for audit purposes. Contact your Administrator to unlock your account.

***

## Single Sign-On (SSO) Access

If your organisation has configured Single Sign-On with FrankieOne, you may access the portal through your company's identity provider (such as Azure AD, Okta, or Google) instead of using a separate password. For information about SSO setup, contact your FrankieOne Customer Success Manager.

***

## Quick Reference: Getting Started

### For new organisations

1. FrankieOne creates your account and initial Administrator user
2. First Administrator receives welcome email and sets password
3. Administrator logs in to both UAT and Production environments to verify access
4. Administrator invites additional team members as needed

### For new team members

1. Identify your organisation's Administrator
2. Request portal access with your name, email, required role(s), and environment(s)
3. Wait for the account creation email
4. Set your password using the link in the email
5. Log in to the portal and review your assigned permissions
6. Contact your Administrator if additional permissions are required

***

## Environment Best Practices

* **Always test in UAT first** — use UAT to test new workflows, configurations, and to train new users
* **Keep Production secure** — limit Production access to users who need to work with live customer data
* **Use appropriate credentials** — never use Production credentials in UAT or vice versa
* **Maintain separate accounts** — users should have separate accounts for UAT and Production environments

***

> **Remember:** FrankieOne provisions your initial portal access. Once your account is established, your Administrator can independently manage all user accounts and permissions. At least one role must be assigned for a user to access the portal.


# FrankieOne Integration Architecture Guide
Source: https://docs.frankieone.com/v2/api/developers/integration-architecture-guide

Understand system connections, data flows, and integration patterns when integrating with FrankieOne.

## Purpose

This guide explains how your systems connect with FrankieOne from an architectural perspective, including:

* System-to-system communication patterns
* Data flow and sequencing
* Infrastructure considerations
* Security and compliance requirements
* Common integration architectures for different use cases

## Audience

* **Solution Architects** — design the integration architecture
* **Technical Leads** — understand system boundaries and responsibilities
* **Project Managers** — understand technical dependencies and timelines
* **Security Teams** — understand data flows and security requirements

***

## Contents

* [Core Architecture Concepts](#core-architecture-concepts)
* [Integration Pattern 1: Hybrid (API + Portal)](#integration-pattern-1-hybrid-api--portal)
* [Integration Pattern 2: Fully Automated (API-Only)](#integration-pattern-2-fully-automated-api-only)
* [Integration Pattern 3: Platform/Marketplace Model](#integration-pattern-3-platformmarketplace-model)
* [Technical Considerations](#technical-considerations)
* [Security & Compliance](#security--compliance)
* [When to Consult FrankieOne](#when-to-consult-frankieone)
* [Summary: Choosing Your Integration Approach](#summary-choosing-your-integration-approach)

***

## Core Architecture Concepts

### System Boundaries

<img alt="architecture system boundaries" />

Alternate view

```mermaid theme={null}
flowchart LR
  subgraph Your["Your infrastructure"]
    App["App (Web / Mobile)"]
    Backend["Backend"]
    Data["DB / CRM"]
    App --> Backend --> Data
  end

  subgraph Frankie["FrankieOne"]
    API["API"]
    Portal["Portal"]
    Webhooks["Webhooks"]
  end

  Users["Compliance / Ops"]

  Backend -- "API calls" --> API
  Webhooks -- "Events" --> Backend
  API --> Webhooks

  Users <-- "Review / reporting" --> Portal

```

***

### Key Components

#### FrankieOne API

* **Protocol:** HTTPS REST
* **Authentication:** API Key + Customer ID headers
* **Base URLs:**
  * V2 UAT: `https://api.uat.frankie.one/v2/`
  * V2 Production: `https://api.frankie.one/v2/`
  * V1 Production: `https://api.kycaml.frankiefinancial.io/compliance/v1.2/`

**Primary functions**

* Create individuals and organisations
* Execute verification workflows
* Retrieve results
* Update entity data

***

#### Webhooks

* **Direction:** FrankieOne → Your system
* **Protocol:** HTTPS POST
* **Format:** JSON
* **Purpose:** Asynchronous event notifications
* **Retry policy:** Exponential backoff (up to 50 retries over 24 hours)

***

#### FrankieOne Portal

* **Access:** Web UI (HTTPS)
* **Authentication:** Username/password + MFA
* **Purpose:** Case management, manual review, reporting
* **Users:** Compliance and operations teams

***

#### OneSDK (Optional)

* **Type:** Client-side JavaScript SDK
* **Deployment:** Embedded in web or mobile apps
* **Purpose:** Document capture, biometrics, form collection
* **Communication:** Direct to FrankieOne API using session tokens

***

## Data Flow Fundamentals

At a high level, the standard FrankieOne verification flow looks like this:

* **Create an entity and execute a workflow** via API
* Receive an **immediate response** (synchronous result + IDs you'll need later)
* FrankieOne sends **webhooks** if the workflow status changes (or completes asynchronously)
* Your webhook handler should **acknowledge quickly** and then fetch full results
* Your system applies **decision logic** (PASS / FAIL / REVIEW) and proceeds with onboarding

### End-to-end flow diagram

```mermaid theme={null}
sequenceDiagram
    participant Client as Your System
    participant API as FrankieOne API
    participant Webhook as FrankieOne Webhooks

    Client->>API: Create entity + execute workflow
    Note right of Client: POST /v2/individuals/new/.../execute

    API-->>Client: Immediate response
    Note left of API: requestId, entityId,<br/>initial workflowResult

    API-->>Webhook: Workflow completes or status changes
    Webhook-->>Client: Webhook notification
    Note right of Webhook: WorkflowComplete / StatusChanged

    Client->>API: Fetch full results
    Note right of Client: GET workflow execution details

    API-->>Client: Final workflow result
    Note left of API: status, riskAssessment,<br/>issues, steps

    Client->>Client: Apply decision logic<br/>(PASS / FAIL / REVIEW)
```

### Practical notes

* Always store identifiers from step 2 (e.g. `requestId`, `entityId`, and any workflow/execution IDs returned), so you can fetch results later.
* Treat webhooks as a signal, not the full truth. A best practice is:
  * Respond `200` quickly, then
  * Fetch the latest results via API, then
  * Update your database and trigger downstream actions.
* Make webhook handling idempotent (duplicate deliveries can occur).

### Example webhook handling approach (recommended)

```javascript theme={null}
// Pseudocode: acknowledge fast, then process async
app.post("/frankieone-webhook", async (req, res) => {
  res.status(200).send("OK"); // respond quickly

  // enqueue for background processing
  await queue.publish({
    type: req.body.function,
    requestId: req.body.requestId,
    entityId: req.body.entityId,
    payload: req.body
  });
});
```

***

## Integration Pattern 1: Hybrid (API + Portal)

### Overview

Use this pattern when you want **automated verification** with **manual review handled in the FrankieOne Portal**.

**Common scenarios**

* Fintech onboarding with edge-case review
* E-commerce seller verification
* Lending platforms with risk-based decisioning

***

### Architecture

```text theme={null}
Your App → Your Backend → FrankieOne API
                         ↘
                          FrankieOne Portal (Manual Review)
                         ↗
                     Webhooks
```

***

### Key Decisions

#### Where does entity data live?

**Recommended: Dual storage**

* Your system remains the source of truth
* FrankieOne stores verification context
* Link records using a stable reference

```json theme={null}
{
  "customerId": "CUST-12345",
  "frankieEntityId": "entity-abc-123",
  "verificationStatus": "PENDING"
}
```

***

#### Synchronous vs Asynchronous Workflows

**Synchronous**

* Immediate response (2–10 seconds)
* Best for real-time onboarding

**Asynchronous**

* Immediate acknowledgement
* Final result via webhook
* Best for high volume or long-running checks

***

#### Webhook Architecture (Recommended)

```text theme={null}
Load Balancer
     ↓
Webhook Endpoint (respond 200 immediately)
     ↓
Message Queue
     ↓
Worker Process (fetch results, update DB)
```

**Requirements**

* HTTPS only
* Idempotent processing
* Fast response under 5s

***

## Integration Pattern 2: Fully Automated (API-Only)

### Overview

Use this pattern when you want **complete control** and already have (or plan to build) your own case management system.

**Common scenarios**

* High-volume lending platforms
* Crypto exchanges
* Enterprises with Salesforce or ServiceNow

***

### Characteristics

* No operational dependency on the FrankieOne Portal
* All decisioning handled in your systems
* FrankieOne used purely as a verification engine

***

### Responsibilities

**You build**

* Case management system
* Review UI
* Escalation workflows
* Decision logic

**FrankieOne provides**

* Verification execution
* Data sources
* Audit trail

***

## Integration Pattern 3: Platform / Marketplace Model

### Overview

Use this pattern when **your customers need to verify their own end-users**, and you provide compliance as a service.

**Common scenarios**

* Marketplaces
* SaaS platforms
* White-label onboarding products

***

### Parent / Child Account Model

```text theme={null}
Your Platform (Parent)
├── Customer A (Child)
│   └── End Users
├── Customer B (Child)
└── Customer C (Child)
```

**Key concept:** Each customer maps to a FrankieOne **child account**.

***

### API Example (Child Routing)

```javascript theme={null}
await frankieOneAPI.createEntity({
  headers: {
    api_key: PLATFORM_API_KEY,
    "X-Frankie-CustomerID": PLATFORM_CUSTOMER_ID,
    "X-Frankie-CustomerChildID": CUSTOMER_CHILD_ID
  },
  body: {
    individual: { ... },
    extraData: [
      { "kvpKey": "platform_customer_id", "kvpValue": "CUSTOMER-A" }
    ]
  }
});
```

***

## Technical Considerations

### Authentication & Secrets

* Never expose API keys client-side
* Store keys in a secrets manager
* Rotate keys regularly

***

### Networking

* Outbound HTTPS (443) to FrankieOne APIs
* Inbound HTTPS (443) for webhooks
* IP allowlisting available on request

***

### Error Handling

| Status  | Meaning      | Action             |
| :------ | :----------- | :----------------- |
| 400     | Bad request  | Fix request        |
| 401/403 | Auth error   | Check credentials  |
| 429     | Rate limited | Retry with backoff |
| 5xx     | Server error | Retry with backoff |

***

## Security & Compliance

### Data Protection

* All data encrypted in transit (TLS 1.2+)
* Encrypted at rest (AES-256)
* SOC 2 Type II & ISO 27001 compliant

***

### Logging Guidance

**Log**

* Request IDs
* Entity IDs
* Status transitions

**Do not log**

* API keys
* Full PII
* Documents or biometrics

***

## When to Consult FrankieOne

Contact FrankieOne if you have:

* High-volume requirements (>10k/day)
* Multi-region or data residency needs
* Complex platform or marketplace architecture
* Custom workflow or data source requirements
* Production performance issues

***

## Summary: Choosing Your Integration Approach

| Your Situation           | Recommended Pattern           |
| :----------------------- | :---------------------------- |
| Fastest time to market   | Hybrid or OneSDK for frontend |
| Full automation          | API-only                      |
| White-label / SaaS       | Platform model                |
| Limited dev resources    | Hybrid                        |
| Existing case management | API-only                      |

***

## Next Steps

* Identify your integration pattern
* Review architecture with FrankieOne
* Implement in UAT
* Test webhooks and failure scenarios
* Go live and monitor


# Understanding Checks, Workflows, and OneSDK Flows in FrankieOne
Source: https://docs.frankieone.com/v2/api/developers/understanding-checks-workflows-in-frankie-one

A Simple Guide to How FrankieOne's Components Work Together

## What This Article Covers

This guide explains how different FrankieOne components relate to each other:

* **Checks** — Individual verification tasks
* **Workflows** — Collections of checks that run together
* **OneSDK Flow IDs** — User interface flows for data collection
* **Entity Profiles (V1 Legacy)** — How checks were grouped in the older system

**Who should read this:**

* Developers integrating FrankieOne
* Product managers planning implementations
* Anyone trying to understand how FrankieOne components fit together

***

## Table of Contents

* [The Big Picture](#the-big-picture)
* [What is a Check?](#what-is-a-check)
* [What is a Workflow?](#what-is-a-workflow)
* [What is a OneSDK Flow ID?](#what-is-a-onesdk-flow-id)
* [How They Work Together](#how-they-work-together)
* [V1 vs V2: Entity Profiles vs Workflows](#v1-vs-v2-entity-profiles-vs-workflows)
* [Common Scenarios](#common-scenarios)
* [FAQs](#faqs)

***

## The Big Picture

Think of FrankieOne verification like building a house:

```mermaid theme={null}
flowchart TB
    %% ENTRY
    OneSDK["OneSDK (User Interface)\n\n• Document capture\n• Selfie capture\n• Personal details\n\nThe front door\nwhere users enter data"]

    %% ENTITY
    Entity["Entity\n(Person or Business)\n\nThe subject being verified\n\n• Name\n• DOB / Address\n• Documents\n• Biometrics"]

    %% WORKFLOW
    Workflow["Workflow\n(Verification Process)\n\nThe blueprint\nthat defines which checks run"]

    KYC["KYC Check"]
    IDV["IDV Check"]
    AML["AML Check"]

    %% RESULT
    Result["Verification Result\n\nPASS · FAIL · REVIEW"]

    %% FLOWS
    OneSDK -->|Collects data| Entity
    Entity -->|Sent through| Workflow

    Workflow --> KYC --> IDV --> AML
    AML -->|Produces| Result
```

### In Simple Terms

| Component   | Description                                         |
| :---------- | :-------------------------------------------------- |
| OneSDK Flow | The user interface that collects information        |
| Entity      | The person or business being verified               |
| Workflow    | The verification process (contains multiple checks) |
| Checks      | Individual verification tasks (KYC, IDV, AML, etc.) |
| Result      | The final outcome (PASS, FAIL, REVIEW)              |

***

## What is a Check?

### Definition

A check is a single verification task that validates one aspect of an entity's identity or compliance status.

Think of a check as asking one specific question:

* "Does this person's name and address match government records?" (KYC Check)
* "Is this document authentic?" (IDV Check)
* "Is this person on any sanctions lists?" (AML Check)

### Types of Checks

| Check Type                  | What It Does                                   | Example                                               |
| :-------------------------- | :--------------------------------------------- | :---------------------------------------------------- |
| KYC (Know Your Customer)    | Verifies identity details against data sources | Checks name, DOB, address against credit bureau       |
| IDV (Identity Verification) | Validates documents and biometrics             | Checks if passport is authentic, selfie matches photo |
| AML (Anti-Money Laundering) | Screens against watchlists                     | Checks for PEP, sanctions, adverse media              |
| Fraud                       | Detects fraud signals                          | Checks device, email, phone for fraud indicators      |
| Duplicate                   | Finds duplicate entities                       | Checks if person already exists in your system        |
| Matchlist                   | Checks against custom lists                    | Checks against your internal blocklist                |

### Check Lifecycle

```text theme={null}
Check Created
     │
     ▼
Check Running ──────┐
     │              │
     ▼              │ (Waiting for data source)
Check Completed ◄───┘
     │
     ├─ PASS
     ├─ FAIL
     ├─ NO_MATCH
     ├─ HIT (for AML)
     └─ ERROR
```

### Example: KYC Check

```json theme={null}
{
  "checkType": "KYC",
  "checkName": "two_",
  "result": "PASS",
  "details": {
    "nameVerified": true,
    "addressVerified": true,
    "dobVerified": true,
    "matchedSources": [
      "Credit Bureau",
      "Electoral Roll"
    ]
  }
}
```

**What happened:**

* The check verified the person's name against 2 data sources ✓
* The check verified the person's address against 2 data sources ✓
* Result: PASS

***

## What is a Workflow?

### Definition

A workflow is a collection of checks that run together in a specific order to verify an entity. It's like a recipe that defines:

* Which checks to run
* In what order
* What conditions trigger each check
* What the final outcome should be

### Workflow Structure

```mermaid theme={null}
flowchart TB
    Start([Start])

    Matchlist["Matchlist Check\n(Internal blocklist)"]
    KYC["KYC Check\n(Identity details)"]
    IDV["IDV Check\n(Documents & biometrics)"]
    AML["AML Screening\n(Watchlists)"]
    Decision["Final Decision"]

    PASS([PASS])
    FAIL([FAIL])
    REVIEW([REVIEW])

    Start --> Matchlist

    Matchlist -->|Hit| FAIL
    Matchlist -->|Clear| KYC

    KYC -->|No match| FAIL
    KYC -->|Match| IDV

    IDV -->|Fail| REVIEW
    IDV -->|Pass| AML

    AML -->|Hit| REVIEW
    AML -->|Clear| Decision

    Decision -->|All checks passed| PASS
    Decision -->|Critical failure| FAIL
    Decision -->|Needs review| REVIEW
```

### Workflow Configuration

Workflows are configured by FrankieOne based on your requirements. Each workflow has:

**1. Name**

Example: `Standard-KYC-AU`, `Enhanced-KYC-US`, `Basic-KYB-UK`

**2. Service Profile**

The category it belongs to (e.g., "DEFAULT", "Fraud")

**3. Lifecycle Phase**

* `ONBOARDING` — Initial verification when customer signs up
* `MONITORING` — Ongoing checks after onboarding
* `REFRESH` — Periodic re-verification

**4. Steps**

The checks to run and their configuration

**5. Rules**

* Logic for when to run each check
* Conditions for PASS/FAIL/REVIEW

### Example: API Call to Execute Workflow

```javascript theme={null}
// Execute a workflow on an entity
POST /v2/individuals/{entityId}/serviceprofiles/DEFAULT/workflows/Standard-KYC-AU/execute

// Response
{
  "requestId": "req-123",
  "workflowResult": {
    "workflowName": "Standard-KYC-AU",
    "workflowExecutionId": "exec-456",
    "status": "PASS",
    "steps": {
      "passed": ["START", "MATCHLIST", "KYC", "IDV", "AML", "DECISION", "FINISH"],
      "failed": [],
      "incomplete": []
    }
  }
}
```

***

## What is a OneSDK Flow ID?

### Definition

A OneSDK Flow ID is a pre-configured user interface flow that guides users through data collection. It's the "front-end" experience that collects the information needed for verification.

**Important:** OneSDK Flow IDs are separate from workflows. The flow collects data, then a workflow verifies that data.

### Available Flow IDs

| Flow ID                 | Purpose              | What It Collects                                        | When to Use                                          |
| :---------------------- | :------------------- | :------------------------------------------------------ | :--------------------------------------------------- |
| `idv`                   | Complete IDV flow    | Document photos + selfie + biometrics                   | Full identity verification with document and face    |
| `idv_review`            | IDV with user review | Document photos + selfie + allows user to edit OCR data | When you want users to review/correct extracted data |
| `ocr_only`              | Document OCR only    | Document photos only (no biometrics)                    | When you only need document data extraction          |
| `manual_kyc`            | eKYC form only       | User manually enters personal details                   | When you don't need document capture                 |
| `doc_upload`            | Document attachment  | Document files (for business entities)                  | For KYB or supporting documents                      |
| `individual_doc_upload` | Document attachment  | Document files (for individuals)                        | For additional documents after initial verification  |

### How OneSDK Flows Work

```text theme={null}
User's Browser/App
       │
       │ 1. Request onboarding URL
       │
       ▼
Your Backend
       │
       │ 2. Call FrankieOne API
       │    POST /idv/v2/idvalidate/onboarding-url
       │    Body: { flowId: "idv", entityId: "..." }
       │
       ▼
FrankieOne API
       │
       │ 3. Returns URL
       │    { url: "https://hosted.frankieone.com/..." }
       │
       ▼
Your Backend
       │
       │ 4. Send URL to user
       │
       ▼
User's Browser/App
       │
       │ 5. User opens URL
       │    - Sees document capture screen
       │    - Takes photo of ID
       │    - Takes selfie
       │    - Reviews data
       │
       ▼
OneSDK (Hosted by FrankieOne)
       │
       │ 6. Data collected
       │    - Document images
       │    - Biometric data
       │    - User consent
       │
       ▼
FrankieOne Platform
       │
       │ 7. Webhook sent to your backend
       │    "IDV data captured"
       │
       ▼
Your Backend
       │
       │ 8. Execute workflow
       │    POST /v2/individuals/{entityId}/.../workflows/{workflowName}/execute
       │
       ▼
FrankieOne Platform
       │
       │ 9. Workflow runs (KYC, IDV, AML checks)
       │
       ▼
Your Backend
       │
       │ 10. Webhook sent
       │     "Workflow complete - PASS"
```

### Example: Using OneSDK Flow

```javascript theme={null}
// Step 1: Generate hosted OneSDK URL
const response = await fetch('https://api.frankie.one/idv/v2/idvalidate/onboarding-url', {
  method: 'POST',
  headers: {
    'api_key': YOUR_API_KEY,
    'X-Frankie-CustomerID': YOUR_CUSTOMER_ID,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    flowId: 'idv',  // ← This is the Flow ID
    entityId: 'entity-123',
    consent: true,
    sendSMS: true,
    phoneNumber: '+61412999999'
  })
});

const { url } = await response.json();

// Step 2: Send URL to user (via SMS, email, or display in app)
// User completes the flow at this URL

// Step 3: Receive webhook when user completes flow
// Step 4: Execute workflow to verify the collected data
```

***

## How They Work Together

### The Complete Flow

Let's walk through a real example: verifying a new customer in Australia.

**Scenario**

You're onboarding a new customer named Sarah. You need to:

* Collect her ID document and selfie
* Verify her identity details
* Screen her against watchlists

### Step-by-Step Process

**1. Create Entity**

```javascript theme={null}
// Your backend creates an entity
POST /v2/individuals
{
  "name": { "givenName": "Sarah", "familyName": "Smith" },
  "dateOfBirth": { "year": "1990", "month": "05", "day": "15" }
}

// Response
{
  "entityId": "entity-abc-123"
}
```

**2. Generate OneSDK URL with Flow ID**

```javascript theme={null}
// Your backend requests hosted OneSDK URL
POST /idv/v2/idvalidate/onboarding-url
{
  "flowId": "idv",  // ← Flow ID: Complete IDV flow
  "entityId": "entity-abc-123",
  "consent": true
}

// Response
{
  "url": "https://hosted.frankieone.com/onboarding/xyz789"
}
```

**3. User Completes OneSDK Flow**

Sarah opens the URL in her browser:

```text theme={null}
Screen 1: Welcome & Consent
  ↓
Screen 2: Select ID Type (Driver License)
  ↓
Screen 3: Capture Front of License
  ↓
Screen 4: Capture Back of License
  ↓
Screen 5: Review Extracted Data
  ↓
Screen 6: Take Selfie
  ↓
Screen 7: Liveness Check
  ↓
Screen 8: Complete
```

**4. OneSDK Sends Data to FrankieOne**

```text theme={null}
Data collected:
- Document images (front & back)
- Extracted data (name, DOB, license number)
- Selfie image
- Biometric data
- User consent
```

**5. Your Backend Receives Webhook**

```javascript theme={null}
// Webhook from FrankieOne
POST https://your-domain.com/webhook/req-123
{
  "function": "RESULTS_RETRIEVED",
  "entityId": "entity-abc-123",
  "message": "IDV results retrieved"
}
```

**6. Your Backend Executes Workflow**

```javascript theme={null}
// Now execute the workflow to verify the data
POST /v2/individuals/entity-abc-123/serviceprofiles/DEFAULT/workflows/Standard-KYC-AU/execute

// This workflow contains these checks:
// 1. MATCHLIST - Check internal blocklist
// 2. KYC - Verify name, DOB, address
// 3. IDV - Verify document authenticity & face match
// 4. AML - Screen watchlists
// 5. DECISION - Calculate final result
```

**7. Workflow Runs All Checks**

```text theme={null}
Check 1: MATCHLIST
  Result: CLEAR (not on blocklist)
  ↓
Check 2: KYC
  Result: MATCH (name & DOB verified)
  ↓
Check 3: IDV
  Result: PASS (document authentic, face matches)
  ↓
Check 4: AML
  Result: CLEAR (no watchlist hits)
  ↓
Check 5: DECISION
  Result: PASS (all checks passed)
```

**8. Your Backend Receives Final Webhook**

```javascript theme={null}
// Webhook from FrankieOne
POST https://your-domain.com/webhook/req-456
{
  "function": "WorkflowComplete",
  "entityId": "entity-abc-123",
  "workflowExecutionId": "exec-789",
  "overallStatus": "PASS"
}
```

**9. Your Backend Fetches Complete Results**

```javascript theme={null}
// Fetch full results
GET /v2/individuals/entity-abc-123/serviceprofiles/DEFAULT/workflows/Standard-KYC-AU/executions/exec-789

// Response
{
  "workflowResult": {
    "status": "PASS",
    "riskAssessment": { "riskLevel": "LOW" },
    "steps": {
      "passed": ["MATCHLIST", "KYC", "IDV", "AML", "DECISION"],
      "failed": []
    },
    "workflowStepResults": [
      {
        "stepName": "KYC",
        "result": "MATCH",
        "summary": { /* detailed KYC results */ }
      },
      {
        "stepName": "IDV",
        "result": "PASS",
        "summary": { /* detailed IDV results */ }
      },
      {
        "stepName": "AML",
        "result": "CLEAR",
        "summary": { /* detailed AML results */ }
      }
    ]
  }
}
```

**10. Your System Makes Decision**

```javascript theme={null}
// Your backend processes the result
if (workflowResult.status === "PASS") {
  // Approve Sarah's account
  await approveCustomer("entity-abc-123");
  await sendEmail(sarah.email, "Account approved!");
}
```

### Visual Summary

```mermaid theme={null}
sequenceDiagram
    participant App as Your System
    participant API as FrankieOne API
    participant SDK as OneSDK (Hosted)
    participant User as End User
    participant WH as Webhooks

    %% 1. Create entity
    App->>API: POST /v2/individuals
    API-->>App: entityId

    %% 2. Generate OneSDK URL
    App->>API: POST /idv/v2/idvalidate/onboarding-url
    Note right of App: flowId = "idv"
    API-->>App: Hosted OneSDK URL

    %% 3. User completes OneSDK flow
    App->>User: Redirect to OneSDK URL
    User->>SDK: Capture document & selfie
    SDK->>API: Submit IDV data

    %% 4. Webhook: IDV complete
    API-->>WH: RESULTS_RETRIEVED
    WH-->>App: Webhook received

    %% 5. Execute verification workflow
    App->>API: Execute workflow (Standard-KYC-AU)
    Note right of API: MATCHLIST → KYC → IDV → AML → DECISION
    API-->>App: requestId / executionId

    %% 6. Webhook: workflow complete
    API-->>WH: WorkflowComplete (PASS / FAIL / REVIEW)
    WH-->>App: Webhook received

    %% 7. Fetch full results
    App->>API: GET workflow execution results
    API-->>App: Full workflowResult

    %% 8. Final decision
    App->>App: Approve / Reject / Review

```

***

## V1 vs V2: Entity Profiles vs Workflows

### Understanding the Difference

FrankieOne has two API versions with different terminology:

| Concept              | V1 API (Legacy)          | V2 API (Current)           |
| :------------------- | :----------------------- | :------------------------- |
| Collection of checks | Entity Profile / Recipe  | Workflow                   |
| How to trigger       | Assign profile to entity | Execute workflow on entity |
| Result object        | `entityProfileResult`    | `workflowResult`           |
| Status field         | `actionRecommended`      | `status`                   |

### V1: Entity Profiles (Legacy)

In V1, you assign an "entity profile" (also called a "recipe") to an entity:

```javascript theme={null}
// V1 API
POST /compliance/v1.2/entity/check
{
  "entityId": "entity-123",
  "checkProfile": "KYC_PROFILE_AU"  // ← Entity Profile
}

// Response
{
  "entityProfileResult": {
    "actionRecommended": "PASS",  // ← V1 status field
    "checkResults": [
      { "checkType": "kyc", "result": "PASS" },
      { "checkType": "idv", "result": "PASS" },
      { "checkType": "aml", "result": "CLEAR" }
    ]
  }
}
```

**Key Points:**

* Entity profiles are assigned to entities
* Checks run automatically when profile is assigned
* Results in `entityProfileResult` object
* Status in `actionRecommended` field

### V2: Workflows (Current)

In V2, you execute a workflow on an entity:

```javascript theme={null}
// V2 API
POST /v2/individuals/entity-123/serviceprofiles/DEFAULT/workflows/Standard-KYC-AU/execute

// Response
{
  "workflowResult": {
    "status": "PASS",  // ← V2 status field
    "workflowStepResults": [
      { "stepName": "KYC", "result": "MATCH" },
      { "stepName": "IDV", "result": "PASS" },
      { "stepName": "AML", "result": "CLEAR" }
    ]
  }
}
```

**Key Points:**

* Workflows are executed on entities
* More explicit control over when checks run
* Results in `workflowResult` object
* Status in `status` field
* More detailed step-by-step results

### OneSDK Works with Both

**Important:** OneSDK Flow IDs work with both V1 and V2 APIs. The flow collects data, then you choose whether to use V1 entity profiles or V2 workflows to verify that data.

```text theme={null}
OneSDK Flow (idv)
       │
       │ Collects data
       │
       ▼
   Entity Data
       │
       ├─────────────────┬─────────────────┐
       │                 │                 │
       ▼                 ▼                 ▼
   V1 API            V2 API           Direct API
   (Entity Profile)  (Workflow)       (Manual checks)
```

***

## Common Scenarios

### Scenario 1: Simple KYC with Document Verification

**Goal:** Verify a customer's identity with document and selfie.

**Components:**

* OneSDK Flow ID: `idv`
* Workflow: `Standard-KYC-AU`
* Checks: KYC, IDV, AML

**Implementation:**

```javascript theme={null}
// 1. Create entity
const entity = await createEntity({ name, dob, address });

// 2. Generate OneSDK URL
const { url } = await generateOnboardingURL({
  flowId: 'idv',  // ← Document + selfie capture
  entityId: entity.entityId
});

// 3. Send URL to user
await sendSMS(user.phone, `Complete verification: ${url}`);

// 4. Wait for webhook (user completed flow)
// 5. Execute workflow
const result = await executeWorkflow({
  entityId: entity.entityId,
  workflowName: 'Standard-KYC-AU'  // ← Runs KYC, IDV, AML checks
});

// 6. Process result
if (result.status === 'PASS') {
  await approveCustomer(entity.entityId);
}
```

### Scenario 2: eKYC Only (No Documents)

**Goal:** Verify customer using only data sources, no document capture.

**Components:**

* OneSDK Flow ID: `manual_kyc`
* Workflow: `eKYC-Only-AU`
* Checks: KYC, AML (no IDV)

**Implementation:**

```javascript theme={null}
// 1. Create entity
const entity = await createEntity({ name, dob, address });

// 2. Generate OneSDK URL
const { url } = await generateOnboardingURL({
  flowId: 'manual_kyc',  // ← Form only, no document capture
  entityId: entity.entityId
});

// 3. User fills form
// 4. Execute workflow (no IDV check)
const result = await executeWorkflow({
  entityId: entity.entityId,
  workflowName: 'eKYC-Only-AU'  // ← Runs KYC, AML only
});
```

### Scenario 3: Document OCR Only

**Goal:** Extract data from document without biometric verification.

**Components:**

* OneSDK Flow ID: `ocr_only`
* Workflow: None (just data extraction)
* Checks: None initially

**Implementation:**

```javascript theme={null}
// 1. Create entity
const entity = await createEntity({ name });

// 2. Generate OneSDK URL
const { url } = await generateOnboardingURL({
  flowId: 'ocr_only',  // ← Document capture only, no selfie
  entityId: entity.entityId
});

// 3. User captures document
// 4. Receive webhook with OCR data
// 5. Review extracted data
// 6. Optionally execute workflow later
```

### Scenario 4: Re-verification

**Goal:** Re-verify an existing customer with updated documents.

**Components:**

* OneSDK Flow ID: `idv_review`
* Workflow: `Refresh-KYC-AU`
* Checks: IDV, AML (skip KYC if data unchanged)

**Implementation:**

```javascript theme={null}
// 1. Entity already exists
const entityId = 'existing-entity-123';

// 2. Generate OneSDK URL for re-verification
const { url } = await generateOnboardingURL({
  flowId: 'idv_review',  // ← Allows user to review/edit data
  entityId: entityId
});

// 3. User updates document
// 4. Execute refresh workflow
const result = await executeWorkflow({
  entityId: entityId,
  workflowName: 'Refresh-KYC-AU'  // ← Re-runs relevant checks
});
```

### Scenario 5: Business Verification (KYB)

**Goal:** Verify a business entity with company documents.

**Components:**

* OneSDK Flow ID: `doc_upload`
* Workflow: `Standard-KYB-AU`
* Checks: Company registry, AML, UBO verification

**Implementation:**

```javascript theme={null}
// 1. Create organization entity
const org = await createOrganization({
  name: 'Acme Corp',
  registrationNumber: '123456789'
});

// 2. Generate OneSDK URL for document upload
const { url } = await generateOnboardingURL({
  flowId: 'doc_upload',  // ← Business document upload
  entityId: org.entityId
});

// 3. User uploads company documents
// 4. Execute KYB workflow
const result = await executeWorkflow({
  entityId: org.entityId,
  workflowName: 'Standard-KYB-AU'  // ← Runs KYB checks
});
```

***

## FAQs

### Q: Do I need to use OneSDK to use workflows?

**A:** No. OneSDK is optional. You can:

* Use OneSDK to collect data (easier, pre-built UI)
* Build your own UI and send data via API
* Use a combination (OneSDK for documents, your UI for forms)

### Q: Can I use multiple workflows on the same entity?

**A:** Yes. You can execute different workflows at different times:

* Initial onboarding: `Standard-KYC-AU`
* Ongoing monitoring: `Monitoring-AML-AU`
* Re-verification: `Refresh-KYC-AU`

### Q: What's the difference between a workflow and a check?

**A:** A workflow contains multiple checks.

* **Check** = Single verification task (e.g., "verify document")
* **Workflow** = Collection of checks in a specific order (e.g., "KYC → IDV → AML")

### Q: Can I customize workflows?

**A:** Yes, but workflows are configured by FrankieOne. Contact your FrankieOne representative to:

* Create custom workflows
* Modify existing workflows
* Add/remove checks
* Change check order or conditions

### Q: What happens if a check fails in a workflow?

**A:** It depends on the workflow configuration. Common behaviors:

* Critical check fails → Workflow stops, returns FAIL
* Non-critical check fails → Workflow continues, returns REVIEW
* Optional check fails → Workflow continues, may still PASS

### Q: Can I run individual checks without a workflow?

**A:** In V1, yes. In V2, checks are always part of workflows.

* **V1:** You can run individual checks via API
* **V2:** Checks are organized into workflows (recommended approach)

### Q: How do I know which OneSDK Flow ID to use?

**A:** Choose based on what data you need:

| Need                    | Flow ID                                 |
| :---------------------- | :-------------------------------------- |
| Document + biometrics   | `idv`                                   |
| Document only           | `ocr_only`                              |
| Form data only          | `manual_kyc`                            |
| User to review OCR data | `idv_review`                            |
| Upload documents        | `doc_upload` or `individual_doc_upload` |

### Q: Can I use the same workflow for different countries?

**A:** Usually no. Workflows are typically country-specific because:

* Different data sources per country
* Different regulatory requirements
* Different document types

You'll typically have:

* `Standard-KYC-AU` (Australia)
* `Standard-KYC-US` (United States)
* `Standard-KYC-UK` (United Kingdom)

### Q: What's the relationship between OneSDK Flow ID and workflow?

**A:** They're independent but complementary:

```text theme={null}
OneSDK Flow ID (Frontend)
    ↓
Collects Data
    ↓
Workflow (Backend)
    ↓
Verifies Data
```

* **Flow ID** = How you collect data from the user
* **Workflow** = How you verify that data

You can use any Flow ID with any workflow, as long as the workflow has the data it needs.

### Q: Can I change the workflow after it's started?

**A:** No, but you can execute a different workflow. Once a workflow execution starts, it runs to completion. If you need different checks, execute a new workflow.

### Q: How do I test workflows?

**A:** Use the UAT environment:

* FrankieOne provides UAT credentials
* Execute workflows in UAT
* Use test data (FrankieOne provides test entities)
* Review results in UAT Portal
* Once satisfied, move to production

### Q: What if I need a check that's not in my workflow?

**A:** Contact FrankieOne to add it. Your FrankieOne representative can:

* Add checks to existing workflows
* Create new workflows with different checks
* Configure check parameters

***

## Summary

### Key Takeaways

**Check** = Single verification task

* Example: KYC check, IDV check, AML check

**Workflow** = Collection of checks that run together

* Example: `Standard-KYC-AU` workflow contains KYC + IDV + AML checks

**OneSDK Flow ID** = User interface for data collection

* Example: `idv` flow shows document capture + selfie screens

**They work together:**

* OneSDK Flow → Collects Data → Workflow → Runs Checks → Result

**V1 vs V2:**

* V1: Entity Profiles (legacy)
* V2: Workflows (current, recommended)

***

## Next Steps

* Identify your use case: What data do you need to collect? What checks do you need to run?
* Choose your components: Select appropriate OneSDK Flow ID and identify required workflow
* Contact FrankieOne: Discuss your requirements, get workflows configured, receive UAT credentials
* Implement: Integrate OneSDK (if using), integrate API for workflow execution, test in UAT, deploy to production

***

## Need Help?

Contact your FrankieOne representative if you:

* Need help choosing the right workflow
* Want to customize workflows
* Need to add new checks
* Have questions about OneSDK Flow IDs
* Need implementation support

**Resources:**

* API Documentation: [https://docs.frankieone.com](https://docs.frankieone.com)
* OneSDK Documentation: [https://docs.frankieone.com/docs/about-onesdk](https://docs.frankieone.com/docs/about-onesdk)
* Support: Contact your FrankieOne representative


# Generate Hosted URL
Source: https://docs.frankieone.com/api-reference/hosted-url/generate-hosted-url

/specs/fc-kyb-facade-bundled_generated.yaml post /v2/organizations/hostedUrl
Generate a hosted URL for onboarding new organization.