KYC Management

Know Your Customer (KYC) is the compliance process that every investor must complete before they can invest. This guide walks you through fetching the KYC form, submitting answers, and triggering the compliance analysis.

Before you start

Read the Account concept guide for KYC status values and the Forms concept guide for a detailed explanation of form steps and questions.

KYC Status Overview

Your integration will typically drive the investor through the first three states. The transition to validated or refused is performed by the platform's compliance team.

Step 1 — Retrieving KYC Form Steps

Before presenting the form to the Investor, fetch the list of steps available for their account. Steps may vary depending on the account type (individual vs corporate).

query GetKycSteps {
  GetKycFormSteps(accountId: "123") {
    id
    technicalCode
    label
    commentsCount
    # ...Other ConfigurableFormStep fields
  }
}

→ Type reference: ConfigurableFormStep → Reference: GetKycFormSteps

Example response:

{
  "GetKycFormSteps": [
    { "technicalCode": "identity",        "label": "Identity",        "position": 1, "isCompleted": false },
    { "technicalCode": "address",         "label": "Address",         "position": 2, "isCompleted": false },
    { "technicalCode": "financial_info",  "label": "Financial Info",  "position": 3, "isCompleted": false },
    { "technicalCode": "documents",       "label": "Documents",       "position": 4, "isCompleted": false }
  ]
}

Step 2 — Fetching Questions for a Step

For each step, retrieve the questions and their current answers (if any):

query GetKycStep {
  GetKycForm(
    accountId: "123"
    formStep: "identity"
  ) {
    id
    technicalCode
    label
    answer {
      value
      # For file questions, answer may contain document information
    }
    # ...Other FormQuestionWithAnswer fields
  }
}

→ Type reference: FormQuestionWithAnswer → Reference: GetKycForm

Step 3 — Submitting Answers

Submit answers for a step using the AnswerKyc mutation. You can re-call this mutation as many times as needed — previous answers for the step will be overwritten.

mutation SubmitIdentityStep {
  AnswerKyc(
    accountId: "123"
    stepTechnicalCode: "identity"
    formAnswers: [
      { technicalCode: "first_name",    value: "Alice" }
      { technicalCode: "last_name",     value: "Dupont" }
      { technicalCode: "birth_date",    value: "1985-04-12" }
      { technicalCode: "nationality",   value: "FR" }
    ]
  ) {
    id
    kycStatusDetailed { 
      code
      label
    }
    # ...Other Account fields
  }
}

→ Type reference: Account → Reference: AnswerKyc

Repeat this for each step until all steps are marked isCompleted: true.

Linking KYC Answers to an Investment

Some subscription forms extend the KYC with investment-specific questions. Pass investmentId to scope the answers to that investment:

mutation SubmitInvestmentKycStep {
  AnswerKyc(
    accountId: "123"
    investmentId: "456"
    stepTechnicalCode: "investment_profile"
    formAnswers: [
      { technicalCode: "investment_horizon", value: "long_term" }
      { technicalCode: "risk_tolerance",     value: "moderate" }
    ]
  ) {
    id
    kycStatusDetailed {
      code
      label
    }
    # ...Other Account fields
  }
}

→ Type reference: Account

Step 4 — Triggering KYC Analysis

Once all steps are completed, trigger the automated compliance analysis. This requires ROLE_CAN_VALIDATE_KYC.

mutation RunKycAnalysis {
  AnalyzeKyc(accountId: "123") {
    id
    kycStatusDetailed { 
      code
      label
    }
    kycAnalysisResult
    investorInfo {
      lcbftLevel {
        code
        label
      }
    }
    # ...Other Account fields
  }
}

→ Type reference: Account → Reference: AnalyzeKyc

The mutation runs automated checks (sanctions screening, PEP checks, etc.) and updates the account's kycStatus accordingly. After analysis, the status typically transitions to pending_review or completed.

Step 5 — Electronic Signature (optional)

If the KYC form requires a signed document, send it to the signature provider:

mutation SendForSignature {
  SendKycDocumentToSignatureProvider(
    accountId: "123"
    formStep: "documents"
    redirectTo: "https://yourapp.com/kyc/callback"
  )
  # Returns a URL to redirect the investor to for signing
}

→ Reference: SendKycDocumentToSignatureProvider

Step 6 — Validating or Refusing (Admin Only)

After human review, an admin finalizes the KYC:

Validate:

mutation ValidateKyc {
  SetAccountKycStatus(
    accountId: "123"
    kycStatus: validated
    withEmail: true
  ) {
    id
    kycStatusDetailed { 
      code
      label
    }
    # ...Other Account fields
  }
}

→ Type reference: Account

Refuse:

mutation RefuseKyc {
  SetAccountKycStatus(
    accountId: "123"
    kycStatus: refused
    withEmail: true
    kycRefusedComment: "Identity document is not legible. Please resubmit."
  ) {
    id
    kycStatusDetailed { 
      code
      label
    }
    kycRefusedComment
    # ...Other Account fields
  }
}

→ Type reference: Account → Reference: SetAccountKycStatus

Monitoring Compliance Alerts

To retrieve accounts with elevated AML risk levels or pending compliance actions (requires ROLE_ADMIN):

query ComplianceAlerts {
  GetKycAlerts(
    complianceControlLevel: high
    resultsPerPage: 20
    page: 1
  ) {
    edges {
      node {
        id
        viaLinkControl {
          id
          control
          # ...Other VialinkControl fields
        }
        source
        # ...Other ComplianceControl fields
      }
    }
    totalCount
  }
}

→ Type references: VialinkControl, ComplianceControl → Reference: GetKycAlerts

Related Reference

Operation	Reference
Get KYC form steps	GetKycFormSteps
Get questions for a step	GetKycForm
Submit KYC answers	AnswerKyc
Trigger KYC analysis	AnalyzeKyc
Send documents for e-signature	SendKycDocumentToSignatureProvider
Set KYC status (admin)	SetAccountKycStatus
Get compliance alerts	GetKycAlerts