Contracts API

Retrieve contract records for your business.

Contracts track agreements with customers, including start and end dates, value, and status. The Contracts API gives you read access to all contracts — useful for syncing contract data to external legal or CRM systems.

Read-Only

The Contracts API is read-only. Contracts are created and managed from the Cashfin dashboard.

Use Cases

• Legal System Sync: Pull contract data into your document management system
• Revenue Tracking: Monitor contracted revenue and renewal dates
• CRM Integration: Correlate contracts with customer records in external systems

Endpoints

Method	Endpoint	Description
GET	/business/contract/list	List all contracts
GET	/business/contract/details/:id	Get contract details

---

List Contracts

Retrieve a paginated list of contracts.

GET /business/contract/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, contract number, or description
status	string	-	Filter by status: draft, sent, signed, active, expired, terminated
type	string	-	Filter by contract type

Example Request

cURL

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

JavaScript

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

Python

import requests

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

Success Response

{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439090",
      "contractno": "CON-2024-001",
      "title": "Annual Maintenance Agreement",
      "type": "maintenance",
      "status": "active",
      "amount": 120000.0,
      "starttime": "2024-01-01T00:00:00.000Z",
      "endtime": "2024-12-31T00:00:00.000Z",
      "createdat": "2024-01-01T08:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 14,
    "page": 1,
    "limit": 10,
    "pages": 2
  }
}

---

Get Contract Details

Retrieve full details of a specific contract.

GET /business/contract/details/:id

Path Parameters

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

Example Request

cURL

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

JavaScript

const contractId = "507f1f77bcf86cd799439090";

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

Python

import requests

contract_id = '507f1f77bcf86cd799439090'

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

Success Response

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439090",
    "contractno": "CON-2024-001",
    "title": "Annual Maintenance Agreement",
    "description": "Monthly software maintenance and support services",
    "type": "maintenance",
    "status": "active",
    "amount": 120000.0,
    "starttime": "2024-01-01T00:00:00.000Z",
    "endtime": "2024-12-31T00:00:00.000Z",
    "billed": false,
    "items": [
      {
        "name": "Monthly Maintenance",
        "quantity": 12,
        "rate": 10000.0
      }
    ],
    "createdat": "2024-01-01T08:00:00.000Z",
    "updatedat": "2024-01-01T08:00:00.000Z"
  }
}

---

Contract Statuses

Status	Description
draft	Contract created but not yet sent
sent	Sent to customer for review
signed	Contract signed by both parties
active	Contract is currently active
expired	Contract end date has passed
terminated	Contract terminated early

---

Error Responses

Contract Not Found

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