> For the complete documentation index, see [llms.txt](https://docs.fill-easy.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fill-easy.com/kyc_agent.md). # KYC Agent The KYC agent lets you run **China KYC checks by sending an email**. No portal, no API integration: you email the details (or attach a spreadsheet) to a dedicated address, and the agent reads your request, runs the checks through Fill-Easy, and emails the results back into the same thread. There are two ways to use it: | Mode | When to use it | What you send | What you get back | | --------------- | ------------------- | --------------------------------- | --------------------------------------------------------------- | | **Free-text** | One or a few people | Details typed in the email body | One PDF report per person, emailed as each completes | | **Excel batch** | Many people at once | An `.xlsx` spreadsheet attachment | One results spreadsheet, returned when the whole batch finishes | *** ## 1. Where to send Send your request to the KYC address for your environment: | Environment | Send to | | -------------- | ------------------------------- | | **Production** | `kyc@ses.fill-easy.com` | | Staging | `staging-kyc@ses.fill-easy.com` | | Dev | `dev-kyc@ses.fill-easy.com` | Replies come back from `kyc@fill-easy.com` (prod). Just **reply in the same thread** to add more emails to the same request — the agent reads the whole thread, oldest message first. {% hint style="warning" %} **Email security.** Your message must pass SPF and DMARC checks (these are normal for mail sent from a real corporate mailbox). If it doesn't, the agent still processes the request but adds a security warning to every reply, so downstream readers know the sender couldn't be verified. {% endhint %} *** ## 2. Authentication The agent talks to Fill-Easy on your behalf, so your organization must be **onboarded** before you can use it. Once you're onboarded, there's nothing extra to do — just send from your registered work email address and the agent authenticates your request automatically. If your organization isn't onboarded yet, you'll get a processing reply while support follows up. To get set up, contact your Fill-Easy representative. *** ## 3. Free-text mode — checking one or a few people Just write the person's details in the email body. Plain text is fine. Example: ``` To: kyc@ses.fill-easy.com Subject: KYC check — 张三 Please run a bank 3-factor check (KYC8.2.1) for: 姓名: 张三 身份证号: 11010119900307XXXX 手机号: 13800138000 银行卡号: 6214 8679 9935 327 ``` You can describe **several people in one email** — put each person's details together and the agent emits one request per person. ### Field rules The agent only accepts values it can actually read from your email. It will **never guess or derive** a value (for example, it will not invent an ID issue date from the digits inside an ID number). Anything that doesn't match the expected format is dropped and noted back to you. | Field | Format the agent expects | | --------------------------- | ------------------------------------------------------------------------------------ | | **Name** (姓名) | Chinese characters only. English/Pinyin names are not accepted. | | **ID number** (身份证号) | 18 characters — 17 digits plus a final digit or `X`. | | **ID issue date** | `YYYYMMDD` (8 digits). Must be supplied **together** with the expiry date. | | **ID expiry date** | `YYYYMMDD`, or the literal `长期` for "long-term". Must be paired with the issue date. | | **Mobile** (手机号) | 11 digits, starting `13`–`19`. | | **Bank card number** (银行卡号) | Digits. Spaces and dashes are fine — they're stripped automatically. | | **Address(es)** | City + address in Chinese, optionally tagged as common / work / residential. | {% hint style="info" %} Dates in other formats (e.g. `2020-01-15`) are normalized to `YYYYMMDD` automatically. Spaces and dashes in card / mobile / ID numbers are removed for you. {% endhint %} ### Choosing which checks to run Mention the product code(s) you want, e.g. **"run KYC8.2.1"** or **"KYC2, KYC11"**. See the [product catalogue](#5-kyc-product-catalogue) below. {% hint style="success" %} **Tip — always name the products you want.** If you don't specify any products, the backend runs its full default set of checks, which costs more. Listing the products keeps the run (and the bill) to exactly what you need. {% endhint %} *** ## 4. Excel batch mode — checking many people For larger volumes, attach a single `.xlsx` spreadsheet. The agent switches to batch mode automatically when it sees an Excel attachment. Need a starting point? Download the [KYC template spreadsheet](https://corpverify-samples.s3.us-east-1.amazonaws.com/KYC-Template/KYC_template.xlsx) and add one row per person — a fixed template isn't required (the agent reads your headers), but it's a convenient place to start. ### How to lay out the sheet * One **person per row**. * A **header row** describing each column. It does not have to be the first row — the agent locates it for you. * Columns for the fields you have: name, ID number, ID issue/expiry date, mobile, bank card number, and address columns. The same format rules as free-text mode apply. * A **"Requested Data Fields" / "所需數據字段" / "KYC Products"** column telling the agent which products to run for each row (e.g. `KYC8.1`, or `KYC8.1, KYC2`). The agent figures out which column is which from your headers — you don't need a fixed template. Encrypted (password-protected) workbooks are supported; the results come back encrypted the same way. ### What you get back You'll receive **one acknowledgement email** ("KYC batch received — N rows are being processed"), and then a single **results email** once every check in the batch has completed. The results email attaches **your original spreadsheet** with extra columns appended at the end: * One **`KYCx Result` column per requested product**, colour-coded by outcome: | Cell | Meaning | | ----------------------------- | ---------------------------------------------------------- | | 🟩 **Match** | The check matched. | | 🟥 **No Match** | The check returned a mismatch. | | ⬜ **Not Found** | No record found. | | ⬜ **Not Run** | Product wasn't run for this row. | | 🟨 **Error** / message | The row couldn't be dispatched, or an error occurred. | | 🟦 **Completed — see report** | Informational product — open the PDF for detail. | | 🟧 **Pending / Expired** | Not finished, or the result link expired before retrieval. | * A final **`KYC Status`** column. For completed rows this cell is a **clickable link to that person's full PDF report** (blue, underlined). Rows that couldn't be processed show the reason here instead. {% hint style="warning" %} **Result links are valid for 7 days**, and the underlying report files are deleted after 30 days — download anything you need to keep. {% endhint %} *** ## 5. KYC product catalogue Specify products by their code (the `KYC` prefix is optional — `KYC8.1` and `8.1` are the same), e.g. `KYC8.2.1` or `KYC2, KYC11`. The full list of products — every code, what each one checks, and the inputs it needs — is maintained in the [**KYC China product catalogue**](https://fill-easy.gitbook.io/testing/kyc-china). The agent accepts the same product numbers. A few agent-specific notes: * For a **bank check without a level** (just `KYC8`), the agent picks the strongest bank check your data supports — `8.3` if you supplied ID + mobile, `8.2.1` if just ID, otherwise `8.1`. * Some products (fraud risk, litigation, criminal risk, mobile location / address) are **informational** — they don't return a simple match/no-match; read the PDF report for the detail. * If you request a mix of supported and unsupported products, the supported ones still run and the rest are skipped (and noted in the reply). *** ## 6. What the replies look like 1. **Acknowledgement** — sent as soon as your request is accepted. * Free-text: *"N KYC PROCESSING"* listing each request and its ID. * Excel batch: *"KYC batch received — N rows are being processed."* 2. **Results** * Free-text: one ***ORDER SUCCESS*** email **per person**, with that person's PDF report attached, as each one completes. * Excel batch: a single ***KYC RESULTS*** email with the completed spreadsheet attached. All replies stay in your original email thread, so everything for one request is in one place. *** ## 7. Quick checklist * [ ] Sending to the correct address (`kyc@ses.fill-easy.com` for production). * [ ] Sending from your onboarded, registered work email address. * [ ] Names and addresses are in **Chinese characters**. * [ ] ID number is 18 characters; mobile is 11 digits; dates are `YYYYMMDD`. * [ ] ID issue and expiry dates supplied **together**, or not at all. * [ ] Requested products named explicitly (to control scope and cost). * [ ] For batch runs: one person per row, with a clear header row and a products column. *** ## 8. Troubleshooting | Symptom | Likely cause | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Reply says a field was "dropped" | The value didn't match the required format (e.g. a Pinyin name, an 11-digit ID, an unpaired date). Resend it in the correct format. | | "Security warning" on the reply | Your email failed SPF/DMARC. The request still ran; check with your mail admin if you want it to verify cleanly. | | Result cell shows **Expired** | The report wasn't retrieved before its link expired. Re-submit that row. | | Reply says you can't be authenticated | Your organization or sending address isn't onboarded yet. Contact your Fill-Easy representative. | | Nothing extracted from a request | The email had no usable fields the agent could read. Check the field formats above and resend. | --- # 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.fill-easy.com/kyc_agent.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.