> ## 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.
# Chinese Documents
The FrankieOne KYC v2 API supports some Chinese documents for identity verification. This guide provides details on how to handle these documents effectively.
## Supported Chinese Documents
The FrankieOne KYC v2 API supports the following Chinese documents:
| Document | Code |
| :---------- | :------------ |
| National ID | `NATIONAL_ID` |
***
### Chinese National ID Card (身份证)
Chinese National ID Cards (身份证) are official identification documents issued by the Chinese government that confirm an individual's identity and citizenship. They include personal details such as the individual's name, date of birth, ID card number, and expiration date.
**Required Fields**
| Field Name | Field | Notes |
| ------------- | --------------------- | ------------------------------------------------------------------------------------- |
| Document Type | `type` | Must be `NATIONAL_ID`. |
| Country | `country` | Must be `CHN` (China). |
| Date of Birth | `dateOfBirth` | Format: `YYYY-MM-DD`. |
| Family Name | `familyName` | Pinyin family name in uppercase (e.g., `ZHANG`). |
| Given Name | `givenName` | Pinyin given name (may include middle name), in uppercase (e.g., `WEIMING`). |
| Chinese Name | `homeCountryFullName` | Full name in Chinese characters, provided in `supplementaryData.homeCountryFullName`. |
* Always provide both Pinyin and Chinese character versions of the name.
* Maintain correct character order in both formats.
* Use uppercase for all Pinyin names.
* Ensure UTF-8 encoding for Chinese characters.
* All fields must be completed accurately to avoid validation errors.
| Field Name | Field | Notes |
| ----------- | ------------------- | -------------------------------------------------------- |
| ID Number | `primaryIdentifier` | 18-digit ID number, no spaces or special characters. |
| Document ID | `documentId` | Unique identifier for the document in FrankieOne system. |
The `documentId` uniquely identifies the document record in our system.
The `primaryIdentifier` is the official government-issued ID number.
**Name Handling Guidelines:**
Provide the applicant's name in Pinyin using uppercase letters, matching the order on the ID card.
```json theme={null}
{
"familyName": "ZHANG", // Family name in uppercase Pinyin
"givenName": "WEIMING" // Given name (and middle name, if any) in uppercase Pinyin
}
```
* Use uppercase letters for all Pinyin names.
* Ensure the order and spelling match the official ID card.
* Do not include spaces or special characters.
Provide the full name in Chinese characters exactly as it appears on the ID card, using UTF-8 encoding.
```json theme={null}
{
"supplementaryData": {
"homeCountryFullName": "张伟明" // Full name in Chinese characters
}
}
```
* The Chinese name must match the ID card precisely, including character order.
* Place this value in `supplementaryData.homeCountryFullName`.
* Ensure correct encoding to avoid data loss.
***
### Chinese Name Transliteration Check (Name Validation)
For enhanced identity verification, FrankieOne offers a name transliteration check. This feature verifies that an applicant's English/Pinyin name (e.g., "Wei Wang") is the correct transliteration of their name written in Chinese characters (e.g., "王伟"). This check, historically known as `namev` in v1, uses a specialized third-party service to ensure the two name versions are a plausible match, helping to reduce identity fraud.
**How It Works & Configuration**
The transliteration check is not enabled by default. It must be configured in your workflow by the FrankieOne team as a distinct step called **`NAME_VALIDATION`**.
1. The **anglicized name** is taken from the primary `individual.name` object (`givenName` and `familyName`).
2. The **native script name** is taken from the `document.supplementaryData.homeCountryFullName` field for the Chinese `NATIONAL_ID`.
3. The `NAME_VALIDATION` step in the workflow sends these two names to the transliteration service.
4. If the native script name (`homeCountryFullName`) is not provided, the step will be skipped and the result will be `SKIPPED`.
To enable this feature, please contact your FrankieOne representative and request the `NAME_VALIDATION` step be added to your KYC workflow.
**Example Result**
When the `NAME_VALIDATION` step is executed, a `workflowStepResult` is added to the API response. The outcome is detailed within the `processResult` object, which will have a result of `MATCH` or `NO_MATCH`.
```json theme={null}
{
"workflowStepResults": [
{
"stepName": "NAME_VALIDATION",
"result": "SUCCESS",
"processResults": [
{
"provider": "AsiaConnector",
"objectType": "NAME",
"class": "KYC",
"result": "MATCH",
"checkDate": "2025-10-15T07:40:57.000Z",
"data": {
"reference": "av-ref-12345",
"message": "Name transliteration check passed."
}
}
]
}
]
}
```
***
**Example Document Structure**
```json theme={null}
{
"document": {
"class": "IDENTITY",
"documentId": "92de15f64-5717-4562-b3fc-2c963f6665a7",
"primaryIdentifier": "110105199003077341",
"type": "NATIONAL_ID",
"country": "CHN"
},
"supplementaryData": {
"type": "NATIONAL_ID",
"homeCountryFullName": "张伟明"
}
}
```
##### Important Considerations for National ID
The Chinese National ID number contains encoded information including region code, birth date, sequence number, and checksum digit. Ensure the full 18-digit number is provided without spaces or special characters.
**Common validation issues to avoid:**
* Using incorrect order or casing for Pinyin names
* Omitting the Chinese character version of the name
* Missing or incorrectly formatted date of birth (`YYYY-MM-DD`)
* Providing an invalid or incomplete ID number (must be 18 digits)