KYC

INFO

This documentation is work in progress and subject to change. If you have any questions or feedback, please reach out to us via Support.

This object represents KYC information of your HK 🇭🇰 customer.

Supported Countries

Currently Zetl Embedded API only supports Hong Kong 🇭🇰 and Malaysia 🇲🇾 We're working on expanding our API to other countries!

KYC Object

Property	Type	Description
customer_id	string	Zetl-generated customer ID
type	string \| "HK"	KYC country type
status	string (enum)	KYC status. Possible values: `incomplete`, `missing_supporting_documents`, `complete`
legal_name	string	Legal name of the company
registered_address	Address	Registered address of the company
operating_address	Address?	Operating address of the company
website	string?	Company website
business_registration_number	string	Business registration number
date_of_incorporation	string	Date of incorporation
directors_identity_number	array of Director Identity	Identity number of directors
shareholders_identity_number	array of Shareholder Identity)	Identity number of major shareholders with ≥25% ownership of company shares
corporate_entities_number	numeric	Number of related corporate entities (0 if there are no related corporate entities)
isic	string	Company ISIC code
is_sensitive_business	boolean? \| null	Flag to show whether company runs a sensitive business
has_complex_structure	boolean? \| null	Flag to show whether company has a complex structure
has_namescan_hits	boolean? \| null	Flag to show whether director has namescan screening hits
dow_jones_company_screening_result	object?	Dow Jones company screening result. Optional (Partner-supplied information in any valid JSON key-value format)
dow_jones_batch_screening_result	object?	Dow Jones batch screening result. Optional (Partner-supplied information in any valid JSON key-value format)
supporting_documents	object (See: Supporting Documents)	Status of each supporting documents available for the KYC type
created_at	string	Resource creation ISO datetime string (UTC)
updated_at	string	Resource last modified ISO datetime string (UTC)

Address Object

Property	Type	Description
address_line_1	string	First line address information
address_line_2	string?	Second line address information
address_line_3	string?	Third line address information
postal_code	string	Postal code
city	string	City
country	string	Country

Director Identity Object

Property	Type	Description
type	string (enum)	Identity type. Currently supported type: `national_id`, `passport`, `driver_license`
id	string	Identity number

Shareholder Identity Object

Property	Type	Description
company_legal_name	string	Company legal name where this shareholder belongs to, use the same value with `legal_name` for shareholder that belongs to the current company.
type	string (enum)	Identity type. Currently supported type: `national_id`, `passport`, `driver_license`
id	string	Identity number

Supporting Documents Object

This property list the status of each supporting documents related with the KYC resource. The key represents the name of the type of the document with its value represents the status of the supporting document.

The possible status values of each supporting documents are: missing, not_uploaded, uploaded.

You can see list of available supporting documents for HK KYC below:

Document Type	Description
business_registration_certificate	Required. Business registration certificate
directors_identity	Required. Director's identity documents
directors_address_proof	Required. Director's address proof documents
shareholders_identity	Required. Shareholder's identity documents
shareholders_address_proof	Required. Shareholder's address proof documents
company_structure_chart	Required. Company structure chart
litigation_history	Optional. Litigation history document
nnc1	Required. Incorporation Form
nar1	Required. Annual Return Form

KYC Object Example

JSON

json

