Collections Resource

Execute collections and monitor their status. The Collections resource leverages the Smart Collections Engine to optimize collection timing and maximize success rates.

Endpoints

POST /collections/execute - Execute smart collections
GET /collections/{id} - Query collection status

Execute Smart Collections

Trigger the monthly collections cycle for policies.

Endpoint: POST /collections/execute

Request:

POST /collections/execute
Content-Type: application/json

{
  "period_month": "2025-11",
  "policy_ids": ["POL001", "POL002"]  // Optional - omit to collect all
}

Response:

{
  "execution_id": "exec_123",
  "status": "processing",
  "policies_queued": 2
}

Use Case: Trigger monthly collections cycle
Agreement Reference: Section 4.2

How Smart Collections Works

The Smart Collections Engine automatically:

Analyzes customer income patterns - Identifies salary dates and irregular income
Optimizes collection timing - Collects 1-2 days after income deposits
Splits into partial debits - For customers with irregular income
Auto-retries on failures - Throughout the month
Aims for full collection - By month end

No manual intervention required - the engine handles everything automatically.

Query Collection Status

Check the status of a specific collection.

Endpoint: GET /collections/{collectionId}

Response:

{
  "id": "coll_123",
  "period_month": "2025-11",
  "customer_id": "CUST001",
  "external_customer_ref": "EXT123",
  "policy_number": "POL001",
  "product_code": "FUNERAL_01",
  "collection_amount_due": 150.00,
  "collection_amount_collected": 150.00,
  "shortfall": 0.00,
  "collection_status": "PAID_FULL",
  "first_attempt_date": "2025-11-05",
  "last_attempt_date": "2025-11-05",
  "number_of_attempts": 1,
  "last_failure_reason": null
}

Collection Status Values:

PAID_FULL - Full amount collected
PAID_PARTIAL - Partial amount collected (shortfall > 0)
UNPAID - No amount collected
CANCELLED - Policy cancelled during period

Use Case: Check individual collection progress
Agreement Reference: Section 5.2b

Example: Failed Collection → Auto Retry → Success

Timeline:

Day 5:  First attempt R150 → FAILED (insufficient funds)
Day 26: Auto-retry after salary deposit → SUCCESS ✅

Result:
  collection_status: PAID_FULL
  number_of_attempts: 2
  collection_amount_collected: 150.00

Example: Partial Collections (Gig Worker)

Scenario: Customer with irregular income, R300/month premium

Day 5:  Income R80 detected  → Collect R80
Day 12: Income R70 detected  → Collect R70
Day 18: Income R90 detected  → Collect R90
Day 25: Income R60 detected  → Collect R60

Total collected: R300 ✅
Strategy: 4 partial debits
Status: PAID_FULL

Reports Resource - Export collection results
Use Cases - More collection examples
Full API Reference - Interactive API documentation

Collections

On this page