# Data Exchange - Advance Care Planning (PZP) STU3 v1.0.0

## Data Exchange

This page describes the two transaction methods for exchanging a patient's Advance Care Planning (ACP) information using RESTful API.

1. [As individual resources.](#method-1-retrieve-acp-as-individual-resources)By fetching specific resources (`Consent`,`Goal`,`Observation`, etc.) that together form the patient's ACP. See[Data Model page](data-model.md)for a complete overview.
1. [As a form](#method-2-retrieve-acp-questionnaireresponse). Fetching`QuestionnaireResponse`resource(s). This contains the ACP agreements recorded according to the structured form for uniform registration of ACP.

### Conformance Requirements Actors

This implementation guide defines two actors:

* ACP Actor Consulter: a client application that retrieves a patient's ACP information.
* ACP Actor Provider: a server application that exposes a patient's ACP information.

To be conformant the ACP Actor Consulter SHALL support both transaction groups. This ensures the actor can retrieve ACP information from any provider, regardless of the exchange method implemented. The ACP Actor Provider SHALL support at least one of the two transaction groups. The individual resources method is preferred over the form-based method for system-to-system exchange, as it offers a more standardized and reusable data structure.

### General API requirements

This IG focuses solely on defining how ACP health information is accessed and structured for data exchange. It does not specify supporting functionalities such as addressing, routing, localization, consent management, or authentication. These capabilities are expected to be provided by the underlying infrastructure specifications and agreements in use, such as Generic Functions, LSP, Twiin, or Nuts.

Within this scope, the following requirements apply:

1. **Authorization**: Accessing ACP information is subject to strict privacy and security rules. All API requests MUST be properly authenticated and authorized. The client application is expected to use a secure mechanism to obtain an access token with the necessary scopes to read the patient's clinical data.
1. **Patient Context**: All queries described in this guide are patient-specific. The client needs to know the logical ID of the patient and include it in every query (e.g.,`patient=123`or`subject=Patient/123`). The method for obtaining the patient's logical ID is not specified in this IG, but may include: an initial search request on the Patient endpoint using a patient identifier such as the BSN; interactions as defined in[IHE PDQm ITI-119](https://profiles.ihe.net/ITI/PDQm/3.2.0/ITI-119.html); or any other method provided by the infrastructure.
1. **Resolving References**: The returned resources may contain nested resources or references to other resources (such as`Practitioner`or`RelatedPerson`). The client application may need to perform subsequent requests to resolve these references and display the full details.

-------

### Method 1: Retrieve ACP as Individual Resources

This approach provides granular access to the individual clinical statements that constitute the ACP. It allows applications to query for specific data points without processing an entire form.

This approach is useful for applications that need to query specific parts of a patient's ACP, like treatment wishes or stated goals. While it requires multiple API calls, it provides more granular control and returns the ACP in usable resources. The below listed client requests are in scope of a Patient's context for which an initial request may be needed to match the Patient resource id with an identifier (e.g. BSN).

#### Client Requests

The below listed search requests show how all the ACP agreements, procedural information and relevant clinical context can be retrieved. Information on individuals involved in the ACP process are referenced from these resources and can be retrieved using the `_include` statement as defined below, or by resolving the references. Standard FHIR rules apply on the search syntax.

```
1a GET [base]/Procedure?patient=Patient/[id]&code=http://snomed.info/sct|713603004,urn:oid:2.16.840.1.113883.2.4.3.120.5.3|411600B,urn:oid:2.16.840.1.113883.2.4.3.27.15.5|190099&_include=Procedure:encounter

1b GET [base]/Encounter?patient=Patient/[id]&reason=http://snomed.info/sct|713603004,urn:oid:2.16.840.1.113883.2.4.3.120.5.3|411600B,urn:oid:2.16.840.1.113883.2.4.3.27.15.5|190099

2 GET [base]/Consent?patient=Patient/[id]&category=http://snomed.info/sct|11291000146105&_include=Consent:actor

3 GET [base]/Consent?patient=Patient/[id]&category=http://snomed.info/sct|11341000146107&_include=Consent:actor

4 GET [base]/Goal?patient=Patient/[id]&category=http://snomed.info/sct|713603004

5 GET [base]/Observation?patient=Patient/[id]&code=http://snomed.info/sct|665671000146101,http://snomed.info/sct|153851000146100,http://snomed.info/sct|395091006,http://snomed.info/sct|340171000146104,http://snomed.info/sct|247751003,http://snomed.info/sct|570801000146104

6 GET [base]/DeviceUseStatement?patient=Patient/[id]&device:Device.type=http://snomed.info/sct|72506001,http://snomed.info/sct|465460004,http://snomed.info/sct|468542000,http://snomed.info/sct|704707009,http://snomed.info/sct|1263462004,http://snomed.info/sct|1236894001&_include=DeviceUseSatement:device

7 GET [base]/CommunicationRequest?patient=Patient/[id]&category=http://snomed.info/sct|223449006

```

1. Both requests are designed to retrieve the same information, but with different approaches:
* A) Retrieves `Procedure` resources representing ACP procedures and includes the associated `Encounter` resource where the procedure took place.
* B) Retrieves `Encounter` resources that list an ACP procedure as their reason. Request A is generally preferred because `Encounter.patient` may not always be present; if absent, it indicates the patient was not involved in the Encounter. Using request A ensures these cases are included as well.

