Skip to content

Upload KYC Images ​

POST /openapi/v2/users/uploadKycImage
ItemValue
HTTP methodPOST
Request path/openapi/v2/users/uploadKycImage
Request typemultipart/form-data

Request parameters ​

FieldTypeRequiredDescription
filefileYesOne file per request, up to 6MB. Accepted formats depend on the purpose and supporting-document type below.
purposestringNoFile purpose: DOCUMENT_FRONT, DOCUMENT_BACK, SELFIE, or SUPPORTING_DOCUMENT. If omitted, primary-document image rules apply.
supportingDocumentTypestringConditionalSupporting-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 ​

ValuePurposeAccepted formatssupportingDocumentType
OmittedApply primary-document image validationJPG, JPEG, PNGOmit
DOCUMENT_FRONTPrimary document, frontJPG, JPEG, PNGOmit
DOCUMENT_BACKPrimary document, backJPG, JPEG, PNGOmit
SELFIESelfieJPG, JPEG, PNGOmit
SUPPORTING_DOCUMENTSupporting proofDepends on the type belowRequired

Supporting-proof type supportingDocumentType ​

Choose the actual material type; there is no default. Values are case-sensitive and must use the uppercase spelling below.

MaterialValueAccepted formats
Valid Hong Kong work visaWORK_VISAPDF only
Employment contractEMPLOYMENT_CONTRACTPDF only
Salary payslipSALARY_PAYSLIPPDF only
Tenancy agreementTENANCY_AGREEMENTPDF only
Address proofADDRESS_PROOFPDF only
Bank statementBANK_STATEMENTPDF only
Proof of visitPROOF_OF_VISITPDF only
Hong Kong immigration endorsementIMMIGRATION_ENDORSEMENTJPG, JPEG, PNG, PDF
Travel permit, frontTRAVEL_PERMIT_FRONTJPG, JPEG, PNG, PDF
Travel permit, backTRAVEL_PERMIT_BACKJPG, 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:

text
file:    front.jpg (file, image/jpeg)
purpose: DOCUMENT_FRONT

Upload a bank statement as PDF:

text
file:                   statement.pdf (file, application/pdf)
purpose:                SUPPORTING_DOCUMENT
supportingDocumentType: BANK_STATEMENT

Use 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:

json
{
  "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 ​

FieldTypeDescription
successbooleanWhether processing succeeded.
codestringPlatform response code.
messagestringPlatform response message.
urlstringStable file URL for storage and KYC submission. Private files cannot be previewed anonymously using this URL.
previewUrlstringPreview URL. Private buckets return a temporary signed GET URL valid for 120 seconds. Use it only for preview, never for KYC submission.
previewExpiresAtstring / nullPreview signature expiration in UTC ISO 8601 format, for example 2026-10-12T02:02:00Z. Null when no signature is generated.
contentTypestringFile MIME type.
sizeintegerFile size in bytes.
originalNamestringOriginal 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.