{
  "customer_id": "b8a1dfe0-c575-4d5c-9840-2fca96b5d96a",
  "type": "HK",
  "status": "missing_supporting_documents",
  "legal_name": "Foo Bar Ltd",
  "registered_address": {
    "address_line_1": "123, Baz Qux Street",
    "address_line_2": "",
    "address_line_3": "",
    "postal_code": "999077",
    "city": "Wan Chai",
    "country": "Hong Kong"
  },
  "operating_address": {
    "address_line_1": "123, Baz Qux Street",
    "address_line_2": "",
    "address_line_3": "",
    "postal_code": "999077",
    "city": "Wan Chai",
    "country": "Hong Kong"
  },
  "website": "https://www.example.com",
  "business_registration_number": "12345678A",
  "date_of_incorporation": "2019-01-01",
  "directors_identity_number": [
    {
      "type": "national_id",
      "id": "Z1234567"
    }
  ],
  "shareholders_identity_number": [
    {
      "company_legal_name": "Foo Bar Ltd",
      "type": "national_id",
      "id": "V1234567"
    },
    {
      "company_legal_name": "Foo Bar Parent Ltd",
      "type": "national_id",
      "id": "X1234567"
    }
  ],
  "corporate_entities_number": 0,
  "isic": "7371",
  "is_sensitive_business": null,
  "has_complex_structure": null,
  "namescan_result": null,
  "dow_jones_company_screening_result": {},
  "dow_jones_batch_screening_result": {},
  "supporting_documents": {
    "company_structure_chart": "missing",
    "business_registration_certificate": "missing",
    "nnc1": "missing",
    "nar1": "missing",
    "directors_identity": "missing",
    "directors_address_proof": "missing",
    "shareholders_identity": "missing",
    "shareholders_address_proof": "missing",
    "litigation_history": "not_uploaded"
  },
  "created_at": "2023-12-01T00:01:00Z",
  "updated_at": "2023-12-01T00:01:00Z"
}

Retrieve a KYC resource

GET /v1/kyc/hk/{customer_id}

https://api.zetl.com/v1/kyc/hk/{customer_id}

Get KYC details of your customer.

Response Properties

Refer to KYC object

Possible Error

See Handling Error for generic possible errors.

Update a KYC

PUT /v1/kyc/hk/{customer_id}

https://api.zetl.com/v1/kyc/hk/{customer_id}

Update KYC information for your HK customer. This endpoint expect you to fully send the complete KYC properties with its updated values.

Request Properties

Property	Type	Description
customer_id	string	Zetl-generated customer ID
legal_name	string	Legal name of the company
registered_address	Address	Registered address of the company
operating_address	Address?	Operating address of the company
website	string?	Company website
business_registration_number	string	Business registration number
date_of_incorporation	string	Date of incorporation
directors_identity_number	array of Director Identity	Identity number of directors
shareholders_identity_number	array of Shareholder Identity)	Identity number of major shareholders with ≥25% ownership of company shares
corporate_entities_number	numeric	Number of related corporate entities (0 if there are no related corporate entities)
isic	string	Company ISIC code
is_sensitive_business	boolean? \| null	Flag to show whether company runs a sensitive business
has_complex_structure	boolean? \| null	Flag to show whether company has a complex structure
has_namescan_hits	boolean? \| null	Flag to show whether director has namescan screening hits
dow_jones_company_screening_result	object?	Dow Jones company screening result. Optional (Partner-supplied information in any valid JSON key-value format)
dow_jones_batch_screening_result	object?	Dow Jones batch screening result. Optional (Partner-supplied information in any valid JSON key-value format)

Request Example

HTTPcurl

http

PUT /v1/kyc/hk/b8a1dfe0-c575-4d5c-9840-2fca96b5d96a HTTP/1.1
Host: api.zetl.com
Content-Type: application/json
Authorization: Bearer <your-private-key>

{
  "legal_name": "Foo Bar Ltd",
  "registered_address": {
    "address_line_1": "123, Baz Qux Street",
    "address_line_2": "",
    "address_line_3": "",
    "postal_code": "999077",
    "city": "Wan Chai",
    "country": "Hong Kong"
  },
  "operating_address": {
    "address_line_1": "123, Baz Qux Street",
    "address_line_2": "",
    "postal_code": "999077",
    "city": "Wan Chai",
    "country": "Hong Kong"
  },
  "website": "https://www.example.com",
  "business_registration_number": "12345678A",
  "date_of_incorporation": "2019-01-01",
  "directors_identity_number": [
    {
      "type": "national_id",
      "id": "Z1234567"
    }
  ],
  "shareholders_identity_number": [
    {
      "company_legal_name": "Foo Bar Ltd",
      "type": "national_id",
      "id": "V1234567"
    },
    {
      "company_legal_name": "Foo Bar Parent Ltd",
      "type": "national_id",
      "id": "X1234567"
    }
  ],
  "corporate_entities_number": 1,
  "isic": "7371"
}

