International Documents

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

Basic Information
ID Details

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)

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.

Example Document Structure

{
  "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:

Pinyin Name Format

{
  "familyName": "ZHANG",     // Family name in CAPS
  "givenName": "WEIMING"     // Given and middle name can be combined
}

Chinese Name Format

{
  "document": {
    "supplementaryData": {
      "homeCountryFullName": "张伟明", // Full name in Chinese characters 
    }
  }
}

LATAM Name Format

{
  "document": {
    "supplementaryData": {
      "paternalFamilyName": "MENDOZA", // Paternal family name
      "maternalFamilyName": "GARCIA"   // Maternal family name
    }
  }
}

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

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

Basic Information
Passport Details

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.

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.

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]

Example Document Structure

{
  "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)
    }
  }
}

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.

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)

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.

​Supported International Documents

​International National ID Card (INE/IFE)