Appointments

The Appointments API allows you to manage patient appointments in Jump EHR. Appointments connect patients with clinicians at specific times and locations.

Endpoints

Method	Endpoint	Description
`GET`	`/appointments`	List all appointments
`GET`	`/appointments/{id}`	Retrieve an appointment
`POST`	`/appointments`	Create an appointment
`PATCH`	`/appointments/{id}`	Update an appointment

Required scopes: read_appointments for GET requests, write_appointments for POST/PATCH requests.

The Appointment Object

{
  "id": "apt_123e4567-e89b-12d3-a456-426614174000",
  "patient_id": "pat_456e7890-e89b-12d3-a456-426614174111",
  "clinician_profile_id": "cli_789a0123-e89b-12d3-a456-426614174222",
  "appointment_type_id": "type_012b3456-e89b-12d3-a456-426614174333",
  "location_id": "loc_345c6789-e89b-12d3-a456-426614174444",
  "title": "Follow-up Consultation",
  "start_time": "2025-01-20T14:00:00Z",
  "end_time": "2025-01-20T14:30:00Z",
  "status": "confirmed",
  "is_remote": false,
  "attendee_name": "Sarah Johnson",
  "attendee_email": "sarah@example.com",
  "attendee_phone": "+44 7700 900123",
  "notes": "Follow-up for blood test results",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Attributes

Field	Type	Description
`id`	string	Unique identifier (UUID)
`patient_id`	string	Associated patient ID
`clinician_profile_id`	string	Assigned clinician ID
`appointment_type_id`	string	Appointment type ID
`location_id`	string	Location ID (null for remote)
`title`	string	Appointment title/description
`start_time`	string	ISO 8601 start time
`end_time`	string	ISO 8601 end time
`status`	string	Status (see below)
`is_remote`	boolean	Whether appointment is virtual
`attendee_name`	string	Attendee's name
`attendee_email`	string	Attendee's email
`attendee_phone`	string	Attendee's phone
`notes`	string	Appointment notes
`created_at`	string	ISO 8601 creation timestamp
`updated_at`	string	ISO 8601 last update timestamp

Status Values

Status	Description
`pending`	Awaiting confirmation
`confirmed`	Confirmed appointment
`cancelled`	Cancelled by patient or clinic
`completed`	Appointment has taken place
`no_show`	Patient did not attend

List Appointments

GET /appointments

Retrieve a paginated list of appointments.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	100	Number of records to return (max 100)
`offset`	integer	0	Number of records to skip
`patient_id`	string	-	Filter by patient ID
`clinician_id`	string	-	Filter by clinician ID
`start_date`	string	-	Filter by start date (YYYY-MM-DD)
`end_date`	string	-	Filter by end date (YYYY-MM-DD)
`status`	string	-	Filter by status

Request

curl -X GET "https://app.usejump.co.uk/functions/v1/api-v1/appointments?start_date=2025-01-20&end_date=2025-01-27&limit=10" \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json"

Response

{
  "data": [
    {
      "id": "apt_123e4567-e89b-12d3-a456-426614174000",
      "patient_id": "pat_456e7890-e89b-12d3-a456-426614174111",
      "clinician_profile_id": "cli_789a0123-e89b-12d3-a456-426614174222",
      "appointment_type_id": "type_012b3456-e89b-12d3-a456-426614174333",
      "title": "Follow-up Consultation",
      "start_time": "2025-01-20T14:00:00Z",
      "end_time": "2025-01-20T14:30:00Z",
      "status": "confirmed",
      "is_remote": false,
      "attendee_name": "Sarah Johnson",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 10,
    "offset": 0,
    "has_more": false
  }
}

Retrieve an Appointment

GET /appointments/{id}

Retrieve a single appointment by ID.

Path Parameters

Parameter	Type	Description
`id`	string	The appointment UUID

Request

curl -X GET "https://app.usejump.co.uk/functions/v1/api-v1/appointments/apt_123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json"

Response

{
  "data": {
    "id": "apt_123e4567-e89b-12d3-a456-426614174000",
    "patient_id": "pat_456e7890-e89b-12d3-a456-426614174111",
    "clinician_profile_id": "cli_789a0123-e89b-12d3-a456-426614174222",
    "appointment_type_id": "type_012b3456-e89b-12d3-a456-426614174333",
    "location_id": "loc_345c6789-e89b-12d3-a456-426614174444",
    "title": "Follow-up Consultation",
    "start_time": "2025-01-20T14:00:00Z",
    "end_time": "2025-01-20T14:30:00Z",
    "status": "confirmed",
    "is_remote": false,
    "attendee_name": "Sarah Johnson",
    "attendee_email": "sarah@example.com",
    "attendee_phone": "+44 7700 900123",
    "notes": "Follow-up for blood test results",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Create an Appointment

POST /appointments

Create a new appointment. Consider using the booking flow for patient-facing scheduling.

For patient self-booking, use the Holds API to temporarily reserve a slot before confirming.

Request Body

Field	Type	Required	Description
`patient_id`	string	Yes	Patient ID
`start_time`	string	Yes	ISO 8601 start time
`end_time`	string	Yes	ISO 8601 end time
`clinician_profile_id`	string	No	Clinician ID
`appointment_type_id`	string	No	Appointment type ID
`location_id`	string	No	Location ID
`title`	string	No	Appointment title
`is_remote`	boolean	No	Whether virtual (default: false)
`attendee_name`	string	No	Attendee's name
`attendee_email`	string	No	Attendee's email
`attendee_phone`	string	No	Attendee's phone
`notes`	string	No	Appointment notes

Request

curl -X POST "https://app.usejump.co.uk/functions/v1/api-v1/appointments" \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "pat_456e7890-e89b-12d3-a456-426614174111",
    "clinician_profile_id": "cli_789a0123-e89b-12d3-a456-426614174222",
    "appointment_type_id": "type_012b3456-e89b-12d3-a456-426614174333",
    "start_time": "2025-01-25T10:00:00Z",
    "end_time": "2025-01-25T10:30:00Z",
    "title": "Initial Consultation",
    "attendee_name": "Sarah Johnson",
    "attendee_email": "sarah@example.com"
  }'

Response

{
  "data": {
    "id": "apt_555e6666-e89b-12d3-a456-426614174555",
    "patient_id": "pat_456e7890-e89b-12d3-a456-426614174111",
    "clinician_profile_id": "cli_789a0123-e89b-12d3-a456-426614174222",
    "appointment_type_id": "type_012b3456-e89b-12d3-a456-426614174333",
    "location_id": null,
    "title": "Initial Consultation",
    "start_time": "2025-01-25T10:00:00Z",
    "end_time": "2025-01-25T10:30:00Z",
    "status": "pending",
    "is_remote": false,
    "attendee_name": "Sarah Johnson",
    "attendee_email": "sarah@example.com",
    "attendee_phone": null,
    "notes": null,
    "created_at": "2025-01-15T12:00:00Z",
    "updated_at": "2025-01-15T12:00:00Z"
  }
}

Update an Appointment

PATCH /appointments/{id}

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

Path Parameters

Parameter	Type	Description
`id`	string	The appointment UUID

Request Body

All fields from the create endpoint are accepted, plus:

Field	Type	Description
`status`	string	Update appointment status

Request

curl -X PATCH "https://app.usejump.co.uk/functions/v1/api-v1/appointments/apt_555e6666-e89b-12d3-a456-426614174555" \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "confirmed",
    "notes": "Patient confirmed via phone"
  }'

Response

{
  "data": {
    "id": "apt_555e6666-e89b-12d3-a456-426614174555",
    "patient_id": "pat_456e7890-e89b-12d3-a456-426614174111",
    "clinician_profile_id": "cli_789a0123-e89b-12d3-a456-426614174222",
    "appointment_type_id": "type_012b3456-e89b-12d3-a456-426614174333",
    "title": "Initial Consultation",
    "start_time": "2025-01-25T10:00:00Z",
    "end_time": "2025-01-25T10:30:00Z",
    "status": "confirmed",
    "is_remote": false,
    "attendee_name": "Sarah Johnson",
    "attendee_email": "sarah@example.com",
    "notes": "Patient confirmed via phone",
    "created_at": "2025-01-15T12:00:00Z",
    "updated_at": "2025-01-15T12:30: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	Appointment not found
`409`	Conflict	Scheduling conflict (time slot unavailable)
`429`	Too Many Requests	Rate limit exceeded

Error Response

{
  "error": "Conflict",
  "details": "The requested time slot is not available",
  "request_id": "req_abc123"
}

Related Resources

Patients - Patient records
Availability - Query available slots
Holds - Temporary slot reservations
Appointment Types - Service types
Clinicians - Clinician profiles
Locations - Practice locations

Problems Documents