International Documents | FrankieOne

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)

Example Document Structure

1 {
2   "document": {
3     "class": "IDENTITY",
4     "documentId": "92de15f64-5717-4562-b3fc-2c963f6665a7",
5     "primaryIdentifier": "000734130", // ID Number
6     "secondaryIdentifier": "q12313124", // Laser Code or File Number when applicable
7     "type": "NATIONAL_ID",
8     "country": "CHN",
9     },
10     "supplementaryData": {
11       "type": "NATIONAL_ID",
12       "homeCountryFullName": "张伟明", // Full name in Foreign characters when applicable
13       "paternalFamilyName": "MENDOZA", // LATAM IDs when applicable
14       "maternalFamilyName": "GARCIA" // LATAM IDs when applicable
15   }
16 }

Name Handling Guidelines:

Pinyin Name Format

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

Chinese Name Format

1 {
2   "document": {
3     "supplementaryData": {
4       "homeCountryFullName": "张伟明", // Full name in Chinese characters 
5     }
6   }
7 }

LATAM Name Format

1 {
2   "document": {
3     "supplementaryData": {
4       "paternalFamilyName": "MENDOZA", // Paternal family name
5       "maternalFamilyName": "GARCIA"   // Maternal family name
6     }
7   }
8 }

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.

Example Document Structure

1 {
2   "document": {
3     "class": "IDENTITY", // Document class, always "IDENTITY" for passports
4     "expiryDate": {
5       "year": "1990", // Expiry year as four digits
6       "month": "03", // Expiry month as two digits
7       "day": "27", // Expiry day as two digits
8       "unstructured": "1990-03-27", // Expiry date in ISO format (YYYY-MM-DD)
9       "type": "GREGORIAN" // Calendar type, typically "GREGORIAN"
10     },
11     "primaryIdentifier": "000734130", // Passport number, include all leading zeros exactly as shown
12     "secondaryIdentifier": "q12313124", // Optional. File number, laser code, or other secondary identifier if present
13     "type": "PASSPORT", // Document type, must be "PASSPORT"
14     "country": "AUS", // Country of issuance, ISO-3166-alpha3 code (e.g., "AUS" for Australia)
15     "supplementaryData": {
16       "type": "PASSPORT", // Repeats document type for supplementary data
17       "homeCountryFullName": "张伟明" // Full name in native script, if applicable (e.g., Chinese characters)
18     }
19   }
20 }

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.