Appointments API

Retrieve appointment type definitions and their booking statistics.

Appointments in Cashfin are bookable service types — for example "30-min Consultation" or "Strategy Session". Each appointment type has its own availability schedule, duration, and booking URL. The Appointments API gives you read access to all appointment types.

Read-Only

The Appointments API is read-only. Appointment types are created and configured from the Cashfin dashboard.

Use Cases

• Booking Widgets: Fetch appointment types to power a custom booking widget
• Availability Sync: Pull appointment data for integration with external scheduling tools
• Analytics: Monitor booking volumes and completion rates per appointment type

Endpoints

Method	Endpoint	Description
GET	/business/appointment/list	List all appointment types
GET	/business/appointment/details/:id	Get appointment type details

---

List Appointments

Retrieve a paginated list of appointment types.

GET /business/appointment/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: active, inactive, archived
category	string	-	Filter by category: meeting, video_call, phone_call, etc.

Example Request

cURL

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

JavaScript

const response = await fetch(
  "https://api.cashfin.africa/business/appointment/list?status=active",
  {
    headers: { Authorization: "cs_your_client_secret" },
  }
);
const data = await response.json();

Python

import requests

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

Success Response

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439080",
      "title": "30-min Strategy Session",
      "description": "A focused session to discuss your business strategy",
      "duration": 30,
      "category": "meeting",
      "status": "active",
      "publicbooking": true,
      "bookingurl": "https://acmecorp.cashfin.africa/book/strategy-session",
      "totalbookings": 45,
      "pendingbookings": 3,
      "completedbookings": 38,
      "createdat": "2024-01-01T09:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 6,
    "page": 1,
    "limit": 10,
    "pages": 1
  }
}

---

Get Appointment Details

Retrieve full details of a specific appointment type, including availability schedule and settings.

GET /business/appointment/details/:id

Path Parameters

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

Example Request

cURL

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

JavaScript

const appointmentId = "507f1f77bcf86cd799439080";

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

Python

import requests

appointment_id = '507f1f77bcf86cd799439080'

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

Success Response

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439080",
    "title": "30-min Strategy Session",
    "description": "A focused session to discuss your business strategy",
    "duration": 30,
    "category": "meeting",
    "status": "active",
    "publicbooking": true,
    "bookingurl": "https://acmecorp.cashfin.africa/book/strategy-session",
    "bookingslug": "strategy-session",
    "location": {
      "type": "virtual",
      "meetinglink": "https://meet.example.com/strategy"
    },
    "availability": {
      "timezone": "Africa/Nairobi",
      "days": [
        {
          "dayofweek": 1,
          "dayname": "Monday",
          "enabled": true,
          "timeslots": [
            { "starttime": "09:00", "endtime": "12:00", "duration": 30, "available": true }
          ]
        }
      ],
      "minnotice": 24,
      "maxadvance": 30
    },
    "settings": {
      "allowcancellation": true,
      "requireapproval": false,
      "maxbookingsperslot": 1
    },
    "totalbookings": 45,
    "pendingbookings": 3,
    "completedbookings": 38,
    "createdat": "2024-01-01T09:00:00.000Z",
    "updatedat": "2024-01-15T10:00:00.000Z"
  }
}

---

Appointment Statuses

Status	Description
active	Accepting new bookings
inactive	Not accepting new bookings
archived	Archived, no longer visible

---

Error Responses

Appointment Not Found

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