List Todos

Returns a paginated, filtered list of todos for the authenticated organisation.

Endpoint

GET /todo-service/v1/todos

Query Parameters

Parameter	Type	Required	Description
clinic_id	string	No	Comma-separated clinic IDs. If omitted, returns todos from all clinics in the organisation
page	integer	No	Page number (1-indexed). Defaults to 1
size	integer	No	Records per page (max 100). Defaults to 20
todo_type	string	No	Filter by todo type, e.g. POC_EXPIRY
todo_status	string	No	Filter by status: ACTIVE, COMPLETED, or CANCELLED
assigned_to_role	string	No	Filter by role: PROVIDER, FRONT_OFFICE, or BILLER
patient_id	integer	No	Filter by patient ID
doctor_id	integer	No	Filter by doctor ID (applies to POC entity types)
priority	string	No	Filter by priority: HIGH, MEDIUM, or LOW
is_overdue	boolean	No	When true, returns only overdue todos
start_date	string	No	Filter by due date start. Accepts RFC3339 or YYYY-MM-DD
end_date	string	No	Filter by due date end. Accepts RFC3339 or YYYY-MM-DD
time_filter	string	No	Predefined time bucket. One of about_to_expire, today, tomorrow, this_week, next_week, expired
entity_type	string	No	Filter by entity type: PLAN_OF_CARE, AUTHORIZATION, APPOINTMENT, or SOAP
entity_id	string	No	Filter by a specific entity ID
insurance_payer_id	string	No	Filter by insurance payer ID. Applies to PLAN_OF_CARE todos only
insurance_plan_type	string	No	Filter by insurance plan type. Applies to PLAN_OF_CARE todos only
authorized_visits	integer	No	Filter by authorized visit count
current_visits	integer	No	Filter by current visit count
remaining_visits	integer	No	Upper bound filter: todos where authorized - consumed <= value
days_until_expiry	integer	No	Upper bound filter: todos expiring within the next N days

Request

curl --location '{base_url}/todo-service/v1/todos?clinic_id=1001&todo_status=ACTIVE&page=1&size=20' \
  --header 'Authorization: Bearer JWT_TOKEN'

Response

Success Response

Code: 200 OK

{
  "todos": [
    {
      "id": "td-9f3a1bc2-4e5d-4f6a-8b7c-123456789abc",
      "todo_type": "POC_EXPIRY",
      "patient_id": 12345,
      "case_id": null,
      "clinic_id": 1001,
      "organisation_id": 2001,
      "todo_status": "ACTIVE",
      "priority": "HIGH",
      "due_date": "2025-02-15T10:00:00Z",
      "days_until_due": 14,
      "is_overdue": false,
      "threshold_count": null,
      "current_count": null,
      "remaining_count": null,
      "assigned_to_user_id": null,
      "assigned_to_role": "PROVIDER",
      "entity_id": "poc-abc-123",
      "entity_type": "PLAN_OF_CARE",
      "context_data": {},
      "actions": [],
      "polling_url": "/todo-service/v1/todos/td-9f3a1bc2-4e5d-4f6a-8b7c-123456789abc/status",
      "created_at": "2025-01-31T08:00:00Z",
      "updated_at": "2025-01-31T08:00:00Z",
      "version": 1,
      "deleted": false,
      "deleted_at": null
    }
  ],
  "total": 42,
  "pages": 3,
  "current": 1,
  "no_of_records": 20
}

Response Fields

Field	Type	Description
todos	array	Array of todo objects. See Get Todo for field descriptions
total	integer	Total number of matching todos
pages	integer	Total number of pages
current	integer	Current page number
no_of_records	integer	Number of todos returned in this page

Error Response

Code: 400 Bad Request

{
  "error": "Invalid clinic_id: abc"
}