SPEC CHANGE - WPP-11130 - Proposed changes to API specs for Invite to Book by simeonparris-nhs · Pull Request #166 · NHSDigital/patient-care-aggregator-api

simeonparris-nhs · 2026-07-16T13:51:17Z

Invite to Book - Task Resource Alignment Summary

Overview

To support the Invite to Book changes, the decision has been made to uplift the existing Task resource in the producer API specification to support both Invitations to Book and Questionnaires, along with being extensible for further use cases. In the Consumer API specification, the current Questionnaire, and the Task introduced in this PR, are not technically resources but are "activities" that are part of the CarePlan resource.

The Consumer API's CarePlan Task activity and Producer API's Task resource have been aligned to support multiple use cases (questionnaires, appointment booking invites, and future task types) while maintaining backwards compatibility with the existing Questionnaire activity in the consumer API's CarePlan. However, there are intentional differences in field naming between the two APIs:

Consumer API uses code field for task type classification and input field for referencing upstream resources
Producer API uses reasonCode field for task type classification and reasonReference field for referencing upstream resources

This aligns the Consumer API spec more closely with FHIR standards.

Why This Change?

Previous Implementation

Questionnaire-centric: The Consumer Task activity was essentially a copy of the Questionnaire activity with additional fields for appointment booking invites
Limited extensibility: The kind enum was rigid and required updates for each new task type
Misaligned with Producer spec: The Consumer spec Task didn't follow the producer-side FHIR Task pattern
Redundancy: Similar fields and logic across Questionnaire and Task resources

New Implementation

Generic task framework: Task can represent any patient action (questionnaires, booking invites, etc.)
FHIR R4 aligned: Follows standard FHIR Task structure with fields like status, intent, code, input
Producer-spec aligned: Matches the Producer API standards for consistency across the aggregator ecosystem
Future-proof: Extensible via code and extensions for new task types
Cleaner architecture: Single generic Task resource instead of type-specific variants

Key Changes

Removed Fields

kind → Replaced by code in Consumer API, reasonCode in Producer API (FHIR standard, provides more semantic meaning)
scheduledPeriod → Replaced by restriction.period (FHIR standard)
performer → Replaced by owner (FHIR standard terminology)

Added Fields

Field	Type	Required	Purpose
`id`	string	Yes	Globally unique identifier for the task
`identifier`	object	No	System-specific identifier (portal database ID)
`intent`	string	Yes	Always "plan" - indicates task intent
`authoredOn`	date-time	Yes	When task became available to patient
`lastModified`	date-time	No	When task was last modified by patient
`restriction.period`	object	No	Start/end dates for task deadline
`focus`	object	No	Reference to linked Appointment (if applicable)
`for`	object	Yes	Patient identifier (NHS number)
`owner`	object	Yes	Responsible organization (provider)
`basedOn`	array	No	Optional reference to care pathway
`code`	object	Yes	Codes and text for task type classification (Consumer API)
`input`	array	Yes	URL and metadata for accessing the task in upstream portal (Consumer API only)
`reasonCode`	object	Yes	Codes and text for task type classification (Producer API only)
`reasonReference`	object	Yes	Reference to Questionnaire or BookingInvitation (Producer API only)

Modified Fields

status: Changed from ["not-started", "in-progress", "completed", "cancelled"] to FHIR-compliant ["requested", "rejected", "cancelled", "in-progress", "on-hold", "completed"]
description: Enhanced with clearer guidance for both questionnaires and invites
extension: Streamlined to include Client ID and Treatment Function (for PIFU only)

Task Type Classification

Consumer API: Using `code` to Distinguish Task Types

The Consumer API uses the code field with an enum of specific task types for semantic clarity:

For Questionnaires:

code:
  coding:
    - system: "https://fhir.nhs.uk/England/CodeSystem/wayfinder-task-type"
      code: "pifu-triage"  # or pre-appointment-questionnaire, post-appointment-questionnaire, etc.
      display: "PIFU Triage Questionnaire"
  text: "Patient Initiated Follow-Up Questionnaire"

For Appointment Booking Invites:

code:
  coding:
    - system: "https://fhir.nhs.uk/England/CodeSystem/wayfinder-task-type"
      code: "appointment-booking-invite"
      display: "Appointment Booking Invitation"
  text: "Invitation to book an appointment"

Producer API: Using `reasonCode` to Distinguish Task Types

The Producer API uses the reasonCode field (system: Extension-Questionnaire-Type) for task type classification, and this will continue to be supported for the purposes of backwards compatibility:

For Questionnaires:

reasonCode:
  coding:
    - system: "https://fhir.nhs.uk/CodeSystem/Task-Type"
      code: "pifu-triage"  # or other questionnaire codes
      display: "PIFU Triage Questionnaire"
  text: "Patient Initiated Follow-Up Questionnaire"

However, the Task resource has also been uplifted to include the code field, with the intention of it initially being used for appointment booking tasks, but as its Code System includes all of the same questionnaire codes used in reasonCode, it can be used in the place of reasonCode, eventually becoming the way the task type is communicated, allowing reasonCode to be later deprecated.

