KYC Manager API

The KYC manager API is used by BackOffice and CRM managers to configure KYC steps, require customer verification, review submitted answers and documents, and inspect audit history.

Manager KYC methods are available through both TCP commands and BackOffice REST routes. TCP command names remain the canonical method names; REST routes are thin HTTP wrappers over the same handler logic.

KYC belongs to Customer, not to a trading account. Profiles are scoped by customer_id and brand; trading accounts only receive the effect of KYC through business rules such as real account opening restrictions.

Architecture

KYC is implemented as a separate KycManager module:

• database: bases/kyc.db;
• cache-first runtime model;
• SQLite writes are synchronized through a queue executed on a strand;
• customer aggregate fields are updated after profile recalculation;
• workflow can create required steps through kyc.require_step and kyc.set_required_level;
• KYC documents reference files registered in StorageManager by file_id.

StorageManager stores physical files in storage/<uuid>.<ext> and keeps metadata in bases/storage.db. KYC stores only the file reference and copied metadata such as original name, content type, size and checksum.

Status Values

Profile Status

Value	Name
0	none
1	draft
2	pending
3	approved
4	rejected
5	expired
6	review_required

Step Status

Value	Name
0	required
1	pending
2	approved
3	rejected
4	expired
5	skipped

Document Status

Value	Name
0	uploaded
1	pending
2	approved
3	rejected
4	expired
5	deleted

Risk Level

Value	Name
0	unknown
1	low
2	medium
3	high
4	prohibited

Questionnaire Schema

KYC step templates can include form_schema. The customer submits answers against this schema.

Template creation and update validate the schema before saving it:

• form_schema must be a JSON object;
• if sections is present, it must be an array;
• each section must be an object;
• if section fields is present, it must be an array;
• every field must have a non-empty string name;
• field names must be unique across the whole schema;
• required, when present, must be boolean;
• select and multi_select options, when present, must be an array.

Supported field types:

• text
• textarea
• date
• country
• file_reference
• number
• boolean
• select
• multi_select

Example:

{
  "sections": [
    {
      "title": "Identity",
      "fields": [
        {
          "name": "first_name",
          "type": "text",
          "required": true
        },
        {
          "name": "country",
          "type": "country",
          "required": true
        },
        {
          "name": "employment_status",
          "type": "select",
          "required": true,
          "options": [
            { "value": "employed", "label": "Employed" },
            { "value": "self_employed", "label": "Self employed" }
          ]
        }
      ]
    }
  ]
}

The server validates required fields, primitive value types and allowed options for select and multi_select when the customer submits answers.

Workflow Hooks

Workflow rules should not attach KYC directly to a trading account. They should operate on the customer profile.

kyc.require_step attaches one explicit step template to a customer profile. It is useful for a specific manual or workflow requirement such as proof_id.

kyc.set_required_level creates or reuses the customer profile and sets the required KYC level. When the level is increased, the manager attaches every active required template for the same brand with level <= required_level. Existing active steps with the same code are not duplicated. This is the preferred flow for deposit-triggered or real-account-triggered KYC rules.

Current Methods

Method	Description
MngAddKycStepTemplate	Create a KYC step template
MngUpdateKycStepTemplate	Update a KYC step template
MngDeleteKycStepTemplate	Delete a KYC step template
MngGetKycStepTemplates	List KYC step templates
MngGetKycProfile	Get a KYC profile with steps and documents
MngGetKycProfiles	List KYC profiles
MngGetKycStep	Get one KYC step with related documents
MngRequireKycStep	Attach a required step to a customer profile
MngSetKycRequiredLevel	Increase required KYC level for a customer
MngApproveKycStep	Approve a submitted step
MngRejectKycStep	Reject a submitted step
MngAddKycDocument	Attach a stored file to a KYC profile
MngGetKycDocuments	List KYC documents
MngApproveKycDocument	Approve a document
MngRejectKycDocument	Reject a document
MngGetKycAudit	Read KYC audit rows

Access

All current manager KYC methods require one of:

SESSION_MANAGER, SESSION_ADMIN, SESSION_DEALER, SESSION_CRM_MANAGER, SESSION_CRM_ADMIN.

BackOffice REST Routes

Method	Route	Command
POST	/manager/kyc/templates	MngAddKycStepTemplate
PUT / PATCH	/manager/kyc/templates/{id}	MngUpdateKycStepTemplate
DELETE	/manager/kyc/templates/{id}	MngDeleteKycStepTemplate
GET	/manager/kyc/templates	MngGetKycStepTemplates
GET	/manager/kyc/profiles	MngGetKycProfiles
GET	/manager/kyc/profiles/{id}	MngGetKycProfile
GET	/manager/kyc/steps/{id}	MngGetKycStep
POST	/manager/kyc/steps/require	MngRequireKycStep
POST	/manager/kyc/required-level	MngSetKycRequiredLevel
POST	/manager/kyc/steps/{id}/approve	MngApproveKycStep
POST	/manager/kyc/steps/{id}/reject	MngRejectKycStep
POST	/manager/kyc/documents	MngAddKycDocument
GET	/manager/kyc/documents	MngGetKycDocuments
POST	/manager/kyc/documents/{id}/approve	MngApproveKycDocument
POST	/manager/kyc/documents/{id}/reject	MngRejectKycDocument
GET	/manager/kyc/audit	MngGetKycAudit

Storage Flow

1. A user uploads a file through POST /upload.
2. StorageManager validates size, extension and real file signature.
3. The file is stored as storage/<uuid>.<ext>.
4. Storage metadata is written to bases/storage.db.
5. The API returns file_id.
6. KYC document methods receive file_id and copy file metadata from StorageManager.

KYC document requests should not send trusted file_name, content_type, file_size or checksum. These fields are derived from storage metadata.