Skip to main content

CreateGuarantorCommand

Overview​

The CreateGuarantorCommand allows you to create new guarantor records for loan applications. Guarantors provide additional security for loans by agreeing to repay the loan if the borrower defaults.

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

Use Cases​

  • Adding guarantors during loan application process
  • Manual entry of guarantor information
  • Recording guarantor details from offline applications
  • Managing multiple guarantors for a single loan

Request Parameters​

Required Parameters​

ParameterTypeDescription
loanQuoteIdlongThe ID of the loan quote/application
namestringFull name of the guarantor
emailAddressstringGuarantor's email address
mobileNumberstringGuarantor's mobile phone number
relationshipstringRelationship to the borrower (e.g., "Brother", "Friend", "Colleague")
addressstringGuarantor's physical address

Optional Parameters​

ParameterTypeDescription
dateOfBirthstringGuarantor's date of birth (ISO format: YYYY-MM-DD)

Request Example​

{
  "commandName": "CreateGuarantorCommand",
  "data": {
    "loanQuoteId": 999,
    "name": "John Doe",
    "emailAddress": "john.doe@email.com",
    "mobileNumber": "08012345678",
    "relationship": "Brother",
    "address": "456 Oak Street, Abuja, Nigeria",
    "dateOfBirth": "1985-05-15"
  }
}

Response Format​

Success Response​

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Guarantor created successfully.",
  "data": {
    "guarantorId": 321,
    "loanQuoteId": 999,
    "name": "John Doe",
    "emailAddress": "john.doe@email.com",
    "mobileNumber": "08012345678",
    "relationship": "Brother",
    "address": "456 Oak Street, Abuja, Nigeria",
    "dateOfBirth": "1985-05-15",
    "verificationStatus": 0,
    "verificationStatusDesc": "PENDING",
    "createdAt": "2026-01-11T10:40:00Z"
  }
}

Error Responses​

Loan Quote Not Found​

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

Duplicate Guarantor​

{
  "isSuccessful": false,
  "statusCode": "04",
  "message": "A guarantor with this name and mobile number already exists for this loan quote."
}

Validation Rules​

  1. Loan Quote Existence: The loanQuoteId must reference an existing loan quote/application
  2. No Duplicates: Cannot create multiple guarantors with the same name and mobileNumber combination for the same loan
  3. Required Fields: All required parameters must be provided
  4. Email Format: Email address should be in valid format
  5. Phone Number: Mobile number should follow expected format

Verification Status​

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

  1. Created: Guarantor is created with status = PENDING
  2. Initiate Verification: Admin uses InitiateGuarantorVerificationCommand
  3. Verification Process: Guarantor is contacted and verified
  4. Approve/Decline: Admin uses ApproveGuarantorVerificationCommand or DeclineGuarantorVerificationCommand
  5. Final Status: Status changes to APPROVED or DECLINED
  • InitiateGuarantorVerificationCommand - Start the guarantor verification process
  • ApproveGuarantorVerificationCommand - Approve a verified guarantor
  • DeclineGuarantorVerificationCommand - Decline a guarantor
  • GetCustomerLoanGuarantorsQuery - Retrieve guarantors for a loan

Integration Example​

cURL Request​

curl -X POST https://api.banklingo.com/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "commandName": "CreateGuarantorCommand",
    "data": {
      "loanQuoteId": 999,
      "name": "John Doe",
      "emailAddress": "john.doe@email.com",
      "mobileNumber": "08012345678",
      "relationship": "Brother",
      "address": "456 Oak Street, Abuja, Nigeria",
      "dateOfBirth": "1985-05-15"
    }
  }'

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: 'CreateGuarantorCommand',
    data: {
      loanQuoteId: 999,
      name: 'John Doe',
      emailAddress: 'john.doe@email.com',
      mobileNumber: '08012345678',
      relationship: 'Brother',
      address: '456 Oak Street, Abuja, Nigeria',
      dateOfBirth: '1985-05-15'
    }
  })
});

const result = await response.json();
console.log('Guarantor created:', result.data.guarantorId);

C# Example​

var command = new
{
    CommandName = "CreateGuarantorCommand",
    Data = new
    {
        LoanQuoteId = 999,
        Name = "John Doe",
        EmailAddress = "john.doe@email.com",
        MobileNumber = "08012345678",
        Relationship = "Brother",
        Address = "456 Oak Street, Abuja, Nigeria",
        DateOfBirth = "1985-05-15"
    }
};

var result = await _mediator.Send(command);

Best Practices​

  1. Multiple Guarantors: Some loans may require multiple guarantors based on loan amount
  2. Verification: Always verify guarantor information through phone/email before approval
  3. Relationship: Document the relationship between borrower and guarantor
  4. Contact Information: Ensure contact details are current and valid
  5. Legal Requirements: Ensure guarantor agreements comply with local regulations
  6. Notification: Notify guarantors about their obligations and rights

Common Relationships​

  • Spouse
  • Parent
  • Sibling (Brother/Sister)
  • Child
  • Friend
  • Colleague
  • Business Partner
  • Employer

Guarantor Verification Flow​

Technical Notes​

  • Entity: GuaratorInformation (note the typo in entity name)
  • Database Table: BPMLoanSelfService.GuaratorInformation
  • Loan-Specific: Unlike identity documents and addresses, guarantors are tied to specific loan applications via LoanQuoteId
  • Duplicate Prevention: The system prevents adding the same guarantor (name + phone) twice to the same loan

See Also​