Episodes

Manage clinical episodes (inbox items) with the Jump EHR API. Create, update, close, reopen, and assign workflow 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.

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

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

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

Authorization

BearerApiKey

AuthorizationBearer <token>

API key with the pk_live_ prefix. pk_test_ keys are refused (403 TEST_MODE_UNAVAILABLE) until a sandbox exists.

In: header

Query Parameters

limit?integer

Maximum number of records to return (1–100, default 20)

Range1 <= value <= 100

Default20

offset?integer

Number of records to skip (default 0)

Range0 <= value

Default0

search?string

patient_id?string

Formatuuid

status?string

Value in

"open"
"pending_patient"
"awaiting_review"
"closed"

status_in?string

Comma-separated

responsibility?string

Value in

"practice"
"patient"
"none"

assigned_to?string

Formatuuid

priority?string

Value in

"low"
"medium"
"high"
"urgent"

journey_type?string

inbox_visibility?string

Value in

"surface"
"silent"

Response Body

`application/json`

curl -X GET "https://example.com/episodes"

{  "data": [    {      "id": "string",      "patient_id": "string",      "title": "string",      "description": "string",      "status": "open",      "responsibility": "practice",      "assigned_to": "string",      "priority": "low",      "journey_type": "string",      "source_type": "string",      "source_id": "string",      "problem_ids": [        "string"      ],      "tags": [        "string"      ],      "due_date": "string",      "closed_at": "string",      "programme_id": "string",      "inbox_visibility": "surface",      "created_at": "string",      "updated_at": "string"    }  ],  "meta": {    "limit": 20,    "next_offset": 1,    "has_more": true,    "request_id": "req_abc123"  }}

Try-it is disabled for POST /episodes

This operation writes data. Running it from these docs would target the production API and change a real record. Copy the request sample and run it against staging first.

Authorization

BearerApiKey

AuthorizationBearer <token>

API key with the pk_live_ prefix. pk_test_ keys are refused (403 TEST_MODE_UNAVAILABLE) until a sandbox exists.

In: header

Header Parameters

Idempotency-Key?string

Optional UUID for request deduplication. Same key + same body returns the cached response. Same key + different body returns 409 CONFLICT. Keys are scoped to your organisation and endpoint, and expire after 24 hours.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

patient_id*string

Formatuuid

title*string

description?string

status?string

Value in

"open"
"pending_patient"
"awaiting_review"

responsibility?string

Value in

"practice"
"patient"
"none"

assigned_to?string

Formatuuid

priority?string

Value in

"low"
"medium"
"high"
"urgent"

journey_type?string

source_type?string

source_id?string

Formatuuid

problem_ids?array<>

tags?array<string>

due_date?string

Formatdate-time

programme_id?string

Formatuuid

inbox_visibility?string

Value in

"surface"
"silent"

Response Body

`application/json`

curl -X POST "https://example.com/episodes" \  -H "Content-Type: application/json" \  -d '{    "patient_id": "3854866a-5476-48be-8313-77029ccdd7a7",    "title": "string"  }'

{  "data": {    "id": "string",    "patient_id": "string",    "title": "string",    "description": "string",    "status": "open",    "responsibility": "practice",    "assigned_to": "string",    "priority": "low",    "journey_type": "string",    "source_type": "string",    "source_id": "string",    "problem_ids": [      "string"    ],    "tags": [      "string"    ],    "due_date": "string",    "closed_at": "string",    "programme_id": "string",    "inbox_visibility": "surface",    "created_at": "string",    "updated_at": "string"  },  "meta": {    "request_id": "req_abc123"  }}

Authorization

BearerApiKey

AuthorizationBearer <token>

API key with the pk_live_ prefix. pk_test_ keys are refused (403 TEST_MODE_UNAVAILABLE) until a sandbox exists.

In: header

Path Parameters

id*string

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/episodes/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "data": {    "id": "string",    "patient_id": "string",    "title": "string",    "description": "string",    "status": "open",    "responsibility": "practice",    "assigned_to": "string",    "priority": "low",    "journey_type": "string",    "source_type": "string",    "source_id": "string",    "problem_ids": [      "string"    ],    "tags": [      "string"    ],    "due_date": "string",    "closed_at": "string",    "programme_id": "string",    "inbox_visibility": "surface",    "created_at": "string",    "updated_at": "string"  },  "meta": {    "request_id": "req_abc123"  }}

Try-it is disabled for PATCH /episodes/{id}

This operation writes data. Running it from these docs would target the production API and change a real record. Copy the request sample and run it against staging first.

Authorization

BearerApiKey

AuthorizationBearer <token>

API key with the pk_live_ prefix. pk_test_ keys are refused (403 TEST_MODE_UNAVAILABLE) until a sandbox exists.

In: header

Path Parameters

