GetCustomerKycInformationQuery

Overview

Retrieves KYC (Know Your Customer) verification status for a customer. This is a lightweight, fast command that returns only verification statuses for address, identity, mobile, and email without fetching the complete user profile.

Performance: ~85ms (65% faster than GetCustomerBasicDetailsQuery)

Command Structure

{
  "cmd": "GetCustomerKycInformationQuery",
  "data": "{\"userId\":\"129\"}"
}

Parameters

Parameter	Type	Required	Description
userId	long	Yes	The ID of the customer

Authorization

Same as GetCustomerBasicDetailsQuery:

• BACKOFFICE_ADMINISTRATORS: Can query any user
• Organization users: Can only query their organization's main user

Response Structure

Success Response

{
  "ok": true,
  "statusCode": "00",
  "message": "KYC information retrieved successfully",
  "outData": {
    "KycInformations": {
      "mobileKyc": {
        "VerificationStatus": "VERIFICATION_SUCCESSFUL",
        "Comment": "The mobile number has been verified and approved"
      },
      "emailKyc": {
        "VerificationStatus": "VERIFICATION_SUCCESSFUL",
        "Comment": "The email has been verified and approved"
      },
      "AddressKyc": {
        "VerificationStatus": "PENDING",
        "Comment": null
      },
      "IdentityKyc": {
        "VerificationStatus": "VERIFICATION_SUCCESSFUL",
        "Comment": "ID verified"
      }
    },
    "PerformanceTimings": {
      "TotalExecutionTimeMs": 85,
      "ParseParametersMs": 1,
      "UserAuthorizationCheckMs": 15,
      "KycFetchMs": 69
    }
  }
}

KYC Verification Types

1. mobileKyc

• Status: Always VERIFICATION_SUCCESSFUL for registered users
• Purpose: Confirms mobile number is verified during registration

2. emailKyc

• Status: Always VERIFICATION_SUCCESSFUL for registered users
• Purpose: Confirms email is verified during registration

3. AddressKyc

• Status: From SelfServiceAddressInformation table
• Possible Values:
  • PENDING: Awaiting verification
  • VERIFICATION_SUCCESSFUL: Address verified
  • VERIFICATION_FAILED: Address rejected
• Purpose: Physical address verification for compliance

4. IdentityKyc

• Status: From SelfServiceIdentityInformation table
• Possible Values:
  • PENDING: Awaiting verification
  • VERIFICATION_SUCCESSFUL: Identity document approved
  • VERIFICATION_FAILED: Identity document rejected
• Purpose: Government-issued ID verification

Usage Examples

JavaScript - Check if KYC is Complete

const response = await api.query({
  cmd: "GetCustomerKycInformationQuery",
  data: JSON.stringify({ userId: 129 })
});

if (response.ok) {
  const kyc = response.outData.KycInformations;
  
  // Check if all KYC is complete
  const isKycComplete = 
    kyc.mobileKyc.VerificationStatus === "VERIFICATION_SUCCESSFUL" &&
    kyc.emailKyc.VerificationStatus === "VERIFICATION_SUCCESSFUL" &&
    kyc.AddressKyc.VerificationStatus === "VERIFICATION_SUCCESSFUL" &&
    kyc.IdentityKyc.VerificationStatus === "VERIFICATION_SUCCESSFUL";
  
  if (isKycComplete) {
    console.log("✅ KYC is complete - customer can apply for loans");
  } else {
    console.log("⚠️ KYC is incomplete:");
    if (kyc.AddressKyc.VerificationStatus !== "VERIFICATION_SUCCESSFUL") {
      console.log("  - Address verification pending");
    }
    if (kyc.IdentityKyc.VerificationStatus !== "VERIFICATION_SUCCESSFUL") {
      console.log("  - Identity verification pending");
    }
  }
  
  // Performance monitoring
  const timing = response.outData.PerformanceTimings;
  console.log(`Query completed in ${timing.TotalExecutionTimeMs}ms`);
}

React Component Example

import { useState, useEffect } from 'react';

