GetCustomerBasicDetailsQuery

Overview

Retrieves complete customer profile including KYC information, user details, corporate profile, branch associations, and role assignments. This is the primary command for fetching comprehensive customer data.

Command Structure

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

Parameters

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

Authorization

Admin Access

• User Classification: BACKOFFICE_ADMINISTRATORS
• Access Level: Can query any user by userId

Organization Access

• User Classification: Organization users
• Access Level: Can only query their own organization's main user

Response Structure

Success Response

{
  "ok": true,
  "statusCode": "00",
  "message": "User retrieved successfully",
  "outData": {
    "User": {
      "KycInformations": { /* KYC verification status */ },
      "UserDetail": { /* User personal information */ },
      "CorporateProfile": { /* Corporate account details */ },
      "BranchAssociations": [ /* Branch access list */ ],
      "RoleAssociations": [ /* Role assignments */ ]
    },
    "PerformanceTimings": {
      "0_TotalExecutionTime": 245,
      "1_ParseParameters": 2,
      "2_BuildPredicate": 1,
      "3_FetchUser": 180,
      "4_GetKycInformation": 55,
      "5_BuildResult": 7
    },
    "PerformanceSummary": {
      "TotalExecutionTimeMs": 245,
      "ParseParametersMs": 2,
      "BuildPredicateMs": 1,
      "FetchUserMs": 180,
      "GetKycInformationMs": 55,
      "BuildResultMs": 7,
      "SlowestOperation": "3_FetchUser"
    }
  }
}

Response Fields

KycInformations

KYC verification status for various document types:

"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"
  }
}

Verification Status Values:

• VERIFICATION_SUCCESSFUL: Document approved
• PENDING: Awaiting verification
• VERIFICATION_FAILED: Document rejected
• NotApplicable: Not required

UserDetail

Personal and account information:

"UserDetail": {
  "UserClassification": "RETAIL_CUSTOMER",
  "UserClassificationDesc": "Retail Customer",
  "AccountType": "INDIVIDUAL",
  "AccountTypeDesc": "Individual Account",
  "MobileNumber": "+2348012345678",
  "MobileCountryCode": "+234",
  "FirstName": "John",
  "LastName": "Doe",
  "Gender": "Male",
  "IdNumber": "12345678901",
  "EmailAddress": "john.doe@example.com",
  "PrimaryAccount": "0123456789",
  "CBCustomerId": "CUST001",
  "BiometricsId": "BIO123",
  "DisplayName": "John Doe",
  "DateOfBirth": "1990-01-15T00:00:00Z",
  "CreatedAt": "2025-01-01T10:00:00Z",
  "IsPinSet": true,
  "IsPinBlocked": false,
  "IsPasswordBlocked": false,
  "TwoFAEnabled": true,
  "BiometricLoginEnabled": true,
  "EnableMerchantServices": false,
  "EnableAgentServices": false,
  "UserStatus": "ACTIVE",
  "UserStatusDesc": "Active User",
  "CustomerCorePlatformReference": "CORE123"
}

CorporateProfile

Corporate account details (null for individual accounts):

"CorporateProfile": {
  "Id": 45,
  "CompanyName": "ABC Corporation",
  "CompanyAddress": "123 Business Street, Lagos",
  "CompanyregistrationNumber": "RC123456",
  "CompanyTaxNumber": "TIN9876543",
  "AdminUserId": 129,
  "UpdateAt": "2025-01-10T14:30:00Z",
  "AllowTransactions": true,
  "Enforce2FAForAccountOwnerTransactions": true,
  "Enforce2FAForNonAccountOwnerTransactions": true,
  "CompanyLogoBase64": "data:image/png;base64,..."
}

BranchAssociations

List of branches the user has access to:

"BranchAssociations": [
  {
    "SelfServiceBranchId": 10,
    "Name": "Lagos Branch",
    "AreaId": 5
  },
  {
    "SelfServiceBranchId": 12,
    "Name": "Abuja Branch",
    "AreaId": 3
  }
]

RoleAssociations

List of roles assigned to the user:

"RoleAssociations": [
  {
    "SelfServiceRoleId": 5,
    "RoleName": "Branch Manager",
    "RoleId": "BRANCH_MANAGER",
    "RoleIdDescription": "Branch Manager"
  },
  {
    "SelfServiceRoleId": 8,
    "RoleName": "Relationship Manager",
    "RoleId": "RELATIONSHIP_MANAGER",
    "RoleIdDescription": "Relationship Manager"
  }
]

Performance Metrics

The response includes detailed timing information to help identify bottlenecks:

Metric	Description	Typical Time
ParseParametersMs	Parameter extraction time	1-3ms
BuildPredicateMs	Authorization predicate construction	1-2ms
FetchUserMs	Database query with all includes	150-200ms
GetKycInformationMs	KYC verification fetch	50-100ms
BuildResultMs	Result object construction	5-10ms
TotalExecutionTimeMs	Overall execution time	200-300ms