id*string

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Metadata only. Status/priority/assignment use action endpoints.

title?string

description?string

due_date?|

Formatdate-time

problem_ids?array<>

tags?array<string>

journey_type?string

source_type?string

source_id?string

Formatuuid

programme_id?|

Formatuuid

inbox_visibility?string

Value in

"surface"
"silent"

Response Body

`application/json`

curl -X PATCH "https://example.com/episodes/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'

{  "data": {    "id": "string",    "patient_id": "string",    "title": "string",    "description": "string",    "status": "open",    "responsibility": "practice",    "assigned_to": "string",    "priority": "low",    "journey_type": "string",    "source_type": "string",    "source_id": "string",    "problem_ids": [      "string"    ],    "tags": [      "string"    ],    "due_date": "string",    "closed_at": "string",    "programme_id": "string",    "inbox_visibility": "surface",    "created_at": "string",    "updated_at": "string"  },  "meta": {    "request_id": "req_abc123"  }}

Try-it is disabled for POST /episodes/{id}/close

This operation writes data. Running it from these docs would target the production API and change a real record. Copy the request sample and run it against staging first.

Authorization

BearerApiKey

AuthorizationBearer <token>

API key with the pk_live_ prefix. pk_test_ keys are refused (403 TEST_MODE_UNAVAILABLE) until a sandbox exists.

In: header

Path Parameters

id*string

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reason?string

Value in

"resolved"
"duplicate"
"patient_declined"
"admin_closed"

note?string

Response Body

`application/json`

curl -X POST "https://example.com/episodes/497f6eca-6276-4993-bfeb-53cbbbba6f08/close" \  -H "Content-Type: application/json" \  -d '{}'

{  "data": {    "id": "string",    "patient_id": "string",    "title": "string",    "description": "string",    "status": "open",    "responsibility": "practice",    "assigned_to": "string",    "priority": "low",    "journey_type": "string",    "source_type": "string",    "source_id": "string",    "problem_ids": [      "string"    ],    "tags": [      "string"    ],    "due_date": "string",    "closed_at": "string",    "programme_id": "string",    "inbox_visibility": "surface",    "created_at": "string",    "updated_at": "string"  },  "meta": {    "request_id": "req_abc123",    "action": "cancelled",    "performed_at": "2026-01-15T10:30:00Z",    "performed_by": "Example performed by"  }}

Try-it is disabled for POST /episodes/{id}/reopen

This operation writes data. Running it from these docs would target the production API and change a real record. Copy the request sample and run it against staging first.

Authorization

BearerApiKey

AuthorizationBearer <token>

API key with the pk_live_ prefix. pk_test_ keys are refused (403 TEST_MODE_UNAVAILABLE) until a sandbox exists.

In: header

Path Parameters

id*string

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

status?string

Default"open"

Value in

"open"
"pending_patient"
"awaiting_review"

responsibility?string

Default"practice"

Value in

"practice"
"patient"

reason?string

Response Body

`application/json`

curl -X POST "https://example.com/episodes/497f6eca-6276-4993-bfeb-53cbbbba6f08/reopen" \  -H "Content-Type: application/json" \  -d '{}'

{  "data": {    "id": "string",    "patient_id": "string",    "title": "string",    "description": "string",    "status": "open",    "responsibility": "practice",    "assigned_to": "string",    "priority": "low",    "journey_type": "string",    "source_type": "string",    "source_id": "string",    "problem_ids": [      "string"    ],    "tags": [      "string"    ],    "due_date": "string",    "closed_at": "string",    "programme_id": "string",    "inbox_visibility": "surface",    "created_at": "string",    "updated_at": "string"  },  "meta": {    "request_id": "req_abc123",    "action": "cancelled",    "performed_at": "2026-01-15T10:30:00Z",    "performed_by": "Example performed by"  }}

Try-it is disabled for POST /episodes/{id}/assign

This operation writes data. Running it from these docs would target the production API and change a real record. Copy the request sample and run it against staging first.

Authorization

BearerApiKey

AuthorizationBearer <token>

API key with the pk_live_ prefix. pk_test_ keys are refused (403 TEST_MODE_UNAVAILABLE) until a sandbox exists.

In: header

Path Parameters

id*string

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

assigned_to*|

User UUID or null to unassign

Formatuuid

responsibility?string

Value in

"practice"
"patient"

Response Body

`application/json`

curl -X POST "https://example.com/episodes/497f6eca-6276-4993-bfeb-53cbbbba6f08/assign" \  -H "Content-Type: application/json" \  -d '{    "assigned_to": "b9f52997-ff03-4166-bbff-22fd35e12939"  }'

