Zetl APIKYC Information
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.
During borrower onboarding process, you are required to supply country-specific KYC information before submitting a funding application.
Supported Countries
Currently Zetl Embedded API only supports Hong Kong 🇭🇰 and Malaysia 🇲🇾 We're working on expanding our API to other countries!
This guide will supply Hong Kong KYC information relevant to the created Customer from previous step.
Sending KYC data
Sending KYC information is a two step process. First step is to send standard text-format KYC information. Second step is to provide supporting documents. Zetl API provides two separate endpoints for this.
Example request for supplying KYC information:
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"
}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"
}'Successful API call will return the following response body in JSON format:
{
"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"
}INFO
Refer to KYC resource for a detailed description of each property on the request and response body.
Uploading supporting documents
As shown in the response example above, current kyc state is missing_supporting_documents you are now required to upload supporting documents for each document type to complete KYC onboarding process.
You can use our upload KYC documents API endpoint to perform upload for each supporting documents type.
TIP
Following API calls need to be performed using multipart/form-data content type as you'll be transferring binary data.
INFO
Request idempotency feature is currently only supported for our application/json endpoints.
Here are a few examples on how to perform file uploads for shareholder_address_proof supporting documents:
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--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.
We limit 10 files per upload request and limit maximum request body to 100MB but each files can be of any size. Each file part must follow ^file[1-9]?$ regex pattern as their name, and with NO duplicating field name should be present.
On successful API call it will return following response body in JSON format:
{
"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"
}
]
}INFO
Refer to KYC resource for a detailed description of each property on the request and response body.
After finishing uploading all required supporting documents, you can then start Submitting a Funding Request