1. Retrieves`Consent`resources for Treatment Directives and includes the agreement parties (Patient, ContactPersons, and HealthProfessionals).
1. Retrieves`Consent`resources for Advance Directives and includes the representatives (ContactPersons).
1. Retrieves`Goal`resources related to advance care planning.
1. Retrieves`Observation`resources related to specific wishes, plans and whether the patient is legally capable regarding medical treatment decisions, as defined by the profiles in the Implementation Guide.
1. Retrieves`DeviceUseStatement`resources for devices representing an ICD, and includes the corresponding`Device`resource.
1. Retrieves`CommunicationRequest`resources representing requests made to the patient to inform their relatives.

For `RelatedPerson` and `Practitioner` there is no specific query as according to the model there are references made to these resources. If there is a legal representative we expect that to be present in `Patient.contact`. For related persons attending the encounter a reference is expected to be made in `Encounter.participant`.

##### Distinguishing ICD deactivation from additional 'Other' treatment directives

The treatment directive regarding ICD deactivation is represented as a treatment directive with code `Other`. The SNOMED CT code `400231000146108` for ICD deactivation cannot be communicated in a structured coding element as the treatment directive `extension:treatment.value[x].valueCodeableConcept` element is bound to the national **BehandelingCodelijst**. To enable consistent identification of this specific directive, systems are expected to use the SNOMED CT code `400231000146108` in the `extension:treatment.value[x].valueCodeableConcept` element as demonstrated in this [Example](Consent-ACP-TreatmentDirective-SwitchOffICD-2025-Pat1.md). Receiving systems are expected to use this SNOMED CT code to map the received treatment directive to the dedicated ICD deactivation treatment directive field or functionality in their user interface. The SNOMED CT code itself should not be displayed to end users. This requirement applies only to the treatment directive regarding ICD deactivation and not to other treatment directives categorized as `Other`.

##### Mapping observation codes to ACP profiles

The data model defines several `Observation` profiles, each constraining a specific ACP concept by fixing a SNOMED CT code in the `Observation.code` element. Client request 5 retrieves these Observations using a code-based search. To support consistent implementation, the association between the SNOMED CT codes and the ACP Observation profiles is made explicit in the table below.

| | |
| :--- | :--- |
| 665671000146101 | [ACP-LegallyCapableTreatmentDecisions](StructureDefinition-ACP-LegallyCapableTreatmentDecisions.md) |
| 153851000146100 | [ACP-SpecificCareWishes](StructureDefinition-ACP-SpecificCareWishes.md) |
| 395091006 | [ACP-PreferredPlaceOfDeath](StructureDefinition-ACP-PreferredPlaceOfDeath.md) |
| 340171000146104 | [ACP-PositionRegardingEuthanasia](StructureDefinition-ACP-PositionRegardingEuthanasia.md) |
| 247751003 | [ACP-SenseOfPurpose](StructureDefinition-ACP-SenseOfPurpose.md) |
| 570801000146104 | [ACP-OrganDonationChoiceRegistration](StructureDefinition-ACP-OrganDonationChoiceRegistration.md) |

#### Advanced Search Parameters Supported

The queries above use several search parameter types and modifiers:

* `_include`: Returns referenced resources in the same `Bundle`, reducing the need for additional API calls.
* Chained parameters: Used for searching within referenced resources. For example, to find `DeviceUseStatement` resources with a specific `Device`, or `Encounter` resources that have an advance care planning `Procedure` as their reason.

#### Server Response

Standard FHIR rules apply for every resource request:

* Success: `200 OK`. The server will return a Bundle containing the matching resource(s) for the patient.
* Not Found: If the patient has no matching resources, the server will return a 200 OK with an empty Bundle.

-------

### Method 2: Retrieve ACP QuestionnaireResponse

This approach is used to retrieve the complete form for uniform registration of ACP in its original context. It retrieves `QuestionnaireResponse` resources that contain the content discussed by the individuals involved in the ACP conversation.

This method is included to lower the implementation burden for data providers who already use a form-based registration process. By allowing them to expose their existing form as a `QuestionnaireResponse`, it accelerates the availability of exchangeable ACP data. The trade-off is that this approach requires more effort from the ACP Actor Consulter, as they need to support multiple methods. The preferred method for system-to-system exchange is the individual resources method, as it offers a more standardized and reusable data structure.

#### Client Request

A client retrieves the `QuestionnaireResponse` by performing a `GET` search operation. The search is scoped to a specific patient and is filtered by the canonical URL of the [ACP Questionnaire](Questionnaire-ACP-zib2017.md) to ensure that only the correct form is returned.

> GET [base]/QuestionnaireResponse?subject=Patient/[id]&questionnaire=https://api.iknl.nl/docs/pzp/stu3/Questionnaire/ACP-zib2017

#### Server Response

The server follows standard FHIR response rules:

* Success: `200 OK`. The response body will contain a Bundle with the matching QuestionnaireResponse resource(s). Example QuestionnaireResponse resources are available [here](QuestionnaireResponse-HendrikHartman-20201001.md) and [here](QuestionnaireResponse-HendrikHartman-20221108.md).
* Not Found: `200 OK`. If there is no completed form for this patient, the server will return an empty Bundle.

