Global KYC

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.

$
POST /v2/individuals

$
POST /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/execute

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.

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.

1
{
2
  "individual": {
3
    "name": {
4
      "givenName": "Jane",
5
      "familyName": "Citizen"
6
    },
7
    "dateOfBirth": {
8
      "year": "1990",
9
      "month": "01",
10
      "day": "15"
11
    },
12
    "documents": {
13
      "IDENTITY": [
14
        {
15
          "type": "PASSPORT",
16
          "country": "AUS",
17
          "primaryIdentifier": "E1234567"
18
        }
19
      ]
20
    }
21
  }
22
}

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.

1
{
2
  "individual": {
3
    "name": {
4
      "givenName": "John",
5
      "familyName": "Smith"
6
    },
7
    "dateOfBirth": {
8
      "year": "1985",
9
      "month": "05",
10
      "day": "20"
11
    },
12
    "documents": {
13
      "IDENTITY": [
14
        {
15
          "type": "DRIVERS_LICENSE",
16
          "country": "AUS",
17
          "subdivision": "NSW",
18
          "primaryIdentifier": "98765432",
19
          "secondaryIdentifier": "1234567890"
20
        }
21
      ]
22
    }
23
  }
24
}

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.

1
{
2
  "individual": {
3
    "name": {
4
      "givenName": "Jane",
5
      "familyName": "Citizen"
6
    },
7
    "documents": {
8
      "IDENTITY": [
9
        {
10
          "type": "MARRIAGE_CERT",
11
          "country": "AUS",
12
          "subdivision": "VIC",
13
          "primaryIdentifier": "98765/1990",
14
          "supplementaryData": {
15
            "type": "MARRIAGE_CERT",
16
            "marriageDate": "1990-12-15",
17
            "partner2GivenName": "John",
18
            "partner2FamilyName": "Doe"
19
          }
20
        }
21
      ]
22
    }
23
  }
24
}

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

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.