For Appointment Booking Invites:

code:
  coding:
    - system: "https://fhir.nhs.uk/England/CodeSystem/wayfinder-task-type"
      code: "appointment-booking-invite"
      display: "Appointment Booking Invitation"

For Questionnaires:

code:
  coding:
    - system: "https://fhir.nhs.uk/England/CodeSystem/wayfinder-task-type"
       code: "pre-appointment-questionnaire" 
       display: "Pre-Appointment Questionnaire"

Accessing Upstream Resources

Consumer API: Using `input` Field

The Consumer API uses the input array to provide the URL and metadata for accessing the task in the upstream portal system:

input:
  - type:
      coding:
        - system: "https://fhir.nhs.uk/England/CodeSystem/wayfinder-task-input-type"
           code: portal-url
           display: "URL to portal system"
    valueUrl: "https://my.portal.com/Questionnaire/c21417eb-ffef-4a9e-b367-ebd8b8c29e7c"

Producer API: Using `reasonReference` Field

The Producer API uses the reasonReference field to reference the upstream resource (Questionnaire or BookingInvitation):

reasonReference:
  type: Questionnaire
  reference: "https://my.portal.com/Questionnaire/c21417eb-ffef-4a9e-b367-ebd8b8c29e7c"

Backwards Compatibility

CarePlan Questionnaire Activity Preserved

The existing Questionnaire activity remains unchanged
Current consumers can continue using the The CarePlan's Questionnaire activity without modification
No breaking changes to the Questionnaire schema

Migration Path

Phase 1 (Current): Both Task and Questionnaire activities available
Phase 2 (Future): Clients should migrate to using Task for new questionnaire implementations
Phase 3 (Future): Questionnaire activity may be deprecated (with advance notice)

Use Cases

For NHS App and Consumer Applications (Consumer API):

Retrieve aggregated tasks across multiple Portal systems
Display unified task interface to patient
Use standardized enum-based task type codes in code field
Access portal URLs via input.valueUrl
Leverage Client ID extension to identify Portal source

For Portal/Provider Systems (Producer API):

Implement Portal-specific appointment and document APIs
Return tasks in Portal-native format with reasonCode
Reference upstream resources via reasonReference
Support appointment booking invitations and questionnaires
Implement treatment function extensions for PIFU

Data Models

Appointment Booking Invite (Task) - Producer API

id: ad8baee0-f2b2-4258-ad25-a8de19c32c14
status: requested
intent: plan
description: Book your Dermatology appointment
authored: '2026-07-16T09:00:00+00:00'
code:
  coding:
    - system: "https://fhir.nhs.uk/England/CodeSystem/wayfinder-task-type"
      code: "appointment-booking-invite"
      display: "Appointment Booking Invitation"
  text: "Invitation to book an appointment"
reasonReference:
  type: Task
  reference: "https://my.portal.com/BookingInvitation/ad8baee0-f2b2-4258-ad25-a8de19c32c14"
for:
  type: Patient
  identifier:
    system: "https://fhir.nhs.uk/Id/nhs-number"
    value: "9000000002"
owner:
  type: Organization
  identifier:
    system: "https://fhir.nhs.uk/Id/ods-organization-code"
    value: "RXP"
  display: "COUNTY DURHAM AND DARLINGTON NHS FOUNDATION TRUST"
restriction:
  period:
    end: '2026-08-16T23:59:59+00:00'

Questionnaire (Task) - Producer API

id: c21417eb-ffef-4a9e-b367-ebd8b8c29e7c
status: requested
intent: plan
description: Dermatology PIFU follow-up questionnaire
authored: '2025-06-20T18:00:00+00:00'
reasonCode:
  coding:
    - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Questionnaire-Type"
      code: "pifu-triage"
      display: "PIFU Triage Questionnaire"
  text: "Patient Initiated Follow-Up Questionnaire"
reasonReference:
  type: Questionnaire
  reference: "https://my.portal.com/Questionnaire/c21417eb-ffef-4a9e-b367-ebd8b8c29e7c"
extension:
  - url: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction"
    valueCoding:
      system: "https://fhir.nhs.uk/CodeSystem/Specialty-1"
      code: "330"
      display: "Dermatology"

Appointment Booking Invite (Task) - Consumer API

id: ad8baee0-f2b2-4258-ad25-a8de19c32c14
status: requested
intent: plan
description: Book your Dermatology appointment
authoredOn: '2026-07-16T09:00:00.000Z'
code:
  coding:
    - system: "https://fhir.nhs.uk/England/CodeSystem/wayfinder-task-type"
      code: "appointment-booking-invite"
      display: "Appointment Booking Invitation"
  text: "Invitation to book an appointment"
input:
  - type:
      coding:
        - system: "https://fhir.nhs.uk/England/CodeSystem/wayfinder-input-task-type"
          code: portal-url
          display: "URL to appointment booking screen in portal system"
    valueUrl: "https://my.portal.com/BookingInvitation/ad8baee0-f2b2-4258-ad25-a8de19c32c14"
