Episode Events

Episode events form the timeline within an episode — every status change, note, assignment, and clinical action is recorded as an event. Events are append-only and cannot be edited or deleted.

Endpoints

Method	Endpoint	Description
`GET`	`/episodes/{id}/events`	List events for an episode
`POST`	`/episodes/{id}/events`	Create an event on an episode
`GET`	`/episode-events/{id}`	Retrieve an event by ID (direct lookup)

Events are append-only. PATCH and DELETE return 405. To correct an event, create a new event with event_type: "note" referencing the original.

The Event Object

{
  "id": "evt_123e4567-e89b-12d3-a456-426614174000",
  "episode_id": "ep_456e7890-e89b-12d3-a456-426614174111",
  "event_type": "note",
  "title": "Clinical note added",
  "description": "Patient reported improvement in symptoms after medication change.",
  "created_by": "usr_789a0123-e89b-12d3-a456-426614174222",
  "created_by_type": "user",
  "mentioned_users": [],
  "extracted_tags": ["medication", "improvement"],
  "related_object_type": null,
  "related_object_id": null,
  "created_at": "2025-01-15T14:30:00Z",
  "updated_at": "2025-01-15T14:30:00Z"
}

Event Types

Type	Description
`note`	Free-text clinical note
`status_change`	Episode status transition (auto-created by close/reopen actions)
`assignment`	Assignment change (auto-created by assign action)
`priority_change`	Priority change (auto-created by change-priority action)
`questionnaire`	Questionnaire request
`questionnaire_response`	Questionnaire submitted
`communication`	Email/SMS sent or received
`appointment`	Appointment-related activity
`lab_result`	Lab result received
`invoice`	Billing event
`prescription`	Prescription activity
`identity_verification`	Identity check completed
`automation`	System automation event
`notification`	Notification sent
`system`	System event

List Events for an Episode

GET /episodes/{id}/events

Query Parameters

Parameter	Type	Description
`limit` / `offset`	integer	Pagination (default 20)
`search`	string	Search by title or description
`event_type`	string	Filter by event type
`event_type_in`	string	Multiple types (comma-separated)
`created_by`	string	Filter by creator ID
`created_by_type`	string	`user`, `system`, or `patient`
`related_object_type`	string	Filter by related object type
`related_object_id`	string	Filter by related object ID
`created_at_gte` / `created_at_lte`	string	Date range filter

Create an Event

POST /episodes/{id}/events

Add a new event to an episode's timeline. Supports idempotency via Idempotency-Key header (scoped to the episode).

Required Fields

Field	Type	Description
`event_type`	string	One of the event types listed above
`description`	string	Event description

Optional Fields

Field	Type	Default	Description
`title`	string	-	Short title
`created_by`	string	-	User UUID who created the event
`created_by_type`	string	`system`	`user`, `system`, or `patient`
`mentioned_users`	array	-	UUIDs of mentioned users
`extracted_tags`	array	-	Tags
`related_object_type`	string	-	Type of related object
`related_object_id`	string	-	ID of related object

The episode_id comes from the URL — do not include it in the request body.

Request

curl -X POST "https://app.usejump.co.uk/functions/v1/api-v1/episodes/ep_456e7890/events" \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "note",
    "title": "Follow-up call",
    "description": "Spoke with patient, symptoms improving. Will review in 2 weeks."
  }'

Response (201 Created)

{
  "data": {
    "id": "evt_new123",
    "episode_id": "ep_456e7890",
    "event_type": "note",
    "title": "Follow-up call",
    "description": "Spoke with patient, symptoms improving. Will review in 2 weeks.",
    "created_by_type": "system",
    "created_at": "2025-01-15T15:00:00Z"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Retrieve an Event

GET /episode-events/{id}

Direct lookup by event ID. Useful when you have an event ID from a webhook or another source.

Related Resources

Episodes - Parent episode resource

Episodes Questionnaire Templates