Skip to content

KYC

Customer KYC endpoints are available only for SESSION_CUSTOMER.

The terminal flow is:

  1. Upload a file with POST /upload.
  2. Receive file_id.
  3. Read current KYC state with GET /customer/kyc.
  4. Open a step detail with GET /customer/kyc/steps/{id} when the UI needs full step data and attached documents.
  5. Attach the file to KYC with POST /customer/kyc/documents.
  6. Submit questionnaire answers with POST /customer/kyc/steps/{id}/submit.
  7. Refresh current state with GET /customer/kyc.

KYC is scoped to the authenticated customer. The server verifies that uploaded files belong to the customer before attaching them to a KYC profile.

Endpoints

Method Route Description
GET /customer/kyc Current profile, steps and documents
GET /customer/kyc/steps/{id} One step with related documents
POST /customer/kyc/steps/{id}/submit Submit step answers
GET /customer/kyc/documents List customer KYC documents
POST /customer/kyc/documents Attach uploaded file to KYC

Upload Flow

POST /upload accepts multipart/form-data and requires a valid session token.

The server stores the file in storage/<uuid>.<ext>, registers metadata in StorageManager, and returns file_id.

Example response:

{
  "file_name": "2d8b3e5c-5b02-43f4-8b31-1a1cc33c7d12.pdf",
  "file_id": "2d8b3e5c-5b02-43f4-8b31-1a1cc33c7d12",
  "files": [
    {
      "uuid": "2d8b3e5c-5b02-43f4-8b31-1a1cc33c7d12",
      "storage_name": "2d8b3e5c-5b02-43f4-8b31-1a1cc33c7d12.pdf",
      "original_name": "passport.pdf",
      "extension": "pdf",
      "signature": "application/pdf",
      "content_type": "application/pdf",
      "file_size": 245000,
      "checksum": "..."
    }
  ]
}

Allowed extensions include png, jpg, jpeg, gif, webp, svg, ico, pdf, txt, csv, doc, docx, xls, and xlsx. The server checks the real file signature and does not trust the extension alone.

Status Values

Profile, step, document and risk enums are documented in the manager KYC API section.