Query supplementary document templates, upload proof, and submit JSON. Both L1 and L2 support an API-only flow.

KYC Supplementary Documents

Merchants use GET /v1/kyc/supplements to obtain each pending request's id, level, message, and fields template with index, then upload proof and call POST /v1/kyc/supplements/{id} to submit JSON. Both L1 and L2 are supported.

Use GET /v1/kyc/supplements for pending supplementary requests. Example entry:

{
  "id": "ksup_456",
  "level": "L2",
  "message": "请补充证明材料",
  "fields": [
    { "index": 0, "label": "资金来源说明", "type": "text", "required": true },
    { "index": 1, "label": "补充证明", "type": "photo", "required": true }
  ],
  "created_at": "2026-09-24T12:05:00.000Z",
  "expires_in_days": 14
}

The actual response is {data: [条目], next_cursor: null, has_more: false} and retains the compatibility field hosted_url, which API-only clients can ignore. The list contains both L1 and L2 entries, distinguished by level. Expiration is 14 days after creation; expires_in_days is a fixed policy, not the remaining number of days.

Upload supplementary proof first, then call POST /v1/kyc/supplements/{id} (the id in this example is ksup_456):

{
  "answers": [
    { "index": 0, "value": "工资收入及储蓄，详见附件" },
    { "index": 1, "value": "<补充证明 file_url>" }
  ]
}

Submit using the server template's index, not a translated label as the field identifier. text allows up to 500 characters; photo uses a file URL uploaded for the current member. required=true fields must be filled; optional fields may be omitted. index values must not repeat or fall outside the template range.

Success returns HTTP 200: {"id":"ksup_456","level":"L2","status":"submitted"}. The request and review state update atomically, entering supplementary review. Retrying unchanged with the same idempotency key returns the original result; resubmitting a completed request with a new key returns state_invalid.

See the L2 Integration Guide for complete authentication, upload, and error rules.