Skip to main content

Retrieve Contact By ID

Overview​

The Retrieve Contact By ID API allows financial institutions to fetch detailed information about a specific customer contact using their unique identifier.

Command Details​

Command Name: RetrieveContactByIdQuery

Operation Type: Query (Read Operation)

Use Cases​

  • Customer Profile View: Display complete customer information
  • Transaction Verification: Verify customer details before transactions
  • Customer Service: Access customer information during support calls
  • Administrative Review: Review customer data for updates or verification

API Endpoint​

POST /api/bpm/qry
Content-Type: application/json
Authorization: Bearer {access_token}

Request Structure​

Request Body​

{
  "queryName": "RetrieveContactByIdQuery",
  "data": {
    "id": 12345
  }
}

Request Fields​

Field NameTypeMandatoryDescription
idIntegerYesClient ID

Sample Requests​

1. Retrieve Contact​

{
  "queryName": "RetrieveContactByIdQuery",
  "data": {
    "id": 12345
  }
}

Response Structure​

Success Response​

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Client with ID 12345 found.",
  "data": {
    "id": 12345,
    "encodedKey": "8a8e87e87d1234567890abcd",
    "customerNumber": "CUST1000245",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Michael",
    "emailAddress": "john.doe@email.com",
    "phoneNumber": "+234 123 456 7890",
    "dateOfBirth": "1990-05-15T00:00:00Z",
    "gender": "Male",
    "maritalStatus": 1,
    "maritalStatusDescription": "Single",
    "address": "123 Main Street",
    "city": "Lagos",
    "state": "Lagos State",
    "country": "Nigeria",
    "identificationType": "National ID",
    "identificationNumber": "NIN12345678901",
    "customerType": "Individual",
    "clientState": 1,
    "clientStateDescription": "Active",
    "isBlacklisted": false,
    "branchId": 100,
    "branchEncodedKey": "8a8e87e87d1234567890abcd",
    "branchName": "Main Branch",
    "accountOfficerId": 50,
    "accountOfficerName": "Jane Smith",
    "dateCreated": "2025-01-01T00:00:00Z",
    "lastModified": "2025-12-15T10:30:00Z"
  }
}

Response Fields​

Field NameTypeDescription
idIntegerClient ID
encodedKeyStringUnique encoded identifier
customerNumberStringCustomer account number
firstNameStringCustomer's first name
lastNameStringCustomer's last name
middleNameStringCustomer's middle name (optional)
emailAddressStringEmail address
phoneNumberStringPhone number
dateOfBirthStringDate of birth (ISO 8601)
genderStringGender
maritalStatusIntegerMarital status code (see MaritalStatusEnum)
maritalStatusDescriptionStringHuman-readable marital status
addressStringStreet address
cityStringCity
stateStringState/Province
countryStringCountry
identificationTypeStringType of ID document
identificationNumberStringID document number
customerTypeStringCustomer category
clientStateIntegerClient state code (see ClientStateEnum)
clientStateDescriptionStringHuman-readable client state
isBlacklistedBooleanWhether client is blacklisted
branchIdIntegerBranch ID
branchEncodedKeyStringBranch encoded key
branchNameStringBranch name
accountOfficerIdIntegerAccount officer ID
accountOfficerNameStringAccount officer name
dateCreatedStringCreation date (ISO 8601)
lastModifiedStringLast modification date (ISO 8601)

Enumerations​

ClientStateEnum​

ValueNameDescription
0AllAll states (filter value)
1ActiveClient is active
3PendingApprovalAwaiting approval
4ApprovedApproved but not yet active
5RejectedApplication rejected
6BlackListedClient is blacklisted
7ExitedClient has exited

MaritalStatusEnum​

ValueNameDescription
1SingleSingle/unmarried
3MarriedMarried
4SeparatedSeparated
5WidowWidow/widower
6OthersOther status

Error Handling​

Common Error Responses​

Contact Not Found​

{
  "isSuccessful": false,
  "statusCode": "CBS_404",
  "message": "Client with ID 12345 not found."
}

Missing ID​

{
  "isSuccessful": false,
  "statusCode": "CBS_400",
  "message": "Client ID is required."
}

Error Codes​

Status CodeMessageCause
CBS_400Invalid requestMissing or invalid client ID
CBS_401UnauthorizedInvalid authentication
CBS_403ForbiddenInsufficient permissions
CBS_404Contact not foundInvalid client ID
CBS_500Internal server errorSystem error

Code Examples​

cURL​

curl -X POST https://api.example.com/api/bpm/qry \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "queryName": "RetrieveContactByIdQuery",
    "data": {
      "id": 12345
    }
  }'

C# Example​

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Bearer", accessToken);

var request = new
{
    queryName = "RetrieveContactByIdQuery",
    data = new
    {
        id = 12345
    }
};

var response = await client.PostAsJsonAsync(
    "https://api.example.com/api/bpm/qry", 
    request
);
var result = await response.Content.ReadFromJsonAsync<ApiResponse>();

JavaScript/TypeScript Example​

const response = await fetch('https://api.example.com/api/bpm/qry', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    queryName: 'RetrieveContactByIdQuery',
    data: {
      id: 12345
    }
  })
});

const result = await response.json();

Implementation Notes​

  • This query internally uses RetrieveContactListQuery with ID filter
  • Returns complete customer profile information
  • Includes blacklist status and client state
  • Requires appropriate user permissions
  • Returns single contact record or error if not found

Best Practices​

  1. Validation: Validate client ID before making request
  2. Error Handling: Handle "not found" scenarios appropriately
  3. Permissions: Ensure user has permission to view client data
  4. Caching: Consider caching frequently accessed client data
  5. Security: Never expose sensitive client data in logs or error messages

Handler: AdministrationCoreContactCommandHandlers