Create Contact

Overview

The Create Contact API allows financial institutions to register new customer contacts in the banking system. This operation creates the foundational customer record that serves as the basis for account opening, relationship management, and customer service activities.

Command Details

Command Name: CreateContactCommand

Operation Type: Command (Write Operation)

Use Cases

• New Customer Onboarding: Register new customers during account opening process
• Corporate Client Registration: Create business entities and corporate customers
• Individual Customer Enrollment: Add personal customers to the banking system
• Relationship Establishment: Begin customer relationships with complete contact details
• KYC Compliance: Capture required customer information for regulatory compliance

API Endpoint

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

Request Structure

Request Body

{
  "commandName": "CreateContactCommand",
  "data": {
    "firstName": "string",
    "lastName": "string",
    "middleName": "string",
    "emailAddress": "string",
    "phoneNumber": "string",
    "dateOfBirth": "2000-01-01",
    "gender": "Male",
    "address": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "identificationType": "string",
    "identificationNumber": "string",
    "customerType": "Individual",
    "branchEncodedKey": "string"
  }
}

Request Fields

Field Name	Type	Mandatory	Description
firstName	String	Yes	Customer's first name
lastName	String	Yes	Customer's last name
middleName	String	No	Customer's middle name
emailAddress	String	Yes	Valid email address
phoneNumber	String	Yes	Contact phone number
dateOfBirth	Date	Yes	Date of birth (YYYY-MM-DD format)
gender	String	Yes	Gender (Male, Female, Other)
address	String	Yes	Residential or business address
city	String	Yes	City of residence
state	String	Yes	State or region
country	String	Yes	Country of residence
identificationType	String	Yes	Type of identification document
identificationNumber	String	Yes	Identification document number
customerType	String	Yes	Customer type (Individual, Corporate)
branchEncodedKey	String	Yes	Home branch encoded key

Sample Requests

1. Create Individual Customer

{
  "commandName": "CreateContactCommand",
  "data": {
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Michael",
    "emailAddress": "john.doe@email.com",
    "phoneNumber": "+234 123 456 7890",
    "dateOfBirth": "1990-05-15",
    "gender": "Male",
    "address": "123 Main Street, Apt 4B",
    "city": "Lagos",
    "state": "Lagos State",
    "country": "Nigeria",
    "identificationType": "National ID",
    "identificationNumber": "NIN12345678901",
    "customerType": "Individual",
    "branchEncodedKey": "8a8e87e87d1234567890abcd"
  }
}

2. Create Corporate Customer

{
  "commandName": "CreateContactCommand",
  "data": {
    "firstName": "Acme",
    "lastName": "Corporation",
    "emailAddress": "info@acmecorp.com",
    "phoneNumber": "+234 098 765 4321",
    "dateOfBirth": "2010-01-01",
    "gender": "Other",
    "address": "456 Business Plaza, Tower 2",
    "city": "Abuja",
    "state": "FCT",
    "country": "Nigeria",
    "identificationType": "Corporate Registration",
    "identificationNumber": "RC1234567",
    "customerType": "Corporate",
    "branchEncodedKey": "8a8e87e87d0987654321efgh"
  }
}

Response Structure

Success Response

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Contact created successfully.",
  "data": {
    "contactEncodedKey": "8a8e87e87d1234567890abcd",
    "customerNumber": "CUST1000245",
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "john.doe@email.com",
    "phoneNumber": "+234 123 456 7890"
  }
}

Error Handling

Common Error Responses

1. Duplicate Customer

{
  "isSuccessful": false,
  "statusCode": "CBS_400",
  "message": "A customer with this identification number already exists."
}

2. Invalid Branch

{
  "isSuccessful": false,
  "statusCode": "CBS_404",
  "message": "Invalid branch encoded key."
}

3. Validation Error

{
  "isSuccessful": false,
  "statusCode": "CBS_400",
  "message": "Invalid email address format."
}

Error Codes

Status Code	Message	Cause
CBS_400	Validation error	Invalid or missing required fields
CBS_404	Branch not found	Invalid branch encoded key
CBS_409	Duplicate customer	Customer with same ID already exists
CBS_500	Internal server error	System error occurred

Code Examples

cURL

curl -X POST https://api.example.com/api/bpm/cmd \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "commandName": "CreateContactCommand",
    "data": {
      "firstName": "John",
      "lastName": "Doe",
      "emailAddress": "john.doe@email.com",
      "phoneNumber": "+234 123 456 7890",
      "dateOfBirth": "1990-05-15",
      "gender": "Male",
      "address": "123 Main Street",
      "city": "Lagos",
      "state": "Lagos State",
      "country": "Nigeria",
      "identificationType": "National ID",
      "identificationNumber": "NIN12345678901",
      "customerType": "Individual",
      "branchEncodedKey": "8a8e87e87d1234567890abcd"
    }
  }'

C# Example

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

var request = new
{
    commandName = "CreateContactCommand",
    data = new
    {
        firstName = "John",
        lastName = "Doe",
        emailAddress = "john.doe@email.com",
        phoneNumber = "+234 123 456 7890",
        dateOfBirth = "1990-05-15",
        gender = "Male",
        address = "123 Main Street",
        city = "Lagos",
        state = "Lagos State",
        country = "Nigeria",
        identificationType = "National ID",
        identificationNumber = "NIN12345678901",
        customerType = "Individual",
        branchEncodedKey = "8a8e87e87d1234567890abcd"
    }
};

var response = await client.PostAsJsonAsync(
    "https://api.example.com/api/bpm/cmd", 
    request
);

Notes

• Email addresses must be unique across the system
• Identification numbers must be unique per identification type
• All mandatory fields must be provided
• Date of birth must be in the past
• Valid branch encoded key is required
• System generates unique customer number automatically

Related APIs

• Update Contact
• Retrieve Contact List
• Retrieve Contact By ID
• Request Customer Approval