> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/application/image-vision/id-card-recognition.md). # ID Card Recognition When enterprises process identity verification, account opening, onboarding, and other workflows, they often need to manually enter names, ID numbers, addresses, and other information from documents one by one — a process that is both time-consuming and error-prone. With MaiAgent's multimodal AI assistant, users simply upload a document photo, and the system automatically recognizes and outputs structured JSON data that can be directly integrated with downstream business systems. Compared to traditional OCR solutions, MaiAgent combines the multimodal capabilities of large language models with the following advantages: | | Traditional OCR Engine | MaiAgent Multimodal AI | | --------------------- | ---------------------------------------------------- | -------------------------------------------------------------- | | Layout Adaptability | Requires designing a template for each document type | Automatically understands different document layouts | | Front/Back Processing | Requires separate processing and manual matching | Can recognize both front and back from a single image | | Field Expansion | Requires code modifications | Simply modify the JSON Schema | | Deployment Cost | Self-hosted OCR service or purchased license | Platform configuration, no coding required | | Error Handling | Returns raw text, requires post-processing | AI understands semantics and automatically corrects formatting | ## Use Cases * **Banking Account Opening**: Customer uploads ID card, automatically extracting name, ID number, and other information to fill in the account opening form * **HR Onboarding Process**: New employees upload documents, and the system automatically creates records * **Medical Registration**: Patients upload health insurance card or ID card, automatically filling in basic information * **Government Agency Counter Service**: Citizens present documents for instant recognition and auto-population of application forms ## Solution Architecture ```mermaid graph LR User -->|Upload Document Image| AI-Assistant["Document OCR Recognition Assistant
(Multimodal LLM)"] AI-Assistant -->|Recognition + Structuring| JSON-Output["JSON Schema Output"] JSON-Output --> WebChat["Web Chat Real-Time Display"] JSON-Output --> API["API Integration with Business Systems"] AI-Assistant -.->|Role Instructions| Recognition-Rules["Recognition Rules
Front/Back Field Mapping"] AI-Assistant -.->|Output Format| Schema["JSON Schema
9 Standard Fields"] ``` ## Setup Steps ### Step 1: Create an AI Assistant 1. Left sidebar → **AI Features** → **AI Assistants** 2. Click **Create AI Assistant** in the upper right corner 3. Fill in basic settings: | Field | Value | | ------------------------ | ----------------------------------------------- | | **Assistant Name** | Document OCR Recognition Assistant | | **Large Language Model** | Gemini 3.1 Flash-Lite (must support multimodal) | {% hint style="info" %} When selecting a large language model, make sure the model supports **multimodal** (image input), such as the Gemini series. If you select a text-only model, it will not be able to recognize image content. {% endhint %} ### Step 2: Set Response Mode and JSON Schema Switch to the **Response Mode Settings** tab: | Field | Value | | ----------------- | ------------------ | | **Response Mode** | RAG Q\&A | | **Output Format** | Output JSON Format | After selecting **Output JSON Format**, enter the following content in the JSON Schema field below: ```json { "type": "object", "properties": { "document_type": { "type": "string", "description": "Document type, such as ROC National ID Card, driver's license, passport, health insurance card, residence permit, etc." }, "name": { "type": "string", "description": "Full name of the document holder, read from the name field on the front" }, "gender": { "type": "string", "enum": ["Male", "Female"], "description": "Gender" }, "date_of_birth": { "type": "string", "description": "Date of birth, in ROC calendar year format" }, "military_service": { "type": ["string", "null"], "description": "Military service status, such as exempt, completed, pending, alternative service. Null for females or if field is absent" }, "place_of_birth": { "type": ["string", "null"], "description": "Place of birth, read from the back" }, "id_number": { "type": "string", "description": "National ID number, 1 English letter + 9 digits" }, "expiry_or_issue_date": { "type": ["string", "null"], "description": "Issue date or expiry date, in ROC calendar year format" }, "address": { "type": ["string", "null"], "description": "Full address, read from the address field on the back, including city, district, borough, neighborhood, road, section, lane, alley, number, and floor" } }, "required": [ "document_type", "name", "gender", "date_of_birth", "military_service", "place_of_birth", "id_number", "expiry_or_issue_date", "address" ] } ```

JSON Schema output format settings