The SlowestOperation field automatically identifies which step took the longest.

Error Responses

User Not Found

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

System Error

{
  "ok": false,
  "statusCode": "99",
  "message": "Error retrieving user: Connection timeout",
  "outData": {
    "ExecutionTimeMs": 5000,
    "Timings": {
      "1_ParseParameters": 2,
      "2_BuildPredicate": 1,
      "3_FetchUser": 4997
    }
  }
}

Usage Examples

JavaScript/TypeScript

// Fetch complete customer profile
const response = await api.query({
  cmd: "GetCustomerBasicDetailsQuery",
  data: JSON.stringify({ userId: 129 })
});

if (response.ok) {
  const customer = response.outData.User;
  const timings = response.outData.PerformanceSummary;
  
  console.log(`Customer: ${customer.UserDetail.DisplayName}`);
  console.log(`KYC Status: ${customer.KycInformations.IdentityKyc.VerificationStatus}`);
  console.log(`Execution time: ${timings.TotalExecutionTimeMs}ms`);
  console.log(`Slowest operation: ${timings.SlowestOperation}`);
  
  // Check performance
  if (timings.TotalExecutionTimeMs > 300) {
    console.warn('Query is slow, consider optimizing or using dedicated commands');
  }
} else {
  console.error(`Error: ${response.message}`);
}

C# / .NET

var request = new GetCustomerBasicDetailsQuery
{
    Data = JsonSerializer.Serialize(new { userId = 129 })
};

var response = await _mediator.Send(request);

if (response.IsSuccessful)
{
    var data = JsonSerializer.Deserialize<dynamic>(response.Data);
    var customer = data.User;
    var timings = data.PerformanceSummary;
    
    Console.WriteLine($"Customer: {customer.UserDetail.DisplayName}");
    Console.WriteLine($"Total time: {timings.TotalExecutionTimeMs}ms");
}

Python

import json
import requests

response = requests.post(api_url, json={
    "cmd": "GetCustomerBasicDetailsQuery",
    "data": json.dumps({"userId": "129"})
})

if response.json()["ok"]:
    customer = response.json()["outData"]["User"]
    timings = response.json()["outData"]["PerformanceSummary"]
    
    print(f"Customer: {customer['UserDetail']['DisplayName']}")
    print(f"Execution time: {timings['TotalExecutionTimeMs']}ms")
else:
    print(f"Error: {response.json()['message']}")

Performance Optimization

Problem: Slow Execution

If GetCustomerBasicDetailsQuery is taking too long (>300ms), consider these optimizations:

1. Use Dedicated Commands

Instead of fetching everything, use specific commands:

// Instead of this (245ms):
const fullProfile = await api.query({
  cmd: "GetCustomerBasicDetailsQuery",
  data: JSON.stringify({ userId: 129 })
});

// Use specific commands (85-45ms each):
const [kyc, branches] = await Promise.all([
  api.query({ cmd: "GetCustomerKycInformationQuery", data: JSON.stringify({ userId: 129 }) }),
  api.query({ cmd: "GetCustomerBranchAssociationsQuery", data: JSON.stringify({ userId: 129 }) })
]);

2. Cache Results

Cache user data that doesn't change frequently:

const CACHE_DURATION = 5 * 60 * 1000; // 5 minutes
const customerCache = new Map();

async function getCustomer(userId) {
  const cached = customerCache.get(userId);
  if (cached && Date.now() - cached.timestamp < CACHE_DURATION) {
    return cached.data;
  }
  
  const response = await api.query({
    cmd: "GetCustomerBasicDetailsQuery",
    data: JSON.stringify({ userId })
  });
  
  customerCache.set(userId, {
    data: response.outData.User,
    timestamp: Date.now()
  });
  
  return response.outData.User;
}

3. Analyze Performance Metrics

Use the returned timing data to identify bottlenecks:

const timings = response.outData.PerformanceTimings;

if (timings["3_FetchUser"] > 200) {
  console.warn("Database query is slow - consider adding indexes");
}

if (timings["4_GetKycInformation"] > 100) {
  console.warn("KYC fetch is slow - consider caching KYC status");
}

Best Practices

✅ DO use this command when you need complete customer profile
✅ DO monitor performance metrics to identify issues
✅ DO cache results for frequently accessed customers
✅ DO use dedicated commands when you only need specific data

❌ DON'T call this command repeatedly in loops
❌ DON'T ignore performance warnings
❌ DON'T fetch full profile if you only need KYC or roles

Related Commands

• GetCustomerKycInformationQuery - Get only KYC status (65% faster)
• GetCustomerAddressDetailsQuery - Get address information
• GetCustomerBranchAssociationsQuery - Get only branches (82% faster)
• GetCustomerRoleAssociationsQuery - Get only roles (87% faster)

Change Log

Version	Date	Changes
1.1	2026-01-11	Added performance timing metrics
1.0	2025-12-01	Initial implementation