---
title: "Book an Appointment"
description: "Create an appointment for a patient using a timeslot found in the availability flow."
canonical_url: "http://localhost/api/quickstart/book-appointment"
---
# Book an Appointment

> Create an appointment for a patient using a timeslot found in the availability flow.

Learn how to create appointments for patients using available timeslots. This guide shows you how to book appointments once you've found available times.

<u-alert color="primary" icon="heroicons:key" variant="subtle">
<template v-slot:description="">

This guide requires `care_unit_id` and an available `timeslot` from [Show Doctor's Availability](http://localhost/api/quickstart/show-availability), and a valid `patient_id` from [Find or Get Patient](http://localhost/api/quickstart/find-patient) or [Create Patient](http://localhost/api/quickstart/create-patient). If the patient does not exist yet, create them first.

</template>
</u-alert>

## Flow Overview

![Book Appointment Flow](http://localhost/images/quickstart/book-appointment.png)

## Understanding Appointments

- **Appointment**: A scheduled meeting between a patient and a healthcare resource
- **Patient identifier (patient_id)**: Can be internal EHR ID or a typed identifier like `se_personal_number:*` (see [Patient ID guide](http://localhost/api/guides/patient-id))
- **Timeslot**: Must be available before booking

## Code Example

<u-collapsible>
<u-button className="mb-4" color="neutral" label="View full example" trailing-icon="i-heroicons-code-bracket-16-solid" variant="subtle">



</u-button>

<template v-slot:content="">
<code-lang-tabs>
<template v-slot:python="">

```python
import requests
from datetime import datetime
from zoneinfo import ZoneInfo

CLIENT_ID = "your-client-id"
CLIENT_SECRET = "your-client-secret"
BASE_URL = "https://api.leyr.io/api"
EMR = "webdoc"

headers = {
    "x-leyr-client-id": CLIENT_ID,
    "x-leyr-client-secret": CLIENT_SECRET,
    "Content-Type": "application/json"
}

care_unit_id = "care-unit-123"
timeslot = {
    "start": "2024-03-25T14:00:00+01:00",
    "end": "2024-03-25T14:30:00+01:00",
    "resource_id": "doctor-789",
    "healthcare_service_id": "service-101"
}
patient_id = "se_personal_number:191212121212"

# 1. Prepare the appointment payload
appointment_data = {
    "start": timeslot["start"],
    "end": timeslot["end"],
    "patient_id": patient_id,
    "resource_id": timeslot["resource_id"],
    "healthcare_service_id": timeslot["healthcare_service_id"],
    "comment": "First consultation"
}

# 2. Create the appointment
response = requests.post(
    f"{BASE_URL}/emrs/{EMR}/care-units/{care_unit_id}/appointments",
    headers=headers,
    json=appointment_data
)

appointments = response.json()
appointment = appointments[0]

# 3. Read key values from the response
print("✓ Appointment booked successfully!")
print(f"  Appointment ID: {appointment['id']}")
print(f"  Status: {appointment['status']}")
print(f"  Care Unit ID: {appointment['care_unit_id']}")

start_time = datetime.fromisoformat(appointment["start"])
print(f"  Time (Europe/Stockholm): {start_time.astimezone(ZoneInfo('Europe/Stockholm')).strftime('%Y-%m-%d %H:%M')}")
```

</template>

<template v-slot:javascript="">

```javascript
const CLIENT_ID = "your-client-id";
const CLIENT_SECRET = "your-client-secret";
const BASE_URL = "https://api.leyr.io/api";
const EMR = "webdoc";

const headers = {
  "x-leyr-client-id": CLIENT_ID,
  "x-leyr-client-secret": CLIENT_SECRET,
  "Content-Type": "application/json"
};

const careUnitId = "care-unit-123";
const timeslot = {
  start: "2024-03-25T14:00:00+01:00",
  end: "2024-03-25T14:30:00+01:00",
  resource_id: "doctor-789",
  healthcare_service_id: "service-101"
};
const patientId = "se_personal_number:191212121212";

// 1. Prepare the appointment payload
const appointmentData = {
  start: timeslot.start,
  end: timeslot.end,
  patient_id: patientId,
  resource_id: timeslot.resource_id,
  healthcare_service_id: timeslot.healthcare_service_id,
  comment: "First consultation"
};

// 2. Create the appointment
const response = await fetch(
  `${BASE_URL}/emrs/${EMR}/care-units/${careUnitId}/appointments`,
  {
    method: "POST",
    headers,
    body: JSON.stringify(appointmentData)
  }
);

const appointments = await response.json();
const appointment = appointments[0];

// 3. Read key values from the response
console.log("✓ Appointment booked successfully!");
console.log(`  Appointment ID: ${appointment.id}`);
console.log(`  Status: ${appointment.status}`);
console.log(`  Care Unit ID: ${appointment.care_unit_id}`);

const startTime = new Date(appointment.start);
console.log(`  Time (Europe/Stockholm): ${startTime.toLocaleString("sv-SE", { timeZone: "Europe/Stockholm" })}`);
```

</template>
</code-lang-tabs>
</template>
</u-collapsible>

### Shared setup

<code-lang-tabs :items="[{"label":"Python","icon":"i-vscode-icons-file-type-python","slot":"python"},{"label":"JavaScript","icon":"i-vscode-icons-file-type-js-official","slot":"javascript"}]">
<template v-slot:python="">

```python
import requests
from datetime import datetime
from zoneinfo import ZoneInfo

CLIENT_ID = "your-client-id"
CLIENT_SECRET = "your-client-secret"
BASE_URL = "https://api.leyr.io/api"
EMR = "webdoc"

headers = {
    "x-leyr-client-id": CLIENT_ID,
    "x-leyr-client-secret": CLIENT_SECRET,
    "Content-Type": "application/json"
}

care_unit_id = "care-unit-123"
timeslot = {
    "start": "2024-03-25T14:00:00+01:00",
    "end": "2024-03-25T14:30:00+01:00",
    "resource_id": "doctor-789",
    "healthcare_service_id": "service-101"
}
patient_id = "se_personal_number:191212121212"
```

</template>

<template v-slot:javascript="">

```javascript
const CLIENT_ID = "your-client-id";
const CLIENT_SECRET = "your-client-secret";
const BASE_URL = "https://api.leyr.io/api";
const EMR = "webdoc";

const headers = {
  "x-leyr-client-id": CLIENT_ID,
  "x-leyr-client-secret": CLIENT_SECRET,
  "Content-Type": "application/json"
};

const careUnitId = "care-unit-123";
const timeslot = {
  start: "2024-03-25T14:00:00+01:00",
  end: "2024-03-25T14:30:00+01:00",
  resource_id: "doctor-789",
  healthcare_service_id: "service-101"
};
const patientId = "se_personal_number:191212121212";
```

</template>
</code-lang-tabs>

#### 1. Prepare the appointment payload

<code-lang-tabs :items="[{"label":"Python","icon":"i-vscode-icons-file-type-python","slot":"python"},{"label":"JavaScript","icon":"i-vscode-icons-file-type-js-official","slot":"javascript"}]">
<template v-slot:python="">

```python
appointment_data = {
    "start": timeslot["start"],
    "end": timeslot["end"],
    "patient_id": patient_id,
    "resource_id": timeslot["resource_id"],
    "healthcare_service_id": timeslot["healthcare_service_id"],
    "comment": "First consultation"
}
```

</template>

<template v-slot:javascript="">

```javascript
const appointmentData = {
  start: timeslot.start,
  end: timeslot.end,
  patient_id: patientId,
  resource_id: timeslot.resource_id,
  healthcare_service_id: timeslot.healthcare_service_id,
  comment: "First consultation"
};
```

</template>
</code-lang-tabs>

#### 2. Create the appointment

<code-lang-tabs :items="[{"label":"Python","icon":"i-vscode-icons-file-type-python","slot":"python"},{"label":"JavaScript","icon":"i-vscode-icons-file-type-js-official","slot":"javascript"}]">
<template v-slot:python="">

```python
response = requests.post(
    f"{BASE_URL}/emrs/{EMR}/care-units/{care_unit_id}/appointments",
    headers=headers,
    json=appointment_data
)

appointments = response.json()
appointment = appointments[0]
```

</template>

<template v-slot:javascript="">

```javascript
const response = await fetch(
  `${BASE_URL}/emrs/${EMR}/care-units/${careUnitId}/appointments`,
  {
    method: "POST",
    headers,
    body: JSON.stringify(appointmentData)
  }
);

const appointments = await response.json();
const appointment = appointments[0];
```

</template>
</code-lang-tabs>

#### 3. Read key values from the response

<code-lang-tabs :items="[{"label":"Python","icon":"i-vscode-icons-file-type-python","slot":"python"},{"label":"JavaScript","icon":"i-vscode-icons-file-type-js-official","slot":"javascript"}]">
<template v-slot:python="">

```python
print("✓ Appointment booked successfully!")
print(f"  Appointment ID: {appointment['id']}")
print(f"  Status: {appointment['status']}")
print(f"  Care Unit ID: {appointment['care_unit_id']}")

start_time = datetime.fromisoformat(appointment["start"])
print(f"  Time (Europe/Stockholm): {start_time.astimezone(ZoneInfo('Europe/Stockholm')).strftime('%Y-%m-%d %H:%M')}")
```

</template>

<template v-slot:javascript="">

```javascript
console.log("✓ Appointment booked successfully!");
console.log(`  Appointment ID: ${appointment.id}`);
console.log(`  Status: ${appointment.status}`);
console.log(`  Care Unit ID: ${appointment.care_unit_id}`);

const startTime = new Date(appointment.start);
console.log(`  Time (Europe/Stockholm): ${startTime.toLocaleString("sv-SE", { timeZone: "Europe/Stockholm" })}`);
```

</template>
</code-lang-tabs>

## Key Insights

### Appointment Status

Appointments can have different statuses:

- **booked** - Successfully scheduled (most common)
- **awaiting_confirmation** - Requires additional confirmation (some EHRs)
- **completed** - Appointment has occurred
- **cancelled** - Appointment was cancelled

If you receive `awaiting_confirmation`, you may need to provide additional confirmation data. See the [Appointment Confirmation guide](http://localhost/api/guides/appointments/confirm-appointments) for details.

## Using `patient_id` formats

`patient_id` can be provided in multiple formats:

<code-lang-tabs :items="[{"label":"Python","icon":"i-vscode-icons-file-type-python","slot":"python"},{"label":"JavaScript","icon":"i-vscode-icons-file-type-js-official","slot":"javascript"}]">
<template v-slot:python="">

```python
patient_id = "abc_12345"
patient_id = "emr_id:abc_12345"
patient_id = "se_personal_number:191212121212"
```

</template>

<template v-slot:javascript="">

```javascript
let patientId = "abc_12345";
patientId = "emr_id:abc_12345";
patientId = "se_personal_number:191212121212";
```

</template>
</code-lang-tabs>

For more details on patient ID formats, see the [Patient ID Guide](http://localhost/api/guides/patient-id).

## Next steps

<card-group>
<card icon="i-heroicons-document-text" title="Write a Medical Note" to="http://localhost/api/quickstart/write-medical-note">

Document the consultation on the patient's record.

</card>

<card icon="i-heroicons-pencil-square" title="Update Appointments" to="http://localhost/api/guides/appointments/update-appointments">

Reschedule or modify booked appointments.

</card>
</card-group>

## API Reference

For detailed API documentation, see:

- [Appointments API](https://api.leyr.io/docs#tag/Appointments)
- [Patient ID Guide](http://localhost/api/guides/patient-id)


## Sitemap

See the full [sitemap](http://localhost/sitemap.md) for all pages.