Upload KYC Images
POST/openapi/v2/users/uploadKycImage| Item | Value |
|---|---|
| HTTP method | POST |
| Request path | /openapi/v2/users/uploadKycImage |
| Request type | multipart/form-data |
Request parameters
| Field | Type | Required | Description |
|---|---|---|---|
file | file | Yes | One file per request, up to 6MB. Accepted formats depend on the purpose and supporting-document type below. |
purpose | string | No | File purpose: DOCUMENT_FRONT, DOCUMENT_BACK, SELFIE, or SUPPORTING_DOCUMENT. If omitted, primary-document image rules apply. |
supportingDocumentType | string | Conditional | Supporting-proof category, not the primary identity-document type. Required when purpose=SUPPORTING_DOCUMENT; omit for other purposes. See the values below. |
Use an empty string for RAW_BODY when signing. See Authentication and signatures.
File purpose purpose
| Value | Purpose | Accepted formats | supportingDocumentType |
|---|---|---|---|
| Omitted | Apply primary-document image validation | JPG, JPEG, PNG | Omit |
DOCUMENT_FRONT | Primary document, front | JPG, JPEG, PNG | Omit |
DOCUMENT_BACK | Primary document, back | JPG, JPEG, PNG | Omit |
SELFIE | Selfie | JPG, JPEG, PNG | Omit |
SUPPORTING_DOCUMENT | Supporting proof | Depends on the type below | Required |
Supporting-proof type supportingDocumentType
Choose the actual material type; there is no default. Values are case-sensitive and must use the uppercase spelling below.
| Material | Value | Accepted formats |
|---|---|---|
| Valid Hong Kong work visa | WORK_VISA | PDF only |
| Employment contract | EMPLOYMENT_CONTRACT | PDF only |
| Salary payslip | SALARY_PAYSLIP | PDF only |
| Tenancy agreement | TENANCY_AGREEMENT | PDF only |
| Address proof | ADDRESS_PROOF | PDF only |
| Bank statement | BANK_STATEMENT | PDF only |
| Proof of visit | PROOF_OF_VISIT | PDF only |
| Hong Kong immigration endorsement | IMMIGRATION_ENDORSEMENT | JPG, JPEG, PNG, PDF |
| Travel permit, front | TRAVEL_PERMIT_FRONT | JPG, JPEG, PNG, PDF |
| Travel permit, back | TRAVEL_PERMIT_BACK | JPG, JPEG, PNG, PDF |
UTILITY_BILL is not supported by the current upload endpoint. The file extension, declared MIME type, and actual content must agree. If MIME is omitted or set to application/octet-stream, the extension and content are still checked. Renaming an image to .pdf does not convert it to PDF.
Request examples
These examples show multipart/form-data fields. Send file as an actual file, not a path string. Authentication headers are still required.
Upload the front of a primary document; omit supportingDocumentType:
file: front.jpg (file, image/jpeg)
purpose: DOCUMENT_FRONTUpload a bank statement as PDF:
file: statement.pdf (file, application/pdf)
purpose: SUPPORTING_DOCUMENT
supportingDocumentType: BANK_STATEMENTUse the returned url, not previewUrl, in Submit User KYC. For supporting proof, keep documentType consistent with the upload's supportingDocumentType, as in this KYC request fragment:
{
"supportingDocuments": [
{
"documentType": "BANK_STATEMENT",
"fileUrl": "url returned by the upload endpoint"
}
]
}Upload travel-permit sides separately, then include both TRAVEL_PERMIT_FRONT and TRAVEL_PERMIT_BACK in supportingDocuments when submitting KYC. A successful upload means the file passed upload validation; it does not mean KYC approval.
Response data
| Field | Type | Description |
|---|---|---|
success | boolean | Whether processing succeeded. |
code | string | Platform response code. |
message | string | Platform response message. |
url | string | Stable file URL for storage and KYC submission. Private files cannot be previewed anonymously using this URL. |
previewUrl | string | Preview URL. Private buckets return a temporary signed GET URL valid for 120 seconds. Use it only for preview, never for KYC submission. |
previewExpiresAt | string / null | Preview signature expiration in UTC ISO 8601 format, for example 2026-10-12T02:02:00Z. Null when no signature is generated. |
contentType | string | File MIME type. |
size | integer | File size in bytes. |
originalName | string | Original file name. |
The preview URL and expiration come from the same signature. For public storage configurations, previewUrl equals url and previewExpiresAt is null. New reads fail after the signature expires. This endpoint does not refresh preview signatures.
Input validation errors: V2 common responses.
