> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**

<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" color="#FFCA16" iconType="regular">
  ##### 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" color="#3DD892" iconType="regular">
  ##### 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" color="#FFCA16" iconType="regular">
  ##### 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>