for:
  type: Patient
  identifier:
    system: "https://fhir.nhs.uk/Id/nhs-number"
    value: "9000000002"
owner:
  type: Organization
  identifier:
    system: "https://fhir.nhs.uk/Id/ods-organization-code"
    value: "RXP"
  display: "COUNTY DURHAM AND DARLINGTON NHS FOUNDATION TRUST"
extension:
  - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id
    valueCode: myportal-01
restriction:
  period:
    start: '2026-07-16T09:00:00.000Z'
    end: '2026-08-16T23:59:59.000Z'

Questionnaire (Task) - Consumer API

id: c21417eb-ffef-4a9e-b367-ebd8b8c29e7c
status: requested
intent: plan
description: Dermatology PIFU follow-up questionnaire
authoredOn: '2025-06-20T18:00:00.000Z'
restriction:
  period:
    start: '2025-06-20T18:00:00.000Z'
    end: '2025-12-20T00:00:00.000Z'
code:
  coding:
    - system: "https://fhir.nhs.uk/England/CodeSystem/wayfinder-task-type"
      code: "pifu-triage"
      display: "PIFU Triage Questionnaire"
  text: "Patient Initiated Follow-Up Questionnaire"
input:
  - type:
      coding:
        - system: "https://fhir.nhs.uk/England/CodeSystem/wayfinder-input-task-type"
          code: portal-url
          display: "PIFU Questionnaire portal system URL"
    valueUrl: "https://my.portal.com/Questionnaire/c21417eb-ffef-4a9e-b367-ebd8b8c29e7c"
for:
  type: Patient
  identifier:
    system: "https://fhir.nhs.uk/Id/nhs-number"
    value: "9000000002"
owner:
  type: Organization
  identifier:
    system: "https://fhir.nhs.uk/Id/ods-organization-code"
    value: "RXP"
  display: "COUNTY DURHAM AND DARLINGTON NHS FOUNDATION TRUST"
extension:
  - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id
    valueCode: myportal-01
  - url: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction"
    valueCoding:
      system: "https://fhir.nhs.uk/CodeSystem/Specialty-1"
      code: "330"
      display: "Dermatology"

Implementation Notes

For Consumer API Users

No immediate changes required if using Questionnaire activity
Optional migration: Adopt Task activity for future questionnaire implementations
New integrations: Use Task activity for all task types
Access pattern: Use input.valueUrl to get the portal URL where the task is performed

For Portal Providers (Producer API)

Already implemented: Producer spec Task resource remains unchanged
Consistency: Consumer spec now aligns with Producer spec (with field naming differences)
Contract testing: Ensure portal systems work with both old Questionnaire and new Task patterns during transition

For the Aggregator Service

Data mapping: When aggregating from Portals (Producer API), transform incoming Task data from Producer format to Consumer format before returning in Consumer API responses:
- Transform Producer's reasonCode → Consumer's code
- Transform Producer's reasonReference.reference → Consumer's input.valueUrl
Field normalization: Ensure consistent Consumer API contracts
Gradual rollout: Transition consumers to the CarePlan's Task activity over time while maintaining Questionnaire activity support
Validation: Ensure both Questionnaire and Task activity patterns are properly validated in API responses

Status Values Mapping

The new Task activity uses FHIR R4 compliant status values:

Old (Questionnaire)	New (Task)	Meaning
`not-started`	`requested`	Task available but not yet started by patient
`in-progress`	`in-progress`	Task started by patient
`completed`	`completed`	Task finished by patient
`cancelled`	`cancelled`	Task cancelled by system or patient
(new)	`rejected`	Patient explicitly declined/rejected task
(new)	`on-hold`	Patient cannot find a suitable appointment slot when booking; on hold until hospital booking team can arrange appointment directly with patient

Extension Framework

The Consumer API supports extensions to provide additional metadata:

Client ID (optional)
- Unique identifier for the upstream Portal system
- System: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id
- Example value: "myportal-01"
Treatment Function (conditional)
- For PIFU questionnaires and questionnaires linked to specific specialties
- System: https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction
- Required for PIFU questionnaires

The Producer API includes similar extensions:

Treatment Function (conditional)
- For PIFU questionnaires only
- System: https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction

Questions & Clarifications

Q: When will the Questionnaire activity be deprecated?
A: No immediate deprecation. The Questionnaire activity will remain supported during a transition period (to be determined). We'll provide advance notice before any deprecation.

Q: Do I need to update my system immediately?
A: No. Existing implementations using Questionnaire continue to work. Adopt Task activity for new implementations or when ready to migrate.

Q: How do I distinguish between task types?
A:

Consumer API: Use the code.coding.code field with values like "pifu-triage", "appointment-booking-invite", "pre-appointment-questionnaire", etc. All codes use system https://fhir.nhs.uk/England/CodeSystem/wayfinder-task-type.
Producer API: Use the reasonCode.coding.code field. The system is https://fhir.nhs.uk/StructureDefinition/Extension-Questionnaire-Type.

Q: How do I access the upstream portal resource?
A:

