Contacts API

Create and manage business contacts programmatically.

Contacts are people associated with your business — team members, clients, or anyone you interact with. Unlike customers (who have a billing relationship), contacts are a general-purpose directory.

Use Cases

• People Directory: Maintain a contact list for your team or client base
• CRM Sync: Import contacts from external platforms
• Communication: Store contact info for use in campaigns and outreach

Endpoints

Method	Endpoint	Description
POST	/business/contact/create	Create a new contact
GET	/business/contact/list	List all contacts
GET	/business/contact/details/:id	Get contact details

---

Create Contact

Add a new contact to your business directory.

POST /business/contact/create

Request Body

Field	Type	Required	Description
name	string	Yes	Contact's full name
email	string	No	Email address
phone	string	No	Phone number
position	string	No	Job title or role
companyname	string	No	Company or organisation

Example Request

cURL

curl -X POST "https://api.cashfin.africa/business/contact/create" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Wanjiku",
    "email": "[email protected]",
    "phone": "+254712345678",
    "position": "Procurement Manager",
    "companyname": "Acme Corp"
  }'

JavaScript

const response = await fetch(
  "https://api.cashfin.africa/business/contact/create",
  {
    method: "POST",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Jane Wanjiku",
      email: "[email protected]",
      phone: "+254712345678",
      position: "Procurement Manager",
      companyname: "Acme Corp",
    }),
  }
);
const data = await response.json();

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://api.cashfin.africa/business/contact/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_POSTFIELDS     => json_encode([
    'name'        => 'Jane Wanjiku',
    'email'       => '[email protected]',
    'phone'       => '+254712345678',
    'position'    => 'Procurement Manager',
    'companyname' => 'Acme Corp',
  ]),
  CURLOPT_HTTPHEADER     => [
    "Authorization: cs_your_client_secret",
    "Content-Type: application/json"
  ],
]);

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

Python

import requests

response = requests.post(
    'https://api.cashfin.africa/business/contact/create',
    headers={
        'Authorization': 'cs_your_client_secret',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Jane Wanjiku',
        'email': '[email protected]',
        'phone': '+254712345678',
        'position': 'Procurement Manager',
        'companyname': 'Acme Corp',
    }
)

Success Response

{
  "success": true,
  "message": "Contact created successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439045",
    "name": "Jane Wanjiku",
    "email": "[email protected]",
    "phone": "+254712345678",
    "position": "Procurement Manager",
    "companyname": "Acme Corp",
    "createdat": "2024-01-15T12:00:00.000Z"
  }
}

---

List Contacts

Retrieve a paginated list of contacts.

GET /business/contact/list

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	10	Results per page (max: 100)
search	string	-	Search by name, email, phone, or company

Example Request

cURL

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

JavaScript

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

Python

import requests

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

Success Response

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439045",
      "name": "Jane Wanjiku",
      "email": "[email protected]",
      "phone": "+254712345678",
      "position": "Procurement Manager",
      "companyname": "Acme Corp",
      "createdat": "2024-01-15T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 62,
    "page": 1,
    "limit": 10,
    "pages": 7
  }
}

---

Get Contact Details

Retrieve full details of a specific contact.

GET /business/contact/details/:id

Path Parameters

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

Example Request

cURL

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

JavaScript

const contactId = "507f1f77bcf86cd799439045";

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

Python

import requests

contact_id = '507f1f77bcf86cd799439045'

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

Success Response

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439045",
    "name": "Jane Wanjiku",
    "email": "[email protected]",
    "phone": "+254712345678",
    "position": "Procurement Manager",
    "companyname": "Acme Corp",
    "active": true,
    "createdat": "2024-01-15T12:00:00.000Z",
    "updatedat": "2024-01-15T12:00:00.000Z"
  }
}

---

Error Responses

Contact Not Found

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