KYC Licensee
One-request screening of an insurance-intermediary candidate: the Hong Kong licence registers (IA, SFC, MPFA), court records, AML watchlist screening, and — with a mainland resident ID — the mainland China background checks all run in parallel from a single payload and come back as one consolidated result.
Send what you have: only the English name is required, and each check runs only when its own input is present — a licence/registration number per register, the name forms for courts and screening, the resident-ID pair for the mainland. The flow is asynchronous — request, then poll or receive a webhook.
Screens an insurance-intermediary candidate (an individual licensee) across every check the supplied fields enable, in one request: the three Hong Kong licence registers (IA, SFC, MPFA), Hong Kong court records, AML watchlist screening with full profiles, and — when a mainland resident ID is supplied — the mainland China background checks. The outcomes come back as one consolidated result holding each check's raw response.
No single field is required — every check does the best it can with the data given (a request just needs at least one name or one identifier). The three registers run by their own identifier when supplied (an unambiguous lookup), otherwise by name — several same-named register entries then come back as an unresolved 422 entry, a finding in its own right. The mainland checks alone need their identity pair.
ia
IA Register of Licensed Insurance Intermediaries
iaLicenceNo, else the names
sfc
SFC Public Register of Licensed Persons
sfcCeRef, else the names
mpfa
MPFA Register of Subsidiary Intermediaries
mpfaRegistrationNo, else the names
litigation
Hong Kong court records — one search per name form
the name forms (English name, nameChineseTraditional, aliases)
screening
Sanctions / PEP / adverse media — one screen per name form, narrowed by dob / gender / country
the name forms
cn
Mainland China background (/kyc/cn products)
cnIdNumber + nameChineseSimplified — skipped without the pair
director
Companies Registry Directors Index — every company where the person is or was a director
the full English name (else nameChineseTraditional); hkid narrows to an exact match
The director search runs by the full English name (surname + other names; the Chinese name when the English pair is incomplete); a supplied hkid upgrades it to an exact match of the name plus the HKID's leading characters (the partial form the Registry stores) — the only way to resolve same-name candidates.
Asynchronous contract
The checks run in parallel and take up to a few minutes (bounded at 10), so this endpoint validates, queues, and returns a token immediately. Poll POST /kyc/licensee/poll every ~10 seconds, or supply a callbackUrl to receive the completed result as a webhook — event: kyc.licensee.completed, or kyc.licensee.partial when the time budget expired before every check finished. Polling remains available regardless.
Validation is strict and free: a 400 lists every problem in problems, so a corrected request can be built in one pass. Nothing is searched or billed on a 400.
Billing
Each underlying check bills exactly as it does when called directly — each register lookup, each AML screen (one per name form), each mainland product, and the directorship search — plus one bill for the licensee screening itself. A dryRun request calls no upstream and is free.
Client ID in x-client-id header.
Client Secret in x-client-secret header.
No single field is required — supply whatever identity data you have; the only rejection is a request with no name and no identifier at all (nothing any check could search). Strings are trimmed and identifiers upper-cased before validation.
English surname, casing free.
CHANEnglish given names, casing free.
Tai Man DavidChinese name in Traditional characters, as Hong Kong registers publish it. Adds a Chinese-language search to the court and screening checks — the IA register and the courts match Traditional only.
陳大文Chinese name in Simplified characters, exactly as on the mainland resident ID card — pinyin is not accepted. Required with cnIdNumber; the pair unlocks the mainland China checks.
陈大文Other name forms — former names, alternative spellings, English or Chinese. Each becomes a separate court search and AML screen (script is detected automatically). Duplicates of the searched primary names are dropped; at most 10 may remain after that deduplication.
["CHAN David","陳戴維"]IA insurance intermediary licence number — 2 letters + 4 digits. Resolves the IA register lookup unambiguously; without it the register is searched by name, which several same-named licensees can leave unresolved.
GA1234SFC Central Entity (CE) number — 3 letters + 3 digits. Resolves the SFC register lookup unambiguously; without it the register is searched by name, which several same-named persons can leave unresolved.
ABC123MPF registration number — 6 digits for a person, A + 6 digits for an agency. Resolves the MPFA register lookup unambiguously; without it the register is searched by name, which several same-named intermediaries can leave unresolved.
123456Hong Kong Identity Card number, full (A123456(7)) or partial. Upgrades the Companies Registry directorship search from a loose name search to an exact match of the English name plus the HKID's leading characters (the partial form the Registry stores) — the way to resolve same-name candidates. A full HKID has its check digit verified.
A123456(7)18-digit mainland China Resident Identity Card number (last character may be X). With nameChineseSimplified, unlocks the mainland China checks and makes their findings identity-certain. Never echoed back in results. When dob is also supplied, digits 7–14 must match it.
44030119900101123XDate of birth, YYYY-MM-DD. Narrows watchlist screening.
1990-01-01Narrows watchlist screening.
Nationality, citizenship, or residency — country name or code. Narrows watchlist screening.
Hong KongYour own reference id, echoed back in poll and webhook payloads.
HTTPS URL to receive a webhook POST when the result is ready — the consolidated result wrapped in the standard webhook envelope. Delivered once, best-effort; polling remains available regardless.
^https://.+When true, no upstream is called and nothing is billed: every check the input enables returns a static sample body with the status a real run would carry, so the aggregate mirrors a real run exactly — only the top-level dryRun: true in the result marks it. Use to integrate against the contract for free, and to preview which checks a payload triggers.
Request validated and queued. Poll with the returned token, or await the webhook if a callbackUrl was supplied.
JWT token
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$KYC_LS_a1b2c3d4e5f6Validation failed — nothing was searched or billed. problems lists every issue found, so one corrected request can fix them all.
POST /kyc/licensee HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 497
{
"surname": "CHAN",
"otherNames": "Tai Man David",
"nameChineseTraditional": "陳大文",
"nameChineseSimplified": "陈大文",
"aliases": [
"CHAN David",
"陳戴維"
],
"iaLicenceNo": "GA1234",
"sfcCeRef": "ABC123",
"mpfaRegistrationNo": "123456",
"hkid": "A123456(7)",
"cnIdNumber": "44030119900101123X",
"dob": "1990-01-01",
"gender": "male",
"country": "Hong Kong",
"externalRefId": "onboarding-7781",
"callbackUrl": "https://kyc-agent.example.com/webhook/licensee",
"callbackHeaders": {
"Authorization": "Bearer eyJhbGciOi..."
}
}{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U",
"requestId": "KYC_LS_a1b2c3d4e5f6"
}Returns the state of a licensee screening started with POST /kyc/licensee: 202 while checks are running, 200 with the consolidated result once done. Results are kept for 30 days; afterwards the poll returns 410.
Client ID in x-client-id header.
Client Secret in x-client-secret header.
JWT token
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$Screening finished — the consolidated result.
Consolidated result of a licensee screening — the raw JSON response of every check that ran, keyed by check name. Also delivered as the data of the completion webhook.
KYC_LS_a1b2c3d4e5f6Echoed from the request, if any.
true when the 10-minute budget expired before every check finished — the unfinished ones carry status: timeout.
Epoch milliseconds when the checks finished.
Presigned download link for the report bundle, minted fresh on every poll (valid 7 days; the file is kept 30). The zip holds summary.pdf (the consolidated background screening report), every file the checks produced (register page prints, screening reports, the mainland report), and a <check>.json with the raw response for entries that produced no file. Omitted if the bundle could not be stored — the structured result is unaffected.
Suggested file name for the report bundle.
licensee-KYC_LS_a1b2c3d4e5f6.zipChecks still running. Poll again in ~10 seconds.
The result has expired — results are kept for 30 days.
The screening run failed and has been flagged for follow-up.
POST /kyc/licensee/poll HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 120
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U"
}{
"requestId": "KYC_LS_a1b2c3d4e5f6",
"externalRefId": "text",
"partial": true,
"dryRun": true,
"completedTime": 1,
"zipUrl": "https://example.com",
"zipFileName": "licensee-KYC_LS_a1b2c3d4e5f6.zip",
"input": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"checks": {
"ia": {
"status": 1,
"body": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"name": "text",
"requestId": "text"
},
"sfc": {
"status": 1,
"body": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"name": "text",
"requestId": "text"
},
"mpfa": {
"status": 1,
"body": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"name": "text",
"requestId": "text"
},
"litigation": [
{
"status": 1,
"body": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"name": "text",
"requestId": "text"
}
],
"screening": [
{
"status": 1,
"body": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"name": "text",
"requestId": "text"
}
],
"cn": {
"status": 1,
"body": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"name": "text",
"requestId": "text"
},
"director": {
"status": 1,
"body": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"name": "text",
"requestId": "text"
}
}
}Last updated

