Written by Technical Team | Last updated 17.10.2025 | 15 minute read
GP Connect’s Access Document capability exists to do one thing exceptionally well: let authorised care settings retrieve unstructured documents that are already held in a patient’s registered GP practice record. Think discharge summaries, clinic letters, scanned reports and externally generated PDFs that the practice has filed in the patient’s record. By exposing a standardised, Spine-brokered interface, the capability allows a community nurse, an urgent treatment centre, or a hospital service to view the exact same artefacts the GP team can see, without waiting for paper or relying on ad-hoc email.
Although “unstructured” might sound like a drawback, it’s a strength for clinical fidelity. Unstructured documents preserve author intent, layout and legally relevant wording — aspects that can be diluted when you flatten everything into codes. The Access Document capability complements, rather than competes with, GP Connect’s structured record and HTML views: the structured capability is ideal for medication lists or allergy data you want to compute over; Access Document is for the authoritative letter you need to read, attach to your EPR, or print for a ward round. The API deliberately keeps its operation set small and safe: search for a patient’s documents, then retrieve the selected document. That narrow focus reduces implementation complexity and helps suppliers pass assurance faster.
The core user story is simple: “As a clinician in a non-GP setting, I can quickly find and view the hospital correspondence or attachments held by the GP practice.” Because the GP practice acts as custodian for much incoming information from across the health and care system, surfacing those documents can unlock continuity of care in situations where you don’t have direct access to the original hospital system. In short, Access Document bridges care boundaries with the least effort from consuming systems, and with strong governance baked in via Spine, HSCN and role-based controls.
At a transport level, GP Connect is Spine-brokered and internet-facing only via the Spine Secure Proxy (SSP). Consuming systems call the provider’s FHIR endpoint through SSP; the proxy becomes the single control point for authentication, authorisation, audit and data-sharing checks. Every HTTP leg is protected with TLS Mutual Authentication (TLS MA): the consumer-to-SSP hop and the SSP-to-provider hop are both mutually authenticated, reducing the attack surface and ensuring only accredited parties talk to each other.
Authorisation happens in two places. First, the consumer must operate local role-based access control (RBAC) and include a JSON Web Token (JWT) in every request that conveys who the user is, what role they are acting under (including smartcard SDS role identifiers if applicable), the consuming system identity, and the consumer organisation’s ODS code. Second, SSP enforces centrally recorded data-sharing agreements and validates that the consumer is permitted to communicate with the provider. These design decisions are informed by clinical safety: the platform assumes that document access is direct care, time-critical, and auditable.
Network placement matters. The Access Document capability requires connectivity to the Health and Social Care Network (HSCN). While some NHS APIs have internet-exposed channels, Access Document assumes you’re “on net” and have suitable routing and firewall rules for SSP. This is typically handled as part of your organisation’s network architecture and supplier onboarding, but developers should plan for it early.
From an API style perspective, Access Document is deliberately conservative. It’s a synchronous FHIR-based interface aligned to UK Core on FHIR Release 3 (STU3). The search interaction uses the DocumentReference resource and returns a FHIR Bundle that may include related Patient, Organization, Practitioner and PractitionerRole resources via _include/_revinclude. The retrieval interaction returns a FHIR Binary resource carrying the base64-encoded content and its MIME type. This split pattern — metadata via DocumentReference, content via Binary — is a standard FHIR idiom that supports safe filtering and consistent caching behaviour.
Finally, the API is operated as a silver service: it runs 24×7×365 but is supported during normal business hours. If your clinical workflow is mission-critical out-of-hours, architect your solution with suitable retry, graceful degradation and operational monitoring; silver does not mean unavailable, it means you should take responsibility for your resilience posture.
Highlights of the security and governance model:
At the heart of the capability are two interactions you will implement end-to-end: Search for a patient’s documents and Retrieve a document. The search is a FHIR RESTful query against DocumentReference scoped to a specific patient resource ID. You can add search parameters to constrain results, and — critically — you must send a set of _include and _revinclude parameters to reduce round-trips by fetching the immediately related resources alongside the documents. The retrieve operation then fetches the Binary resource identified by the document reference, returning the base64-encoded content you can render, download, or store in your EPR.
The relative form of the search looks like this:
GET /Patient/[id]/DocumentReference
?_include=DocumentReference:subject:Patient
&_include=DocumentReference:custodian:Organization
&_include=DocumentReference:author:Organization
&_include=DocumentReference:author:Practitioner
&_revinclude:recurse=PractitionerRole:practitioner
[&created=ge2020-01-01]
[&created=le2025-01-01]
[&author=urn:oid:1.2.826.0.1285.0.1.10|A12345]
[&description=discharge]
The include set isn’t optional in practice. The specification says consumers MUST send those _include/_revinclude parameters so that providers can return the minimal graph of people and organisations needed to display document provenance safely. Providers SHALL support created, author and description as search parameters; where DocumentReference.created is absent, providers must use DocumentReference.indexed for date filtering. The description search must match against both DocumentReference.description and DocumentReference.type. This careful wording is important: don’t make assumptions about metadata completeness, and always code defensively for created/indexed substitutions.
The search request must include SSP headers that drive proxy routing and audit: Ssp-TraceID, Ssp-From (your ASID), Ssp-To (provider ASID), and the interaction ID urn:nhs:names:services:gpconnect:documents:fhir:rest:search:documentreference-1. Use Accept and Content-Type of application/fhir+json;charset=utf-8. On success you get a 200 OK and a FHIR Bundle that includes one or more DocumentReference resources and the related actors/resources you asked to include. Error conditions are expressed via OperationOutcome with Spine error codes such as PATIENT_NOT_FOUND, NO_PATIENT_CONSENT or INVALID_PARAMETER when mandatory _includes are missing.
Understanding DocumentReference content is key to a good UI. The profile fixes important fields:
Retrieval is a simple GET /Binary/[id] using a different interaction ID: urn:nhs:names:services:gpconnect:documents:fhir:rest:read:binary-1. The response is a FHIR Binary resource containing the MIME type and base64-encoded payload. Your consumer should honour the versionId in metadata; while GP Connect returns only the current version for Access Document, the presence of a version attribute matters for audit and any future reconciliation. Typical errors include “document not found” and “file size exceeds limit”, both mapped to NO_RECORD_FOUND, so design your UI to distinguish “no such ID” from “too large to fetch” in a user-friendly way (for example, by offering to open the document in the source system if your integration supports it).
A subtle but useful pattern emerges from the two interactions: treat DocumentReference as the index and Binary as the library book. Build navigation and filtering on the Reference, then retrieve the Binary selectively and cache it briefly if your information governance allows. Because the API is synchronous and Spine-brokered, you should also plan for back-pressure and timeouts by keeping retrieval on-demand rather than front-loading every document in a patient’s history.
Before you write any production code, sort out connectivity and environments. You’ll develop and iterate using the internet-facing demonstrator (the “orange” environment) and then progress through integration and assurance. The demonstrator gives you a stable place to exercise the search and retrieval flows against realistic data without touching live GP systems. Plan to script your calls (Postman or automated tests) with SSP headers and JWT generation so your application code stays clean.
The Access Document page outlines two parallel testing streams: clinical and technical. Clinical testing ensures the way you display and process returned information is safe; technical testing verifies your messages conform to the FHIR spec and Spine rules (headers, interaction IDs, routing). The clinical path provides “known” test records with hazards you’re expected to mitigate — for instance, how you label and order multi-author documents or how you prevent mis-filing. The technical path is about message integrity, not payload semantics. Running them in parallel speeds up assurance and helps you balance UX decisions against conformance.
Every call must carry the four SSP headers: Ssp-TraceID (a GUID to correlate logs), Ssp-From (your ASID), Ssp-To (the provider’s ASID) and the correct Ssp-InteractionID for the operation you’re invoking. Failing to include the mandatory _include set on the search request will trigger an INVALID_PARAMETER error; failing to route to an enabled practice will result in ACCESS DENIED. This is why pre-resolving the provider’s endpoint from the Spine Directory Service (SDS) and verifying enablement is not “optional hygiene” but a pre-requisite for reliable test cycles.
Access Document is explicit about common failure modes. For search, anticipate “patient not found” because the patient is inactive, deceased, not registered at that practice, sensitive, or the NHS number lacks a “present and verified” status. Also expect “no consent” when the patient has dissented from sharing. For retrieval, be prepared for the file to be missing or too large to retrieve. Providers must return a GPConnect-OperationOutcome-1 to supply diagnostic detail; surface that detail to the clinician when it’s safe to do so (for example, “document was too large to retrieve; please contact the GP practice” rather than a cryptic code).
A well-behaved DocumentReference includes description (the human-readable title), author, custodian, created or indexed, and practiceSetting. Displaying these elements clearly makes a big difference to clinical utility: clinicians care about who wrote the letter, where and when. When created is missing, sort by indexed. When type is provided via the SNOMED refset, display the preferred term but preserve the original title to avoid ambiguity. And because content.attachment.url points to the Binary, you can show a “Retrieve” button per row that lazily calls the Binary endpoint only when a user chooses to view or download.
The spec emphasises reducing API chatter via _include and _revinclude; that’s half the story. The other half is being judicious with search parameters. Filter by a sensible date range (ge/le) — for example, last six months for acute contexts — and by description keywords relevant to your workflow (“discharge”, “clinic letter”). If you support searching by the author’s ODS code, wire your UI to helpful pickers rather than free text. You’ll get better performance, smaller bundles and a faster path to the single document the clinician needs.
Practical checklist for your first integration:
Access to live GP data is gated — appropriately — by onboarding and assurance. Start by validating you meet the prerequisites: HSCN access; the ability to perform PDS trace or work with an accredited PDS service; and alignment with the Direct Care Information Governance model. You will also need to operate local RBAC and demonstrate that your use case is strictly for direct care of NHS patients in England. Once you’re confident, submit a concise use case to NHS England describing your product, setting and benefits. You should receive an initial response confirming the next steps.
Assurance proceeds on two rails. The technical conformance track proves your system talks to providers via Spine, honours FHIR requirements and sends/receives the right headers and payloads. The clinical safety track shows you have an appointed Clinical Safety Officer (CSO), you’re applying DCB0129/0160 appropriately, and your product’s workflows mitigate known hazards. Expect a sequence of meetings — an initial safety review, process readiness, and a clinical evaluation of readiness for deployment — supported by published guidance and artefacts. This is not bureaucracy for its own sake; it’s how the platform scales safely across thousands of organisations, suppliers and users.
Keep an eye on versions and service status. As of mid-2025, the working Access Document specification is 1.5.1 (in production, beta), with 1.6.0 planned and stated as backward-compatible with 1.5.1 from a consumer perspective. That means your investment in search and retrieval patterns will carry forward. The page also labels the API as a silver service, so fold that into your run-book: adopt appropriate monitoring, alerting and user messaging for transient failures. And remember that Access Document doesn’t live in isolation: related APIs you may need include GP Connect Access Record: Structured (for coded data), PDS FHIR (for patient trace and GP practice lookup), and the Spine Directory Service (to resolve endpoints and organisation identities).
When you render search results, show the author, custodian, creation/indexed date, type and title. Clinicians depend on provenance to judge relevance and trustworthiness. If the type is coded, expose both the coding’s display term and the free-text description so users can cross-check. If created is missing, sort by indexed and label it as “date added”. These seemingly small choices collapse decision time for end users across dozens of cases per day.
A generic “search everything” control is rarely helpful. In urgent care, default date filters to recent months and pre-fill description with keywords like “ED discharge” or “clinic letter”. In community care, widen to a year. Offer an “include older documents” toggle that expands the range. Crucially, store the user’s last filter per patient — clinicians often revisit the same patient repeatedly during a single episode of care.
When the user clicks a document, call GET /Binary/[id], decode the base64 and present it with a viewer that respects the MIME type (PDF, image, text). For large PDFs, implement streaming to the viewer when your platform allows, but continue to handle the “file too large” error path. Offer a “Download” action, and — where your information governance policies permit — a short-lived cache so subsequent opens are instant during the same session.
If the patient is flagged as sensitive or has dissented, don’t convert that into a generic “not found”. Instead, present a respectful message that explains access cannot be granted and makes clear to the clinician that the absence of data is a policy decision, not a system fault. Log the OperationOutcome details for audit and support triage. When _include headers are missing and you get INVALID_PARAMETER, surface a clear developer-facing message in your logs so the fix is obvious.
Create a traceability matrix that maps each Access Document requirement to a test case in your CI suite. Include negative tests (missing SSP headers, invalid ASIDs, absent _include params, malformed JWT, date filter edge cases). Wire in synthetic “Orange” environment runs overnight so regressions are caught quickly. This habit transforms assurance from a deadline scramble into a largely clerical step backed by evidence.
Silver service means you own user communications out-of-hours. Provide status banners when Spine or a provider estate has a known incident (you can detect via characteristic error patterns). Gracefully degrade: show cached DocumentReference metadata even if Binary retrieval is temporarily failing, and nudge users with suggested next steps (“Try again in a few minutes” or “Contact the practice for a copy”). That’s good clinical UX.
If your workflow needs structured, computable data (for example, to reconcile medicines), pair Access Document with Access Record: Structured. If you want clinician-friendly sections rendered as HTML to embed, look at Access Record: HTML. If your system needs to send a consultation summary back to the GP, that’s a separate “Send Document” capability using GP Connect messaging. Access Document stays focused on reading what the practice already holds.
The 1.5.1 working spec and the 1.6.0 roadmap give you a stable base — and the latter is signposted as backward-compatible for consumers. That means today’s investment in robust search, provenance display, and binary retrieval will carry forward. Keep an eye on the reinstatement of search parameters like type and facility once provider metadata quality reaches the bar; adding those into your UI as optional filters later will give clinicians even finer control.
Is your team looking for help with GP Connect integration? Click the button below.
Get in touch