### Step 3: Write Role Instructions In the **Role Instructions** section on the same tab, enter the following content: ``` You are a professional document OCR recognition assistant. Users will upload document images, and you must carefully recognize all text in the image and extract key information. ## Most Important: Carefully Scan All Areas of the Entire Image ⚠️ Users often photograph both the front and back of a document in the same image (side by side or stacked vertically). You must: 1. First scan the entire image to identify how many document faces are present (may be 1 or 2) 2. Separately recognize the text in each area 3. Merge the front and back information into the results Never say "back not provided" or "information not in the image" unless you have confirmed that the information truly cannot be found in any area of the entire image. ## ROC National ID Card Field Locations ### Front (has national flag, photo) - "Name": Next to the photo, this is the document holder's own name - "Date of Birth": ROC Year XX Month XX Day XX - "Gender": Marked as "Male" or "Female" - "ID Number": At the bottom, 1 uppercase English letter + 9 digits - "Issue Date": Bottom left ### Back (has father/mother/spouse fields, background is usually darker) - "Father" "Mother": Parents' names (not the document holder) - "Spouse": Spouse's name - "Military Service": Military service status - "Place of Birth": e.g., "Taipei City", "New Taipei City" - "Address": Full registered address ## Recognition Rules 1. Document Type: Determine based on appearance 2. Name: Must be read from the "Name" field on the front; do not read the father/mother/spouse names from the back 3. Gender: Read from the front 4. Date of Birth: Read from the front, in ROC calendar year format 5. Military Service: Read from the back. Females typically have no military service; fill null 6. Place of Birth: Read from the back 7. ID Number: Read from the bottom of the front, carefully recognizing each character 8. Issue Date: Read from the "Issue Date" field on the front 9. Address: Read from the "Address" field on the back, completely including city, district, borough, neighborhood, road, section, lane, alley, number, and floor ## Output Notes - Fill null for fields that cannot be recognized - All recognition results must be faithful to the image content; do not guess or fabricate ```

Role instructions settings

Click **Save** to complete the assistant setup. ### Step 4: Test Recognition Results 1. Enter the assistant's **Test Conversation** 2. Upload a document image (can include both front and back) 3. Enter "Please recognize this document image" 4. Verify the returned JSON structure and field content are correct ## Usage Example Upload an image containing both the front and back of an ID card, and the AI assistant will automatically recognize and output structured JSON: ```json { "document_type": "ROC National ID Card", "name": "陳筱玲", "gender": "Female", "date_of_birth": "ROC Year 57, June 5", "military_service": null, "place_of_birth": "Taipei City", "id_number": "A234567890", "expiry_or_issue_date": "ROC Year 94, July 1", "address": "No. 218, Aly. 165, Ln. 283, Sec. 6, Minquan E. Rd., Huzhou Borough, Neihu Dist., Taipei City" } ``` {% hint style="warning" %} Recognition accuracy depends on image quality. Ensure adequate lighting when taking photos, avoid glare, and lay the document flat for photography. If photographing both front and back simultaneously, arrange them side by side or stacked vertically. {% endhint %} ## JSON Output Field Descriptions | Field | Type | Source | Description | | ---------------------- | ----------- | ------ | --------------------------------- | | `document_type` | string | Front | Document type | | `name` | string | Front | Document holder's name | | `gender` | string | Front | Gender (Male/Female) | | `date_of_birth` | string | Front | Date of birth (ROC calendar year) | | `military_service` | string/null | Back | Military service status | | `place_of_birth` | string/null | Back | Place of birth | | `id_number` | string | Front | National ID number | | `expiry_or_issue_date` | string/null | Front | Issue date | | `address` | string/null | Back | Full address | ## API Integration This assistant can be integrated with business systems via the MaiAgent API to automate the document recognition process. ### Call Flow ```mermaid sequenceDiagram participant Client as Business System participant API as MaiAgent API participant Bot as OCR Recognition Assistant Client->>API: POST /attachments-upload/
Upload Document Image API-->>Client: Return Attachment ID Client->>API: POST /chatbots/{id}/completions/
Include Attachment ID API->>Bot: Image Recognition Bot-->>API: JSON Structured Result API-->>Client: Return OCR JSON ``` ### Step 1: Upload Image to Get Attachment ID ```bash curl -X POST \ -H "Authorization: Api-Key YOUR_API_KEY" \ -F "file=@/path/to/id_card.jpeg" \ "https://api.maiagent.ai/api/v1/attachments-upload/" ``` Note the `id`, `type`, `file`, and `filename` fields from the response — they will be used in the next step. ### Step 2: Call the Assistant for Recognition ```bash curl -X POST \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": { "content": "Please recognize this document image", "attachments": [{ "id": "{id from Step 1}", "type": "image", "file": "{file URL from Step 1}", "filename": "id_card.jpeg" }] }, "isStreaming": false }' \ "https://api.maiagent.ai/api/v1/chatbots/{assistant_id}/completions/" ``` ### Step 3: Parse the Response The `content` field in the response contains the recognition result in JSON format: **Python** ```python import json ocr_result = json.loads(response["content"]) print(ocr_result["name"]) # 陳筱玲 print(ocr_result["id_number"]) # A234567890 print(ocr_result["address"]) # 臺北市內湖區葫洲里1鄰民權東路六段283巷165弄218號 ``` **JavaScript** ```javascript const ocrResult = JSON.parse(response.content); console.log(ocrResult.name); // 陳筱玲 console.log(ocrResult.id_number); // A234567890 console.log(ocrResult.address); // 臺北市內湖區葫洲里1鄰民權東路六段283巷165弄218號 ``` {% hint style="info" %} For complete example code, refer to [Playma-Co-Ltd/maiagent-api-examples](https://github.com/Playma-Co-Ltd/maiagent-api-examples). {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/application/image-vision/id-card-recognition.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.