# Hong Kong

Hong Kong eKYB validates the legitimacy of Hong Kong businesses by checking their tax ID (CR number), business name, address, UBOs, and directors against Hong Kong's government database.

Incode supports input in Chinese, English, and Pinyin.

## Source

| Country   | Source                        | Description                                                                                |
| --------- | ----------------------------- | ------------------------------------------------------------------------------------------ |
| Hong Kong | Hong Kong government database | Verifies submitted business details against records maintained in the government database. |

## Direct API approach

For general integration notes and shared response semantics, see the [eKYB API Reference](https://developer.incode.com/docs/ekyb-api-reference).

### Request parameters

| Parameter      | Required  | Description                                                                                                                                                                                              |
| -------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plugins`      | Mandatory | Array. Must be `["ekyb"]`.                                                                                                                                                                               |
| `country`      | Mandatory | String. Two-letter Alpha-2 country code. Must be `HK`.                                                                                                                                                   |
| `taxId`        | Mandatory | String. Hong Kong CR number (8 digits, e.g. `12345678`). Extended formats such as `12345678-000-09-20-3`, `12345678-000-11-23-A`, and `1234567800007210` are accepted; only the first 8 digits are used. |
| `businessName` | Mandatory | String. Name of the business.                                                                                                                                                                            |
| `addressLine2` | Optional  | String. Full business address, including house number, street, city, state, and postal code.                                                                                                             |
| `uboNames`     | Optional  | Array. Full legal names of Unique Beneficial Owners to check against records associated with the CR number.                                                                                              |
| `directors`    | Optional  | Array. Full legal names of directors to check against records associated with the CR number.                                                                                                             |

The `country` parameter limits business validation to the specified region. Only businesses established in the country specified in the eKYB request are validated.

### Sample request

```json
{
  "plugins": ["ekyb"],
  "country": "HK",
  "taxId": "12345678",
  "businessName": "Dummy Company Limited",
  "addressLine2": "105-111 MAIN ROAD, WAN CHAI, Hong Kong, 999077",
  "uboNames": ["Lin Xi Wein"],
  "directors": ["Andrew Chang"]
}
```

### Sample response

```json
{
  "kyb": [
    { "key": "name", "sub_label": "Verified" },
    { "key": "tin", "sub_label": "Verified" },
    { "key": "address_verification", "sub_label": "Verified" },
    { "key": "registrationStatus", "sub_label": "Active" },
    {
      "key": "entityType",
      "entityType": { "entityType": "Private company limited by shares" }
    },
    {
      "key": "ubo_name_match",
      "sub_label": "Verified",
      "uboName_input": "Li Xi Wein",
      "ubo_ownership": "100.00%"
    },
    {
      "key": "directors_name_match",
      "sub_label": "Unverified",
      "directorsName_input": "Andrei Blang"
    }
  ]
}
```

### Response fields

| Key                    | Status                                        | Description                                                                                                                                    |
| ---------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                 | `Verified`, `Approximate Match`, `Unverified` | Submitted business name against the business name associated with the CR number.                                                               |
| `tin`                  | `Verified`, `Unverified`                      | Submitted CR number against the government database.                                                                                           |
| `address_verification` | `Verified`, `Approximate Match`, `Unverified` | Submitted address against the address associated with the CR number.                                                                           |
| `registrationStatus`   | `Active`, `Inactive`, `Unknown`               | Registration status of the business in the government database. See [Registration status values](#registration-status-values) for definitions. |
| `entityType`           | Legal entity type of the business             | The legal entity type of the company, if available (e.g. Private company limited by shares). If not available, displays `Unknown`.             |
| `ubo_name_match`       | `Verified`, `Approximate Match`, `Unverified` | Submitted UBO against UBOs associated with the CR number. Distinguished by the `uboName_input` field on each entry.                            |
| `ubo_ownership`        | Percentage                                    | Ownership percentage of the matched UBO, as recorded in the government database. Returned on `ubo_name_match` entries where a match is found.  |
| `directors_name_match` | `Verified`, `Approximate Match`, `Unverified` | Submitted director against directors associated with the CR number. Distinguished by the `directorsName_input` field on each entry.            |

### Registration status values

| Status   | Description                                                                         |
| -------- | ----------------------------------------------------------------------------------- |
| Active   | The business registration is active.                                                |
| Inactive | The business registration is suspended, inactive, or the business no longer exists. |
| Unknown  | Registration status is not available.                                               |

### Approximate Match

`Approximate Match` is generated through Incode's proprietary fuzzy matching algorithm. It is returned when the submitted string is similar to, but not an exact match for, the value stored in the government database. This accounts for misspellings, typographical errors, and slight variations in input data.

### Error responses

See the [eKYB API Reference](https://developer.incode.com/docs/ekyb-api-reference) for standard error responses.

Custom 400 responses include `taxId and country are minimum required fields.` when `taxId`, `country`, or `businessName` is missing or empty.

## Single Session Dashboard results

View eKYB results on the Business tab in [single Session view](/dashboard-platform-administration/single-session-view/).