Patients

The Patients API allows you to manage patient records in Jump EHR. Patients are the core resource that other clinical data (episodes, appointments, questionnaires) relates to.

Endpoints

Method	Endpoint	Description
`GET`	`/patients`	List patients
`GET`	`/patients/{id}`	Retrieve a patient
`POST`	`/patients`	Create a patient
`PATCH`	`/patients/{id}`	Update a patient
`GET`	`/patients/{id}/observations`	Patient observations (longitudinal)
`GET`	`/patients/{id}/medications`	Patient medications (longitudinal)
`GET`	`/patients/{id}/problems`	Patient problem list (longitudinal)
`GET`	`/patients/{id}/referrals`	Patient referrals (longitudinal)
`GET`	`/patients/{id}/allergies`	Patient allergy record (longitudinal)
`GET`	`/patients/{id}/immunisations`	Patient immunisations (longitudinal)

Deleting patients is not permitted (clinical data protection). Use PATCH to archive instead.

The Patient Object

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "first_name": "Sarah",
  "last_name": "Johnson",
  "middle_name": null,
  "preferred_name": "Sally",
  "title": "Ms",
  "date_of_birth": "1985-03-15",
  "biological_sex": "female",
  "gender": "woman",
  "ethnicity": null,
  "nhs_number": "1234567890",
  "email": "sarah.johnson@example.com",
  "phone": "+44 7700 900123",
  "mobile_phone": "+44 7700 900123",
  "home_phone": null,
  "address_line_1": "123 High Street",
  "address_line_2": "Flat 4",
  "address_line_3": null,
  "town_city": "London",
  "postcode": "SW1A 1AA",
  "country": "United Kingdom",
  "preferred_contact_method": "email",
  "status": "active",
  "patient_type": "active",
  "is_deceased": false,
  "date_of_death": null,
  "requires_review": false,
  "review_reason": null,
  "accessibility_needs": null,
  "accessibility_notes": null,
  "occupation": "Teacher",
  "patient_notes": null,
  "consent_sms": true,
  "consent_email": true,
  "consent_marketing": false,
  "consent_electronic_communication": true,
  "archived_at": null,
  "archived_by": null,
  "archive_reason": null,
  "archive_notes": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-06-20T14:45:00Z"
}

Status Values

Value	Description
`active`	Current patient
`inactive`	No longer attending
`archived`	Archived record
`merged`	Merged into another record

Patient Types

Value	Description
`active`	Standard patient
`temporary`	Temporary registration
`dummy`	Test record
`archived`	Archived
`merged`	Merged

List Patients

GET /patients

Retrieve a paginated list of patients.

Query Parameters

Parameter	Type	Description
`limit`	integer	Records per page (1–100, default 20)
`offset`	integer	Records to skip (default 0)
`search`	string	Search by first name, last name, email, or NHS number
`status`	string	Filter by status
`status_in`	string	Filter by multiple statuses (comma-separated)
`patient_type`	string	Filter by patient type
`created_at_gte`	string	Created on or after (ISO 8601)
`created_at_lte`	string	Created on or before (ISO 8601)

Request

curl -X GET "https://app.usejump.co.uk/functions/v1/api-v1/patients?search=sarah&limit=10" \
  -H "Authorization: Bearer pk_live_your_api_key"

Response

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "first_name": "Sarah",
      "last_name": "Johnson",
      "date_of_birth": "1985-03-15",
      "email": "sarah.johnson@example.com",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-06-20T14:45:00Z"
    }
  ],
  "meta": {
    "limit": 10,
    "next_offset": null,
    "has_more": false,
    "request_id": "req_abc123"
  }
}

Retrieve a Patient

GET /patients/{id}

Request

curl -X GET "https://app.usejump.co.uk/functions/v1/api-v1/patients/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer pk_live_your_api_key"

Create a Patient

POST /patients

Required Fields

Field	Type	Description
`first_name`	string	Patient's first name
`last_name`	string	Patient's last name
`date_of_birth`	string	Date of birth (YYYY-MM-DD)

Optional Fields

All other fields from the patient object are accepted. Key optional fields:

Field	Type	Validation
`email`	string	Must be a valid email format
`nhs_number`	string	Must match `\d{3}-?\d{3}-?\d{4}` pattern
`status`	string	`active`, `inactive`, `archived`, `merged`
`patient_type`	string	`active`, `temporary`, `dummy`, `archived`, `merged`
`biological_sex`	string	`male`, `female`, `unknown`, `indeterminate`
`gender`	string	`man`, `woman`, `non_binary`, `other`, `prefer_not_to_say`

Request

curl -X POST "https://app.usejump.co.uk/functions/v1/api-v1/patients" \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Smith",
    "date_of_birth": "1990-07-22",
    "email": "john.smith@example.com",
    "phone": "+44 7700 900456"
  }'

Response (201 Created)

