Retrieve a document

Use case

Retrieve a document from a GP practice.

Security

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

Prerequisites

Consumer

The consumer system:

API usage

Interaction diagram

Retrieve a document interaction diagram

Request

FHIR® relative request

GET /Binary/[id]

FHIR® absolute request

GET https://[proxy_server]/https://[documents_provider_server]/[documents_fhir_base]/Binary/[id]

File size limit

Documents up to 5MB can be retrieved using this interaction.

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:read:binary-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:read:binary-1

Payload request body

N/A

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 document could not be found with the document id provided NO_RECORD_FOUND
The document could not be retrieved due to it exceeding the file size limit NO_RECORD_FOUND
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
The request is for an inactive or deceased patient and the request is received after the allowed access period PATIENT_NOT_FOUND

Request response

Response headers

Provider systems are not expected to add any specific headers beyond that described in the HTTP and FHIR® standards.

Payload response body

Provider systems MUST:

  • return a 200 OK HTTP status code to indicate successful execution of the operation
  • return a Binary resource conforming to the Binary resource definition
  • include the versionId of the current version of the Binary resource

Payload response examples

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