Appointment XIS OpenAPI specification

This page describes the Appointment API specification the XIS should provide to Spreekuur.nl.

• getGet Bookable Appointment Types
• getSearch for Practitioner Roles
• getSearch for Schedules
• getSearch for available slots
• getSearch for Appointments
• postCreate a new Appointment
• postCancel an appointment with an Appointment Response

API docs by Redocly

XIS appointment FHIR API (1.0.0)

Download OpenAPI specification:Download

Get Bookable Appointment Types

Responses

https://docs.spreekuur.nl/ValueSet/BookableAppointmentTypes

Response samples

• 200

Content type

application/fhir+json

{

• "resourceType": "AppointmentType",
• "compose": {

  • "include": [

    • {

      • "actor": {

        • "system": "http://www.example-xis.nl/ns/communication-type",
        • "concept": {

          • "code": "E-CONSULT",
          • "display": "E-Consult"

          }

        }

      }

    ]

  }

}

Search for Practitioner Roles

Responses

https://docs.spreekuur.nl/PractitionerRole

Response samples

• 200

Content type

application/fhir+json

{

• "resourceType": "Bundle",
• "entry": [

  • {

    • "fullUrl": "https://api.example-xis.com/fhir/PractitionerRole/123",
    • "resource": {

      • "resourceType": "PractitionerRole",
      • "id": 123,
      • "name": "Dr. John Doe",
      • "speciality": {

        • "coding": [

          • {

            • "system": "http://www.example-xis.nl/ns/speciality",
            • "code": "0100",
            • "display": "Huisartsen, niet nader gespecificeerd"

            }

          ]

        }

      }

    }

  ]

}

Search for Schedules

query Parameters

service-category

string The service category a schedule is related to. System and value should be provided in the format "system|value"

Responses

https://docs.spreekuur.nl/Schedule

Response samples

• 200

Content type

application/fhir+json

{

• "resourceType": "Bundle",
• "type": "searchset",
• "entry": [

  • {

    • "resourceType": "Schedule",
    • "id": 123,
    • "serviceCategory": [

      • {

        • "coding": [

          • {

            • "system": "http://www.example-xis.nl/ns/communication-type",
            • "code": "E-CONSULT",
            • "display": "E-Consult"

            }

          ]

        }

      ],
    • "actor": [

      • {

        • "reference": "PractitionerRole/topicus-practitioner-1-practitionerrole-1"

        }

      ]

    }

  ]

}

Search for available slots

query Parameters

service-category	string The service category a slot is related to. System and value should be provided in the format "system|value"
schedule.date=ge	string The date in ISO-8601 from which to search for available slots.
schedule.date=le	string The date in ISO-8601 to which to search for available slots.
schedule.actor:PractitionerRole	string A comma seperated list of PractitionerRole id's which are related to the slots

Responses

https://docs.spreekuur.nl/Slot

Response samples

• 200

Content type

application/fhir+json

{

• "resourceType": "Bundle",
• "type": "searchset",
• "entry": [

  • {

    • "resourceType": "Slot",
    • "id": 123,
    • "status": "free",
    • "start": "2025-04-10T09:00:00Z",
    • "end": "2025-04-10T09:30:00Z",
    • "serviceCategory": [

      • {

        • "coding": [

          • {

            • "system": "http://www.example-xis.nl/ns/communication-type",
            • "code": "E-CONSULT",
            • "display": "E-Consult"

            }

          ]

        }

      ],
    • "extension": [

      • {

        • "url": "urn:extension:actor",
        • "valueReference": {

          • "reference": "PractitionerRole/topicus-practitioner-1-practitionerrole-1",
          • "display": "Dokter Jansen"

          }

        }

      ],
    • "slotType": {

      • "coding": [

        • {

          • "system": "http://www.example-xis.nl/ns/slot-type",
          • "code": "E-CONSULT",
          • "display": "E-Consult"

          }

        ]

      }

    }

  ]

}

Search for Appointments

query Parameters

id	string The appointment id to search for

Responses

https://docs.spreekuur.nl/Appointment

Response samples

• 200

Content type

application/fhir+json

{

• "resourceType": "Bundle",
• "type": "searchset",
• "entry": [

  • {

    • "fullUrl": "https://api.example.com/fhir/Appointment/123",
    • "resource": {

      • "resourceType": "Appointment",
      • "id": "123",
      • "status": "proposed",
      • "start": "2025-04-10T09:00:00Z",
      • "end": "2025-04-10T09:30:00Z",
      • "comment": "Please arrive 10 minutes early.",
      • "serviceCategory": [

        • {

          • "coding": [

            • {

              • "system": "http://www.example-xis.nl/ns/communication-type",
              • "code": "E-CONSULT",
              • "display": "E-Consult"

              }

            ]

          }

        ],
      • "participant": [

        • {

          • "actor": {

            • "reference": "Patient/456",
            • "display": "John Doe",
            • "required": "required"

            },
          • "status": "needs-action"

          }

        ]

      }

    }

  ]

}

Create a new Appointment

Request Body schema: application/fhir+json

required

resourceType required	string Value: "Appointment"
id required	string
status required	string Enum: "proposed" "booked" "cancelled"
start required	string <date-time>
end required	string <date-time>
comment required	string
required	Array of objects (serviceCategory)
required	Array of objects When the appointment is created, two participants are added: the patient and the practitioner. When the approval flow is enabled, the practitioner has the status 'needs-action'. If not, the status is 'accepted' The patient always has the status 'accepted'.

Responses

https://docs.spreekuur.nl/Appointment

Request samples

• Payload

Content type

application/fhir+json

{

• "resourceType": "Appointment",
• "id": "123",
• "status": "proposed",
• "start": "2025-04-10T09:00:00Z",
• "end": "2025-04-10T09:30:00Z",
• "comment": "Please arrive 10 minutes early.",
• "serviceCategory": [

  • {

    • "coding": [

      • {

        • "system": "http://www.example-xis.nl/ns/communication-type",
        • "code": "E-CONSULT",
        • "display": "E-Consult"

        }

      ]

    }

  ],
• "participant": [

  • {

    • "actor": {

      • "reference": "Patient/456",
      • "display": "John Doe",
      • "required": "required"

      },
    • "status": "needs-action"

    }

  ]

}

Cancel an appointment with an Appointment Response

Request Body schema: application/fhir+json

required

required	object
comment required	string
required	object
participantStatus required	string Value: "declined"

Responses

https://docs.spreekuur.nl/AppointmentResponse

Request samples

• Payload

Content type

application/fhir+json

{

• "actor": {

  • "reference": {

    • "identifier": [

      • {

        • "system": "http://fhir.nl/fhir/NamingSystem/bsn",
        • "value": "123456789"

        }

      ]

    }

  },
• "comment": "Deze afspraak is afgezegd door de patiënt via Spreekuur.nl",
• "appointment": {

  • "reference": "Appointment/123"

  },
• "participantStatus": "declined"

}