Episodes

Episodes are the core clinical workflow unit in Jump EHR — they represent items in the practice inbox. Each episode tracks a clinical workflow for a patient, from initial trigger (appointment booking, lab result, questionnaire submission) through to resolution.

Endpoints

Method	Endpoint	Description
`GET`	`/episodes`	List episodes
`GET`	`/episodes/{id}`	Retrieve an episode
`POST`	`/episodes`	Create an episode
`PATCH`	`/episodes/{id}`	Update an episode
`POST`	`/episodes/{id}/close`	Close an episode
`POST`	`/episodes/{id}/reopen`	Reopen a closed episode
`POST`	`/episodes/{id}/assign`	Assign an episode
`POST`	`/episodes/{id}/change-priority`	Change priority
`GET`	`/episodes/{id}/events`	List events for an episode
`POST`	`/episodes/{id}/events`	Add an event to an episode

Status, priority, and assignment changes must use action endpoints — they cannot be changed via PATCH. This ensures audit trails are maintained.

The Episode Object

{
  "id": "ep_123e4567-e89b-12d3-a456-426614174000",
  "patient_id": "pat_456e7890-e89b-12d3-a456-426614174111",
  "title": "Lab result review — Blood panel",
  "description": "Routine blood test results received from TDL",
  "status": "open",
  "responsibility": "practice",
  "assigned_to": "usr_789a0123-e89b-12d3-a456-426614174222",
  "priority": "medium",
  "journey_type": "clinical_result",
  "source_type": "lab_result",
  "source_id": "lr_012b3456-e89b-12d3-a456-426614174333",
  "problem_ids": [],
  "tags": ["blood-panel", "routine"],
  "due_date": "2025-01-20T17:00:00Z",
  "closed_at": null,
  "programme_id": null,
  "inbox_visibility": "surface",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T14:20:00Z"
}

Status Values

Status	Responsibility	Description
`open`	`practice` or `patient`	Active, awaiting action
`pending_patient`	`patient`	Waiting on patient response
`awaiting_review`	`practice`	Ready for clinical review
`closed`	`none`	Resolved

Journey Types

Episodes are partitioned by journey type to prevent unrelated events from merging:

general, access, questionnaire, clinical_result, communication, identity, billing, prescription, clinical_access, document

Priority Values

low, medium, high, urgent

List Episodes

GET /episodes

Sorted by updated_at descending (most recently active first) — inbox semantics.

Query Parameters

Parameter	Type	Description
`limit` / `offset`	integer	Pagination (default 20)
`search`	string	Search by title or description
`patient_id`	string	Filter by patient
`status`	string	Filter by status
`status_in`	string	Multiple statuses (comma-separated)
`responsibility`	string	Filter by `practice` or `patient`
`assigned_to`	string	Filter by assigned user ID
`priority`	string	Filter by priority
`priority_in`	string	Multiple priorities (comma-separated)
`journey_type`	string	Filter by journey type
`journey_type_in`	string	Multiple journey types (comma-separated)
`source_type`	string	Filter by source type
`source_id`	string	Filter by source ID
`programme_id`	string	Filter by care programme
`inbox_visibility`	string	`surface` or `silent`
`due_date_gte` / `due_date_lte`	string	Due date range
`created_at_gte` / `created_at_lte`	string	Creation date range

Request

curl -X GET "https://app.usejump.co.uk/functions/v1/api-v1/episodes?status=open&priority_in=high,urgent&limit=20" \
  -H "Authorization: Bearer pk_live_your_api_key"

Create an Episode

POST /episodes

Supports idempotency via Idempotency-Key header.

Required Fields

Field	Type	Description
`patient_id`	string	Patient ID
`title`	string	Episode title

Optional Fields

Field	Type	Description
`description`	string	Detailed description
`status`	string	Initial status (not `closed`)
`responsibility`	string	`practice`, `patient`, or `none`
`assigned_to`	string	User ID to assign
`priority`	string	`low`, `medium`, `high`, `urgent`
`journey_type`	string	Journey type classification
`source_type`	string	What created this episode
`source_id`	string	Source object ID
`problem_ids`	array	Linked problem UUIDs
`tags`	array	Tags
`due_date`	string	ISO 8601 due date
`programme_id`	string	Care programme ID
`inbox_visibility`	string	`surface` or `silent`

⚠️

Consistency rules are enforced on create: status: "pending_patient" requires responsibility: "patient", and responsibility: "none" is only valid for closed episodes.

Update an Episode

PATCH /episodes/{id}

Updates metadata fields only. For status, priority, and assignment changes, use the action endpoints below.

Updatable Fields

title, description, due_date, problem_ids, tags, journey_type, source_type, source_id, programme_id, inbox_visibility

Close an Episode

POST /episodes/{id}/close

Close an open, pending_patient, or awaiting_review episode. Already-closed episodes return 422 INVALID_STATE_TRANSITION.

Request Body (optional)

Field	Type	Description
`reason`	string	`resolved`, `duplicate`, `patient_declined`, or `admin_closed`
`note`	string	Free-text note

Response

{
  "data": { "id": "ep_123", "status": "closed", "responsibility": "none", "closed_at": "2025-01-15T15:00:00Z" },
  "meta": {
    "request_id": "req_abc123",
    "action": "closed",
    "performed_at": "2025-01-15T15:00:00Z",
    "performed_by": "key_abc123"
  }
}

Reopen an Episode

POST /episodes/{id}/reopen

Reopen a closed episode. Only closed episodes can be reopened.

Request Body (optional)

Field	Type	Default	Description
`status`	string	`open`	Target status (`open`, `pending_patient`, `awaiting_review`)
`responsibility`	string	`practice`	`practice` or `patient`
`reason`	string	-	Free-text reason

Assign an Episode

POST /episodes/{id}/assign

Assign or unassign an episode. Cannot assign closed episodes.

Request Body

Field	Type	Required	Description
`assigned_to`	string\|null	Yes	User UUID, or `null` to unassign
`responsibility`	string	No	`practice` or `patient`

⚠️

You cannot set responsibility: "practice" with assigned_to: null. Either provide an assignee or set responsibility to patient.

Change Priority

POST /episodes/{id}/change-priority

Change the priority of a non-closed episode.

Request Body

Field	Type	Required	Description
`priority`	string	Yes	`low`, `medium`, `high`, or `urgent`
`reason`	string	No	Reason for change

Episode Events

See Episode Events for the nested event endpoints (GET /episodes/{id}/events and POST /episodes/{id}/events).

Related Resources

Episode Events - Timeline events within episodes
Patients - Patient records
Pathway Configs - How events route into episodes

Consultations Episode Events