Customers API

Manage customer records programmatically and build lasting relationships with your clients.

The Customers API allows you to create, retrieve, and manage customer profiles. Each customer can have contact details, billing preferences, and can be associated with orders, invoices, and subscriptions for complete relationship tracking.

Use Cases

User Registration: Create customer records when users sign up
Order Processing: Associate orders and invoices with customer accounts
CRM Integration: Sync customer data with your existing CRM systems
Personalization: Retrieve customer preferences for personalized experiences

Endpoints

Method	Endpoint	Description
`POST`	`/business/customer/create`	Create a new customer
`GET`	`/business/customer/list`	List all customers
`GET`	`/business/customer/details/:id`	Get customer details
`PATCH`	`/business/customer/update/:id`	Update a customer

Create Customer

Create a new customer in your business account.

http

POST /business/customer/create

Request Body

Field	Type	Required	Description
`name`	string	Yes	Customer's full name
`email`	string	Yes	Customer's email address
`phone`	string	Yes	Customer's phone number
`country`	string	Yes	Customer's country
`currency`	string	Yes	Preferred currency (e.g., `KES`, `USD`)
`company`	string	No	Company name (for business customers)
`address`	string	No	Street address
`city`	string	No	City
`type`	string	No	`individual` or `business`

Example Request

cURLJavaScriptPython

bash

curl -X POST "https://api.cashfin.africa/business/customer/create" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+254712345678",
    "country": "Kenya",
    "currency": "KES"
  }'

javascript

const response = await fetch(
  "https://api.cashfin.africa/business/customer/create",
  {
    method: "POST",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "John Doe",
      email: "[email protected]",
      phone: "+254712345678",
      country: "Kenya",
      currency: "KES",
    }),
  }
);

python

import requests

response = requests.post(
    'https://api.cashfin.africa/business/customer/create',
    headers={'Authorization': 'cs_your_client_secret'},
    json={
        'name': 'John Doe',
        'email': '[email protected]',
        'phone': '+254712345678',
        'country': 'Kenya',
        'currency': 'KES'
    }
)

Response

json

{
  "success": true,
  "message": "Customer created successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+254712345678",
    "country": "Kenya",
    "currency": "KES",
    "active": true,
    "sourceorigin": "api",
    "createdat": "2024-01-15T10:30:00.000Z"
  }
}

List Customers

Retrieve a paginated list of customers.

http

GET /business/customer/list

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page (default: 10)
`search`	string	Search by name, email, or phone

Example Request

cURLJavaScriptPython

bash

curl -X GET "https://api.cashfin.africa/business/customer/list?page=1&limit=10" \
  -H "Authorization: cs_your_client_secret"

javascript

const response = await fetch(
  "https://api.cashfin.africa/business/customer/list?page=1&limit=10",
  {
    headers: {
      Authorization: "cs_your_client_secret",
    },
  }
);

python

import requests

response = requests.get(
    'https://api.cashfin.africa/business/customer/list',
    headers={'Authorization': 'cs_your_client_secret'},
    params={'page': 1, 'limit': 10}
)

Response

json

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+254712345678",
      "active": true,
      "createdat": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "limit": 10,
    "pages": 15
  }
}

Get Customer Details

Retrieve detailed information about a specific customer.

http

GET /business/customer/details/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Customer ID (MongoDB ObjectID)

Example Request

cURLJavaScriptPHPPython

bash

curl -X GET "https://api.cashfin.africa/business/customer/details/507f1f77bcf86cd799439011" \
  -H "Authorization: cs_your_client_secret"

javascript

const customerId = "507f1f77bcf86cd799439011";

const response = await fetch(
  `https://api.cashfin.africa/business/customer/details/${customerId}`,
  {
    headers: {
      Authorization: "cs_your_client_secret",
    },
  }
);

const data = await response.json();
console.log(data);

php

<?php
$customerId = '507f1f77bcf86cd799439011';

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://api.cashfin.africa/business/customer/details/{$customerId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => [
    "Authorization: cs_your_client_secret"
  ],
]);

$response = curl_exec($curl);
$result   = json_decode($response, true);

