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.

Licensee screening - Request

post

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.

Check

Searches

Searched by

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.

Authorizations

x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body

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.

surnamestringOptional

English surname, casing free.

Example: CHAN

otherNamesstringOptional

English given names, casing free.

Example: Tai Man David

nameChineseTraditionalstringOptional

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

Example: 陳大文

nameChineseSimplifiedstringOptional

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.

Example: 陈大文

aliasesstring[]Optional

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.

Example: ["CHAN David","陳戴維"]

iaLicenceNostringOptional

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.

Example: GA1234

sfcCeRefstringOptional

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

Example: ABC123

mpfaRegistrationNostringOptional

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

Example: 123456

hkidstringOptional

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

Example: A123456(7)

cnIdNumberstringOptional

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.

Example: 44030119900101123X

dobstringOptional

Date of birth, YYYY-MM-DD. Narrows watchlist screening.

Example: 1990-01-01

genderstring · enumOptional

Narrows watchlist screening.

Possible values:

countrystringOptional

Nationality, citizenship, or residency — country name or code. Narrows watchlist screening.

Example: Hong Kong

externalRefIdstringOptional

Your own reference id, echoed back in poll and webhook payloads.

callbackUrlstring · uriOptional

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.

Pattern: ^https://.+

dryRunbooleanOptional

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.

Responses

200

Request validated and queued. Poll with the returned token, or await the webhook if a callbackUrl was supplied.

application/json

tokenstringRequired

JWT token

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$

requestIdstringRequiredExample: KYC_LS_a1b2c3d4e5f6

400

Validation failed — nothing was searched or billed. problems lists every issue found, so one corrected request can fix them all.

application/json

post/kyc/licensee

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"
}

Licensee screening - Poll

post

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.

Authorizations

x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body

tokenstringRequired

JWT token

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$

Responses

200

Screening finished — the consolidated result.

application/json

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.

requestIdstringRequiredExample: KYC_LS_a1b2c3d4e5f6

externalRefIdstringOptional

Echoed from the request, if any.

partialbooleanOptional

true when the 10-minute budget expired before every check finished — the unfinished ones carry status: timeout.

dryRunbooleanOptional

completedTimenumberOptional

Epoch milliseconds when the checks finished.

zipUrlstring · uriOptional

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.

zipFileNamestringOptional

Suggested file name for the report bundle.

Example: licensee-KYC_LS_a1b2c3d4e5f6.zip

202

Checks still running. Poll again in ~10 seconds.

application/json

410

The result has expired — results are kept for 30 days.

application/json

503

The screening run failed and has been flagged for follow-up.

application/json

post/kyc/licensee/poll

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 3 days ago