GP Connect - Access Document

Search for a patient's documents

Use case

Search for a patient’s documents from a GP practice.

API specification

See GP Connect Access Document - FHIR API.

Search parameters

Provider systems SHALL support the following search parameters:

Name	Type	Description	Paths
`created`	`date` or `dateTime`	Creation/Edit datetime of the document	`DocumentReference.created`
`author`	`token`	The organisation that authored the document	`DocumentReference.author`
`description`	`string`	Keyword based search	`DocumentReference.description` + `DocumentReference.type`

Important: GP Connect does not support searching for documents based on a practitioner author. The author search parameter MUST only be used to search by an organisation author using an ODS code

Important: The type and facility parameters have been removed from the API. These will be reinstated in the future when provider systems contain the metadata to support them. The original release of the Access Documents capability contained type and facility parameters which could be used to search for types of clinical document and the types of clinical settings where they were created. These have been removed while the quality of the metadata in provider systems around these items improves. They will be reinstated at the point that they can be supported.

_include parameters

Provider systems SHALL support the following include parameters:

Name	Description	Paths
`_include= DocumentReference:subject:Patient`	Include `Patient` resources referenced within the returned `DocumentReference` resources	`DocumentReference.subject`
`_include= DocumentReference:custodian:Organization`	Details of organisations that are custodians for the documents that are returned in DocumentReference resources
`_include= DocumentReference:author:Organization`	Details of organisations that authored the documents that are returned in DocumentReference resources
`_include= DocumentReference:author:Practitioner`	Details of who/what authored the documents that are returned in DocumentReference resources
`_revinclude:recurse= PractitionerRole:practitioner`	Include `PractitionerRole` resources referenced from matching `Practitioner` resources	`DocumentReference.author:Practitioner`

Consumer systems MUST send the following parameters to reduce the number of API calls:

_include=DocumentReference:subject:Patient
_include=DocumentReference:custodian:Organization
_include=DocumentReference:author:Organization
_include=DocumentReference:author:Practitioner
_revinclude:recurse=PractitionerRole:practitioner

Consumer systems MAY send the following parameters in the request:

created
author
description

When using the ‘created’ parameter, consumers MUST do the following

to search for a lower boundary of a date:
- a single created parameter with a date prefixed by ge should be supplied
to search for a upper boundary of a date:
- a single created parameter with a date prefixed by le should be supplied
to search between two dates:
- two created parameters should be supplied
  - a single created parameter with a date prefixed by ge
  - a single created parameter with a date prefixed by le

Interaction diagram

documents-search-patient-document-interaction-diagram

Payload response body

Provider systems MUST:

return a 200 OK HTTP status code to indicate successful search of a patient’s documents
return a Bundle
return the following resources in the Bundle:
- Patient matching the NHS Number sent in the body of the request
- Organization matching the patient’s registered GP practice, referenced from Patient.generalPractitioner
- Organization matching the organisation serving the request, if different from above, referenced from Patient.managingOrganization
- Practitioner matching the patient’s usual GP, if they have one, referenced from Patient.generalPractitioner
- PractitionerRole matching the usual GP’s role
- Practitioner resources for supplementary actors
- PractitionerRole resources for the roles of supplementary actors
- DocumentReference resources conforming to the CareConnect-GPC-DocumentReference-1 profile that match the supplied search criteria
  - where the created parameter has been supplied and DocumentReference.created doesn’t exist, DocumentReference.indexed MUST be used instead
  - where the description parameter has been supplied, both DocumentReference.description and DocumentReference.type MUST be searched
- Organization resources for supplementary actors

Examples

See Search for a patient's documents.