Collections API¶

Delinquency tracking, collection queues, collection actions, dunning schedules, and collection agency management.

Base permission: IsViewerOrAbove (read), IsCollectorOrAbove (write)

Delinquency¶

Method	Path	Description	Permission
`GET`	`/delinquency`	List delinquency records	`IsViewerOrAbove`
`GET`	`/delinquency/{id}`	Get delinquency record	`IsViewerOrAbove`

Delinquency records are maintained automatically by the daily delinquency engine (Celery task). They are read-only via the API.

Delinquency Record¶

{
  "id": "...",
  "loan_id": "550e8400-e29b-41d4-a716-446655440000",
  "days_past_due": 45,
  "delinquency_bucket": "dpd_30_59",
  "amount_past_due": "625.00",
  "is_non_accrual": false,
  "last_payment_date": "2025-12-01",
  "updated_at": "2026-01-15T02:30:00Z"
}

Delinquency Buckets¶

Bucket	Days Past Due
`current`	0
`dpd_1_29`	1--29
`dpd_30_59`	30--59
`dpd_60_89`	60--89
`dpd_90_119`	90--119
`dpd_120_plus`	120+

Collection Queues¶

Queues organize delinquent loans by priority for collector assignment.

Method	Path	Description	Permission
`GET`	`/collection-queues`	List queues	`IsViewerOrAbove`
`GET`	`/collection-queues/{id}`	Get queue	`IsViewerOrAbove`
`POST`	`/collection-queues`	Create queue	`IsAdminOrAbove`
`PUT`	`/collection-queues/{id}`	Update queue	`IsAdminOrAbove`
`DELETE`	`/collection-queues/{id}`	Archive queue	`IsAdminOrAbove`
`GET`	`/collection-queues/{id}/dashboard`	Queue dashboard stats	`IsCollectorOrAbove`

Create Queue¶

POST /api/v1/collection-queues

{
  "name": "Early Stage Collections",
  "description": "Loans 1-29 DPD",
  "priority": 1,
  "min_dpd": 1,
  "max_dpd": 29,
  "auto_assign": true,
  "assignment_method": "round_robin"
}

Queue Dashboard¶

Returns aggregate statistics for a collection queue.

GET /api/v1/collection-queues/{id}/dashboard

Response:

{
  "total_loans": 45,
  "total_amount_past_due": "28750.00",
  "by_bucket": {
    "dpd_1_29": 30,
    "dpd_30_59": 10,
    "dpd_60_89": 5
  },
  "promises_to_pay": 8,
  "actions_today": 12
}

Collection Actions¶

Record collector interactions and actions on delinquent loans.

Method	Path	Description	Permission
`GET`	`/collection-actions`	List actions	`IsViewerOrAbove`
`GET`	`/collection-actions/{id}`	Get action	`IsViewerOrAbove`
`POST`	`/collection-actions`	Create action	`IsCollectorOrAbove`
`PUT`	`/collection-actions/{id}`	Update action	`IsCollectorOrAbove`

Create Collection Action¶

POST /api/v1/collection-actions

{
  "loan_id": "550e8400-e29b-41d4-a716-446655440000",
  "action_type": "phone_call",
  "result": "promise_to_pay",
  "notes": "Borrower agreed to pay $500 by Jan 25",
  "next_action_date": "2026-01-26",
  "next_action_type": "follow_up"
}

Action Types¶

Type	Description
`phone_call`	Outbound phone call
`email`	Email sent
`letter`	Letter sent
`sms`	SMS sent
`visit`	Field visit
`follow_up`	Follow-up action
`skip_trace`	Skip tracing attempt
`legal_referral`	Referred to legal
`agency_referral`	Referred to collection agency

Dunning Schedules¶

Automated dunning communication sequences triggered by days past due.

Method	Path	Description	Permission
`GET`	`/dunning-schedules`	List schedules	`IsViewerOrAbove`
`GET`	`/dunning-schedules/{id}`	Get schedule	`IsViewerOrAbove`
`POST`	`/dunning-schedules`	Create schedule	`IsAdminOrAbove`
`PUT`	`/dunning-schedules/{id}`	Update schedule	`IsAdminOrAbove`
`DELETE`	`/dunning-schedules/{id}`	Delete schedule	`IsAdminOrAbove`

Create Dunning Schedule¶

POST /api/v1/dunning-schedules

{
  "program_id": "661f9511-f3ac-52e5-b827-557766551111",
  "name": "Standard Dunning",
  "steps": [
    {
      "dpd_trigger": 5,
      "channel": "email",
      "template_id": "...",
      "description": "Friendly reminder"
    },
    {
      "dpd_trigger": 15,
      "channel": "sms",
      "template_id": "...",
      "description": "Payment overdue notice"
    },
    {
      "dpd_trigger": 30,
      "channel": "letter",
      "template_id": "...",
      "description": "Formal demand letter"
    }
  ]
}

Note

Dunning communications respect the borrower's do_not_contact flag and communication_preference settings. Borrowers flagged do_not_contact = true receive zero automated communications.

Collection Agencies¶

External collection agency management for escalated accounts.

Method	Path	Description	Permission
`GET`	`/collection-agencies`	List agencies	`IsViewerOrAbove`
`GET`	`/collection-agencies/{id}`	Get agency	`IsViewerOrAbove`
`POST`	`/collection-agencies`	Create agency	`IsAdminOrAbove`
`PUT`	`/collection-agencies/{id}`	Update agency	`IsAdminOrAbove`
`POST`	`/collection-agencies/{id}/assignments`	Assign loan to agency	`IsAdminOrAbove`
`POST`	`/collection-agencies/{id}/assignments/{assignment_id}/recall`	Recall from agency	`IsAdminOrAbove`
`POST`	`/collection-agencies/{id}/assignments/{assignment_id}/resolve`	Mark resolved	`IsAdminOrAbove`