shell

curl --request PUT \
  --url https://api.zetl.com/v1/kyc/hk/b8a1dfe0-c575-4d5c-9840-2fca96b5d96a \
  --header 'Authorization: Bearer <your-private-key>' \
  --header 'Content-Type: application/json' \
  --data '{
	"legal_name": "Foo Bar Ltd",
	"registered_address": {
    "address_line_1": "123, Baz Qux Street",
    "address_line_2": "",
    "address_line_3": "",
    "postal_code": "999077",
    "city": "Wan Chai",
    "country": "Hong Kong"
	},
	"operating_address": {
		"address_line_1": "123, Baz Qux Street",
    "address_line_2": "",
    "postal_code": "999077",
    "city": "Wan Chai",
    "country": "Hong Kong"
	},
  "website": "https://www.example.com",
  "business_registration_number": "12345678A",
  "date_of_incorporation": "2019-01-01",
  "directors_identity_number": [
		{ "type": "national_id", "id": "Z1234567" }
	],
  "shareholders_identity_number": [
    {
			"company_legal_name": "Foo Bar Ltd",
      "type": "national_id",
      "id": "V1234567"
    },
    {
			"company_legal_name": "Foo Bar Parent Ltd",
      "type": "national_id",
      "id": "X1234567"
    }
  ],
	"corporate_entities_number": 1,
  "isic": "7371"
}'

Response Properties

Refer to KYC object

Possible Error

See Handling Error for generic possible errors.

KYC Documents

Upload KYC Documents

POST /v1/kyc/documents/{customer_id}

https://api.zetl.com/v1/kyc/documents/{customer_id}

Upload one type of supporting document for the customer KYC. (Max 10 documents per request). We limit 10 files per upload request and limit maximum request body to 100MB but each files can be of any size.

Unlike other endpoints which uses application/json as its content type, this endpoint require you to send multipart/form-data request.

Documents Upload Mechanism

A single upload request may only contain a single document type, which might consist of multiple files, and should always be uploaded together in a single request.

For example, you should upload director_identity documents for several people in a single request (preferably in the same order as directors_identity_number information).

Uploading documents will overwrite any existing documents of the same document type that might have been previously uploaded before.

Request Body

The endpoint expect request using multipart/form-data body with the following form parts:

Part	Type	Description
metadata	object	Metadata of the upload request. See Metadata Part for more details.
Regex: `^file[1-9]?$`	file	File(s) to be uploaded, at least one file, up to 10 files (`file`, `file1`, `file2`, ...., `file9`), with NO duplicating field name should be present.

Metadata Part

The metadata of the upload request with the following properties:

Property	Type	Description
type	string	Type of the uploaded document(s). See Supporting Documents Object to check available document types.
files	object	Metadata of the uploaded file(s), corresponding the uploaded file(s). See Files Metadata Field for more details.

Files Metadata Property

The files property value contains request's uploaded files metadata that's represented as JSON object which contains keys that corresponds to the uploaded file(s) part name in the same request matching that match regex rule ^file[1-9]?$ (Ex: file, file1, file2, ...., file9).

NO duplicating part name should be present. The value of each key is an object with the following properties:

Property	Type	Description
filename	string	Filename of the uploaded file (without extension, we are going to append the extension ourselves based on `mime_type` key sent).
mime_type	string	Mime type of the uploaded file.
hash	string	SHA-256 hash result of the uploaded file content.

