Clinical Documents Use Cases

Overview of the Clinical Document Service (CDS)

Submit a Clinical Document to the CDS

Mark a Clinical Document as Potentially Misfiled

If a user suspects that a clinical document has been filed against the wrong patient record, they can flag the document as potentially misfiled by invoking the $mark-potentially-misfiled operation. The CDR creates a Task to manage the review, which must be completed by an authorised user who can confirm or reject the suspected misfiling.

The operation can be invoked at the DocumentReference instance level, using the CDR-assigned DocumentReference.id, or at the DocumentReference type level, using the document's business identifier in the documentIdentifier input parameter.

Input Parameters

The operation accepts the following input parameters:

  • documentIdentifier – the business identifier of the DocumentReference. This parameter is required for a type-level invocation and must not be supplied for an instance-level invocation. For example, it may contain a supersession-set-identifier, or external-supersession-set-identifier where supported.
  • source – the source Device from which the operation request originated. This parameter is required.
  • timestamp – the date and time at which the document was marked as potentially misfiled. This parameter is optional. If it is not supplied, the CDR uses the date and time at which the operation is processed.
  • requester – the Practitioner requesting that the document be marked as potentially misfiled. This parameter is required.
  • misfileReason – the reason why the requester considers the document to be potentially misfiled. This parameter is required.

Output Parameter

The operation returns the following output parameter:

  • return – the Task created to manage the review of the potentially misfiled document. The Task has the code review-document-misfile.

Example API Request

The following example shows the HTTP POST request used to invoke the operation at the DocumentReference type level. The documentIdentifier parameter identifies the DocumentReference by its business identifier.

POST [base]/DocumentReference/$mark-potentially-misfiled HTTP/1.1 Authorization: Bearer [access-token] Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"id": "Example-CDR-Parameters-DocumentReference-MarkPotentiallyMisfiled-Type",
"parameter": [
{
"name": "documentIdentifier",
"valueIdentifier": {
"system": "https://fhir.nhs.wales/Id/supersession-set-identifier",
"value": "550e8400-e29b-41d4-a716-446655440000"
}
},
{
"name": "source",
"resource": {
"resourceType": "Device",
"identifier": [
{
"system": "https://fhir.nhs.wales/Id/application-instance-identifier",
"value": "210"
}
],
"deviceName": [
{
"name": "Welsh Clinical Portal",
"type": "user-friendly-name"
}
]
}
},
{
"name": "timestamp",
"valueDateTime": "2026-08-22T10:30:00Z"
},
{
"name": "requester",
"resource": {
"resourceType": "Practitioner",
"identifier": [
{
"system": "https://fhir.hl7.org.uk/Id/gmc-number",
"value": "9630339"
}
],
"name": [
{
"family": "Jones",
"given": [
"Anne"
],
"prefix": [
"Dr"
]
}
]
}
},
{
"name": "misfileReason",
"valueString": "Document appears to be associated with the wrong patient record."
}
]
}

The following example shows the HTTP POST request used to invoke the operation at the DocumentReference instance level. The CDR-assigned DocumentReference.id identifies the target resource, so documentIdentifier is not supplied. The request body is omitted from this example.

POST [base]/DocumentReference/[id]/$mark-potentially-misfiled HTTP/1.1 Authorization: Bearer [access-token]

Accept a Document Misfile

If the reviewer confirms that the document is misfiled, they can invoke the $accept-document-misfile operation against the Task created by the $mark-potentially-misfiled operation. On successful execution, the CDR completes the Task, records an accepted review outcome, and updates the focus DocumentReference to entered-in-error. The CDR also updates the document's errorstatus meta tag to indicate that the document is misfiled.

Accept Input Parameters

The operation accepts the following input parameters:

  • source – the source Device from which the operation request originated. This parameter is required.
  • timestamp – the date and time at which the document misfile review was completed. This parameter is optional. If it is not supplied, the CDR uses the date and time at which the operation is processed.
  • reviewer – the Practitioner reviewing the potentially misfiled document. This parameter is required.
  • misfileAcceptedReason – the reason why the reviewer accepts that the document is misfiled. This parameter is required.