{  "data": {    "id": "string",    "patient_id": "string",    "title": "string",    "description": "string",    "status": "open",    "responsibility": "practice",    "assigned_to": "string",    "priority": "low",    "journey_type": "string",    "source_type": "string",    "source_id": "string",    "problem_ids": [      "string"    ],    "tags": [      "string"    ],    "due_date": "string",    "closed_at": "string",    "programme_id": "string",    "inbox_visibility": "surface",    "created_at": "string",    "updated_at": "string"  },  "meta": {    "request_id": "req_abc123",    "action": "cancelled",    "performed_at": "2026-01-15T10:30:00Z",    "performed_by": "Example performed by"  }}

Try-it is disabled for POST /episodes/{id}/change-priority

This operation writes data. Running it from these docs would target the production API and change a real record. Copy the request sample and run it against staging first.

Authorization

BearerApiKey

AuthorizationBearer <token>

API key with the pk_live_ prefix. pk_test_ keys are refused (403 TEST_MODE_UNAVAILABLE) until a sandbox exists.

In: header

Path Parameters

id*string

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

priority*string

Value in

"low"
"medium"
"high"
"urgent"

reason?string

Response Body

`application/json`

curl -X POST "https://example.com/episodes/497f6eca-6276-4993-bfeb-53cbbbba6f08/change-priority" \  -H "Content-Type: application/json" \  -d '{    "priority": "low"  }'

{  "data": {    "id": "string",    "patient_id": "string",    "title": "string",    "description": "string",    "status": "open",    "responsibility": "practice",    "assigned_to": "string",    "priority": "low",    "journey_type": "string",    "source_type": "string",    "source_id": "string",    "problem_ids": [      "string"    ],    "tags": [      "string"    ],    "due_date": "string",    "closed_at": "string",    "programme_id": "string",    "inbox_visibility": "surface",    "created_at": "string",    "updated_at": "string"  },  "meta": {    "request_id": "req_abc123",    "action": "cancelled",    "performed_at": "2026-01-15T10:30:00Z",    "performed_by": "Example performed by"  }}

Authorization

BearerApiKey

AuthorizationBearer <token>

API key with the pk_live_ prefix. pk_test_ keys are refused (403 TEST_MODE_UNAVAILABLE) until a sandbox exists.

In: header

Path Parameters

id*string

Formatuuid

Query Parameters

limit?integer

Maximum number of records to return (1–100, default 20)

Range1 <= value <= 100

Default20

offset?integer

Number of records to skip (default 0)

Range0 <= value

Default0

event_type?string

event_type_in?string

created_by_type?string

Value in

"user"
"system"
"patient"

Response Body

`application/json`

curl -X GET "https://example.com/episodes/497f6eca-6276-4993-bfeb-53cbbbba6f08/events"

{  "data": [    {      "id": "string",      "episode_id": "string",      "event_type": "string",      "title": "string",      "description": "string",      "created_by": "string",      "created_by_type": "user",      "mentioned_users": [        "string"      ],      "extracted_tags": [        "string"      ],      "related_object_type": "string",      "related_object_id": "string",      "created_at": "string",      "updated_at": "string"    }  ],  "meta": {    "limit": 20,    "next_offset": 1,    "has_more": true,    "request_id": "req_abc123"  }}

Try-it is disabled for POST /episodes/{id}/events

This operation writes data. Running it from these docs would target the production API and change a real record. Copy the request sample and run it against staging first.

Authorization

BearerApiKey

AuthorizationBearer <token>

API key with the pk_live_ prefix. pk_test_ keys are refused (403 TEST_MODE_UNAVAILABLE) until a sandbox exists.

In: header

Use the request body type in TypeScript.

event_type*string

Value in

"note"
"questionnaire"
"communication"
"system"
"status_change"
"questionnaire_response"
"assignment"
"priority_change"
"appointment"
"invoice"
"lab_result"
"identity_verification"
"automation"
"notification"
"prescription"

description*string

title?string

created_by?string

Formatuuid

created_by_type?string

Default"system"

Value in

"user"
"system"
"patient"

mentioned_users?array<>

extracted_tags?array<string>

related_object_type?string

related_object_id?string

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/episodes/497f6eca-6276-4993-bfeb-53cbbbba6f08/events" \  -H "Content-Type: application/json" \  -d '{    "event_type": "note",    "description": "string"  }'

{  "data": {    "id": "string",    "episode_id": "string",    "event_type": "string",    "title": "string",    "description": "string",    "created_by": "string",    "created_by_type": "user",    "mentioned_users": [      "string"    ],    "extracted_tags": [      "string"    ],    "related_object_type": "string",    "related_object_id": "string",    "created_at": "string",    "updated_at": "string"  },  "meta": {    "request_id": "req_abc123"  }}

200application/json

201application/json

409application/json

422application/json

200application/json

404application/json

200application/json

404application/json

422application/json

200application/json

422application/json

200application/json

200application/json

200application/json

200application/json

404application/json

201application/json

404application/json

409application/json

422application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`