Supported Mime Types

Currently, we only support the following types:

image/jpeg
image/png
application/pdf

Request Example

HTTPcurl

http

POST /v1/kyc/documents/b8a1dfe0-c575-4d5c-9840-2fca96b5d96a HTTP/1.1
Host: api.zetl.com
Authorization: Bearer <your-private-key>
Content-Type: multipart/form-data; boundary=------WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="metadata"

{"type": "shareholders_address_proof", "files": {"file": {"filename": "ShareholderAddressProof", "hash": "046a9aaa83711158c3c4afa585a30be3bee8a34231ee72caac625faef48b4abe", "mime_type": "image/png"}, "file1": {"filename": "ShareholderAddressProof1", "hash": "146a9aaa83711158c3c4afa585a30be3bee8a34231ee72caac625faef48b4abf", "mime_type": "image/png"}}}
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="ShareholderAddressProof.png"
Content-Type: image/png

<binary data>
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file1"; filename="ShareholderAddressProof1.png"
Content-Type: image/png

<binary data>
------WebKitFormBoundary7MA4YWxkTrZu0gW--

shell

curl --request \
  --url https://api.zetl.com/v1/kyc/documents/b8a1dfe0-c575-4d5c-9840-2fca96b5d96a \
  --header 'Authorization: Bearer <your-private-key>' \
  --form 'metadata={"type": "shareholders_address_proof", "files": {"file": {"filename": "ShareholderAddressProof", "hash": "046a9aaa83711158c3c4afa585a30be3bee8a34231ee72caac625faef48b4abe", "mime_type": "image/png"}, "file1": {"filename": "ShareholderAddressProof1", "hash": "146a9aaa83711158c3c4afa585a30be3bee8a34231ee72caac625faef48b4abf", "mime_type": "image/png"}}}' \
  --form 'file=@ShareholderAddressProof.png;type=image/png' \
  --form 'file1=@ShareholderAddressProof1.png;type=image/png'

WARNING

Do not manually set Content-Type header, as it might be missing required boundary value. Let your request package/library automatically detect the content type so that it can automatically generate properly formed Content-Type header.

We also highly recommend to put required metadata field part first on top of the request body before placing any binary data.

Response Example

JSON

json

{
  "type": "shareholder_address_proof",
  "files": [
    {
      "document_id": "47a62de6-0b5f-4db1-9350-887238641066",
      "filename": "2023-04-04T204749.204Z-ShareholderAddressProof.png",
      "mime_type": "image/png"
    },
    {
      "document_id": "070da6a1-2d95-4967-ae75-e278c813e61d",
      "filename": "2023-04-04T204749.204Z-ShareholderAddressProof1.png",
      "mime_type": "image/png"
    }
  ]
}

Possible Error

See Handling Error for generic possible errors.

Code	Description
body_invalid	Metadata part is a malformed JSON object.
metadata_duplicate	Request has more than one part with the same "metadata" field name
metadata_invalid	Metadata has invalid, or unknown properties
file_missing	Request has no file part or missing a valid `^file[1-9]?$` file part that's described inside metadata.
file_duplicate	Request has more than one file part with the same field name.
file_metadata_missing	Request has file part with missing file metadata.
file_metadata_unknown	Request files metadata has unknown property (violates `^file[1-9]?$`).
file_metadata_invalid	File metadata object has one or more invalid/missing/unknown parameters.
file_signature_invalid	Uploaded file and metadata hash signature mismatched.

