Bookings API

Retrieve booking and scheduling records for your business.

Bookings represent scheduled sessions, meetings, or events — either created internally or booked by customers through your public booking page. The Bookings API gives you read access to all booking records.

Read-Only

The Bookings API is read-only. Bookings are created through the Cashfin dashboard or public booking pages.

Use Cases

• Calendar Sync: Pull bookings into an external calendar system
• CRM Integration: Correlate bookings with customer records in your CRM
• Reporting: Analyse booking volumes, completion rates, and revenue

Endpoints

Method	Endpoint	Description
GET	/business/booking/list	List all bookings
GET	/business/booking/details/:id	Get booking details

---

List Bookings

Retrieve a paginated list of bookings.

GET /business/booking/list

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	10	Results per page (max: 100)
search	string	-	Search by title or description
status	string	-	Filter by status: scheduled, completed, cancelled, no-show

Example Request

cURL

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

JavaScript

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

Success Response

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439070",
      "title": "Product Demo - Acme Corp",
      "status": "scheduled",
      "starttime": "2024-01-20T10:00:00.000Z",
      "endtime": "2024-01-20T11:00:00.000Z",
      "allday": false,
      "type": "meeting",
      "amount": 0,
      "createdat": "2024-01-15T09:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 22,
    "page": 1,
    "limit": 10,
    "pages": 3
  }
}

---

Get Booking Details

Retrieve full details of a specific booking.

GET /business/booking/details/:id

Path Parameters

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

Example Request

cURL

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

JavaScript

const bookingId = "507f1f77bcf86cd799439070";

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

Python

import requests

booking_id = '507f1f77bcf86cd799439070'

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

Success Response

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439070",
    "title": "Product Demo - Acme Corp",
    "description": "30-minute product walkthrough",
    "status": "scheduled",
    "starttime": "2024-01-20T10:00:00.000Z",
    "endtime": "2024-01-20T11:00:00.000Z",
    "allday": false,
    "type": "meeting",
    "priority": "medium",
    "location": {
      "type": "virtual",
      "bookinglink": "https://meet.example.com/abc123"
    },
    "participant": {
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+254712345678"
    },
    "amount": 0,
    "billed": false,
    "createdat": "2024-01-15T09:00:00.000Z",
    "updatedat": "2024-01-15T09:00:00.000Z"
  }
}

---

Booking Statuses

Status	Description
scheduled	Booking confirmed, yet to take place
completed	Booking took place successfully
cancelled	Booking was cancelled
no-show	Customer did not attend

---

Error Responses

Booking Not Found

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