{
  "data": {
    "id": "456e7890-e89b-12d3-a456-426614174111",
    "first_name": "John",
    "last_name": "Smith",
    "date_of_birth": "1990-07-22",
    "email": "john.smith@example.com",
    "phone": "+44 7700 900456",
    "status": "active",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Update a Patient

PATCH /patients/{id}

Only include fields you want to change. All fields from the patient object are updatable except id, created_at, updated_at, and archived_* fields.

Request

curl -X PATCH "https://app.usejump.co.uk/functions/v1/api-v1/patients/456e7890-e89b-12d3-a456-426614174111" \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+44 7700 900789",
    "address_line_1": "456 New Street",
    "town_city": "Manchester"
  }'

Clinical Collections

These endpoints expose patient-level longitudinal clinical data directly from the underlying patient record tables. Unlike consultation endpoints, they are not scoped to a single encounter and do not reconstruct the consultation card or POMR structure.

Each collection returns unfiltered full history by default (including past, stopped, and inactive records). Use query filters to narrow results — for example, ?status=active for current medications.

⚠️

Status filters are case-sensitive and must match exact values. See individual collection docs below for valid values.

Available Collections

Method	Endpoint	Description
`GET`	`/patients/{id}/observations`	All clinical observations
`GET`	`/patients/{id}/medications`	All medications
`GET`	`/patients/{id}/problems`	Full problem list
`GET`	`/patients/{id}/referrals`	All referrals
`GET`	`/patients/{id}/allergies`	Full allergy record
`GET`	`/patients/{id}/immunisations`	All immunisations

All collection endpoints support limit and offset pagination (default: 20 per page, max: 100).

Provenance

Where available, records include provenance fields to indicate where and when they were created:

consultation_context — UUID of the consultation in which the record was created (nullable, no FK constraint)
created_by / recorder_id / authored_by_user_id — the user who created the record (field name varies by collection)
source_system, external_id — present on imported records (observations, medications, allergies)
created_at, updated_at — system timestamps

consultation_context is not a substitute for consultation endpoints. To reconstruct what happened in a specific consultation, use GET /consultations/{id}.

Observations

GET /patients/{id}/observations

All clinical observations for a patient, sorted by effective_datetime DESC (clinical time), then id DESC. Records with null effective_datetime appear last.

effective_datetime — when the measurement was clinically taken
created_at — when the record was entered into the system

Filters

Parameter	Type	Description
`code`	string	SNOMED code (exact match)
`status`	string	`final`, `preliminary`, `amended`, `cancelled`
`effective_datetime_gte`	string	On or after (ISO 8601)
`effective_datetime_lte`	string	On or before (ISO 8601)

Request

curl -X GET "https://app.usejump.co.uk/functions/v1/api-v1/patients/{id}/observations?status=final&limit=50" \
  -H "Authorization: Bearer pk_live_your_api_key"

Medications

GET /patients/{id}/medications

All medications (active and stopped), sorted by created_at DESC. Draft medications are excluded.

Filters

Parameter	Type	Description
`status`	string	`active`, `stopped`, `expired`
`status_in`	string	Comma-separated statuses

Request

curl -X GET "https://app.usejump.co.uk/functions/v1/api-v1/patients/{id}/medications?status=active" \
  -H "Authorization: Bearer pk_live_your_api_key"

Problems

GET /patients/{id}/problems

Full problem list (active and past), sorted by created_at DESC.

Filters

Parameter	Type	Description
`status`	string	`Active`, `Health Administration`, `Past Ended` (case-sensitive)
`status_in`	string	Comma-separated statuses
`significance`	string	`Significant`, `Minor`

Request

curl -X GET "https://app.usejump.co.uk/functions/v1/api-v1/patients/{id}/problems?status=Active" \
  -H "Authorization: Bearer pk_live_your_api_key"

Referrals

GET /patients/{id}/referrals

All referral records, sorted by authored_on DESC. Draft referrals are excluded.

Filters

Parameter	Type	Description
`status`	string	`active`, `completed`, `cancelled`
`priority`	string	`routine`, `urgent`, `asap`, `stat`
`authored_on_gte`	string	On or after (ISO 8601)
`authored_on_lte`	string	On or before (ISO 8601)

Request

curl -X GET "https://app.usejump.co.uk/functions/v1/api-v1/patients/{id}/referrals?status=active" \
  -H "Authorization: Bearer pk_live_your_api_key"

Allergies

GET /patients/{id}/allergies

Full allergy record, sorted by created_at DESC. Includes nested allergy codes and reactions.

Filters

Parameter	Type	Description
`clinical_status`	string	`active`, `inactive`, `resolved`
`criticality`	string	`low`, `high`, `unable-to-assess`

Request

curl -X GET "https://app.usejump.co.uk/functions/v1/api-v1/patients/{id}/allergies?clinical_status=active" \
  -H "Authorization: Bearer pk_live_your_api_key"

Immunisations

GET /patients/{id}/immunisations

All immunisation records, sorted by created_at DESC. Draft records are excluded.

Filters

Parameter	Type	Description
`status`	string	`completed`, `entered-in-error`, `not-done`

Request

curl -X GET "https://app.usejump.co.uk/functions/v1/api-v1/patients/{id}/immunisations?status=completed" \
  -H "Authorization: Bearer pk_live_your_api_key"

Related Resources

Consultations - Encounter-scoped clinical data (POMR structure)
Episodes - Clinical workflow episodes for a patient
Appointments - Patient appointments
Questionnaire Responses - Completed questionnaires

API Explorer Appointments