Skip to main content

CreateIdentityDocumentCommand

Overview​

The CreateIdentityDocumentCommand allows you to create new identity documents for self-service users in the loan origination system. This command supports multiple identity document types and enables manual entry of identity information.

Handler File: CB.Administration.Api/Commands/BPM/SelfService/SelfServiceserDetailCommandHandlers.cs

Use Cases​

  • Manual entry of customer identity documents
  • Uploading identity documents during loan application
  • Recording identity information from physical documents
  • Supporting customers who complete identity verification offline

Supported Identity Types​

The command supports four types of identity documents:

TypeEnum ValueDescription
National ID1Government-issued national identity card
International Passport2International travel passport
Driver's License3Government-issued driver's license
Voter's Card4Electoral voter registration card

Request Parameters​

Required Parameters​

ParameterTypeDescription
userIdlongThe ID of the self-service user
identityTypeintIdentity document type (1-4)
idNumberstringThe identity document number
base64DocstringDocument image encoded in base64
docExtensionstringFile extension (e.g., ".jpg", ".pdf")

Optional Parameters​

ParameterTypeDescription
issuingAuthoritystringOrganization that issued the document
issueDatestringDate document was issued (ISO format)
expiryDatestringDate document expires (ISO format)

Request Example​

{
  "commandName": "CreateIdentityDocumentCommand",
  "data": {
    "userId": 123,
    "identityType": 1,
    "idNumber": "A12345678",
    "issuingAuthority": "NIMC",
    "base64Doc": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
    "docExtension": ".jpg",
    "issueDate": "2020-01-01",
    "expiryDate": "2030-01-01"
  }
}

Response Format​

Success Response​

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Identity document created successfully.",
  "data": {
    "identityId": 456,
    "userId": 123,
    "identityType": 1,
    "identityTypeDesc": "National ID",
    "idNumber": "A12345678",
    "verificationStatus": 0,
    "verificationStatusDesc": "PENDING",
    "createdAt": "2026-01-11T10:30:00Z"
  }
}

Error Responses​

User Not Found​

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

Duplicate ID Number​

{
  "isSuccessful": false,
  "statusCode": "04",
  "message": "An identity document with this ID number already exists for this user and identity type."
}

Invalid Identity Type​

{
  "isSuccessful": false,
  "statusCode": "04",
  "message": "Invalid identity type. Must be 1-4."
}

Validation Rules​

  1. User Existence: The userId must reference an existing self-service user
  2. No Duplicates: Cannot create multiple documents with the same idNumber, identityType, and userId combination
  3. Valid Identity Type: The identityType must be between 1 and 4
  4. Required Fields: All required parameters must be provided

Verification Status​

When a document is created, it automatically receives a verification status of PENDING (0). The document must then go through the approval workflow:

  1. Created: Document is created with status = PENDING
  2. Admin Review: Admin uses ApproveIdentityDocumentCommand or RejectIdentityDocumentCommand
  3. Approved/Rejected: Status changes to APPROVED or REJECTED
  • ApproveIdentityDocumentCommand - Approve a pending identity document
  • RejectIdentityDocumentCommand - Reject a pending identity document
  • GetCustomerIdentityDetailsQuery - Retrieve identity documents for a user

Integration Example​

cURL Request​

curl -X POST https://api.banklingo.com/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "commandName": "CreateIdentityDocumentCommand",
    "data": {
      "userId": 123,
      "identityType": 1,
      "idNumber": "A12345678",
      "issuingAuthority": "NIMC",
      "base64Doc": "BASE64_ENCODED_IMAGE_HERE",
      "docExtension": ".jpg",
      "issueDate": "2020-01-01",
      "expiryDate": "2030-01-01"
    }
  }'

JavaScript Example​

const response = await fetch('https://api.banklingo.com/execute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    commandName: 'CreateIdentityDocumentCommand',
    data: {
      userId: 123,
      identityType: 1, // National ID
      idNumber: 'A12345678',
      issuingAuthority: 'NIMC',
      base64Doc: base64EncodedImage,
      docExtension: '.jpg',
      issueDate: '2020-01-01',
      expiryDate: '2030-01-01'
    }
  })
});

const result = await response.json();
console.log('Identity document created:', result.data.identityId);

C# Example​

var command = new
{
    CommandName = "CreateIdentityDocumentCommand",
    Data = new
    {
        UserId = 123,
        IdentityType = 1, // National ID
        IdNumber = "A12345678",
        IssuingAuthority = "NIMC",
        Base64Doc = Convert.ToBase64String(imageBytes),
        DocExtension = ".jpg",
        IssueDate = "2020-01-01",
        ExpiryDate = "2030-01-01"
    }
};

var result = await _mediator.Send(command);

Best Practices​

  1. Image Size: Compress images before encoding to base64 to reduce payload size
  2. File Formats: Use standard formats like JPG, PNG, or PDF
  3. Validation: Validate ID numbers against known formats before submission
  4. Expiry Dates: Check document expiry dates and warn users if documents are expiring soon
  5. Security: Always transmit document data over HTTPS
  6. Storage: The system stores the base64 encoded document - ensure adequate storage capacity

Technical Notes​

  • Entity: SelfServiceIdentityInformation
  • Database Table: BPMLoanSelfService.SelfServiceIdentityInformation
  • LoanQuoteId: This field is commented out in the entity - identity documents are user-level, not loan-specific
  • Async Operation: This is a synchronous operation despite the async signature

See Also​