Create Todo

Creates a new todo item for a patient. The organisation_id is derived from the caller's JWT and cannot be overridden by the request body.

Endpoint

POST /todo-service/v1/todos

Request Body

Parameter	Type	Required	Description
todo_type	string	Yes	Type of todo. Common values: POC_EXPIRY, AUTHORIZATION_EXPIRY, SOAP_DOCUMENTATION
patient_id	integer	Yes	ID of the patient this todo is for
clinic_id	integer	Yes	ID of the clinic
case_id	string	No	ID of the case to link this todo to
priority	string	No	Priority level: HIGH, MEDIUM, or LOW
due_date	string (date-time)	No	Due date in RFC3339 format
threshold_count	integer	No	Target count (e.g. authorized visits)
current_count	integer	No	Current count toward the threshold
assigned_to_user_id	string	No	User ID of the assigned staff member
assigned_to_role	string	No	Role responsible for this todo: PROVIDER, FRONT_OFFICE, or BILLER
entity_id	string	No	ID of the associated entity (e.g. plan of care or authorization ID)
entity_type	string	No	Type of the associated entity: PLAN_OF_CARE, AUTHORIZATION, APPOINTMENT, or SOAP
context_data	object	No	Arbitrary structured metadata specific to the todo_type
actions	array	No	List of available actions for this todo

Request

curl --location '{base_url}/todo-service/v1/todos' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "todo_type": "POC_EXPIRY",
    "patient_id": 12345,
    "clinic_id": 1001,
    "priority": "HIGH",
    "due_date": "2025-02-15T10:00:00Z",
    "assigned_to_role": "PROVIDER",
    "entity_id": "poc-abc-123",
    "entity_type": "PLAN_OF_CARE",
    "context_data": {
      "plan_of_care_id": "poc-abc-123"
    }
  }'

Response

Success Response

Code: 201 Created

{
  "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": {
    "plan_of_care_id": "poc-abc-123"
  },
  "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
}

Response Fields

Field	Type	Description
id	string	Unique identifier for the todo
todo_type	string	Type of todo
patient_id	integer	Associated patient ID
case_id	string	Associated case ID, or null
clinic_id	integer	Clinic ID
organisation_id	integer	Organisation ID derived from the JWT
todo_status	string	Current status: ACTIVE, COMPLETED, or CANCELLED
priority	string	Priority level: HIGH, MEDIUM, or LOW
due_date	string	Due date in RFC3339, or null
days_until_due	integer	Days until due date, or null if no due date set
is_overdue	boolean	Whether the todo is past its due date
threshold_count	integer	Target count, or null
current_count	integer	Current count, or null
remaining_count	integer	Computed as threshold_count - current_count, or null
assigned_to_user_id	string	Assigned user ID, or null
assigned_to_role	string	Assigned role
entity_id	string	Associated entity ID, or null
entity_type	string	Associated entity type, or null
context_data	object	Arbitrary metadata
actions	array	Available actions
polling_url	string	Relative URL for status polling
created_at	string	Creation timestamp
updated_at	string	Last update timestamp
version	integer	Optimistic concurrency version
deleted	boolean	Whether the todo is soft-deleted
deleted_at	string	Deletion timestamp, or null

Error Response

Code: 400 Bad Request

{
  "error": "Missing required fields: todo_type, patient_id, clinic_id, organisation_id"
}