Consumer API: Use the input.valueUrl field to get the portal URL. The input array contains type information (with code "portal-url") and the valueUrl with the direct link to the task in the upstream system.
Producer API: Use the reasonReference.reference field to get the reference to the upstream resource.

Q: What about linked appointments?
A: Use the focus field to reference an Appointment this task relates to:

For questionnaires before appointment: focus may be empty (appointment doesn't exist yet)
For questionnaires linked to appointments: focus.reference points to the related appointment
For appointment booking invites: focus is not required since the appointment doesn't exist until the patient completes the booking

Q: Can I store custom data in Task?
A: Yes, use extensions (array) to add custom fields following FHIR extension patterns.

so that it is suitable for a variety of tasks rather than just questionnaire responses

so that a variety of task details, such as booking invites and questionnaire responses can be communicated

…r-ItB

for allAppointmentBookingInvitationStates

…hile backwards compatible

RavenDuffyNHS · 2026-07-21T08:22:37Z

Just want to check this has been aligned with kevin/sachit?

edwardbowyer-nhs · 2026-07-21T09:51:41Z

Just want to check this has been aligned with kevin/sachit?

The design has been run through with Sachit yes, we collaborated on that, but not this specific spec change. Reaching out to David Rabbich in Sachit and Kevin's absence.

RavenDuffyNHS · 2026-07-21T10:01:36Z

Just want to check this has been aligned with kevin/sachit?

The design has been run through with Sachit yes, we collaborated on that, but not this specific spec change. Reaching out to David Rabbich in Sachit and Kevin's absence.

Definitely think this will be a positive change as the line between tasks and questionnaires is currently quite blurry.

…nts and only trigger after an API spec change

nebh2 · 2026-08-14T14:18:50Z

+              description: Resource type being referenced.
+              type: string
+              enum:
+                - Task


The schema currently restricts reasonReference.type to Task, but examples reference Questionnaire and BookingInvitation URLs. Could we align schema and examples so referenced resource type and reference targets are consistent?

Will be removing from Consumer spec as replaced by Task.Input. The Producer will support Task and Questionnaire , I believe all those examples are correct

nebh2 · 2026-08-14T14:25:04Z

            type: 
              type: string
-              description: Questionnaire FHIR Resource
+              description: The type of task, used to differentiate behaviour in the Aggregator. Must be either `BookingInvitation` for Invite to Book tasks, or `Questionnaire` for questionnaire completion tasks.


There is a mismatch between description and enum here: description mentions BookingInvitation for invites, while enum allows Questionnaire and Task. Could we align these so allowed values are unambiguous?

Good spot updated thanks

nebh2 · 2026-08-14T14:25:54Z

@@ -1063,8 +1065,8 @@ components:
        - for
        - authored


Consumer Task now uses authoredOn, while Producer still uses authored. Is this divergence intentional, or should Producer also move to authoredOn for cross-spec alignment?

Confirming the difference is intentional, as the Producer spec is currently in use by the PEPs for Questionnaire flow, we are unable to alter it at this time to maintain compatibility. However as we're adding to the Consumer spec, we are aligning strongly with FHIR standards.

nebh2 · 2026-08-14T14:26:10Z

        - authored
        - reasonReference
-        - owner
        - reasonCode


Consumer Task now classifies task type in code. Producer still carries task-type semantics in reasonCode for questionnaire flow. Can we confirm if this difference is intentional or align both specs to the same model?

Confirming the difference is intentional, as the Producer spec is currently in use by the PEPs for Questionnaire flow, we are unable to alter it at this time to maintain compatibility. However as we're adding to the Consumer spec, we are aligning strongly with FHIR standards.

nebh2 · 2026-08-14T14:26:30Z

@@ -1063,8 +1065,8 @@ components:
        - for
        - authored
        - reasonReference


Could we confirm reasonReference semantics are aligned between producer and consumer? Current shape/typing appears to differ, which may cause mapping ambiguity for Invite-to-Book vs Questionnaire tasks.

reasonReference is now being removed from Consumer spec to use Task.Input to purvey URL

KazeemHamzat · 2026-08-14T15:20:49Z

Under

Invite to Book - Task Resource Alignment Summary

Overview

To support the Invite to Book changes, the design has been made to uplift the existing Task resource to support both Invitations to Book and Questionnaires, along with being extensible for further use cases.

The Consumer API Task resource and Producer API Task resource have been aligned to support multiple use cases (questionnaires, appointment booking invites, and future task types) while maintaining backwards compatibility with the existing Questionnaire resource. However, there are intentional differences in field naming between the two APIs:

Consumer API uses code field for task type classification

Producer API uses reasonCode field for task type classification

This aligns the Consumer API spec more closely with FHIR standards.

Why This Change?

Previous Implementation

Questionnaire-centric: The Consumer Task resource was essentially a copy of the Questionnaire resource with additional fields for appointment booking invites

Limited extensibility: The kind enum was rigid and required updates for each new task type

Misaligned with Producer spec: The Consumer spec Task didn't follow the producer-side FHIR Task pattern

Redundancy: Similar fields and logic across Questionnaire and Task resources

New Implementation

Generic task framework: Task resource can represent any patient action (questionnaires, booking invites, etc.)

FHIR R4 aligned: Follows standard FHIR Task structure with fields like status, intent, reasonCode, reasonReference

Producer-spec aligned: Matches the Producer API standards for consistency across the aggregator ecosystem

Future-proof: Extensible via reasonCode and extensions for new task types

Cleaner architecture: Single generic Task resource instead of type-specific variants

Key Changes

Removed Fields

kind → Replaced by code in Consumer API, reasonCode in Producer API (FHIR standard, provides more semantic meaning)

scheduledPeriod → Replaced by restriction.period (FHIR standard)

performer → Replaced by owner (FHIR standard terminology)

Added Fields

Field Type Required Purpose
id string Yes Globally unique identifier for the task
identifier object No System-specific identifier (portal database ID)
intent string Yes Always "plan" - indicates task intent
authored date-time Yes When task became available to patient
lastModified date-time No When task was last modified by patient
restriction.period object No Start/end dates for task deadline
focus object No Reference to linked Appointment (if applicable)
for object Yes Patient identifier (NHS number)
owner object Yes Responsible organization (provider)
basedOn array No Optional reference to care pathway
code object Yes Codes and text for task type classification (Consumer API)
reasonCode object Yes Codes and text for task type classification (Producer API)
reasonReference object Yes Reference to Questionnaire or BookingInvitation

Modified Fields

status: Changed from ["not-started", "in-progress", "completed", "cancelled"] to FHIR-compliant ["requested", "rejected", "cancelled", "in-progress", "completed"]

description: Enhanced with clearer guidance for both questionnaires and invites

extension: Streamlined to include Client ID and Treatment Function (for PIFU only)

Task Type Classification

Consumer API: Using code to Distinguish Task Types

The Consumer API uses the code field with an enum of specific task types for semantic clarity:

For Questionnaires:
code:
  coding:
    - system: "https://fhir.nhs.uk/CodeSystem/Task-Type"
      code: "pifu-triage"  # or pre-appointment-questionnaire, post-appointment-questionnaire, etc.
      display: "PIFU Triage Questionnaire"
  text: "Patient Initiated Follow-Up Questionnaire"
For Appointment Booking Invites:
code:
  coding:
    - system: "https://fhir.nhs.uk/CodeSystem/Task-Type"
      code: "appointment-booking-invite"
      display: "Appointment Booking Invitation"
  text: "Invitation to book an appointment"
Producer API: Using reasonCode to Distinguish Task Types

The Producer API uses the reasonCode field (system: Extension-Questionnaire-Type) for task type classification:

For Questionnaires:
reasonCode:
  coding:
    - system: "https://fhir.nhs.uk/CodeSystem/Task-Type"
      code: "pifu-triage"  # or other questionnaire codes
      display: "PIFU Triage Questionnaire"
  text: "Patient Initiated Follow-Up Questionnaire"
For Appointment Booking Invites:
reasonCode:
  coding:
    - system: "https://fhir.nhs.uk/CodeSystem/Task-Type"
      code: "appointment-booking-invite"
      display: "Appointment Booking Invitation"
  text: "Invitation to book an appointment"
Backwards Compatibility

Questionnaire Resource Preserved

The existing Questionnaire resource remains unchanged

Current consumers can continue using the Questionnaire resource without modification

No breaking changes to the Questionnaire schema

Migration Path

Phase 1 (Current): Both Task and Questionnaire resources available

Phase 2 (Future): Clients should migrate to using Task for new questionnaire implementations

Phase 3 (Future): Questionnaire resource may be deprecated (with advance notice)

Use Cases

For NHS App and Consumer Applications (Consumer API):

Retrieve aggregated tasks across multiple Portal systems

Display unified task interface to patient

Use standardized enum-based task type codes

Leverage Client ID extension to identify Portal source

For Portal/Provider Systems (Producer API):

Implement Portal-specific appointment and document APIs

Return tasks in Portal-native format with reasonCode

Support appointment booking invitations and questionnaires

Implement treatment function extensions for PIFU

Data Models

Appointment Booking Invite (Task)
id: ad8baee0-f2b2-4258-ad25-a8de19c32c14
status: requested
intent: plan
description: Book your Dermatology appointment
authoredOn: '2026-07-16T09:00:00.000Z'
code:
  coding:
    - system: "https://fhir.nhs.uk/CodeSystem/Task-Type"
      code: "appointment-booking-invite"
      display: "Appointment Booking Invitation"
  text: "Invitation to book an appointment"
reasonReference:
  type: Task
  reference: "https://my.portal.com/BookingInvitation/ad8baee0-f2b2-4258-ad25-a8de19c32c14"
for:
  type: Patient
  identifier:
    system: "https://fhir.nhs.uk/Id/nhs-number"
    value: "9000000002"
owner:
  type: Organization
  identifier:
    system: "https://fhir.nhs.uk/Id/ods-organization-code"
    value: "RXP"
  display: "COUNTY DURHAM AND DARLINGTON NHS FOUNDATION TRUST"
restriction:
  repetitions: 1
  period:
    start: '2026-07-16T09:00:00.000Z'
    end: '2026-08-16T23:59:59.000Z'
Questionnaire (Task) - Consumer API
id: c21417eb-ffef-4a9e-b367-ebd8b8c29e7c
status: requested
intent: plan
description: Dermatology PIFU follow-up questionnaire
authoredOn: '2025-06-20T18:00:00.000Z'
code:
  coding:
    - system: "https://fhir.nhs.uk/CodeSystem/Task-Type"
      code: "pifu-triage"
      display: "PIFU Triage Questionnaire"
  text: "Patient Initiated Follow-Up Questionnaire"
reasonReference:
  type: Task
  reference: "https://my.portal.com/Questionnaire/c21417eb-ffef-4a9e-b367-ebd8b8c29e7c"
extension:
  - url: "https://fhir.nhs.uk/StructureDefinition/Extension-Client-id"
    valueCode: "myportal-01"
  - url: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction"
    valueCoding:
      system: "https://fhir.nhs.uk/CodeSystem/Specialty-1"
      code: "330"
      display: "Dermatology"
Appointment Booking Invite (Task) - Producer API
id: ad8baee0-f2b2-4258-ad25-a8de19c32c14
status: requested
intent: plan
description: Book your Dermatology appointment
authored: '2026-07-16T09:00:00+00:00'
code:
  coding:
    - system: "https://fhir.nhs.uk/CodeSystem/Task-Type"
      code: "appointment-booking-invite"
      display: "Appointment Booking Invitation"
  text: "Invitation to book an appointment"
reasonReference:
  type: Task
  reference: "https://my.portal.com/BookingInvitation/ad8baee0-f2b2-4258-ad25-a8de19c32c14"
for:
  type: Patient
  identifier:
    system: "https://fhir.nhs.uk/Id/nhs-number"
    value: "9000000002"
owner:
  type: Organization
  identifier:
    system: "https://fhir.nhs.uk/Id/ods-organization-code"
    value: "RXP"
  display: "COUNTY DURHAM AND DARLINGTON NHS FOUNDATION TRUST"
restriction:
  period:
    end: '2026-08-16T23:59:59+00:00'
Questionnaire (Task) - Producer API
id: c21417eb-ffef-4a9e-b367-ebd8b8c29e7c
status: requested
intent: plan
description: Dermatology PIFU follow-up questionnaire
authored: '2025-06-20T18:00:00+00:00'
reasonCode:
  coding:
    - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Questionnaire-Type"
      code: "pifu-triage"
      display: "PIFU Triage Questionnaire"
  text: "Patient Initiated Follow-Up Questionnaire"
reasonReference:
  type: Questionnaire
  reference: "https://my.portal.com/Questionnaire/c21417eb-ffef-4a9e-b367-ebd8b8c29e7c"
extension:
  - url: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction"
    valueCoding:
      system: "https://fhir.nhs.uk/CodeSystem/Specialty-1"
      code: "330"
      display: "Dermatology"
Implementation Notes

For Consumer API Users

No immediate changes required if using Questionnaire resource

Optional migration: Adopt Task resource for future questionnaire implementations

New integrations: Use Task resource for all task types

For Portal Providers (Producer API)

Already implemented: Producer spec Task resource remains unchanged

Consistency: Consumer spec now aligns with Producer spec

Contract testing: Ensure portal systems work with both old Questionnaire and new Task patterns during transition

For the Aggregator Service

Data mapping: When aggregating from Portals (Producer API), transform incoming Task data from Producer format (reasonCode) to Consumer format (code) before returning in Consumer API responses

Field normalization: Map Producer's reasonCode to Consumer's code to maintain consistent Consumer API contracts

Gradual rollout: Transition consumers to Task resource over time while maintaining Questionnaire resource support

Validation: Ensure both Questionnaire and Task resource patterns are properly validated in API responses

Status Values Mapping

The new Task resource uses FHIR R4 compliant status values:

Old (Questionnaire) New (Task) Meaning
not-started requested Task available but not yet started by patient
in-progress in-progress Task started by patient
completed completed Task finished by patient
cancelled cancelled Task cancelled by system or patient
(new) rejected Patient explicitly declined/rejected task

Extension Framework

The Consumer API supports extensions to provide additional metadata:

Client ID (optional)

Unique identifier for the upstream Portal system

System: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id

Example value: "myportal-01"

Treatment Function (conditional)

For PIFU questionnaires and questionnaires linked to specific specialties

System: https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction

Required for PIFU questionnaires

The Producer API includes similar extensions:

Treatment Function (conditional)

For PIFU questionnaires only

System: https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction

Questions & Clarifications

Q: When will the Questionnaire resource be deprecated? A: No immediate deprecation. The Questionnaire resource will remain supported during a transition period (to be determined). We'll provide advance notice before any deprecation.

Q: Do I need to update my system immediately? A: No. Existing implementations using Questionnaire continue to work. Adopt Task resource for new implementations or when ready to migrate.

Q: How do I distinguish between task types? A:

Consumer API: Use the code.coding.code field with values like "pifu-triage", "appointment-booking-invite", "pre-appointment-questionnaire", etc. All codes use system https://fhir.nhs.uk/CodeSystem/Task-Type.

Producer API: Use the reasonCode.coding.code field. The system is https://fhir.nhs.uk/StructureDefinition/Extension-Questionnaire-Type.

Q: What about linked appointments? A: Use the focus field to reference an Appointment this task relates to:

For questionnaires before appointment: focus may be empty (appointment doesn't exist yet)

For questionnaires linked to appointments: focus.reference points to the related appointment

For appointment booking invites: focus is not required since the appointment doesn't exist until the patient completes the booking

Q: Can I store custom data in Task? A: Yes, use extensions (array) to add custom fields following FHIR extension patterns.

Under the section for Extension Framework.
Could you update the following as follows. Change System to URL. System applies to vocabulary while URL applies to StructuredDefinition. In this context, Extension element.

1* System: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id to

- URL: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id

2 * URL: https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction

- For PIFU questionnaires only

URL: https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction

4.reasonCode:

coding:
- system: "https://fhir.nhs.uk/CodeSystem/Questionnaire-Type"
code: "pifu-triage"
display: "PIFU Triage Questionnaire"
text: "Patient Initiated Follow-Up Questionnaire"

5* Producer API: Use the reasonCode.coding.code field. The system is https://fhir.nhs.uk/CodeSystem/Questionnaire-Type.

However, there is also a need to clarify how this CodeSystem 'https://fhir.nhs.uk/CodeSystem/Questionnaire-Type' relates to PIFU option in 'https://fhir.nhs.uk/England/CodeSystem/Task-Type'

pre-appointment-questionnaire
- post-appointment-questionnaire
- general-update-questionnaire
- pifu-triage
- appointment-booking-invite

github-actions · 2026-08-17T11:09:41Z

API Spec HTML Docs

Built from commit 5f940c4 — view workflow run

Download HTML API Specs: api-specs-html-docs-5f940c4.zip

to align more closely with FHIR standard and more clearly indicate the URL needed to perform the task in the portal system

to replace reasonReference with input

github-actions · 2026-08-17T12:25:33Z

API Spec HTML Docs

Built from commit f78fa18 — view workflow run

Download HTML API Specs: api-specs-html-docs-f78fa18.zip

github-actions · 2026-08-17T16:35:38Z

API Spec HTML Docs

Built from commit e15ce17 — view workflow run

Download HTML API Specs: api-specs-html-docs-e15ce17.zip

nebh2 · 2026-08-18T12:36:29Z

+                  system: "https://fhir.nhs.uk/Id/ods-organization-code"
+                  value: "RFF"
+                display: "Barnsley Hospital NHS Foundation Trust"
+              code:


reasonCode is listed as required at the Task level, but this example doesn't include it (only code is present). Since reasonCode was kept for questionnaire backward-compatibility, can we make it conditionally required (e.g. only when the task is a questionnaire type) rather than universally required? Otherwise this example fails schema validation.

Ah yes of course, thank you, I've removed reasonCode from required at task level.

…to be used for qeuestionnaires and tasks

…hub.com:NHSDigital/patient-care-aggregator-api into apm-000-WPP-11130-proposed-task-changes-for-ItB

github-actions · 2026-08-18T12:46:49Z

API Spec HTML Docs

Built from commit 5e80716 — view workflow run

Download HTML API Specs: api-specs-html-docs-5e80716.zip

nebh2

LGTM from SCS

to reference tasks rather than just questionnaires

…r-ItB

github-actions · 2026-08-24T15:33:09Z

API Spec HTML Docs

Built from commit 270119f — view workflow run

Download HTML API Specs: api-specs-html-docs-270119f.zip

for the task type and task input type

github-actions · 2026-08-27T09:23:23Z

API Spec HTML Docs

Built from commit 536d058 — view workflow run

Download HTML API Specs: api-specs-html-docs-536d058.zip

github-actions · 2026-08-27T14:10:32Z

API Spec HTML Docs

Built from commit d81a485 — view workflow run

Download HTML API Specs: api-specs-html-docs-d81a485.zip

to consumer and producer API specs

to consumer API spec

github-actions · 2026-09-15T11:18:05Z

❌ Branch Name Validation Failed

Branch format is invalid.

Expected format: <prefix>/<JIRA-key>-<kebab-description>

Ensure JIRA ticket key is included. Allowed prefixes: feat, feature, chore, spike, hotfix, bugfix, release, revert

apm-000-WPP-11130-proposed-task-changes-for-ItB

github-actions · 2026-09-15T11:18:29Z

API Spec HTML Docs

Built from commit 39a9d54 — view workflow run

Download HTML API Specs: api-specs-html-docs-39a9d54.zip

simeonparris-nhs and others added 11 commits July 15, 2026 12:36

modify task resource in producer spec

9073c7d

so that it is suitable for a variety of tasks rather than just questionnaire responses

add task resource to the consumer spec

1a7e6ce

so that a variety of task details, such as booking invites and questionnaire responses can be communicated

Merge branch 'master' into apm-000-WPP-11130-proposed-task-changes-fo…

cb5b9a1

…r-ItB

update producer task overview

7ebc882

add consumer spec task examples

31daaf1

add more examples to consumer spec

2d4f6cf

for allAppointmentBookingInvitationStates

add task examples to producer spec

0916cbf

correct producer spec task response

8d7513c

correct spelling of allQuestionnaireStates in consumer spec

986cb75

Aligned Task consumer spec more closely with Producer spec, generic w…

44e6d2b

…hile backwards compatible

Merged aligned Consumer Task resource with Producer

8a7a520

edwardbowyer-nhs changed the title ~~DRAFT - WPP-11130 - Proposed changes to API specs for Invite to Book~~ DRAFT - SPEC CHANGE - WPP-11130 - Proposed changes to API specs for Invite to Book Jul 20, 2026

NHSDigital deleted a comment from github-actions Bot Jul 21, 2026

edwardbowyer-nhs added 4 commits July 21, 2026 11:54

enhance workflow to include short SHA in artifact naming and PR comme…

048b1ed

…nts and only trigger after an API spec change

Merge

a58c410

Unused file removed

aed2821

Added link to download artificat directly from PR

8dc8f5a

NHSDigital deleted a comment from github-actions Bot Jul 21, 2026

Update comment to direclty link to download

59d8e4c

nebh2 reviewed Aug 14, 2026

View reviewed changes

Updating reasonReference description

31eb2c8

simeonparris-nhs added 3 commits August 17, 2026 12:46

replace consumer Task reasonReference with input

1cf2cad

to align more closely with FHIR standard and more clearly indicate the URL needed to perform the task in the portal system

update consumer spec task examples

7ff65b7

to replace reasonReference with input

fix typo in consumer spec

7f18333

define enum for consumer Task.input.type.coding.code

5394ea3

nebh2 reviewed Aug 18, 2026

View reviewed changes

edwardbowyer-nhs added 2 commits August 18, 2026 13:44

removed the reasonCode as Required to allow both code and reasonCode …

2a4fe6b

…to be used for qeuestionnaires and tasks

Merge branch 'apm-000-WPP-11130-proposed-task-changes-for-ItB' of git…

e15acf5

…hub.com:NHSDigital/patient-care-aggregator-api into apm-000-WPP-11130-proposed-task-changes-for-ItB

nebh2 approved these changes Aug 18, 2026

View reviewed changes

simeonparris-nhs added 2 commits August 24, 2026 16:14

update descriptions in records service api spec

670f6dc

to reference tasks rather than just questionnaires

Merge branch 'master' into apm-000-WPP-11130-proposed-task-changes-fo…

0b382ee

…r-ItB

update CodeSystem canonical URLs

cf74926

for the task type and task input type

correct code system URL from producer Task.code

753b702

simeonparris-nhs added 2 commits September 15, 2026 12:14

add on-hold Task.status code

ab54fcc

to consumer and producer API specs

add example of invite task with on-hold status

36e4a26

to consumer API spec

Conversation

simeonparris-nhs commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Invite to Book - Task Resource Alignment Summary

Overview

Why This Change?

Previous Implementation

New Implementation

Key Changes

Removed Fields

Added Fields

Modified Fields

Task Type Classification

Consumer API: Using code to Distinguish Task Types

For Questionnaires:

For Appointment Booking Invites:

Producer API: Using reasonCode to Distinguish Task Types

For Questionnaires:

For Appointment Booking Invites:

For Questionnaires:

Accessing Upstream Resources

Consumer API: Using input Field

Producer API: Using reasonReference Field

Backwards Compatibility

CarePlan Questionnaire Activity Preserved

Migration Path

Use Cases

Data Models

Appointment Booking Invite (Task) - Producer API

Questionnaire (Task) - Producer API

Appointment Booking Invite (Task) - Consumer API

Questionnaire (Task) - Consumer API

Implementation Notes

For Consumer API Users

For Portal Providers (Producer API)

For the Aggregator Service

Status Values Mapping

Extension Framework

Questions & Clarifications

Uh oh!

RavenDuffyNHS commented Jul 21, 2026

Uh oh!

edwardbowyer-nhs commented Jul 21, 2026

Uh oh!

RavenDuffyNHS commented Jul 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

edwardbowyer-nhs Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KazeemHamzat commented Aug 14, 2026

Invite to Book - Task Resource Alignment Summary

Overview

Why This Change?

Previous Implementation

New Implementation

Key Changes

Removed Fields

Added Fields

Modified Fields

Task Type Classification

Consumer API: Using code to Distinguish Task Types

simeonparris-nhs commented Jul 16, 2026 •

edited

Loading

Consumer API: Using `code` to Distinguish Task Types

Producer API: Using `reasonCode` to Distinguish Task Types

Consumer API: Using `input` Field

Producer API: Using `reasonReference` Field

edwardbowyer-nhs Aug 17, 2026 •

edited

Loading

Consumer API: Using `code` to Distinguish Task Types

Producer API: Using `reasonCode` to Distinguish Task Types