---
updatedAt: 2026-09-30T01:00:28.000Z
agentTools:
  projectIndex: https://developers.halaxy.com/llms.txt
---

# Create an appointment

```shell Shell
curl --request POST \
     --url 'https://au-api.halaxy.com/main/Appointment/$book' \
     --header 'accept: application/fhir+json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer ••••••' \
     --data '
{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "appt-resource",
            "resource": {
                "start": "2027-06-15T15:00:00+10:00",
                "end": "2027-06-15T16:00:00+10:00",
                "minutesDuration": 60,
                "resourceType": "Appointment",
                "participant": [
                    {
                        "actor": {
                            "reference": "https://au-api.halaxy.com/main/PractitionerRole/PR-1234567",
                            "type": "PractitionerRole"
                        }
                    }
                ]
            }
        },
        {
            "name": "patient-id",
            "valueReference": {
                "reference": "https://au-api.halaxy.com/main/Patient/12345678",
                "type": "Patient"
            }
        },
        {
            "name": "healthcare-service-id",
            "valueReference": {
                "reference": "https://au-api.halaxy.com/main/HealthcareService/33",
                "type": "HealthcareService"
            }
        },
        {
            "name": "location-type",
            "valueCode": "clinic"
        },
        {
            "name": "status",
            "valueCode": "booked"
        },
        {
            "name": "charge-item-definition-id",
            "valueReference": {
                "reference": "https://au-api.halaxy.com/main/ChargeItemDefinition/123456",
                "type": "ChargeItemDefinition"
            }
        },
        {
            "name": "fail-on-double-booking",
            "valueBoolean": true
        }
    ]
}'
```

```json Response Example
{
  "start": "2027-06-15T15:00:00+10:00",
  "end": "2027-06-15T16:00:00+10:00",
  "minutesDuration": 60,
  "created": "2026-09-30T10:40:34+10:00",
  "participant": [
    {
      "type": [
        {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
              "code": "ATND",
              "display": "attender"
            }
          ]
        }
      ],
      "actor": {
        "reference": "https://au-api.halaxy.com/main/PractitionerRole/PR-1234567",
        "type": "PractitionerRole"
      }
    },
    {
      "actor": {
        "reference": "https://au-api.halaxy.com/main/Patient/12345678",
        "type": "Patient"
      },
      "modifierExtension": [
        {
          "url": "https://terminology.halaxy.com/StructureDefinition/appointment-participant-status",
          "valueCoding": {
            "system": "https://au-api.halaxy.com/presets/CodeSystem/appointment-participant-status",
            "code": "booked",
            "display": "booked"
          }
        }
      ]
    }
  ],
  "supportingInformation": [
    {
      "reference": "https://au-api.halaxy.com/main/HealthcareService/33",
      "type": "HealthcareService"
    }
  ],
  "id": "1234567890",
  "meta": {
    "lastUpdated": "2026-09-30T10:40:34+10:00"
  },
  "resourceType": "Appointment"
}
```

# Set up your request

<!-- shell@1-6 -->

Send a `POST` request to the `$book` endpoint, using the base URL for your region. Every reference in the request body should use the same base URL.

Include these headers:

- `accept`: `application/fhir+json` to receive the response in FHIR format
- `content-type`: `application/json`
- `Authorization`: `Bearer` followed by your access token

See [Request structure](https://developers.halaxy.com/docs/request-structure) for base URLs, and [Authentication](https://developers.halaxy.com/docs/authentication) to generate your access token.

# Set resourceType to Parameters

<!-- shell@8 -->

The appointment details will be set as specific properties under parameters.

# Enter the general appointment details

<!-- shell@10-26 -->

This includes:

- Start time
- End time
- Duration (in minutes)
- `resourceType` (set to Appointment)
- participant > actor (set to `PractitionerRole`)

Note: Because you are using `PractitionerRole` as the participant, this automatically sets both the practitioner AND location for this appointment.

# Set the patient for this appointment

<!-- shell@27-33 -->

Reference the patient via the `Patient` resource, using the patient's ID.

The patient must already exist in Halaxy. To create one first, see the [Add a new patient](https://developers.halaxy.com/recipes/add-a-new-patient) recipe.

# Set the appointment type (optional)

<!-- shell@34-40 -->

Reference the appointment type via the `HealthcareService` resource.

Note: If the appointment type is currently linked to a fee, the fee is not automatically added to the appointment. You must still add the fee in the parameters.

# Set the location type for the appointment

<!-- shell@41-44 -->

Note: Only clinic is currently supported.

# Set the appointment status

<!-- shell@45-48 -->

Enter the status you want this appointment to be set to upon creation.

# Set the appointment fee

<!-- shell@49-55 -->

Reference the fee via the `ChargeItemDefinition` resource.

# Prevent double bookings (optional)

<!-- shell@56-59 -->

Set `fail-on-double-booking` to true to stop the booking if the practitioner already has an appointment at that time. The request returns a `409 Conflict` instead of creating the appointment.

If left out or set to `false`, the appointment is booked even if it overlaps an existing appointment.