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

---

Create Customer

Create a new customer in your business account.

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

cURL

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

{
  "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.

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

cURL

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

{
  "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
  }
}

---

Error Responses

Validation Error

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

Duplicate Customer

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