--- title: "Retrieve attachment (A042, FHIR R4)" method: GET path: "/R4/Binary/{id}" tags: ["Retrieve clinical information"] --- # Retrieve attachment (A042, FHIR R4) `GET /R4/Binary/{id}` ## Overview Use this endpoint to retrieve a file that is attached to a referral or advice request. Referral information can also include: - Structured clinical information added by an integrated primary care system - Service provider activity - Advice and guidance conversation This additional clinical information must be retrieved via [[HYPERLINK_A007]] [Read](https://digital.nhs.uk/developer/guides-and-documentation/building-healthcare-software/referrals-and-bookings/e-referral-service/retrieve-clinical-referral-information-as-a-service-provider) our building healthcare software guide for detailed information. ## Supported security patterns - Application-restricted, unattended access - Healthcare worker, user-restricted access ## Pre-requisites ### Application-restricted, unattended access In order to use this endpoint you must be an authenticated e-RS calling application, working in the context of a Service Provider Organisation. ### Healthcare worker, user-restricted access In order to use this endpoint you must be an authenticated e-RS user or application and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` - `SERVICE_PROVIDER_CLINICIAN` - `SERVICE_PROVIDER_CLINICIAN_ADMIN` ### Attachment availability To use this endpoint, the attachment must be available for download. Attachments are only available after successful validation and malware scans. A request to retrieve an attachment that is not available for download will result in a 422 error. See the Response HTTP 422 section for further information. The availability status of an attachment can be retrieved via any endpoint that provides details of an attachment in the success response. Details of the availability statuses that may be returned via these endpoints can be found in the specification for [[HYPERLINK_A005]]. Prior to retrieving an attachment, you will need to have retrieved the referral or advice request the attachment is associated with (via the [[HYPERLINK_A005]] or [[HYPERLINK_A024]] endpoints, for example). Referrals and advice requests include resolvable URLs to the files currently attached to them, which can be used with this endpoint to retrieve the attachments themselves. ## Support for a temporary redirect This endpoint makes use of a HTTP 307 temporary redirect. It redirects the caller to a temporary location from which the file contents can be downloaded directly. The temporary location is only valid for a short period of time and should be used immediately. Callers of this endpoint must ensure they: - follow this redirect to retrieve the file - do not cache the temporary location - generate a new redirect each time the file is downloaded See the Response HTTP 307 section for further information. ## Important notes A referral pathway in e-RS can be made up of more than one UBRN. For example: a referral is booked and seen in a general knee clinical assessment service (UBRN #1), and the service decides to onward refer to a more specialist knee meniscus service (UBRN #2). This would result in two UBRNs for the referral pathway. There may be additional related UBRNs if there are multiple onward referrals. As such, it is important that all clinical information is obtained from across all the related UBRNs referenced in [[HYPERLINK_A005]]. You can do this using the following endpoints: - [[HYPERLINK_A006]] - [[HYPERLINK_A007]] Note: It is possible that the initial UBRN may be the only one in the referral pathway to have clinical information and/or attachments associated. ## Use case As an authenticated user I need to retrieve a clinical attachment associated with a referral or advice request So that I can assess its content and decide what further action may be needed. ## Related endpoints - [[HYPERLINK_A005]] to retrieve details of a referral. This includes references to clinical attachments, related referrals and other important data. - [[HYPERLINK_A024]] to retrieve the summary of an advice and guidance request. This endpoint provides important contextual information about the advice and guidance request (e.g. the service/specialty to which advice has been requested, etc). - [[HYPERLINK_A025]] to retrieve the advice and guidance conversation between the referring organisation and service providing organisation. - [[HYPERLINK_A007]] to generate a PDF file that summarises clinical information for a referral. ## Sandbox test scenarios The sandbox for this endpoint is a simple implementation that only supports success cases. Inline with the behaviour described in "Support for a temporary redirect", the sandbox will return a HTTP 307 temporary redirect. For simplicity, the temporary location will be static and never expire, unlike the live environment. A successful response will always be returned, provided the Binary ID is in a valid format. The Availability Status of a file is not considered in the sandbox and a file will always be available for retrieval. Successful responses will always return the same example PDF file. ## Path parameters - `id` string, required ## Headers - `NHSD-eRS-Business-Function` 'REFERRING_CLINICIAN' | 'REFERRING_CLINICIAN_ADMIN' | 'REFERRING_ADMIN' | 'COMMISSIONER' | 'SERVICE_PROVIDER_CLINICIAN_ADMIN' | 'SERVICE_PROVIDER_CLINICIAN' | 'SERVICE_PROVIDER_ADMIN' | 'INFORMATION_ANALYST' | 'BOOKING_MANAGER' | 'ADDITIONAL_REQUIREMENTS_MANAGER' - `NHSD-End-User-Organisation-ODS` string - `NHSD-eRS-On-Behalf-Of-User-ID` string ## Parameters - `#/paths/~1R4~1Practitioner/get/parameters/0` — unresolved $ref - `#/paths/~1R4~1Practitioner/get/parameters/1` — unresolved $ref ## Other responses - `307` — Response redirects the user agent to a location (via the Location header) in the object store from which the attachment can be downloaded from. - `400` — Where status code 400 (Bad Request) is returned then an [NHSDigital-OperationOutcome](https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome) will be included in the body, as detailed below. Check diagnostics property for specific information regarding the error. | issue.details.coding.code | issue.code | Coding System | Description | | ------------------------- | ---------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | REC_BAD_REQUEST | invalid | [BaRS Error Code](https://fhir.nhs.uk/CodeSystem/http-error-codes) | The request could not be processed due to an error. This could be due to either an error with the request or the state of the resource requested. See the diagnostics field for further information. | - `401` — unresolved $ref - `403` — Where status code 403 (Forbidden) is returned then an [NHSDigital-OperationOutcome](https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome) will be included in the body, as detailed below. Check diagnostics property for specific information regarding the error. | issue.details.coding.code | issue.code | Coding System | Description | | ------------------------- | ---------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | | REC_FORBIDDEN | forbidden | [BaRS Error Code](https://fhir.nhs.uk/CodeSystem/http-error-codes) | A call attempts to access or operate upon a resource without proper authorisation. | | NO_RELATIONSHIP | forbidden | [eRS Error Code](https://fhir.nhs.uk/CodeSystem/ers-error-codes) | The caller has no legitimate relationship with the resource. | | ACCESS_DENIED | forbidden | [APIM Error Code](https://fhir.nhs.uk/CodeSystem/NHSD-API-ErrorOrWarningCode) | The request could not be authenticated due to insufficient credentials being provided. | - `404` — Where status code 404 (Not Found) is returned then an [NHSDigital-OperationOutcome](https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome) will be included in the body, as detailed below. Check diagnostics property for specific information regarding the error. | issue.details.coding.code | issue.code | Coding System | Description | | ------------------------- | ---------- | ------------------------------------------------------------------ | ---------------------------------------------------------- | | REC_NOT_FOUND | not-found | [BaRS Error Code](https://fhir.nhs.uk/CodeSystem/http-error-codes) | The supplied URL or Resource does not exist on the server. | - `422` — Where status code 422 (Unprocessable Entity) is returned then an [NHSDigital-OperationOutcome](https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome) will be included in the body, as detailed below. Check diagnostics property for specific information regarding the error. | issue.details.coding.code | issue.code | Coding System | Description | | ------------------------- | ---------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PENDING | invalid | [eRS Error Code](https://fhir.nhs.uk/CodeSystem/ers-error-codes) | The file is being scanned and cannot be retrieved. Wait at least 5 minutes before checking its availability again. | | THREATS_FOUND | invalid | [eRS Error Code](https://fhir.nhs.uk/CodeSystem/ers-error-codes) | The file has been quarantined after detecting a threat and cannot be retrieved. Contact the organisation that uploaded the file to resolve the issue and get the information you need. Details of who uploaded the file can be retrieved via any endpoint that provides details of an attachment in the success response (via the [[HYPERLINK_A005]] or [[HYPERLINK_A024]] endpoints, for example)| | VALIDATION_FAILED | invalid | [eRS Error Code](https://fhir.nhs.uk/CodeSystem/ers-error-codes) | The file has failed validation and cannot be retrieved. Contact the organisation that uploaded the file to resolve the issue and get the information you need. Details of who uploaded a file can be retrieved via any endpoint that provides details of an attachment in the success response (via the [[HYPERLINK_A005]] or [[HYPERLINK_A024]] endpoints, for example)
Validation can fail because the: | - `429` — unresolved $ref - `500` — unresolved $ref - `503` — unresolved $ref --- [API](https://skmtc.dev/nhs/apis/e-referrals-service-api.md) · [All operations](https://skmtc.dev/nhs/apis/e-referrals-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nhs/e-referrals-service-api/revisions/916969ea472f/schema)