Lists API

Create and manage marketing contact lists programmatically.

Lists are groups of email or SMS contacts used for targeting campaigns. The Lists API lets you create lists, retrieve them, and add contacts — making it easy to sync subscriber data from forms, your website, or external platforms.

Use Cases

Form Integrations: Add subscribers from your website forms directly into Cashfin lists
CRM Sync: Keep Cashfin lists in sync with segments from your CRM
Subscriber Management: Programmatically manage opt-ins from external sources

Endpoints

Method	Endpoint	Description
`POST`	`/business/list/create`	Create a new list
`GET`	`/business/list/list`	List all lists
`GET`	`/business/list/details/:id`	Get list details and contact count
`POST`	`/business/list/:id/contact/add`	Add a contact to a list

Create List

Create a new marketing contact list.

http

POST /business/list/create

Request Body

Field	Type	Required	Description
`name`	string	Yes	List name (must be unique within your account)
`description`	string	No	Description of the list
`type`	string	No	List type: `email` or `sms` (default: `email`)

Example Request

cURLJavaScriptPHPPython

bash

curl -X POST "https://api.cashfin.africa/business/list/create" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Subscribers",
    "description": "Monthly newsletter subscribers from website",
    "type": "email"
  }'

javascript

const response = await fetch(
  "https://api.cashfin.africa/business/list/create",
  {
    method: "POST",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Newsletter Subscribers",
      description: "Monthly newsletter subscribers from website",
      type: "email",
    }),
  }
);
const data = await response.json();

php

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL            => "https://api.cashfin.africa/business/list/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_POSTFIELDS     => json_encode([
    'name'        => 'Newsletter Subscribers',
    'description' => 'Monthly newsletter subscribers from website',
    'type'        => 'email',
  ]),
  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/list/create',
    headers={
        'Authorization': 'cs_your_client_secret',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Newsletter Subscribers',
        'description': 'Monthly newsletter subscribers from website',
        'type': 'email',
    }
)

Success Response

json

{
  "success": true,
  "message": "List created successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439110",
    "name": "Newsletter Subscribers",
    "description": "Monthly newsletter subscribers from website",
    "type": "email",
    "status": "active",
    "createdat": "2024-01-15T12:00:00.000Z"
  }
}

List All Lists

Retrieve a paginated list of marketing lists.

http

GET /business/list/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 or description
`status`	string	-	Filter by status: `active`, `inactive`, `archived`
`type`	string	-	Filter by type: `email`, `sms`

Example Request

cURLJavaScriptPython

bash

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

javascript

const response = await fetch(
  "https://api.cashfin.africa/business/list/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/list/list',
    headers={'Authorization': 'cs_your_client_secret'},
    params={'page': 1, 'limit': 10}
)

Success Response

json

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439110",
      "name": "Newsletter Subscribers",
      "description": "Monthly newsletter subscribers from website",
      "type": "email",
      "status": "active",
      "createdat": "2024-01-15T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 8,
    "page": 1,
    "limit": 10,
    "pages": 1
  }
}

Get List Details

Retrieve full details of a specific list, including its current contact count.

http

GET /business/list/details/:id

Path Parameters

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

Example Request

cURLJavaScriptPython

bash

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

javascript

const listId = "507f1f77bcf86cd799439110";

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

python

import requests

list_id = '507f1f77bcf86cd799439110'

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

Success Response

json

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439110",
    "name": "Newsletter Subscribers",
    "description": "Monthly newsletter subscribers from website",
    "type": "email",
    "status": "active",
    "contactcount": 1240,
    "createdat": "2024-01-15T12:00:00.000Z",
    "updatedat": "2024-01-15T12:00:00.000Z"
  }
}

Add Contact to List

Add a subscriber to a specific list.

http

POST /business/list/:id/contact/add

Path Parameters

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

Request Body

Field	Type	Required	Description
`email`	string	Yes	Contact's email address
`firstname`	string	No	First name
`lastname`	string	No	Last name
`phone`	string	No	Phone number
`company`	string	No	Company name

Example Request

cURLJavaScriptPython

bash

curl -X POST "https://api.cashfin.africa/business/list/507f1f77bcf86cd799439110/contact/add" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstname": "Alice",
    "lastname": "Kamau",
    "company": "Example Ltd"
  }'

javascript

const listId = "507f1f77bcf86cd799439110";

const response = await fetch(
  `https://api.cashfin.africa/business/list/${listId}/contact/add`,
  {
    method: "POST",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: "[email protected]",
      firstname: "Alice",
      lastname: "Kamau",
      company: "Example Ltd",
    }),
  }
);
const data = await response.json();

python

import requests

list_id = '507f1f77bcf86cd799439110'

response = requests.post(
    f'https://api.cashfin.africa/business/list/{list_id}/contact/add',
    headers={
        'Authorization': 'cs_your_client_secret',
        'Content-Type': 'application/json'
    },
    json={
        'email': '[email protected]',
        'firstname': 'Alice',
        'lastname': 'Kamau',
        'company': 'Example Ltd',
    }
)

Success Response

json

{
  "success": true,
  "message": "Contact added to list successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439115",
    "email": "[email protected]",
    "firstname": "Alice",
    "lastname": "Kamau",
    "createdat": "2024-01-15T12:05:00.000Z"
  }
}

Error Responses

Duplicate List Name

json

{
  "success": false,
  "error": "A list with this name already exists"
}

Duplicate Contact Email

json

{
  "success": false,
  "error": "Contact with this email is already in the list"
}

List Not Found

json

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

Lists API ​

Endpoints ​

Create List ​

Request Body ​

Example Request ​

Success Response ​

List All Lists ​

Query Parameters ​

Example Request ​

Success Response ​

Get List Details ​

Path Parameters ​

Example Request ​

Success Response ​

Add Contact to List ​

Path Parameters ​

Request Body ​

Example Request ​

Success Response ​

Error Responses ​

Duplicate List Name ​

Duplicate Contact Email ​

List Not Found ​

Lists API

Endpoints

Create List

Request Body

Example Request

Success Response

List All Lists

Query Parameters

Example Request

Success Response

Get List Details

Path Parameters

Example Request

Success Response

Add Contact to List

Path Parameters

Request Body

Example Request

Success Response

Error Responses

Duplicate List Name

Duplicate Contact Email

List Not Found