print_r($result);

python

import requests

customer_id = '507f1f77bcf86cd799439011'

response = requests.get(
    f'https://api.cashfin.africa/business/customer/details/{customer_id}',
    headers={'Authorization': 'cs_your_client_secret'}
)

result = response.json()
print(result)

Success Response

json

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+254712345678",
    "company": "Doe Enterprises",
    "country": "Kenya",
    "currency": "KES",
    "type": "business",
    "address": "123 Nairobi St",
    "city": "Nairobi",
    "state": "Nairobi County",
    "website": "https://doe.example.com",
    "active": true,
    "sourceorigin": "api",
    "createdat": "2024-01-15T10:30:00.000Z",
    "updatedat": "2024-01-15T10:30:00.000Z"
  }
}

Update Customer

Update fields on an existing customer. Only the fields you provide will be changed.

http

PATCH /business/customer/update/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Customer ID (MongoDB ObjectID)

Request Body

All fields are optional. Only provided fields will be updated.

Field	Type	Description
`name`	string	Customer's full name
`email`	string	Customer's email address
`phone`	string	Customer's phone number
`company`	string	Company name
`address`	string	Street address
`city`	string	City
`state`	string	State or region
`country`	string	Country
`currency`	string	Preferred currency (e.g., `KES`, `USD`)
`website`	string	Website URL
`type`	string	`individual` or `business`

Example Request

cURLJavaScriptPHPPython

bash

curl -X PATCH "https://api.cashfin.africa/business/customer/update/507f1f77bcf86cd799439011" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+254799000001",
    "city": "Mombasa"
  }'

javascript

const customerId = "507f1f77bcf86cd799439011";

const response = await fetch(
  `https://api.cashfin.africa/business/customer/update/${customerId}`,
  {
    method: "PATCH",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phone: "+254799000001",
      city: "Mombasa",
    }),
  }
);

const data = await response.json();
console.log(data);

php

<?php
$customerId = '507f1f77bcf86cd799439011';

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://api.cashfin.africa/business/customer/update/{$customerId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST  => "PATCH",
  CURLOPT_POSTFIELDS     => json_encode(['phone' => '+254799000001', 'city' => 'Mombasa']),
  CURLOPT_HTTPHEADER     => [
    "Authorization: cs_your_client_secret",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$result   = json_decode($response, true);

print_r($result);

python

import requests

customer_id = '507f1f77bcf86cd799439011'

response = requests.patch(
    f'https://api.cashfin.africa/business/customer/update/{customer_id}',
    headers={
        'Authorization': 'cs_your_client_secret',
        'Content-Type': 'application/json'
    },
    json={'phone': '+254799000001', 'city': 'Mombasa'}
)

result = response.json()
print(result)

Success Response

json

{
  "success": true,
  "message": "Customer updated successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "modified": 1
  }
}

Error Responses

Validation Error

json

{
  "success": false,
  "error": "There are problems with your submission",
  "errors": {
    "email": "Email is required",
    "phone": "Phone is required"
  }
}

Customer Not Found

json

{
  "success": false,
  "error": "Customer not found"
}

Invalid Customer ID

json

{
  "success": false,
  "error": "Invalid customer ID format"
}

Duplicate Customer

json

{
  "success": false,
  "error": "Customer with this email already exists"
}

Customers API ​

Endpoints ​

Create Customer ​

Request Body ​

Example Request ​

Response ​

List Customers ​

Query Parameters ​

Example Request ​

Response ​

Get Customer Details ​

Path Parameters ​

Example Request ​

Success Response ​

Update Customer ​

Path Parameters ​

Request Body ​

Example Request ​

Success Response ​

Error Responses ​

Validation Error ​

Customer Not Found ​

Invalid Customer ID ​

Duplicate Customer ​

Customers API

Endpoints

Create Customer

Request Body

Example Request

Response

List Customers

Query Parameters

Example Request

Response

Get Customer Details

Path Parameters

Example Request

Success Response

Update Customer

Path Parameters

Request Body

Example Request

Success Response

Error Responses

Validation Error

Customer Not Found

Invalid Customer ID

Duplicate Customer