> ## 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 ID Documents

## Chinese National ID Card (身份证)

<Info>
  The Chinese National ID Card (身份证) is the primary identification document
  for Chinese citizens. This guide explains how to properly verify these
  documents in your application.
</Info>

### Required Fields

<AccordionGroup>
  <Accordion title="Name Requirements">
    Two name formats are required:

    * **Pinyin Name:** Romanized version using English alphabet
      * Family name
      * Given name (can include middle name)
    * **Chinese Name:** Full name in Chinese characters
          <Callout icon="star" color="#3DD892" iconType="regular">
            The Chinese name supports UTF-8 characters and can be provided in either `extraData` or `name.DisplayName`
          </Callout>
  </Accordion>

  <Accordion title="Basic Information">
    * **Date of Birth:** Must be in `YYYY-MM-DD` format
    * **ID Type:** Must be `NATIONAL_ID`
    * **Country:** Must be `CHN`
    * **Document Number:** The full ID number in `idNumber` field
  </Accordion>
</AccordionGroup>

<Panel>
  <CodeGroup>
    ```json Example Request theme={null}
    {
      "identityDocs": [
        {
          "idType": "NATIONAL_ID",
          "country": "CHN",
          "idNumber": "123456789012345678",
          "name": {
            "familyName": "ZHANG",
            "givenName": "WEIMING",
            "displayName": "张伟明"
          },
          "extraData": [
            {
              "kvpKey": "home_country_fullname",
              "kvpValue": "张伟明"
            }
          ]
        }
      ]
    }
    ```
  </CodeGroup>
</Panel>

<Callout icon="bell" color="#FFCA16" iconType="regular">
  Common validation issues to avoid: - Incorrect name format in either Pinyin or
  Chinese characters - Missing or improperly formatted date of birth - Invalid
  ID number format
</Callout>

### Name Handling Guidelines

<Tabs>
  <Tab title="Pinyin Name Format">
    ```json theme={null}
    {
      "familyName": "ZHANG",     // Family name in CAPS
      "givenName": "WEIMING"     // Given and middle name can be combined
    }
    ```
  </Tab>

  <Tab title="Chinese Name Format">
    ```json theme={null}
    {
      "kvpKey": "home_country_fullname",
      "kvpValue": "张伟明"        // Full name in Chinese characters
    }
    ```
  </Tab>
</Tabs>

<Callout icon="star" color="#3DD892" iconType="regular">
  ##### Name Best Practices

  When handling Chinese names:

  1. Always provide both Pinyin and Chinese character versions
  2. Maintain correct character order in both formats
  3. Use uppercase for Pinyin names
  4. Ensure UTF-8 encoding for Chinese characters
</Callout>

<Info title="Document Number Verification">
  The Chinese National ID number contains encoded information including:

  * Region code
  * Birth date
  * Sequence number
  * Checksum digit

  Ensure the full number is provided without spaces or special characters.
</Info>