Error Example

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "file_missing",
    "message": "At least one file must be submitted. Please refer to https://docs.zetl.com/embedded/references/kyc for more information."
  }
}

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "file_duplicate",
    "message": "Field name \"file\" is used more than once. Please refer to https://docs.zetl.com/embedded/references/kyc for more information."
  }
}

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "metadata_duplicate",
    "message": "Field name \"metadata\" is used more than once. Please refer to https://docs.zetl.com/embedded/references/kyc for more information."
  }
}

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "file_metadata_invalid",
    "message": "File metadata property \"files.file\" invalid. Please refer to https://docs.zetl.com/embedded/references/kyc for more information."
  }
}

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "file_metadata_unknown",
    "message": "File metadata property \"rogue_metadata\" unknown. Please refer to https://docs.zetl.com/embedded/references/kyc for more information."
  }
}

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "file_signature_invalid",
    "message": "File \"file1\" signature mismatch. Please refer to https://docs.zetl.com/embedded/references/kyc for more information."
  }
}

Possible Error

See Handling Error for generic possible errors.

Download KYC Documents

GET /v1/kyc/documents/{customer_id}/{document_id}

https://api.zetl.com/v1/kyc/documents/{customer_id}/{document_id}

Response Properties

Property	Type	Description
document_id	string	The unique identifier of the document.
type	string	The document type of the uploaded file. See Supporting Documents List)
filename	string	Final filename of the uploaded file (with appended extension and generated identifier by us).
mime_type	string	Mime type of the uploaded file.
url	string	Pre-signed URL to download the file. Expire in 5 minutes.

Response Example

JSON

json

{
  "document_id": "47a62de6-0b5f-4db1-9350-887238641066",
  "type": "shareholders_address_proof",
  "filename": "2023-04-04T204749.204Z-ShareholderAddressProof.png",
  "mime_type": "image/png",
  "url": "<pre-signed short-lived downloadable link>"
}

Possible Error

See Handling Error for generic possible errors.

Retrieve KYC Documents Information

GET /v1/kyc/documents/{customer_id}

https://api.zetl.com/v1/kyc/documents/{customer_id}

Get list of uploaded KYC supporting documents summary of a customer.

Response Properties

Refer to Supporting Documents Object for possible key, and array of KYC Document summary as value.

Response Example

JSON

json

{
  "business_registration_certificate": [],
  "directors_identity": [],
  "directors_address_proof": [],
  "shareholders_identity": [],
  "shareholders_address_proof": [
    {
      "document_id": "47a62de6-0b5f-4db1-9350-887238641066",
      "filename": "2023-04-04T204749.204Z-ShareholderAddressProof.png",
      "mime_type": "image/png"
    },
    {
      "document_id": "070da6a1-2d95-4967-ae75-e278c813e61d",
      "filename": "2023-04-04T204749.204Z-ShareholderAddressProof1.png",
      "mime_type": "image/png"
    }
  ],
  "company_structure_chart": [],
  "litigation_history": [],
  "nnc1": [],
  "nar1": []
}

KYC

KYC ​

KYC Object ​

Address Object ​

Director Identity Object ​

Shareholder Identity Object ​

Supporting Documents Object ​

KYC Object Example ​

Retrieve a KYC resource ​

Response Properties ​

Possible Error ​

Update a KYC ​

Request Properties ​

Request Example ​

Response Properties ​

Possible Error ​

KYC Documents ​

Upload KYC Documents ​

Request Body ​

Metadata Part ​

Files Metadata Property ​

Request Example ​

Response Example ​

Possible Error ​

Error Example ​

Possible Error ​

Download KYC Documents ​

Response Properties ​

Response Example ​

Possible Error ​

Retrieve KYC Documents Information ​

Response Properties ​

Response Example ​

KYC

KYC Object

Address Object

Director Identity Object

Shareholder Identity Object

Supporting Documents Object

KYC Object Example

Retrieve a KYC resource

Response Properties

Possible Error

Update a KYC

Request Properties

Request Example

Response Properties

Possible Error

KYC Documents

Upload KYC Documents

Request Body

Metadata Part

Files Metadata Property

Request Example

Response Example

Possible Error

Error Example

Possible Error

Download KYC Documents

Response Properties

Response Example

Possible Error

Retrieve KYC Documents Information

Response Properties

Response Example