> 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-hong-kong.md).
# KYC Hong Kong
Hong Kong KYC checks, each completed in a single synchronous call: AML name screening against global watchlists, and lookups against Hong Kong's official public registers returning the structured register record together with a page print (PDF) of the register's own detail page.
## Single-name AML / sanctions / PEP screening
> Screens a single name against global \*\*sanctions\*\*, \*\*PEP\*\* (Politically Exposed Person),\
> and \*\*adverse-media\*\* watchlists (data sourced from Acuris Risk Intelligence) and returns\
> any matches in one synchronous call.\
> \
> Supply at least one name field — \`name\`, \`nameEnglish\`, \`nameChinese\`, or \`nameOtherLang\`.\
> Optional \`dob\`, \`gender\`, \`country\`, and \`entityType\` narrow the screen.\
> \
> The response \`summary\` counts matches by resolution status, and \`matches\` lists each\
> watchlist hit with its strength (\`0\`–\`1\`), the categories it appears on (\`PEP\`, \`Sanction\`,\
> …), and identifying details. A returned \`caseId\` references the screening case for future\
> retrieval.\
> \
> Set \`full: true\` to also include each match's \*\*complete profile\*\* (addresses, ID & passport\
> numbers, sanction regime & measures, PEP positions, linked persons, evidence sources, photo,\
> …) under \`matches\[].profile\`. This is heavier — it makes one extra upstream call per match —\
> so it defaults to \`false\`, returning only the headline match data.\
> \
> Every screening also produces a \*\*PDF report\*\* of the result, returned as a presigned\
> download link in \`pdfUrl\` (valid for 7 days; the file is retained for 30 days). Download\
> it promptly — there is no endpoint to re-fetch the link later. With \`full: true\` the\
> report also renders each match's complete profile — sanctions, PEP positions, linked\
> persons, and evidence sources. If report generation fails, the screening still succeeds\
> and \`pdfUrl\` is omitted from the response.
```json
{"openapi":"3.1.0","info":{"title":"Fill Easy Services","version":"1.0.0"},"tags":[{"name":"KYC Hong Kong","description":"Hong Kong KYC checks, each completed in a single synchronous call: AML name screening\nagainst global watchlists, and lookups against Hong Kong's official public registers\nreturning the structured register record together with a page print (PDF) of the\nregister's own detail page.\n"}],"servers":[{"url":"sandbox.staging-api.fill-easy.com"}],"security":[{"ClientID":[],"ClientSecret":[]}],"components":{"securitySchemes":{"ClientID":{"type":"apiKey","description":"Client ID in x-client-id header.","name":"x-client-id","in":"header"}}},"paths":{"/kyc/hk/screening":{"post":{"tags":["KYC Hong Kong"],"summary":"Single-name AML / sanctions / PEP screening","description":"Screens a single name against global **sanctions**, **PEP** (Politically Exposed Person),\nand **adverse-media** watchlists (data sourced from Acuris Risk Intelligence) and returns\nany matches in one synchronous call.\n\nSupply at least one name field — `name`, `nameEnglish`, `nameChinese`, or `nameOtherLang`.\nOptional `dob`, `gender`, `country`, and `entityType` narrow the screen.\n\nThe response `summary` counts matches by resolution status, and `matches` lists each\nwatchlist hit with its strength (`0`–`1`), the categories it appears on (`PEP`, `Sanction`,\n…), and identifying details. A returned `caseId` references the screening case for future\nretrieval.\n\nSet `full: true` to also include each match's **complete profile** (addresses, ID & passport\nnumbers, sanction regime & measures, PEP positions, linked persons, evidence sources, photo,\n…) under `matches[].profile`. This is heavier — it makes one extra upstream call per match —\nso it defaults to `false`, returning only the headline match data.\n\nEvery screening also produces a **PDF report** of the result, returned as a presigned\ndownload link in `pdfUrl` (valid for 7 days; the file is retained for 30 days). Download\nit promptly — there is no endpoint to re-fetch the link later. With `full: true` the\nreport also renders each match's complete profile — sanctions, PEP positions, linked\npersons, and evidence sources. If report generation fails, the screening still succeeds\nand `pdfUrl` is omitted from the response.\n","operationId":"kycHkScreening","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"At least one of `name`, `nameEnglish`, `nameChinese`, or `nameOtherLang` is required.","properties":{"name":{"type":"string","description":"Name to screen. Use this when you have a single name and don't need to disambiguate the script."},"nameEnglish":{"type":"string","description":"Name in English / Latin script."},"nameChinese":{"type":"string","description":"Name in Chinese script."},"nameOtherLang":{"type":"string","description":"Name in a language other than English or Chinese."},"entityType":{"type":"string","enum":["Individual","Entity","Aircraft","Vessel","Country"],"description":"Type of entity being screened. Optional."},"dob":{"type":"string","description":"Date of birth in `YYYY-MM-DD` format. Optional."},"gender":{"type":"string","enum":["male","female"],"description":"Optional."},"country":{"type":"string","description":"Nationality, citizenship, or residency — name or code of the country/region. Optional."},"externalRefId":{"type":"string","description":"Your own reference id for this screen, echoed back in the response. Optional.\n**Must be unique per screening request** — it permanently identifies the\nscreening case, and an id that was ever submitted before (even on a request\nthat returned an error) is rejected with `422`. Use a fresh id for every\nattempt, including retries.\n"},"full":{"type":"boolean","description":"When `true`, fetch each match's complete profile and include it as\n`matches[].profile` and as a detailed section in the PDF report. Adds one\nupstream call per match. Defaults to `false` (headline match data only).\n"},"dryRun":{"type":"boolean","description":"When `true`, the watchlist provider is not called and nothing is billed: the\nresponse carries a static sample screen (with matches; `full` controls whether\ntheir profiles are included) and its PDF report is rendered from it, so the\nbody mirrors a real screen exactly — only `dryRun: true` marks it. Use to\nintegrate against the contract for free.\n"}}}}}},"responses":{"200":{"description":"Screening completed. Returns the screening case id and any watchlist matches.","content":{"application/json":{"schema":{"type":"object","required":["requestId","caseId","name","summary","matches"],"properties":{"requestId":{"type":"string","description":"Unique id for this screening request, for tracking and billing reconciliation."},"caseId":{"type":"string","description":"Identifier of the screening case, for future retrieval."},"name":{"type":"string","description":"The name that was screened."},"externalRefId":{"type":"string","description":"The reference id supplied in the request, if any."},"summary":{"type":"object","description":"Count of matches by resolution status.","required":["total","positive","possible","false","unspecified","unresolved"],"properties":{"total":{"type":"number","description":"Total number of matches found."},"positive":{"type":"number","description":"Matches resolved as positive (a true hit)."},"possible":{"type":"number","description":"Matches resolved as possible."},"false":{"type":"number","description":"Matches resolved as false positives."},"unspecified":{"type":"number","description":"Matches resolved without a specified outcome."},"unresolved":{"type":"number","description":"Matches not yet reviewed."}}},"matches":{"type":"array","items":{"type":"object","required":["matchId","matchedName","name","types"],"properties":{"matchId":{"type":"string","description":"Identifier of the matched watchlist record."},"matchedName":{"type":"string","description":"The screened name as matched."},"name":{"type":"string","description":"Primary name of the watchlist record."},"nameType":{"type":"string","description":"How `name` relates to the record (e.g. `Primary`, `AKA`)."},"nameOriginalScript":{"type":"string","description":"The record's name in its original script, if available."},"alias":{"type":"string","description":"Comma-separated known aliases of the record."},"types":{"type":"array","items":{"type":"string"},"description":"Watchlist categories the record appears on (e.g. `PEP`, `Sanction`)."},"matchStrength":{"type":"number","description":"Match confidence from 0 to 1."},"matchType":{"type":"string","description":"How the match was made (e.g. `Native Name Match`)."},"dob":{"type":"string","description":"Date(s) of birth on the record."},"gender":{"type":"string","description":"Gender on the record."},"countryOfResidence":{"type":"string","description":"Country of residence on the record."},"profile":{"type":"object","additionalProperties":true,"description":"The match's complete upstream profile — addresses, ID/passport numbers,\nsanction regime & measures, PEP positions, linked persons, evidence\nsources, photo, and more. Present only when `full: true` was requested.\n"}}}},"pdfUrl":{"type":"string","description":"Presigned download link for the PDF report of this screening. Valid for\n7 days; the file itself is retained for 30 days. Omitted if report\ngeneration failed — the screening result is unaffected.\n"},"pdfFileName":{"type":"string","description":"Suggested file name for the PDF report."},"dryRun":{"type":"boolean","description":"Present and `true` when the screen was a dry run — sample matches, nothing billed."}}}}}},"400":{"description":"Bad Request — no name field supplied."},"422":{"description":"The supplied `externalRefId` was already used by a previous screening request. This is\npermanent — retrying with the same id always fails. Submit a fresh, unique id.\n"},"503":{"description":"Screening provider unavailable or rejected the request."}}}}}}
```
## SFC licensed person register lookup
> Looks up one record in the SFC's \*\*Public Register of Licensed Persons and Registered\
> Institutions\*\* and synchronously returns the structured record — covering every tab of\
> the register's detail pages — together with a page print (PDF) of the first tab\
> (licence details).\
> \
> Identify the person by name, or by \`ceRef\` (Central Entity number). The query must\
> resolve to exactly one register record — a query matching no record returns \`404\`, a\
> query matching more than one returns \`422\` and must be refined (the CE number is always\
> unambiguous).\
> \
> The register matches names case-insensitively and as a \*\*substring\*\*, so short queries\
> resolve to many records — \`Wong\` alone matches over 5,000. Individuals are held\
> surname-first, with the surname capitalised and a comma before any Western given name\
> (\`WONG Tai Man, Peter\`); the comma may be omitted from a query. Because the match is\
> by substring, a name that is complete and correct can still be contained in a longer one;\
> where exactly one of the matched records carries the queried name in full, that record is\
> returned instead of a \`422\`. Records genuinely sharing a name — several licensees are\
> registered as \`LEE Ka Ming\` — remain a \`422\`, listing the candidates and their CE numbers.\
> \
> A \`ceRef\` lookup additionally reaches firms — licensed corporations and registered\
> institutions — which the name search does not cover.
```json
{"openapi":"3.1.0","info":{"title":"Fill Easy Services","version":"1.0.0"},"tags":[{"name":"KYC Hong Kong","description":"Hong Kong KYC checks, each completed in a single synchronous call: AML name screening\nagainst global watchlists, and lookups against Hong Kong's official public registers\nreturning the structured register record together with a page print (PDF) of the\nregister's own detail page.\n"}],"servers":[{"url":"sandbox.staging-api.fill-easy.com"}],"security":[{"ClientID":[],"ClientSecret":[]}],"components":{"securitySchemes":{"ClientID":{"type":"apiKey","description":"Client ID in x-client-id header.","name":"x-client-id","in":"header"}},"schemas":{"KycHkRegisterResult":{"type":"object","description":"Common envelope of all `/kyc/hk` register lookups. Each endpoint adds its register-specific `record`.","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Unique id for this lookup, for tracking and billing reconciliation."},"externalRefId":{"type":"string","description":"Your own reference id, echoed back from the request."},"dryRun":{"type":"boolean","description":"Present and `true` when the lookup was a dry run — sample record, placeholder page print, nothing billed."},"pagePrints":{"$ref":"#/components/schemas/KycHkPagePrints"}}},"KycHkPagePrints":{"type":"array","description":"PDF page prints of the register's own pages for this lookup, as displayed at\nretrieval time. One entry per attempted print — a print that failed to render still\nappears, with `status: failed`. The structured record is unaffected either way.\n","items":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"Per-print status:\n- \"ready\": the print is available, `url` and `fileName` are populated\n- \"failed\": the print could not be rendered in time, no link is issued\n","enum":["ready","failed"]},"url":{"type":"string","format":"uri","description":"Presigned download link (only when status is \"ready\"). Valid for 7 days; the\nfile is retained for 30 days.\n"},"fileName":{"type":"string","description":"Suggested file name (only when status is \"ready\")."}}}},"SfcEntity":{"type":"object","description":"Reference to another SFC register entry (a principal or a registered institution).","required":["name"],"properties":{"ceRef":{"type":"string","description":"Central Entity (CE) number."},"name":{"type":"string"},"nameChinese":{"type":"string"}}},"SfcPerson":{"type":"object","description":"Individual attached to a firm on the SFC register.","required":["name"],"properties":{"ceRef":{"type":"string","description":"Central Entity (CE) number."},"name":{"type":"string"},"nameChinese":{"type":"string"},"activities":{"type":"array","items":{"type":"string"},"description":"Regulated activities the attachment covers."}}},"KycHkRegisterError":{"type":"object","description":"Error body of all `/kyc/hk` register lookups.","required":["message","requestId"],"properties":{"message":{"type":"string"},"requestId":{"type":"string"}}},"KycHkAmbiguousMatch":{"type":"object","description":"Body of the `422` every `/kyc/hk` register lookup returns when the query matched more than one record. Each endpoint adds its register-specific `candidates`.\n","required":["message","requestId","total"],"properties":{"message":{"type":"string"},"requestId":{"type":"string"},"total":{"type":"number","description":"How many records matched."}}}}},"paths":{"/kyc/hk/sfc":{"post":{"tags":["KYC Hong Kong"],"summary":"SFC licensed person register lookup","description":"Looks up one record in the SFC's **Public Register of Licensed Persons and Registered\nInstitutions** and synchronously returns the structured record — covering every tab of\nthe register's detail pages — together with a page print (PDF) of the first tab\n(licence details).\n\nIdentify the person by name, or by `ceRef` (Central Entity number). The query must\nresolve to exactly one register record — a query matching no record returns `404`, a\nquery matching more than one returns `422` and must be refined (the CE number is always\nunambiguous).\n\nThe register matches names case-insensitively and as a **substring**, so short queries\nresolve to many records — `Wong` alone matches over 5,000. Individuals are held\nsurname-first, with the surname capitalised and a comma before any Western given name\n(`WONG Tai Man, Peter`); the comma may be omitted from a query. Because the match is\nby substring, a name that is complete and correct can still be contained in a longer one;\nwhere exactly one of the matched records carries the queried name in full, that record is\nreturned instead of a `422`. Records genuinely sharing a name — several licensees are\nregistered as `LEE Ka Ming` — remain a `422`, listing the candidates and their CE numbers.\n\nA `ceRef` lookup additionally reaches firms — licensed corporations and registered\ninstitutions — which the name search does not cover.\n","operationId":"kycHkSfc","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"At least one of `ceRef`, `name`, or `nameChinese` is required.","properties":{"ceRef":{"type":"string","description":"Central Entity (CE) number. Unambiguous — preferred over name lookups."},"name":{"type":"string","description":"Name in English as it appears on the register — surname first, with the surname capitalised and a comma before any Western given name. Matched case-insensitively as a substring; the comma is optional.\n"},"nameChinese":{"type":"string","description":"Name in Chinese as it appears on the register. Matched as a substring."},"externalRefId":{"type":"string","description":"Your own reference id, echoed back in the response."},"dryRun":{"type":"boolean","description":"When `true`, the register is not queried and nothing is billed: the response\ncarries a static sample record and a placeholder page print, so the body\nmirrors a real lookup exactly — only `dryRun: true` marks it. Use to\nintegrate against the contract for free.\n"}}}}}},"responses":{"200":{"description":"Exactly one register record matched. Returns the structured record and its page print.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/KycHkRegisterResult"},{"type":"object","required":["record"],"properties":{"record":{"type":"object","description":"The full register record. Which tab fields are present depends on the entity kind — individuals carry `licenceDetails`, `accreditedTo` and `executiveOfficerOf`; firms carry the officer/representative lists, `emails` and `websites`.\n","required":["ceRef","name","entityType","status"],"properties":{"ceRef":{"type":"string","description":"Central Entity (CE) number."},"name":{"type":"string","description":"Name in English."},"nameChinese":{"type":"string","description":"Name in Chinese."},"entityType":{"type":"string","enum":["Individual","Executive Officer","Licensed Corporation","Registered Institution"],"description":"Kind of register entry. `Individual` also covers individuals who additionally serve as executive officer of a registered institution; `Executive Officer` alone marks executive officers holding no SFC licence of their own.\n"},"status":{"type":"string","enum":["Active","Inactive"],"description":"Whether the register shows any currently active licence or registration."},"registerStatus":{"type":"string","description":"The register's own page-level status character for the SFO regime, as rendered on the detail page — `A` current licence / registration, `R` licence record exists but no active licence, `S` suspended (the register renders \"Suspended\"). Absent when the register shows no SFO record.\n"},"registerStatusAmlo":{"type":"string","description":"The register's page-level status character for the AMLO regime (virtual assets), same value space as `registerStatus`. Absent when the register shows no AMLO record.\n"},"regulatedActivities":{"type":"array","items":{"type":"string"},"description":"Regulated activities the current SFO licence / registration covers."},"amloRegulatedActivities":{"type":"array","items":{"type":"string"},"description":"Activities covered under the AMLO regime (virtual assets / stablecoins), if any."},"licenceDetails":{"type":"array","description":"Rows of the register's first tab. Individuals get one row per accreditation (principal × regulated activity), firms one row per regulated activity.\n","items":{"type":"object","required":["activity"],"properties":{"regime":{"type":"string","enum":["SFO","AMLO"]},"activityType":{"type":"integer","description":"Regulated activity type number."},"activity":{"type":"string"},"activityChinese":{"type":"string"},"role":{"type":"string","enum":["Representative","Responsible Officer"],"description":"Capacity in which an individual is accredited."},"principal":{"$ref":"#/components/schemas/SfcEntity"},"accreditedSince":{"type":"string","format":"date","description":"Date of accreditation to the principal (individuals)."},"licensedSince":{"type":"string","format":"date","description":"Date the activity was first licensed (individuals)."},"effectiveDate":{"type":"string","format":"date","description":"Effective date of the activity (firms)."},"endDate":{"type":"string","format":"date"},"statusCode":{"type":"string","description":"Raw register status code — `A` current, `S` suspended, `U` suspended approval of responsible officer.\n"},"statusNote":{"type":"string","description":"Register annotation, e.g. cessation-of-business remarks."}}}},"accreditedTo":{"type":"array","description":"Principals a licensed individual is accredited to.","items":{"$ref":"#/components/schemas/SfcEntity"}},"executiveOfficerOf":{"type":"array","description":"Registered institutions the person serves as executive officer for, one row per regulated activity.\n","items":{"type":"object","required":["registeredInstitution","activity"],"properties":{"registeredInstitution":{"$ref":"#/components/schemas/SfcEntity"},"activityType":{"type":"integer"},"activity":{"type":"string"},"activityChinese":{"type":"string"},"effectiveDate":{"type":"string","format":"date"},"statusCode":{"type":"string"}}}},"addresses":{"type":"array","description":"Business addresses; for individuals one entry per principal.","items":{"type":"object","required":["address"],"properties":{"address":{"type":"string"},"addressChinese":{"type":"string"},"principal":{"$ref":"#/components/schemas/SfcEntity"}}}},"emails":{"type":"array","items":{"type":"string"}},"websites":{"type":"array","items":{"type":"string"}},"conditions":{"type":"array","description":"Licensing / registration conditions in force.","items":{"type":"object","required":["condition"],"properties":{"regime":{"type":"string","enum":["SFO","AMLO"]},"condition":{"type":"string"},"conditionChinese":{"type":"string"},"effectiveDate":{"type":"string","format":"date"}}}},"responsibleOfficers":{"type":"array","description":"Responsible officers of a licensed corporation.","items":{"$ref":"#/components/schemas/SfcPerson"}},"representatives":{"type":"array","description":"Licensed representatives accredited to a licensed corporation.","items":{"$ref":"#/components/schemas/SfcPerson"}},"executiveOfficers":{"type":"array","description":"Executive officers of a registered institution.","items":{"$ref":"#/components/schemas/SfcPerson"}},"complaintsOfficers":{"type":"array","items":{"type":"object","properties":{"telephone":{"type":"string"},"fax":{"type":"string"},"email":{"type":"string"},"address":{"type":"string"},"addressChinese":{"type":"string"}}}},"publicDisciplinaryActions":{"type":"array","description":"Public disciplinary actions in the past five years, if any.","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"action":{"type":"string"},"actionChinese":{"type":"string"},"documentUrlEnglish":{"type":"string","description":"Register link to the action's press release / statement."},"documentUrlChinese":{"type":"string"}}}},"licenceRecord":{"type":"array","description":"Full licence / registration history, including past accreditations.","items":{"type":"object","required":["activity"],"properties":{"regime":{"type":"string","enum":["SFO","AMLO"]},"role":{"type":"string","enum":["Representative","Responsible Officer"]},"principal":{"$ref":"#/components/schemas/SfcEntity"},"activityType":{"type":"integer"},"activity":{"type":"string"},"activityChinese":{"type":"string"},"statusCode":{"type":"string"},"effectivePeriods":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}}}}}}}}}}]}}}},"400":{"description":"Bad Request — no identifying field supplied."},"404":{"description":"No register record matched the query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KycHkRegisterError"}}}},"422":{"description":"More than one register record matched — refine the query, ideally with `ceRef`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/KycHkAmbiguousMatch"},{"type":"object","required":["candidates"],"properties":{"candidates":{"type":"array","description":"The first matching records (up to 10), to help refine the query.","items":{"type":"object","required":["ceRef","name"],"properties":{"ceRef":{"type":"string"},"name":{"type":"string"},"nameChinese":{"type":"string"},"entityType":{"type":"string","enum":["Individual","Executive Officer","Licensed Corporation","Registered Institution"]}}}}}}]}}}},"503":{"description":"The register is unavailable or the retrieval failed."}}}}}}
```
## MPFA Subsidiary Intermediary register lookup
> Looks up a person or licensed long-term insurance agency on the \*\*MPFA Public Register of\
> Subsidiary Intermediaries\*\* (mpfa.org.hk) and returns the register record in one synchronous\
> call — registration status, frontline regulator(s), attached principal intermediaries,\
> conditions imposed, and public disciplinary orders of the last 5 years.\
> \
> Supply exactly one identifier — they are used in order of precedence:\
> 1\. \`registrationNo\` — unambiguous, preferred. Numeric for persons (\`123456\`),\
> \`A\`-prefixed for agencies (\`A123456\`).\
> 2\. \`name\` — English name as it appears on the register. For a person, surname first\
> (e.g. \`Chan Tai Man\`); the register holds names in upper case but matches\
> case-insensitively, as a substring.\
> 3\. \`nameChinese\` — Chinese name, in either Simplified or Traditional characters. Matched\
> as a substring, but a whole-name match takes precedence over the longer names it\
> appears in.\
> Whitespace is ignored; an exact match wins, and a substring match is used only when\
> nothing matches exactly.\
> \
> \`registrationNo\` reaches every kind of record. Name lookups reach people only, so an\
> agency must be looked up by its registration number.\
> \
> Because names are matched by substring, a name that is complete and correct can still be\
> contained in a longer one; where exactly one of the matched records carries the queried\
> name in full, that record is returned instead of a \`422\`. Records genuinely sharing a\
> name — a dozen people are registered as \`CHAN WAI MAN\` — remain a \`422\`, listing the\
> candidates and their registration numbers.\
> \
> The lookup only succeeds when it narrows to \*\*exactly one\*\* record — \`404\` when nothing\
> matched, \`422\` with a candidate list when several did.\
> \
> Every successful lookup also produces a \*\*page print PDF\*\* of the official register detail\
> page, returned in \`pagePrints\` as a presigned download link (valid for 7 days; the file\
> is retained for 30 days). If the page print fails to render, the lookup still succeeds and\
> the entry comes back with \`status: failed\`.\
> \
> The register is updated by the MPFA every working day; \`registerRevisionDate\` states the\
> register's own last-revision date at the time of the lookup.\
> \
> The register lists \*\*current registrations only\*\* — a suspended, revoked or disqualified\
> intermediary is removed for the duration of the sanction, so a register miss alone cannot\
> distinguish never-registered from removed-for-cause. Every lookup is therefore\
> cross-checked against the enforcement notices the MPFA has published on its enforcement\
> news page (mpfa.org.hk/en/enforcement/mpf-intermediary/enforcement-news), maintained in\
> the service as a reviewed extract of that page and its press releases; notices naming the\
> queried person come back as \`enforcementNotices\` on both the \`200\` and the \`404\` response.
```json
{"openapi":"3.1.0","info":{"title":"Fill Easy Services","version":"1.0.0"},"tags":[{"name":"KYC Hong Kong","description":"Hong Kong KYC checks, each completed in a single synchronous call: AML name screening\nagainst global watchlists, and lookups against Hong Kong's official public registers\nreturning the structured register record together with a page print (PDF) of the\nregister's own detail page.\n"}],"servers":[{"url":"sandbox.staging-api.fill-easy.com"}],"security":[{"ClientID":[],"ClientSecret":[]}],"components":{"securitySchemes":{"ClientID":{"type":"apiKey","description":"Client ID in x-client-id header.","name":"x-client-id","in":"header"}},"schemas":{"KycHkRegisterResult":{"type":"object","description":"Common envelope of all `/kyc/hk` register lookups. Each endpoint adds its register-specific `record`.","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Unique id for this lookup, for tracking and billing reconciliation."},"externalRefId":{"type":"string","description":"Your own reference id, echoed back from the request."},"dryRun":{"type":"boolean","description":"Present and `true` when the lookup was a dry run — sample record, placeholder page print, nothing billed."},"pagePrints":{"$ref":"#/components/schemas/KycHkPagePrints"}}},"KycHkPagePrints":{"type":"array","description":"PDF page prints of the register's own pages for this lookup, as displayed at\nretrieval time. One entry per attempted print — a print that failed to render still\nappears, with `status: failed`. The structured record is unaffected either way.\n","items":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"Per-print status:\n- \"ready\": the print is available, `url` and `fileName` are populated\n- \"failed\": the print could not be rendered in time, no link is issued\n","enum":["ready","failed"]},"url":{"type":"string","format":"uri","description":"Presigned download link (only when status is \"ready\"). Valid for 7 days; the\nfile is retained for 30 days.\n"},"fileName":{"type":"string","description":"Suggested file name (only when status is \"ready\")."}}}},"MpfaEnforcementNotice":{"type":"object","description":"One MPFA enforcement action against one party, from the MPFA enforcement news page (mpfa.org.hk/en/enforcement/mpf-intermediary/enforcement-news) — the public record of sanctions against MPF intermediaries since 2016, maintained in the service as a reviewed extract of the page and its press releases. A notice is matched against every party its press release sanctions with an MPF registration number of its own: the headline subject, and anyone named only in the release body (the 2024-07-05 HSBC notice also disqualifies a responsible officer the headline does not name). `matchedBy` states the evidence: `registrationNo` means the number the release itself attributes to this party equals the queried or retrieved number — the notice concerns the queried person; `name` means only the name matched (English as a case-insensitive whole name with hyphens as spaces, Chinese exactly) — a party with the same name, not necessarily the queried person.\n","required":["action","url","matchedBy"],"properties":{"date":{"type":"string","format":"date","description":"Date of the enforcement action as listed on the enforcement news page."},"name":{"type":"string","description":"The matched party's name as published (headline, or press-release body for a party the headline does not name). The MPFA masks the name once a disciplinary order has been spent for over five years; masked notices never match.\n"},"nameChinese":{"type":"string","description":"The matched party's Chinese name as published on the Traditional-Chinese edition of the enforcement news page.\n"},"registrationNo":{"type":"string","description":"MPF registration number the press release attributes to this party (by the surname or alias the release itself uses). Absent when the release publishes none for the party — it never carries another party's number.\n"},"action":{"type":"string","description":"Sanction type(s) as published for this party (e.g. `suspension`, `reprimand and disqualification`, `fine`); the notice headline verbatim when it fits no published type.\n"},"periodFrom":{"type":"string","format":"date","description":"First day the sanction is in force, when the notice or its press release states a period for this party.\n"},"periodTo":{"type":"string","format":"date","description":"Last day the sanction is in force (inclusive), when the notice or its press release states a period for this party.\n"},"url":{"type":"string","format":"uri","description":"Link to the enforcement notice's press release."},"matchedBy":{"type":"string","enum":["registrationNo","name"],"description":"How the notice was tied to the query — see the schema description."}}},"KycHkRegisterError":{"type":"object","description":"Error body of all `/kyc/hk` register lookups.","required":["message","requestId"],"properties":{"message":{"type":"string"},"requestId":{"type":"string"}}},"KycHkAmbiguousMatch":{"type":"object","description":"Body of the `422` every `/kyc/hk` register lookup returns when the query matched more than one record. Each endpoint adds its register-specific `candidates`.\n","required":["message","requestId","total"],"properties":{"message":{"type":"string"},"requestId":{"type":"string"},"total":{"type":"number","description":"How many records matched."}}}}},"paths":{"/kyc/hk/mpfa":{"post":{"tags":["KYC Hong Kong"],"summary":"MPFA Subsidiary Intermediary register lookup","description":"Looks up a person or licensed long-term insurance agency on the **MPFA Public Register of\nSubsidiary Intermediaries** (mpfa.org.hk) and returns the register record in one synchronous\ncall — registration status, frontline regulator(s), attached principal intermediaries,\nconditions imposed, and public disciplinary orders of the last 5 years.\n\nSupply exactly one identifier — they are used in order of precedence:\n1. `registrationNo` — unambiguous, preferred. Numeric for persons (`123456`),\n `A`-prefixed for agencies (`A123456`).\n2. `name` — English name as it appears on the register. For a person, surname first\n (e.g. `Chan Tai Man`); the register holds names in upper case but matches\n case-insensitively, as a substring.\n3. `nameChinese` — Chinese name, in either Simplified or Traditional characters. Matched\n as a substring, but a whole-name match takes precedence over the longer names it\n appears in.\n Whitespace is ignored; an exact match wins, and a substring match is used only when\n nothing matches exactly.\n\n`registrationNo` reaches every kind of record. Name lookups reach people only, so an\nagency must be looked up by its registration number.\n\nBecause names are matched by substring, a name that is complete and correct can still be\ncontained in a longer one; where exactly one of the matched records carries the queried\nname in full, that record is returned instead of a `422`. Records genuinely sharing a\nname — a dozen people are registered as `CHAN WAI MAN` — remain a `422`, listing the\ncandidates and their registration numbers.\n\nThe lookup only succeeds when it narrows to **exactly one** record — `404` when nothing\nmatched, `422` with a candidate list when several did.\n\nEvery successful lookup also produces a **page print PDF** of the official register detail\npage, returned in `pagePrints` as a presigned download link (valid for 7 days; the file\nis retained for 30 days). If the page print fails to render, the lookup still succeeds and\nthe entry comes back with `status: failed`.\n\nThe register is updated by the MPFA every working day; `registerRevisionDate` states the\nregister's own last-revision date at the time of the lookup.\n\nThe register lists **current registrations only** — a suspended, revoked or disqualified\nintermediary is removed for the duration of the sanction, so a register miss alone cannot\ndistinguish never-registered from removed-for-cause. Every lookup is therefore\ncross-checked against the enforcement notices the MPFA has published on its enforcement\nnews page (mpfa.org.hk/en/enforcement/mpf-intermediary/enforcement-news), maintained in\nthe service as a reviewed extract of that page and its press releases; notices naming the\nqueried person come back as `enforcementNotices` on both the `200` and the `404` response.\n","operationId":"kycHkMpfa","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"At least one of `registrationNo`, `name`, or `nameChinese` is required.","properties":{"registrationNo":{"type":"string","description":"MPF registration number. Unambiguous — preferred over name lookups."},"name":{"type":"string","description":"English name as appearing on the register, surname first. The register holds names in upper case; matched case-insensitively as a substring. Finds people only — an agency must be looked up by its registration number.\n"},"nameChinese":{"type":"string","description":"Chinese name as appearing on the register. Whitespace is ignored and an exact match is preferred over a substring match. Finds people only — an agency must be looked up by its registration number.\n"},"externalRefId":{"type":"string","description":"Your own reference id, echoed back in the response."},"dryRun":{"type":"boolean","description":"When `true`, the register is not queried and nothing is billed: the response\ncarries a static sample record and a placeholder page print, so the body\nmirrors a real lookup exactly — only `dryRun: true` marks it. Use to\nintegrate against the contract for free.\n"}}}}}},"responses":{"200":{"description":"Exactly one register record matched.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/KycHkRegisterResult"},{"type":"object","required":["record"],"properties":{"registerRevisionDate":{"type":"string","format":"date","description":"The register's own \"Last Review / Revision Date\" at the time of the lookup."},"record":{"type":"object","required":["registrationNo","name","entityType","status","principalIntermediaries"],"properties":{"registrationNo":{"type":"string","description":"MPF registration number."},"name":{"type":"string","description":"English name as on the register."},"nameChinese":{"type":"string","description":"Chinese name as on the register, if any."},"entityType":{"type":"string","enum":["Individual","Agency"],"description":"Whether the subsidiary intermediary is a person or a licensed long-term insurance agency."},"status":{"type":"string","description":"Registration status (e.g. `Active`)."},"statusNote":{"type":"string","description":"Additional status annotation shown on the register, if any."},"frontlineRegulators":{"type":"array","items":{"type":"string"},"description":"Frontline regulator(s) (e.g. `Insurance Authority`)."},"principalIntermediaries":{"type":"array","description":"Principal intermediaries the subsidiary intermediary is attached to.","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"English name of the principal intermediary."},"nameChinese":{"type":"string","description":"Chinese name of the principal intermediary, if shown."},"registrationNo":{"type":"string","description":"MPF registration number of the principal intermediary, cross-referenced\nfrom the MPFA Principal Intermediary register. Omitted when the\ncross-reference is not unambiguous.\n"},"address":{"type":"string","description":"Address of the principal place of business."},"frontlineRegulator":{"type":"string"},"registrationStatus":{"type":"string"},"actingAsResponsibleOfficer":{"type":"string","description":"Whether this subsidiary intermediary acts as a responsible officer (`Yes` / `No`)."},"responsibleOfficerStatus":{"type":"string"},"attachmentStatus":{"type":"string","description":"Status of this subsidiary intermediary's attachment to the principal intermediary."},"remarks":{"type":"string"}}}},"conditionsImposed":{"type":"string","description":"Condition(s) imposed on the registration, or `Nil`."},"disciplinaryOrders":{"type":"array","description":"Public disciplinary orders by the MPFA within the last 5 years. Empty when none.","items":{"type":"object","properties":{"dateOfAction":{"type":"string"},"actionsTaken":{"type":"string"},"againstCapacityOf":{"type":"string"},"pressReleaseUrls":{"type":"array","items":{"type":"string"}}}}},"otherParticulars":{"type":"string","description":"Other particulars shown on the register, or `Nil`."}}},"enforcementNotices":{"type":"array","description":"MPFA enforcement actions naming this intermediary, cross-checked from the MPFA enforcement news page. Present when the cross-check completed (empty when it found nothing); omitted when it could not be completed.\n","items":{"$ref":"#/components/schemas/MpfaEnforcementNotice"}}}}]}}}},"400":{"description":"Bad Request — none of `registrationNo`, `name`, or `nameChinese` supplied."},"404":{"description":"No register record matched the query. Because the register removes a sanctioned intermediary for the duration of the sanction, `enforcementNotices` carries any MPFA enforcement actions naming the queried person — the only public way to tell a removal from a person who was never registered.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/KycHkRegisterError"},{"type":"object","properties":{"enforcementNotices":{"type":"array","description":"MPFA enforcement actions naming the queried person, cross-checked from the MPFA enforcement news page. Present when the cross-check completed (empty when it found nothing); omitted when it could not be completed.\n","items":{"$ref":"#/components/schemas/MpfaEnforcementNotice"}}}}]}}}},"422":{"description":"More than one register record matched — refine the query, ideally with `registrationNo`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/KycHkAmbiguousMatch"},{"type":"object","required":["candidates"],"properties":{"candidates":{"type":"array","description":"The first matching records (up to 10), to help refine the query.","items":{"type":"object","required":["registrationNo","name"],"properties":{"registrationNo":{"type":"string"},"name":{"type":"string"},"nameChinese":{"type":"string"},"entityType":{"type":"string","enum":["Individual","Agency"]}}}}}}]}}}},"503":{"description":"The MPFA register is unavailable."}}}}}}
```
## IA licensed insurance intermediary register lookup
> Looks up an individual on the Hong Kong Insurance Authority's \*\*Register of Licensed\
> Insurance Intermediaries\*\* (iir.ia.org.hk) and returns the register record in one\
> synchronous call — licence and its conditions, appointing principals past and present,\
> and public enforcement actions of the last 5 years — together with a page print (PDF)\
> of the register's own record page, its appointment history expanded.\
> \
> Supply exactly one identifier — they are used in order of precedence:\
> 1\. \`licenceNo\` — unambiguous, preferred.\
> 2\. \`name\` — English name as it appears on the register, surname first\
> (e.g. \`CHAN Tai Man\`). Matched case-insensitively, as a substring.\
> 3\. \`nameChinese\` — Chinese name in \*\*Traditional\*\* characters. Matched as a substring;\
> Simplified input does not match.\
> \
> Only individuals are covered. Licensed insurance agencies and broker companies sit on a\
> separate register this endpoint does not reach.\
> \
> Every licence status is searched, lapsed and revoked included: restricting to active\
> licences hides exactly the people a KYC check needs to find.\
> \
> The register matches names literally — it folds case and normalises nothing else. Spacing\
> and punctuation are part of the stored name (\`Au-Yeung Siu Ming Sam\`, \`Chan Mei Ling,\
> Amy\`), so a name is looked up as written, then retried without its punctuation if that\
> found nothing.\
> \
> Because names are matched by substring, a name that is complete and correct can still be\
> contained in a longer one; where exactly one of the matched records carries the queried\
> name in full, that record is returned instead of a \`422\`. The register holds no personal\
> identifier other than the licence number, so records genuinely sharing a name — 66 people\
> are registered as \`CHAN KA MAN\` — remain a \`422\`, listing the candidates and their\
> licence numbers.\
> \
> The lookup only succeeds when it narrows to \*\*exactly one\*\* record — \`404\` when nothing\
> matched, \`422\` with a candidate list when several did. A query matching more than 1,000\
> records also returns \`422\`: the register caps its results there and stops reporting the\
> true total, so beyond the cap no record can be resolved with confidence.
```json
{"openapi":"3.1.0","info":{"title":"Fill Easy Services","version":"1.0.0"},"tags":[{"name":"KYC Hong Kong","description":"Hong Kong KYC checks, each completed in a single synchronous call: AML name screening\nagainst global watchlists, and lookups against Hong Kong's official public registers\nreturning the structured register record together with a page print (PDF) of the\nregister's own detail page.\n"}],"servers":[{"url":"sandbox.staging-api.fill-easy.com"}],"security":[{"ClientID":[],"ClientSecret":[]}],"components":{"securitySchemes":{"ClientID":{"type":"apiKey","description":"Client ID in x-client-id header.","name":"x-client-id","in":"header"}},"schemas":{"KycHkRegisterResult":{"type":"object","description":"Common envelope of all `/kyc/hk` register lookups. Each endpoint adds its register-specific `record`.","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Unique id for this lookup, for tracking and billing reconciliation."},"externalRefId":{"type":"string","description":"Your own reference id, echoed back from the request."},"dryRun":{"type":"boolean","description":"Present and `true` when the lookup was a dry run — sample record, placeholder page print, nothing billed."},"pagePrints":{"$ref":"#/components/schemas/KycHkPagePrints"}}},"KycHkPagePrints":{"type":"array","description":"PDF page prints of the register's own pages for this lookup, as displayed at\nretrieval time. One entry per attempted print — a print that failed to render still\nappears, with `status: failed`. The structured record is unaffected either way.\n","items":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"Per-print status:\n- \"ready\": the print is available, `url` and `fileName` are populated\n- \"failed\": the print could not be rendered in time, no link is issued\n","enum":["ready","failed"]},"url":{"type":"string","format":"uri","description":"Presigned download link (only when status is \"ready\"). Valid for 7 days; the\nfile is retained for 30 days.\n"},"fileName":{"type":"string","description":"Suggested file name (only when status is \"ready\")."}}}},"IaPrincipal":{"type":"object","description":"Insurer or licensed broker appointing an insurance intermediary.","required":["name"],"properties":{"licenceNo":{"type":"string","description":"The principal's own licence number, where the register states it."},"name":{"type":"string"},"nameChinese":{"type":"string"}}},"KycHkRegisterError":{"type":"object","description":"Error body of all `/kyc/hk` register lookups.","required":["message","requestId"],"properties":{"message":{"type":"string"},"requestId":{"type":"string"}}},"KycHkAmbiguousMatch":{"type":"object","description":"Body of the `422` every `/kyc/hk` register lookup returns when the query matched more than one record. Each endpoint adds its register-specific `candidates`.\n","required":["message","requestId","total"],"properties":{"message":{"type":"string"},"requestId":{"type":"string"},"total":{"type":"number","description":"How many records matched."}}}}},"paths":{"/kyc/hk/ia":{"post":{"tags":["KYC Hong Kong"],"summary":"IA licensed insurance intermediary register lookup","description":"Looks up an individual on the Hong Kong Insurance Authority's **Register of Licensed\nInsurance Intermediaries** (iir.ia.org.hk) and returns the register record in one\nsynchronous call — licence and its conditions, appointing principals past and present,\nand public enforcement actions of the last 5 years — together with a page print (PDF)\nof the register's own record page, its appointment history expanded.\n\nSupply exactly one identifier — they are used in order of precedence:\n1. `licenceNo` — unambiguous, preferred.\n2. `name` — English name as it appears on the register, surname first\n (e.g. `CHAN Tai Man`). Matched case-insensitively, as a substring.\n3. `nameChinese` — Chinese name in **Traditional** characters. Matched as a substring;\n Simplified input does not match.\n\nOnly individuals are covered. Licensed insurance agencies and broker companies sit on a\nseparate register this endpoint does not reach.\n\nEvery licence status is searched, lapsed and revoked included: restricting to active\nlicences hides exactly the people a KYC check needs to find.\n\nThe register matches names literally — it folds case and normalises nothing else. Spacing\nand punctuation are part of the stored name (`Au-Yeung Siu Ming Sam`, `Chan Mei Ling,\nAmy`), so a name is looked up as written, then retried without its punctuation if that\nfound nothing.\n\nBecause names are matched by substring, a name that is complete and correct can still be\ncontained in a longer one; where exactly one of the matched records carries the queried\nname in full, that record is returned instead of a `422`. The register holds no personal\nidentifier other than the licence number, so records genuinely sharing a name — 66 people\nare registered as `CHAN KA MAN` — remain a `422`, listing the candidates and their\nlicence numbers.\n\nThe lookup only succeeds when it narrows to **exactly one** record — `404` when nothing\nmatched, `422` with a candidate list when several did. A query matching more than 1,000\nrecords also returns `422`: the register caps its results there and stops reporting the\ntrue total, so beyond the cap no record can be resolved with confidence.\n","operationId":"kycHkIa","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"At least one of `licenceNo`, `name`, or `nameChinese` is required.","properties":{"licenceNo":{"type":"string","description":"Insurance intermediary licence number. Unambiguous — preferred over name lookups."},"name":{"type":"string","description":"English name as it appears on the register, surname first. Matched case-insensitively as a literal substring: spacing and punctuation count, and are matched as the register stores them. A name that finds nothing is retried with its punctuation dropped. Finds people only — an agency or broker company is not on this register.\n"},"nameChinese":{"type":"string","description":"Chinese name as it appears on the register, in Traditional characters — Simplified input does not match. Matched as a substring; spacing is ignored.\n"},"externalRefId":{"type":"string","description":"Your own reference id, echoed back in the response."},"dryRun":{"type":"boolean","description":"When `true`, the register is not queried and nothing is billed: the response\ncarries a static sample record and a placeholder page print, so the body\nmirrors a real lookup exactly — only `dryRun: true` marks it. Use to\nintegrate against the contract for free.\n"}}}}}},"responses":{"200":{"description":"Exactly one register record matched.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/KycHkRegisterResult"},{"type":"object","required":["record"],"properties":{"record":{"type":"object","required":["licenceNo","name","status","licenceType"],"properties":{"licenceNo":{"type":"string","description":"Insurance intermediary licence number."},"name":{"type":"string","description":"English name as on the register."},"nameChinese":{"type":"string","description":"Chinese name as on the register, if any."},"status":{"type":"string","enum":["Active","Inactive"],"description":"Licence status. Lapsed and revoked licences are `Inactive`."},"licenceType":{"type":"string","description":"Register code, e.g. `IND`, `TRA`, `TRB`."},"licencePeriod":{"type":"object","description":"Validity period of the licence.","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"businessAddress":{"type":"string"},"businessAddressChinese":{"type":"string"},"linesOfBusiness":{"type":"string","description":"Lines of business the licence covers, as the register words it."},"suspended":{"type":"boolean"},"pendingRenewal":{"type":"boolean"},"notes":{"type":"array","description":"Notes the register publishes on the licence, verbatim — e.g. the suspension notice with its ground and effective date.","items":{"type":"object","required":["note"],"properties":{"note":{"type":"string"},"noteChinese":{"type":"string"},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date"}}}},"conditions":{"type":"array","description":"Conditions imposed on the licence.","items":{"type":"object","required":["condition"],"properties":{"condition":{"type":"string"},"conditionChinese":{"type":"string"},"effectiveFrom":{"type":"string","format":"date"},"effectiveTo":{"type":"string","format":"date"}}}},"publicDisciplinaryActions":{"type":"array","description":"Public enforcement actions of the last 5 years.","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"action":{"type":"string"},"actionChinese":{"type":"string"},"pressReleaseUrls":{"type":"array","items":{"type":"string","format":"uri"}}}}},"currentAppointments":{"type":"array","description":"Principals the licensee is currently appointed by.","items":{"type":"object","required":["appointingPrincipal"],"properties":{"appointingPrincipal":{"$ref":"#/components/schemas/IaPrincipal"},"lineOfBusiness":{"type":"string"},"appointmentDate":{"type":"string","format":"date"},"effectiveDate":{"type":"string","format":"date"},"principalType":{"type":"string"},"status":{"type":"string","enum":["Active","Inactive"]},"isResponsibleOfficer":{"type":"boolean"}}}},"appointmentHistory":{"type":"array","description":"Past and present appointments under this licence.","items":{"type":"object","required":["appointingPrincipal"],"properties":{"appointingPrincipal":{"$ref":"#/components/schemas/IaPrincipal"},"lineOfBusiness":{"type":"string"},"status":{"type":"string","enum":["Active","Inactive"]},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}}}}}}}]}}}},"400":{"description":"Bad Request — none of `licenceNo`, `name`, or `nameChinese` supplied."},"404":{"description":"No register record matched the query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KycHkRegisterError"}}}},"422":{"description":"More than one register record matched, or the query ran past the register's 1,000-record cap and its matches can no longer be counted — refine the query, ideally with `licenceNo`.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/KycHkAmbiguousMatch"},{"type":"object","required":["candidates"],"properties":{"candidates":{"type":"array","description":"The first matching records (up to 10), to help refine the query.","items":{"type":"object","required":["licenceNo","name"],"properties":{"licenceNo":{"type":"string"},"name":{"type":"string"},"nameChinese":{"type":"string"}}}}}}]}}}},"503":{"description":"The register is unavailable, or its captcha could not be solved after retries."}}}}}}
```
## CR Directors Index search - Request
> Searches the Hong Kong Companies Registry \*\*Directors Index (Director-based)\*\*: given a\
> person's name and/or partial identifier, returns every company where that person is or\
> was registered as a director, together with page prints (PDF) of the Registry's own\
> result pages.\
> \
> Unlike the other \`/kyc/hk\` register lookups, this search is \*\*asynchronous\*\*: the\
> lookup runs against the Registry in one continuous session, which takes minutes.\
> This endpoint returns a token immediately; poll\
> \[\`POST /kyc/hk/director/poll\`]\(#tag/KYC-Hong-Kong/operation/kycHkDirectorPoll) every\
> \~10 seconds for the outcome. Most searches complete within 2–5 minutes.\
> \
> \### Search modes\
> \
> The supplied fields select the Registry's own search mode:\
> \
> \| Fields supplied | Registry search mode |\
> \|---|---|\
> \| English name (\`surname\` + \`otherNames\`) and/or \`nameChinese\` only | Search by English and/or Chinese name |\
> \| \`partialHkid\` and/or \`partialPassport\` only | Search by partial identifier |\
> \| A name \*\*and\*\* a partial identifier | Exact match of all supplied fields |\
> \
> An English name needs \*\*both\*\* \`surname\` and \`otherNames\` — a surname on its own is\
> rejected (\`400\`), because the Registry will not search it without a manual confirmation\
> the automated flow cannot give. The English name and \`nameChinese\` may also be supplied\
> together. Name searches still match loosely, so several people can share a name; the\
> exact-match mode (a name \*\*and\*\* a partial identifier) is the way to refine after a \`422\`.\
> \
> \### One person, one result\
> \
> The Directors Index groups its records by identity: the same person commonly appears\
> under several name spellings, all rows carrying the same HKID / passport grouping\
> number. Rows of a single grouping resolve to \*\*one\*\* \`200\` result, with the companies\
> of all rows merged and de-duplicated by Business Registration Number. Only genuinely\
> distinct persons (distinct groupings) produce a \`422\` with one candidate per person.\
> \
> Only individual (natural person) directors are searched; body-corporate directors are\
> not covered.
```json
{"openapi":"3.1.0","info":{"title":"Fill Easy Services","version":"1.0.0"},"tags":[{"name":"KYC Hong Kong","description":"Hong Kong KYC checks, each completed in a single synchronous call: AML name screening\nagainst global watchlists, and lookups against Hong Kong's official public registers\nreturning the structured register record together with a page print (PDF) of the\nregister's own detail page.\n"}],"servers":[{"url":"sandbox.staging-api.fill-easy.com"}],"security":[{"ClientID":[],"ClientSecret":[]}],"components":{"securitySchemes":{"ClientID":{"type":"apiKey","description":"Client ID in x-client-id header.","name":"x-client-id","in":"header"}},"schemas":{"Token":{"type":"string","pattern":"^[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]*$","description":"JWT token"},"KycHkRegisterError":{"type":"object","description":"Error body of all `/kyc/hk` register lookups.","required":["message","requestId"],"properties":{"message":{"type":"string"},"requestId":{"type":"string"}}}}},"paths":{"/kyc/hk/director":{"post":{"tags":["KYC Hong Kong"],"summary":"CR Directors Index search - Request","description":"Searches the Hong Kong Companies Registry **Directors Index (Director-based)**: given a\nperson's name and/or partial identifier, returns every company where that person is or\nwas registered as a director, together with page prints (PDF) of the Registry's own\nresult pages.\n\nUnlike the other `/kyc/hk` register lookups, this search is **asynchronous**: the\nlookup runs against the Registry in one continuous session, which takes minutes.\nThis endpoint returns a token immediately; poll\n[`POST /kyc/hk/director/poll`](#tag/KYC-Hong-Kong/operation/kycHkDirectorPoll) every\n~10 seconds for the outcome. Most searches complete within 2–5 minutes.\n\n### Search modes\n\nThe supplied fields select the Registry's own search mode:\n\n| Fields supplied | Registry search mode |\n|---|---|\n| English name (`surname` + `otherNames`) and/or `nameChinese` only | Search by English and/or Chinese name |\n| `partialHkid` and/or `partialPassport` only | Search by partial identifier |\n| A name **and** a partial identifier | Exact match of all supplied fields |\n\nAn English name needs **both** `surname` and `otherNames` — a surname on its own is\nrejected (`400`), because the Registry will not search it without a manual confirmation\nthe automated flow cannot give. The English name and `nameChinese` may also be supplied\ntogether. Name searches still match loosely, so several people can share a name; the\nexact-match mode (a name **and** a partial identifier) is the way to refine after a `422`.\n\n### One person, one result\n\nThe Directors Index groups its records by identity: the same person commonly appears\nunder several name spellings, all rows carrying the same HKID / passport grouping\nnumber. Rows of a single grouping resolve to **one** `200` result, with the companies\nof all rows merged and de-duplicated by Business Registration Number. Only genuinely\ndistinct persons (distinct groupings) produce a `422` with one candidate per person.\n\nOnly individual (natural person) directors are searched; body-corporate directors are\nnot covered.\n","operationId":"kycHkDirector","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Supply an English name (`surname` **and** `otherNames` together), a `nameChinese`, a `partialHkid`, or a `partialPassport` — at least one of these.\n","properties":{"surname":{"type":"string","description":"English surname. Requires `otherNames` alongside it — the Registry rejects a surname on its own.\n"},"otherNames":{"type":"string","description":"English other names (given names), matching the Registry's own field."},"nameChinese":{"type":"string","description":"Chinese name in Traditional characters. May be combined with the English name."},"partialHkid":{"type":"string","description":"Leading characters of the HKID number, up to 5 (the Registry stores and matches only this partial form, e.g. `A123`).\n","maxLength":5},"partialPassport":{"type":"string","description":"Leading characters of the passport number."},"externalRefId":{"type":"string","description":"Your own reference id, echoed back in the poll response."},"dryRun":{"type":"boolean","description":"When `true`, no Registry order is placed and nothing is billed: the poll\nresolves at once to a static sample of the found (`200`) outcome with a\nplaceholder page print — only `dryRun: true` in the poll body marks it. Use\nto integrate against the contract for free.\n"}}}}}},"responses":{"200":{"description":"Search accepted and queued. Poll for the outcome with the returned token.\n","content":{"application/json":{"schema":{"type":"object","required":["token","requestId"],"properties":{"token":{"$ref":"#/components/schemas/Token"},"requestId":{"type":"string"}}}}}},"400":{"description":"The request could not be searched — no identity field supplied, an English name missing `surname` or `otherNames`, or a `partialHkid` longer than the Registry accepts. Rejected before any search is submitted.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KycHkRegisterError"}}}}}}}}}
```
## CR Directors Index search - Poll
> Check the status of a Directors Index search initiated via\
> \[\`POST /kyc/hk/director\`]\(#tag/KYC-Hong-Kong/operation/kycHkDirector). Returns \`202\`\
> while the search is still running; any other status is the search's final outcome,\
> carrying the same register-lookup semantics as the synchronous \`/kyc/hk\` endpoints:\
> \
> \- \`200\` — the search resolved to exactly one person: their name variants and the\
> merged company list, plus a single combined PDF of the Registry's result pages (the\
> record-list page and each company-list page).\
> \- \`404\` — the search found no records. A page print of the Registry's "No records\
> have been found" page is attached as proof of search.\
> \- \`422\` — the search matched more than one distinct person, one candidate per person.\
> Refine the query — ideally by re-submitting with a name \*\*and\*\* a partial\
> identifier (exact-match mode).\
> \- \`410\` — the result has expired (results are kept for 30 days).\
> \- \`503\` — the retrieval failed (the Registry could not be reached or the session\
> could not be completed); the case is flagged for manual follow-up.\
> \
> The page-print link is presigned for 7 days from the moment of the poll — poll again for\
> a fresh link. The underlying file is deleted after 30 days.
```json
{"openapi":"3.1.0","info":{"title":"Fill Easy Services","version":"1.0.0"},"tags":[{"name":"KYC Hong Kong","description":"Hong Kong KYC checks, each completed in a single synchronous call: AML name screening\nagainst global watchlists, and lookups against Hong Kong's official public registers\nreturning the structured register record together with a page print (PDF) of the\nregister's own detail page.\n"}],"servers":[{"url":"sandbox.staging-api.fill-easy.com"}],"security":[{"ClientID":[],"ClientSecret":[]}],"components":{"securitySchemes":{"ClientID":{"type":"apiKey","description":"Client ID in x-client-id header.","name":"x-client-id","in":"header"}},"schemas":{"Token":{"type":"string","pattern":"^[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]*$","description":"JWT token"},"KycHkPagePrint":{"type":"object","description":"A single combined PDF page print of the Registry's own result pages for this search\n(the record-list page, followed by each company-list page), as displayed at retrieval\ntime. `status: failed` when it could not be rendered — the structured result is\nunaffected either way.\n","required":["status"],"properties":{"status":{"type":"string","description":"Print status:\n- \"ready\": the print is available, `url` and `fileName` are populated\n- \"failed\": the print could not be rendered, no link is issued\n","enum":["ready","failed"]},"url":{"type":"string","format":"uri","description":"Presigned download link (only when status is \"ready\"). Valid for 7 days; the\nfile is retained for 30 days.\n"},"fileName":{"type":"string","description":"Suggested file name (only when status is \"ready\")."}}},"KycHkRegisterError":{"type":"object","description":"Error body of all `/kyc/hk` register lookups.","required":["message","requestId"],"properties":{"message":{"type":"string"},"requestId":{"type":"string"}}},"KycHkAmbiguousMatch":{"type":"object","description":"Body of the `422` every `/kyc/hk` register lookup returns when the query matched more than one record. Each endpoint adds its register-specific `candidates`.\n","required":["message","requestId","total"],"properties":{"message":{"type":"string"},"requestId":{"type":"string"},"total":{"type":"number","description":"How many records matched."}}}}},"paths":{"/kyc/hk/director/poll":{"post":{"tags":["KYC Hong Kong"],"summary":"CR Directors Index search - Poll","description":"Check the status of a Directors Index search initiated via\n[`POST /kyc/hk/director`](#tag/KYC-Hong-Kong/operation/kycHkDirector). Returns `202`\nwhile the search is still running; any other status is the search's final outcome,\ncarrying the same register-lookup semantics as the synchronous `/kyc/hk` endpoints:\n\n- `200` — the search resolved to exactly one person: their name variants and the\n merged company list, plus a single combined PDF of the Registry's result pages (the\n record-list page and each company-list page).\n- `404` — the search found no records. A page print of the Registry's \"No records\n have been found\" page is attached as proof of search.\n- `422` — the search matched more than one distinct person, one candidate per person.\n Refine the query — ideally by re-submitting with a name **and** a partial\n identifier (exact-match mode).\n- `410` — the result has expired (results are kept for 30 days).\n- `503` — the retrieval failed (the Registry could not be reached or the session\n could not be completed); the case is flagged for manual follow-up.\n\nThe page-print link is presigned for 7 days from the moment of the poll — poll again for\na fresh link. The underlying file is deleted after 30 days.\n","operationId":"kycHkDirectorPoll","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"$ref":"#/components/schemas/Token"}}}}}},"responses":{"200":{"description":"The search resolved to exactly one person.","content":{"application/json":{"schema":{"type":"object","required":["requestId","director","companies"],"properties":{"requestId":{"type":"string","description":"Unique id for this lookup, for tracking and billing reconciliation."},"externalRefId":{"type":"string","description":"Your own reference id, echoed back from the request."},"director":{"type":"object","description":"The resolved person, merged across their name-variant rows.","required":["names"],"properties":{"names":{"type":"array","description":"Every English name spelling the person's records carry.","items":{"type":"string"}},"namesChinese":{"type":"array","description":"Every Chinese name the person's records carry.","items":{"type":"string"}},"partialHkid":{"type":"string","description":"Partial HKID as the Registry stores it, without the masked tail."},"partialPassport":{"type":"string"},"passportCountry":{"type":"string","description":"Passport issuing country / region code, where stated."}}},"companies":{"type":"array","description":"Companies where the person holds or held a directorship, merged across the person's name-variant rows and de-duplicated by BRN.\n","items":{"type":"object","required":["brn","name","status","capacity"],"properties":{"brn":{"type":"string","description":"Business Registration Number."},"name":{"type":"string","description":"English company name."},"nameChinese":{"type":"string"},"status":{"type":"string","description":"Company status — `Live` or `Dissolved`; any other flag the Registry reports is passed through as-is.\n"},"capacity":{"type":"string","description":"The person's capacity at the company — `Director`; any other flag the Registry reports is passed through as-is.\n"},"remarks":{"type":"string","description":"Registry remarks on the record, where present."},"remarksChinese":{"type":"string"}}}},"dryRun":{"type":"boolean","description":"Present and `true` when the search was a dry run — sample outcome, placeholder page print, nothing billed."},"pagePrint":{"$ref":"#/components/schemas/KycHkPagePrint"}}}}}},"202":{"description":"The search is still running. Poll again in ~10 seconds.","content":{"application/json":{"schema":{"type":"object","required":["status","requestId"],"properties":{"status":{"type":"string","enum":["processing"]},"requestId":{"type":"string"}}}}}},"404":{"description":"The search found no records. The search is still billed; a page print of the \"No records have been found\" page is attached as proof of search.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/KycHkRegisterError"},{"type":"object","properties":{"pagePrint":{"$ref":"#/components/schemas/KycHkPagePrint"}}}]}}}},"410":{"description":"The result has expired — results are kept for 30 days.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KycHkRegisterError"}}}},"422":{"description":"The search matched more than one distinct person.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/KycHkAmbiguousMatch"},{"type":"object","required":["candidates"],"properties":{"candidates":{"type":"array","description":"One entry per distinct person the search matched.","items":{"type":"object","required":["name","companyCount"],"properties":{"name":{"type":"string","description":"English name of the person's first record."},"nameChinese":{"type":"string"},"partialHkid":{"type":"string"},"partialPassport":{"type":"string"},"companyCount":{"type":"number","description":"Directorship records across the person's rows, as counted by the Registry (a company can recur under several name spellings, so this can exceed the number of distinct companies).\n"}}}},"pagePrint":{"$ref":"#/components/schemas/KycHkPagePrint"}}}]}}}},"503":{"description":"The retrieval failed — the Registry was unreachable, or its captcha or payment could not be completed. The case is flagged for manual follow-up.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KycHkRegisterError"}}}}}}}}}
```