Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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.

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:

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.

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.

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 below.

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.

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 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.

Result links are valid for 7 days, and the underlying report files are deleted after 30 days — download anything you need to keep.

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. 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

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.

Last updated