Search loading...


Explore and Make use of Nationally Defined Messaging APIs


Search for a patient's documents

Search for a patient's documents

Use case

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


  • GP Connect utilises TLS Mutual Authentication for system level authorization
  • GP Connect utilises JSON Web Tokens (JWT) to transmit clinical audit and provenance details

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 Who and/or what authored the document.
description string Keyword based search DocumentReference.description + DocumentReference.type

_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

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



The consumer system:

API usage

Interaction diagram

Search for patient's documents interaction diagram


FHIR® relative request

GET /Patient/[id]/DocumentReference?[_include=DocumentReference:subject:Patient]

FHIR® absolute request

GET https://[proxy_server]/https://[documents_provider_server]/[documents_fhir_base]/Patient/[id]/DocumentReference?[_include=DocumentReference:subject:Patient]

Request headers

Consumers MUST include the following additional HTTP request headers:

Header Value
Ssp-TraceID Consumer’s Trace ID (a GUID or UUID)
Ssp-From Consumer’s ASID
Ssp-To Provider’s ASID
Ssp-InteractionID urn:nhs:names:services:gpconnect:documents:fhir:rest:search:documentreference-1

Example HTTP request headers:

Accept: application/fhir+json;charset=utf-8
Content-Type: application/fhir+json;charset=utf-8
Ssp-TraceID: 629ea9ba-a077-4d99-b289-7a9b19fd4e03
Ssp-From: 200000000115
Ssp-To: 200000000116
Ssp-InteractionID: urn:nhs:names:services:gpconnect:documents:fhir:rest:search:documentreference-1

Payload request body


Error handling

The provider system MUST return a GPConnect-OperationOutcome-1 resource that provides additional detail when one or more data field is corrupt or a specific business rule/constraint is breached.

The table below shown common errors that may be encountered during this API call, and the returned Spine error code. Please see Error handling guidance for additional information needed to create the error response or to determine the response for errors encountered that are not shown below.

Errors returned due to query parameter failure MUST include diagnostic information detailing the invalid query parameter.

Error encountered Spine error code returned
A patient could not be found with the patient id provided PATIENT_NOT_FOUND
The request is for the record of an inactive or deceased patient PATIENT_NOT_FOUND
The request is for the record of a non-Regular/GMS patient (i.e. the patient’s registered practice is somewhere else) PATIENT_NOT_FOUND
The patient’s NHS number in the provider system is not associated with a NHS number status indicator code of ‘Number present and verified’ PATIENT_NOT_FOUND
The request is for a sensitive patient PATIENT_NOT_FOUND
The patient has dissented to sharing their clinical record NO_PATIENT_CONSENT
The author query parameter contains an identifier other than an ODS code INVALID_PARAMETER
The request does not contain the mandatory _include parameters INVALID_PARAMETER
GP Connect is not enabled at the practice (see Enablement) ACCESS DENIED
The Access Document capability is not enabled at the practice (see Enablement) ACCESS DENIED

Request response

Response headers

HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/fhir+json; charset=utf-8
Date: Sun, 07 Aug 2016 11:13:05 GMT
Content-Length: 1464

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

Payload response examples

Examples of the payload requests and responses can be found here:

All content is available under the Open Government Licence v3.0, except where otherwise stated