OpenApi v2

This page describes the Appointment API specification the XIS should provide to Spreekuur.nl (versie 2).

• 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 (2.0.0)

Download OpenAPI specification:Download

Get Bookable Appointment Types

query Parameters

service-category

string The service category an appointment type is related to.

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	string The Schedule id to which the slots are related
status	string The Schedule id to which the slots are related

Responses

https://docs.spreekuur.nl/Slot

Response samples

• 200

Content type

application/fhir+json

{

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

  • {

    • "fullUrl": "https://www.example-xis.nl/Slot/123",
    • "resource": {

      • "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"

            }

          }

        ],
      • "schedule": {

        • "reference": "Schedule/123"

        }

      }

    }

  ]

}

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"

    }

  ]

}

Response samples

• 201

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"

}