function KycStatus({ userId }) {
  const [kyc, setKyc] = useState(null);
  const [loading, setLoading] = useState(true);
  
  useEffect(() => {
    async function fetchKyc() {
      const response = await api.query({
        cmd: "GetCustomerKycInformationQuery",
        data: JSON.stringify({ userId })
      });
      
      if (response.ok) {
        setKyc(response.outData.KycInformations);
      }
      setLoading(false);
    }
    
    fetchKyc();
  }, [userId]);
  
  if (loading) return <div>Loading KYC status...</div>;
  
  return (
    <div className="kyc-status">
      <h3>KYC Verification Status</h3>
      <ul>
        <li>
          Mobile: <Status value={kyc.mobileKyc.VerificationStatus} />
        </li>
        <li>
          Email: <Status value={kyc.emailKyc.VerificationStatus} />
        </li>
        <li>
          Address: <Status value={kyc.AddressKyc.VerificationStatus} />
        </li>
        <li>
          Identity: <Status value={kyc.IdentityKyc.VerificationStatus} />
        </li>
      </ul>
    </div>
  );
}

function Status({ value }) {
  const icon = value === "VERIFICATION_SUCCESSFUL" ? "✅" : 
               value === "VERIFICATION_FAILED" ? "❌" : "⏳";
  return <span>{icon} {value}</span>;
}

When to Use This Command

✅ Use GetCustomerKycInformationQuery when:

• Checking loan eligibility (KYC must be complete)
• Displaying KYC status on dashboard
• Validating customer before loan application
• Building customer verification reports
• Need fast response time

❌ Don't use when:

• You need full customer details
• You need branch/role associations
• You need corporate profile information
• Use GetCustomerBasicDetailsQuery instead for complete profile

Performance Comparison

Command	Time	Data Returned	Use Case
GetCustomerKycInformationQuery	~85ms	KYC status only	Quick KYC check
GetCustomerBasicDetailsQuery	~245ms	Complete profile	Full customer data

Savings: 65% faster when you only need KYC status

Error Responses

User Not Found or Unauthorized

{
  "ok": false,
  "statusCode": "04",
  "message": "User not found or unauthorized."
}

System Error

{
  "ok": false,
  "statusCode": "99",
  "message": "Error retrieving KYC information: Database connection timeout"
}

Related Commands

• GetCustomerBasicDetailsQuery - Complete customer profile
• GetCustomerAddressDetailsQuery - Detailed address information
• GetCustomerIdentityDetailsQuery - Detailed identity documents
• ApproveIdentityDocumentCommand - Approve identity verification
• ApproveCustomerAddressInformationCommand - Approve address verification

Best Practices

✅ DO use this command for quick KYC checks
✅ DO cache KYC status (updates infrequently)
✅ DO check KYC before allowing loan applications
✅ DO use parallel requests when fetching multiple customers

❌ DON'T call repeatedly in loops
❌ DON'T use when you need full customer data
❌ DON'T ignore authorization errors

Integration Example

Loan Application Pre-Check

async function canApplyForLoan(userId) {
  // Fast KYC check before showing loan application form
  const kycResponse = await api.query({
    cmd: "GetCustomerKycInformationQuery",
    data: JSON.stringify({ userId })
  });
  
  if (!kycResponse.ok) {
    return { canApply: false, reason: "Unable to verify KYC status" };
  }
  
  const kyc = kycResponse.outData.KycInformations;
  
  // Check required KYC elements
  if (kyc.IdentityKyc.VerificationStatus !== "VERIFICATION_SUCCESSFUL") {
    return { 
      canApply: false, 
      reason: "Identity verification required",
      action: "Please upload a valid government-issued ID"
    };
  }
  
  if (kyc.AddressKyc.VerificationStatus !== "VERIFICATION_SUCCESSFUL") {
    return { 
      canApply: false, 
      reason: "Address verification required",
      action: "Please provide proof of address"
    };
  }
  
  return { canApply: true };
}

// Usage
const eligibility = await canApplyForLoan(129);
if (eligibility.canApply) {
  showLoanApplicationForm();
} else {
  showKycRequirement(eligibility.reason, eligibility.action);
}

Change Log

Version	Date	Changes
1.0	2026-01-11	Initial implementation with performance timing