Skip to main content
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:
DocumentCode
National IDNATIONAL_ID
PassportPASSPORT

​
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

Field NameFieldNotes
CountrycountryMust be set to the ISO-3166-alpha3 country code (e.g. CHN, MEX)
Date of BirthdateOfBirthFormat must be YYYY-MM-DD
Document TypetypeMust be NATIONAL_ID
NamenameMust match the National ID exactly (Given name, Middle name, Family name, and any others)
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: 
{
  "familyName": "ZHANG",     // Family name in CAPS
  "givenName": "WEIMING"     // Given and middle name can be combined
}

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

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

Field NameFieldNotes
CountrycountryMust be the ISO-3166-alpha3 country code of passport issuance (e.g., AUS, GBR).
Date of BirthdateOfBirthFormat: YYYY-MM-DD. Must match the date of birth on the passport.
Document TypetypeMust be PASSPORT.
NamenameEnter the full name exactly as it appears on the passport, including all given, middle, and family names.
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.