Accept Output Parameter

The operation returns the following output parameter:

  • return – the updated Task, recording completion of the document misfile review with an outcome of accepted.

Accept Example API Request

The following example shows the HTTP POST request used to accept a document misfile review.

POST [base]/Task/[id]/$accept-document-misfile HTTP/1.1 Authorization: Bearer [access-token] Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"id": "Example-CDR-Parameters-Task-AcceptDocumentMisfile-Instance",
"parameter": [
{
"name": "source",
"resource": {
"resourceType": "Device",
"identifier": [
{
"system": "https://fhir.nhs.wales/Id/application-instance-identifier",
"value": "210"
}
],
"deviceName": [
{
"name": "Welsh Clinical Portal",
"type": "user-friendly-name"
}
]
}
},
{
"name": "timestamp",
"valueDateTime": "2026-08-23T10:30:00Z"
},
{
"name": "reviewer",
"resource": {
"resourceType": "Practitioner",
"identifier": [
{
"system": "https://fhir.hl7.org.uk/Id/gphc-number",
"value": "2076543"
}
],
"name": [
{
"family": "Davies",
"given": [
"Carys"
],
"prefix": [
"Ms"
]
}
]
}
},
{
"name": "misfileAcceptedReason",
"valueString": "Reviewer confirms the document is misfiled and should be marked in error."
}
]
}

Reject a Document Misfile

If the reviewer does not confirm that the document is misfiled, they can invoke the $reject-document-misfile operation against the Task created by the $mark-potentially-misfiled operation. On successful execution, the CDR completes the Task, records a rejected review outcome, and removes the errorstatus meta tag from the focus DocumentReference.

Reject Input Parameters

The operation accepts the following input parameters:

  • source – the source Device from which the operation request originated. This parameter is required.
  • timestamp – the date and time at which the document misfile review was completed. This parameter is optional. If it is not supplied, the CDR uses the date and time at which the operation is processed.
  • reviewer – the Practitioner reviewing the potentially misfiled document. This parameter is required.
  • misfileRejectedReason – the reason why the reviewer rejects that the document is misfiled. This parameter is required.

Reject Output Parameter

The operation returns the following output parameter:

  • return – the updated Task, recording completion of the document misfile review with an outcome of rejected.

Reject Example API Request

The following example shows the HTTP POST request used to reject a document misfile review.

POST [base]/Task/[id]/$reject-document-misfile HTTP/1.1 Authorization: Bearer [access-token] Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"id": "Example-CDR-Parameters-Task-RejectDocumentMisfile-Instance",
"parameter": [
{
"name": "source",
"resource": {
"resourceType": "Device",
"identifier": [
{
"system": "https://fhir.nhs.wales/Id/application-instance-identifier",
"value": "210"
}
],
"deviceName": [
{
"name": "Welsh Clinical Portal",
"type": "user-friendly-name"
}
]
}
},
{
"name": "timestamp",
"valueDateTime": "2026-08-23T10:30:00Z"
},
{
"name": "reviewer",
"resource": {
"resourceType": "Practitioner",
"identifier": [
{
"system": "https://fhir.hl7.org.uk/Id/gphc-number",
"value": "2076543"
}
],
"name": [
{
"family": "Davies",
"given": [
"Carys"
],
"prefix": [
"Ms"
]
}
]
}
},
{
"name": "misfileRejectedReason",
"valueString": "Reviewer confirms the document is not misfiled after review."
}
]
}

Definitions and Examples

Mark DocumentReference as Potentially Misfiled

Accept Document Misfile

Reject Document Misfile

Revoking a Clinical Document

If a clinician determines that a document should be removed from a patient's record, they can revoke the document by invoking the $revoke operation. This may be appropriate where the document is incorrect or where the clinician determines that it should no longer be retained against the patient record.

Revoking a document does not physically delete the DocumentReference. Instead, the CDR patches the current version of the resource, sets its status to entered-in-error, and updates its meta.tag where the system is errorstatus to the code revoked with the display Revoked.

