Patients

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

Endpoints

Method	Endpoint	Description
`GET`	`/patients`	List all patients
`GET`	`/patients/{id}`	Retrieve a patient
`POST`	`/patients`	Create a patient
`PATCH`	`/patients/{id}`	Update a patient

Required scopes: read_patients for GET requests, write_patients for POST/PATCH requests.

The Patient Object

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "first_name": "Sarah",
  "last_name": "Johnson",
  "date_of_birth": "1985-03-15",
  "nhs_number": "123 456 7890",
  "email": "sarah.johnson@example.com",
  "phone": "+44 7700 900123",
  "address_line_1": "123 High Street",
  "address_line_2": "Flat 4",
  "city": "London",
  "postcode": "SW1A 1AA",
  "country": "United Kingdom",
  "gender": "female",
  "custom_fields": {
    "preferred_contact": "email",
    "marketing_consent": true
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-06-20T14:45:00Z"
}

Attributes

Field	Type	Description
`id`	string	Unique identifier (UUID)
`first_name`	string	Patient's first name
`last_name`	string	Patient's last name
`date_of_birth`	string	Date of birth (YYYY-MM-DD)
`nhs_number`	string	NHS number (UK patients)
`email`	string	Email address
`phone`	string	Phone number
`address_line_1`	string	Primary address line
`address_line_2`	string	Secondary address line
`city`	string	City
`postcode`	string	Postal code
`country`	string	Country
`gender`	string	Gender (male, female, other)
`custom_fields`	object	Organization-defined custom fields
`created_at`	string	ISO 8601 creation timestamp
`updated_at`	string	ISO 8601 last update timestamp

List Patients

GET /patients

Retrieve a paginated list of patients.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	100	Number of records to return (max 100)
`offset`	integer	0	Number of records to skip
`search`	string	-	Search by name or NHS number

Request

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

Response

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "first_name": "Sarah",
      "last_name": "Johnson",
      "date_of_birth": "1985-03-15",
      "nhs_number": "123 456 7890",
      "email": "sarah.johnson@example.com",
      "phone": "+44 7700 900123",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-06-20T14:45:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 10,
    "offset": 0,
    "has_more": false
  }
}

Retrieve a Patient

GET /patients/{id}

Retrieve a single patient by ID.

Path Parameters

Parameter	Type	Description
`id`	string	The patient's UUID

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" \
  -H "Content-Type: application/json"

Response

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "first_name": "Sarah",
    "last_name": "Johnson",
    "date_of_birth": "1985-03-15",
    "nhs_number": "123 456 7890",
    "email": "sarah.johnson@example.com",
    "phone": "+44 7700 900123",
    "address_line_1": "123 High Street",
    "address_line_2": "Flat 4",
    "city": "London",
    "postcode": "SW1A 1AA",
    "country": "United Kingdom",
    "gender": "female",
    "custom_fields": {
      "preferred_contact": "email",
      "marketing_consent": true
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-06-20T14:45:00Z"
  }
}

Create a Patient

POST /patients

Create a new patient record.

Request Body

Field	Type	Required	Description
`first_name`	string	Yes	Patient's first name
`last_name`	string	Yes	Patient's last name
`date_of_birth`	string	Yes	Date of birth (YYYY-MM-DD)
`nhs_number`	string	No	NHS number
`email`	string	No	Email address
`phone`	string	No	Phone number
`address_line_1`	string	No	Primary address line
`address_line_2`	string	No	Secondary address line
`city`	string	No	City
`postcode`	string	No	Postal code
`country`	string	No	Country
`gender`	string	No	Gender (male, female, other)
`custom_fields`	object	No	Custom field values

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

{
  "data": {
    "id": "456e7890-e89b-12d3-a456-426614174111",
    "first_name": "John",
    "last_name": "Smith",
    "date_of_birth": "1990-07-22",
    "nhs_number": null,
    "email": "john.smith@example.com",
    "phone": "+44 7700 900456",
    "address_line_1": null,
    "address_line_2": null,
    "city": null,
    "postcode": null,
    "country": null,
    "gender": null,
    "custom_fields": {},
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Update a Patient

PATCH /patients/{id}

Update an existing patient. Only include fields you want to change.

Path Parameters

Parameter	Type	Description
`id`	string	The patient's UUID

Request Body

All fields from the create endpoint are accepted. Only provided fields will be updated.

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",
    "city": "Manchester"
  }'

Response

{
  "data": {
    "id": "456e7890-e89b-12d3-a456-426614174111",
    "first_name": "John",
    "last_name": "Smith",
    "date_of_birth": "1990-07-22",
    "nhs_number": null,
    "email": "john.smith@example.com",
    "phone": "+44 7700 900789",
    "address_line_1": "456 New Street",
    "address_line_2": null,
    "city": "Manchester",
    "postcode": null,
    "country": null,
    "gender": null,
    "custom_fields": {},
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T11:00:00Z"
  }
}

Errors

Status	Error	Description
`400`	Bad Request	Invalid request body or parameters
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	Missing required scope
`404`	Not Found	Patient not found
`429`	Too Many Requests	Rate limit exceeded

Error Response

{
  "error": "Bad Request",
  "details": "first_name is required",
  "request_id": "req_abc123"
}

Related Resources

Consultations - Patient consultation records
Problems - Patient diagnoses and conditions
Appointments - Patient appointments
Documents - Patient documents
Prescriptions - Patient medications

API Explorer Consultations