Endpoints

Policies

Create, import, and update policies

Policies Resource

Manage policies for collections. The Policies resource provides endpoints for creating, bulk importing, and updating policies.

Endpoints

  • POST /policies - Create a single policy
  • POST /policies/import - Bulk import policies from CSV
  • PATCH /policies/{id} - Update an existing policy

Create Policy

Create a single policy programmatically.

Endpoint: POST /policies

Request:

POST /policies
Content-Type: application/json

{
  "policy_number": "POL001",
  "customer_id": "CUST001",
  "external_customer_ref": "EXT123",
  "product_code": "FUNERAL_01",
  "collection_amount": 150.00
}

Response:

{
  "id": "uuid-here",
  "policy_number": "POL001",
  "status": "active",
  "created_at": "2025-11-26T10:00:00Z"
}

Use Case: Add individual policies programmatically
Agreement Reference: Section 5.1a

Bulk Import Policies

Import multiple policies from a CSV file.

Endpoint: POST /policies/import

Request:

POST /policies/import
Content-Type: multipart/form-data

file: policies.csv

CSV Format:

customer_id,external_customer_ref,policy_number,product_code,collection_amount
CUST001,EXT123,POL001,FUNERAL_01,150.00
CUST002,EXT124,POL002,FUNERAL_01,200.00

Response:

{
  "imported": 2,
  "failed": 0,
  "errors": []
}

Use Case: Bulk onboard policies at start of each month
Agreement Reference: Section 5.1a

Example:

curl -X POST https://api.kasipayments.co.za/v1/policies/import \
  -H "X-API-Key: your-key" \
  -F "file=@policies.csv"

Update Policy

Update an existing policy's collection amount or status.

Endpoint: PATCH /policies/{policyId}

Request:

PATCH /policies/{policyId}
Content-Type: application/json

{
  "collection_amount": 200.00,  // For upgrades/downgrades
  "status": "cancelled"          // For cancellations/lapses
}

Response:

{
  "id": "uuid-here",
  "policy_number": "POL001",
  "collection_amount": 200.00,
  "status": "active",
  "updated_at": "2025-11-26T10:30:00Z"
}

Use Case: Handle policy changes, cancellations, premium adjustments
Agreement Reference: Section 5.1b

Policy Status Values:

  • active - Policy in force
  • lapsed - Non-payment
  • cancelled - Customer cancelled

Collections

Execute smart collections and query collection status

Reports

Export collection results for reconciliation

On this page

Policies ResourceEndpointsCreate PolicyBulk Import PoliciesUpdate PolicyRelated Documentation