The operation can be invoked at the DocumentReference instance level, using the CDR-assigned DocumentReference.id, or at the DocumentReference type level, using the document's business identifier in the optional documentIdentifier input parameter.

Input Parameters

The operation accepts the following input parameters:

  • documentIdentifier – the business identifier of the DocumentReference. This parameter is optional and may be supplied for a type-level invocation. It must not be supplied for an instance-level invocation, where the DocumentReference.id is provided in the request URL.
  • source – the source Device from which the operation request originated. This parameter is required.
  • timestamp – the date and time at which the document was revoked. This parameter is optional. If it is not supplied, the CDR uses the date and time at which the operation is processed.
  • revoker – the Practitioner revoking the DocumentReference. This parameter is required.
  • revocationReason – the reason why the DocumentReference is being revoked. This parameter is required.

Expected Action

On successful execution, the CDR patches the current version of the focus DocumentReference:

  • meta.lastUpdated is set to the supplied timestamp, or to the current date and time if timestamp is not supplied.
  • status is set to entered-in-error.
  • The meta.tag where system is errorstatus is updated with code set to revoked and display set to Revoked.

Example API Requests

The following example shows the HTTP POST request used to invoke the operation at the DocumentReference type level. The documentIdentifier parameter identifies the target DocumentReference by its business identifier.

POST [base]/DocumentReference/$revoke HTTP/1.1 Authorization: Bearer [access-token] Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"id": "Example-CDR-Parameters-DocumentReference-Revoke-Type",
"parameter": [
{
"name": "documentIdentifier",
"valueIdentifier": {
"system": "https://fhir.nhs.wales/Id/supersession-set-identifier",
"value": "550e8400-e29b-41d4-a716-446655440000"
}
},
{
"name": "source",
"resource": {
"resourceType": "Device",
"identifier": [
{
"system": "https://fhir.nhs.wales/Id/application-instance-identifier",
"value": "210"
}
],
"deviceName": [
{
"name": "Welsh Clinical Portal",
"type": "user-friendly-name"
}
]
}
},
{
"name": "timestamp",
"valueDateTime": "2026-08-24T10:30:00Z"
},
{
"name": "revoker",
"resource": {
"resourceType": "Practitioner",
"identifier": [
{
"system": "https://fhir.hl7.org.uk/Id/gmc-number",
"value": "9630339"
}
],
"name": [
{
"family": "Jones",
"given": [
"Anne"
],
"prefix": [
"Dr"
]
}
]
}
},
{
"name": "revocationReason",
"valueString": "Clinician has determined that the document is incorrect and should be removed from the patient record."
}
]
}

See Example Parameters - DocumentReference Revoke (Type Invocation) for the complete example resource.

The following example shows the HTTP POST request used to invoke the operation at the DocumentReference instance level. The CDR-assigned DocumentReference.id identifies the target resource, so documentIdentifier is not supplied.

POST [base]/DocumentReference/[id]/$revoke HTTP/1.1 Authorization: Bearer [access-token] Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"id": "Example-CDR-Parameters-DocumentReference-Revoke-Instance",
"parameter": [
{
"name": "source",
"resource": {
"resourceType": "Device",
"identifier": [
{
"system": "https://fhir.nhs.wales/Id/application-instance-identifier",
"value": "210"
}
],
"deviceName": [
{
"name": "Welsh Clinical Portal",
"type": "user-friendly-name"
}
]
}
},
{
"name": "timestamp",
"valueDateTime": "2026-08-24T10:30:00Z"
},
{
"name": "revoker",
"resource": {
"resourceType": "Practitioner",
"identifier": [
{
"system": "https://fhir.hl7.org.uk/Id/gmc-number",
"value": "9630339"
}
],
"name": [
{
"family": "Jones",
"given": [
"Anne"
],
"prefix": [
"Dr"
]
}
]
}
},
{
"name": "revocationReason",
"valueString": "Clinician has determined that the document is incorrect and should be removed from the patient record."
}
]
}

See Example Parameters - DocumentReference Revoke (Instance Invocation) for the complete example resource.

Formal Definition

See CDR DocumentReference Revoke OperationDefinition for the formal operation definition.