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 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'
reasonCode:
  coding:
    - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Questionnaire-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.

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

and correct example taskQuestionnaire

by removing detail wrapper

github-actions · 2026-08-07T07:36:10Z

API Spec HTML Docs

Built from commit 19784cf — view workflow run

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

nebh2 · 2026-08-07T14:20:32Z

+              description: ODS Organisation name (NHS Trust).
+              type: string
+              example: "THE NEWCASTLE UPON TYNE HOSPITALS NHS FOUNDATION TRUST"
+        reasonCode:


On reasonCode used for task type can we confirm task classification is intended to live in Task.code rather than reasonCode? In FHIR Task, reasonCode is typically rationale/context rather than the primary task type.

Yes, good spot, unfortunately we cannot change the producer, but will align the Consumer with this FHIR standard, will resolve once updated.

Aligned the Consumer spec, now uses Task.code instead of reasonCode

nebh2 · 2026-08-07T14:22:43Z

+              type: string
+              enum:
+                - Questionnaire
+                - BookingInvitation


BookingInvitation is not a base FHIR resource type. Can you confirm whether this is a formally profiled custom resource (with canonical definition/capability declaration)? If yes, please share the canonical contract so consumers can validate references safely.

Aligned with the correct Task type

nebh2 · 2026-08-07T14:24:50Z

+              items:
+                type: object
+                required:
+                  - system


I can see mixed canonical URI styles for coding.system across schema and examples (CodeSystem-style vs StructureDefinition extension-style). Could we standardize to one canonical set so validators and contract tests behave consistently?

Fixed examples

nebh2 · 2026-08-07T14:35:57Z

+    Task:
+      description: A generic task resource representing an action for the patient to complete (e.g. questionnaire, appointment booking invite). Aligns with FHIR R4 Task and Producer spec implementation.
+      type: object
+      required:


Can we align this required list with the documented contract? The spec text describes intent, for, and owner as required, but they are not enforced here. Please either add them to required or mark them optional in the prose for consistency.

Added to required

nebh2 · 2026-08-07T14:39:03Z

+              enum:
+                - Appointment
+            reference:
+              description: Absolute URL to the linked Appointment.


Description says absolute URL, but examples use relative references like Appointment/{id}. Can we clarify allowed formats and keep schema/examples consistent?

Updated examples.

nebh2 · 2026-08-07T14:40:48Z

+              type: string
+              example: "https://my.portal.com/Questionnaire/c21417eb-ffef-4a9e-b367-ebd8b8c29e7c"
+        extension:
+          description: FHIR extensions for task resources. Includes Portal link, client ID, optional linked appointment, and treatment function.


The description mentions Portal link and linked appointment, but the listed extension shapes appear to model client-id and treatment function only. Could we align this section so the declared extensions match what is documented?

Aligned descriptions.

nebh2 · 2026-08-07T14:58:22Z

+        reasonCode:
+          coding:
+            - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Questionnaire-Type"
+              code: "pre-assessment"


I noticed a schema/example mismatch here, this example uses pre-assessment for reasonCode.coding.code, but that value does not appear in the declared enum. Could we align schema and examples (either add this enum value or update the example to an allowed one)?

Aligned with schema.

github-actions · 2026-08-11T11:54:42Z

API Spec HTML Docs

Built from commit 340f635 — view workflow run

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

github-actions · 2026-08-11T16:06:43Z

API Spec HTML Docs

Built from commit 82d0b05 — view workflow run

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

… FHIR spec

github-actions · 2026-08-11T17:01:58Z

API Spec HTML Docs

Built from commit 756e8eb — view workflow run

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

github-actions · 2026-08-12T10:20:31Z

API Spec HTML Docs

Built from commit 73cf431 — view workflow run

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

github-actions · 2026-08-13T10:19:33Z

API Spec HTML Docs

Built from commit 6f93dff — view workflow run

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

github-actions · 2026-08-14T10:27:57Z

❌ 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-08-14T10:28:55Z

API Spec HTML Docs

Built from commit 582522c — view workflow run

Download HTML API Specs: api-specs-html-docs-582522c.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

simeonparris-nhs added 3 commits August 6, 2026 17:06

remove detail wrapper from consumer Task

fa2bfb0

correct Task.reasonCode.coding description

1b90e83

and correct example taskQuestionnaire

correct consumer task examples

c4f4c9c

by removing detail wrapper

nebh2 reviewed Aug 7, 2026

View reviewed changes

Comment thread specification/patient-care-aggregator-api-consumer-api.yaml Outdated

nebh2 reviewed Aug 7, 2026

View reviewed changes

edwardbowyer-nhs added 2 commits August 11, 2026 12:14

Changed examples to use authored and not authoredOn (legacy mistake)

3ed0150

Ensured intent, for, owner and reasonCode are required

4149f3c

Aligned Pre-Appointment questionnare task example

5667725

edwardbowyer-nhs added 2 commits August 11, 2026 17:34

Refactored reasonCode -> code in Consumer spec to align with the Task…

d4d224e

… FHIR spec

aligned reasonReference Type with Task resource

2547950

edwardbowyer-nhs added 4 commits August 11, 2026 18:15

Aligned examples to have full URIs as expected

53d941c

Corrected Task Extension description

7df10c9

Fixed issue in examples conflicting codesystem

9618d70

Fixed linting mistakes

fef1403

aligned reasonReference type, added Task type

1e8320b

Updated authored to be authoredOn in Consumer spec

9d4ebe1

Uh oh!

Conversation

simeonparris-nhs commented Jul 16, 2026 • edited by edwardbowyer-nhs 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:

Backwards Compatibility

Questionnaire Resource Preserved

Migration Path

Use Cases

Data Models

Appointment Booking Invite (Task)

Questionnaire (Task) - Consumer API

Appointment Booking Invite (Task) - Producer API

Questionnaire (Task) - Producer 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!

github-actions Bot commented Aug 7, 2026

API Spec HTML Docs

Uh oh!

Uh oh!

nebh2 Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

edwardbowyer-nhs Aug 11, 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!

edwardbowyer-nhs Aug 11, 2026

Choose a reason for hiding this comment

Uh oh!

nebh2 Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

edwardbowyer-nhs Aug 11, 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!

nebh2 Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

edwardbowyer-nhs Aug 11, 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!

nebh2 Aug 7, 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!

edwardbowyer-nhs Aug 11, 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!

nebh2 Aug 7, 2026

simeonparris-nhs commented Jul 16, 2026 •

edited by edwardbowyer-nhs

Loading

Consumer API: Using `code` to Distinguish Task Types

Producer API: Using `reasonCode` to Distinguish Task Types

edwardbowyer-nhs Aug 11, 2026 •

edited

Loading

edwardbowyer-nhs Aug 11, 2026 •

edited

Loading

edwardbowyer-nhs Aug 11, 2026 •

edited

Loading

nebh2 Aug 7, 2026 •

edited

Loading

edwardbowyer-nhs Aug 11, 2026 •

edited

Loading

edwardbowyer-nhs Aug 11, 2026 •

edited

Loading

edwardbowyer-nhs Aug 11, 2026 •

edited

Loading

edwardbowyer-nhs Aug 11, 2026 •

edited

Loading