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 appointments
`GET`	`/appointments/{id}`	Retrieve an appointment
`POST`	`/appointments`	Create an appointment
`PATCH`	`/appointments/{id}`	Update an appointment
`POST`	`/appointments/{id}/cancel`	Cancel an appointment

Status changes must use the cancel action endpoint. You cannot change status via PATCH.

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",
  "title": "Follow-up Consultation",
  "description": null,
  "start_time": "2025-01-20T14:00:00Z",
  "end_time": "2025-01-20T14:30:00Z",
  "status": "confirmed",
  "appointment_type_id": "type_012b3456-e89b-12d3-a456-426614174333",
  "location_id": "loc_345c6789-e89b-12d3-a456-426614174444",
  "is_remote": false,
  "remote_channel": null,
  "video_link": null,
  "video_provider": null,
  "duration_minutes": 30,
  "attendee_email": "sarah@example.com",
  "attendee_name": "Sarah Johnson",
  "meeting_url": null,
  "attendance_status": null,
  "cancellation_reason": null,
  "booking_source": "api",
  "episode_id": null,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Status Values

Status	Description
`pending_approval`	Awaiting approval
`pending`	Awaiting confirmation
`confirmed`	Confirmed appointment
`scheduled`	Scheduled
`cancelled`	Cancelled
`completed`	Completed
`no_show`	Patient did not attend

List Appointments

GET /appointments

Query Parameters

Parameter	Type	Description
`limit`	integer	Records per page (1–100, default 20)
`offset`	integer	Records to skip (default 0)
`patient_id`	string	Filter by patient ID
`clinician_id`	string	Filter by clinician profile ID
`status`	string	Filter by status
`status_in`	string	Filter by multiple statuses (comma-separated)
`date_gte`	string	Start time on or after (ISO 8601)
`date_lte`	string	Start time on or before (ISO 8601)
`appointment_type_id`	string	Filter by appointment type
`location_id`	string	Filter by location

Request

curl -X GET "https://app.usejump.co.uk/functions/v1/api-v1/appointments?date_gte=2025-01-20&status=confirmed&limit=10" \
  -H "Authorization: Bearer pk_live_your_api_key"

Response

{
  "data": [
    {
      "id": "apt_123e4567-e89b-12d3-a456-426614174000",
      "patient_id": "pat_456e7890-e89b-12d3-a456-426614174111",
      "title": "Follow-up Consultation",
      "start_time": "2025-01-20T14:00:00Z",
      "end_time": "2025-01-20T14:30:00Z",
      "status": "confirmed",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "limit": 10,
    "next_offset": null,
    "has_more": false,
    "request_id": "req_abc123"
  }
}

Retrieve an Appointment

GET /appointments/{id}

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"

Create an Appointment

POST /appointments

Supports idempotency via the Idempotency-Key header.

Required Fields

Field	Type	Description
`title`	string	Appointment title
`start_time`	string	ISO 8601 start time
`end_time`	string	ISO 8601 end time (must be after start_time)

Optional Fields

Field	Type	Description
`patient_id`	string	Patient ID
`clinician_profile_id`	string	Clinician ID
`appointment_type_id`	string	Appointment type ID
`location_id`	string	Location ID
`status`	string	Initial status (`pending_approval`, `confirmed`, `pending`, `scheduled`)
`is_remote`	boolean	Whether virtual (default: false)
`attendee_name`	string	Attendee's name
`attendee_email`	string	Attendee's email
`episode_id`	string	Link to an existing episode

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" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "patient_id": "pat_456e7890-e89b-12d3-a456-426614174111",
    "title": "Initial Consultation",
    "start_time": "2025-01-25T10:00:00Z",
    "end_time": "2025-01-25T10:30:00Z"
  }'

Response (201 Created)

{
  "data": {
    "id": "apt_555e6666-e89b-12d3-a456-426614174555",
    "patient_id": "pat_456e7890-e89b-12d3-a456-426614174111",
    "title": "Initial Consultation",
    "start_time": "2025-01-25T10:00:00Z",
    "end_time": "2025-01-25T10:30:00Z",
    "status": "pending",
    "created_at": "2025-01-15T12:00:00Z",
    "updated_at": "2025-01-15T12:00:00Z"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Update an Appointment

PATCH /appointments/{id}

Update non-status fields. Status changes must use action endpoints (e.g. cancel).

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 '{
    "title": "Follow-up Consultation",
    "attendee_email": "sarah.updated@example.com"
  }'

Cancel an Appointment

POST /appointments/{id}/cancel

Cancel an appointment. Only appointments with status pending_approval, confirmed, pending, or scheduled can be cancelled.

Request Body (optional)

Field	Type	Description
`cancellation_reason`	string	Reason for cancellation

Request

curl -X POST "https://app.usejump.co.uk/functions/v1/api-v1/appointments/apt_555e6666-e89b-12d3-a456-426614174555/cancel" \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "cancellation_reason": "Patient request" }'

Response

{
  "data": {
    "id": "apt_555e6666-e89b-12d3-a456-426614174555",
    "status": "cancelled",
    "cancellation_reason": "Patient request"
  },
  "meta": {
    "request_id": "req_abc123",
    "action": "cancelled",
    "performed_at": "2025-01-15T13:00:00Z",
    "performed_by": "key_abc123"
  }
}

Error: Invalid State Transition

{
  "data": null,
  "meta": { "request_id": "req_abc123" },
  "error": {
    "code": "INVALID_STATE_TRANSITION",
    "message": "Cannot cancel appointment with status \"completed\"",
    "details": {
      "current_status": "completed",
      "attempted_action": "cancel"
    }
  }
}

Related Resources

Patients - Patient records
Appointment Templates - Service type configuration
Episodes - Clinical workflow episodes

Patients Consultations