Written by Technical Team | Last updated 23.01.2026 | 14 minute read
The NHS National Record Locator (NRL) is designed to solve a very specific problem at national scale: helping authorised health and care professionals find where important patient information is held, without turning the locator into yet another store of clinical content. In practice, that means the NRL is less like a shared record and more like a well-governed index of “information pointers”. Those pointers tell a consuming system what exists, who holds it, what it broadly relates to, and how it can be retrieved under the right controls.
This distinction shapes everything about integration. If you approach the NRL as though you are publishing documents, you can easily overcomplicate payloads, mis-model references, or design for the wrong performance characteristics. If you approach it as publishing metadata that helps discovery and safe access, you tend to make better decisions: leaner pointers, stable identifiers, strong semantics, and lifecycle behaviour that matches clinical reality.
Because the NRL uses HL7® FHIR®, integration is mostly about two disciplines working together: FHIR modelling (resources, profiles, references, value sets, bundle behaviour) and API payload design (request/response shape, headers, query construction, versioning, idempotency, and error patterns). Get either side wrong and you will see hard-to-diagnose failures: searches that return empty bundles, pointers that cannot be resolved, supersede flows that break continuity, or consumers that cannot safely interpret what you published.
The goal of this article is to help you integrate with the NRL API in a way that is technically correct, operationally resilient, and clinically meaningful. It focuses on understanding the FHIR resources you will exchange, designing high-quality payloads, and shaping the interactions around real-world record lifecycles.
Most NRL integrations fall into two roles, even if your organisation ultimately needs both. A producer publishes and manages pointers (because it holds patient information). A consumer searches for and reads pointers (because it needs to locate information held elsewhere). In integrated care settings, the same system might act as both: publishing pointers for its own records while also consuming pointers from other organisations.
The NRL is often described as an “index, not a repository”, and that phrasing matters at implementation time. Your producer integration should not try to squeeze every possible clinical nuance into the pointer. A consumer integration should not treat a pointer as proof of clinical truth. The pointer is an addressable record of existence, ownership, and access path—something that supports direct care by making the right information discoverable at the right time.
A typical end-to-end flow looks like this: a producer system determines that a patient has a record of a given type (for example, an end-of-life plan, a care plan, a discharge summary, or another clinically relevant document or dataset). It publishes a pointer that categorises the record and provides a retrievable location or access mechanism. When another organisation needs to support care, its consumer system searches the NRL for that patient, optionally filtering by information type or custodian, and receives a set of pointers describing what is available.
Under the hood, NRL integration usually sits within the NHS Spine ecosystem and relies on a combination of national identity and addressing conventions, organisational identifiers (for example, ODS codes), and application/system identity (often expressed via assured integration patterns). Even when those platform details are abstracted away by gateway components, they still influence what you must put into payloads—especially resource references, custodian identifiers, and the “shape” of search requests.
From a design perspective, treat NRL integration as an interoperability contract: producers promise to publish stable, well-coded pointers that can be discovered and interpreted; consumers promise to call the service correctly, handle empty and partial results safely, and respect governance constraints around access, auditing, and clinical safety.
Although the NRL is an “API”, your day-to-day work is really about a small set of FHIR resources and how they are profiled for the national use case. Understanding what each resource is for will keep your payloads lean and your integration robust.
The primary resource is DocumentReference. In core FHIR, DocumentReference is used to index a document or other binary artefact so that it can be discovered and managed. In the NRL context, DocumentReference becomes the “pointer” itself: a structured statement that “a record of type X exists for patient Y, held by organisation Z, and can be retrieved via these access details”. The pointer’s value is in its metadata: patient subject, type coding, custodian, authorship/creation context, status, identifiers, and content metadata.
Search and read operations typically return a Bundle, usually a searchset bundle for search results. Bundles are not just containers: they carry the total count, links, and a set of entries each holding a resource (most often DocumentReference). Consumers should build their parsing around the bundle semantics rather than assuming “an array of pointers”.
When something goes wrong, the API will generally return an OperationOutcome. OperationOutcome is FHIR’s standard mechanism for describing errors in a structured way. Importantly, you should design error handling around both the HTTP status code and the OperationOutcome details; in mature integrations, you log and report both, because the OperationOutcome carries the actionable information that helps you fix payload issues, header problems, or invalid references.
Two areas routinely trip teams up. The first is profiles and versioning. NRL implementations can span different FHIR release lines or constrained profiles. You cannot assume that a “vanilla” DocumentReference is accepted. You must populate the resource to conform to the relevant NRL profile for the version you’re integrating against, including required fields and binding expectations for code systems. Consumers should also expect that pointers might indicate the profile they conform to (for example via meta.profile) and should be defensive when encountering fields they do not recognise.
The second is references. In FHIR, references are not “free text”; they are structured links to other resources, often expressed as URLs, relative references, or identifiers. The NRL’s use of national patient and organisation addressing conventions means your references need to be precise and consistent. If you mis-format a patient reference, you may end up with pointers that cannot be found by consumer searches, even though the pointer “looks” correct at a glance.
A high-quality NRL pointer starts with a clear decision: what is the stable identity of the thing you are pointing to? In many producer systems, the underlying record has its own internal key, versioning semantics, and lifecycle states. The NRL pointer must map to that reality without making consumers depend on your internal model. This is where identifier strategy and lifecycle design come together.
At the heart of the pointer is the subject, which represents the patient. The subject reference must use the expected patient identity form (commonly aligned to NHS number-based addressing conventions). If you treat the patient element casually—by sending the wrong reference format, mixing identifier patterns, or accidentally publishing a pointer against a test identity—you will create either undiscoverable pointers or, worse, discoverable pointers that point to the wrong person. Producers should validate patient references before publishing and should design safeguards that prevent publication when a patient identity is unverified or incomplete.
Next comes type coding. NRL pointers are only useful if consumers can filter and interpret them reliably. That means DocumentReference.type must be populated with a consistent, nationally meaningful code. You are not merely “labelling a document”; you are enabling safe discovery. Good type coding reduces noise for clinicians, supports targeted workflows (for example, “show me end-of-life plans”), and improves performance by enabling combination searches that reduce result sets. Poor type coding has the opposite effect: consumers must show long lists of ambiguous entries, and clinical users lose trust.
You also need to model custodian correctly. Custodian identifies the organisation responsible for maintaining the record being pointed to, not necessarily the system that created the pointer payload. In integrated environments (shared care record platforms, outsourced hosting, multi-tenant EPRs), these can diverge. If custodian is wrong, consumers will route access requests to the wrong organisation, operational contacts become ineffective, and governance obligations (like accountability for corrections) become muddled. Custodian should be represented in a way that ties back to nationally recognised organisational identity, typically aligned to ODS coding conventions.
Finally, the pointer must carry content metadata that supports retrieval. In FHIR DocumentReference, content captures details about the document or artefact, including attachment metadata. In NRL payload design, a common approach is to include a retrievable location (such as a URL or endpoint reference) rather than embedding large binary content. This keeps the locator lean, avoids turning the NRL into a de facto repository, and reduces the risk of over-sharing sensitive payloads at the locator layer.
A practical payload design checklist for producers often includes:
From the consumer side, the same elements become your parsing and presentation contract. When you ingest pointers, you should treat type and custodian as the primary drivers for display and routing, and treat identifiers as the keys for deduplication and lifecycle tracking. If you design your consumer UI around free-text titles or implementation-specific fields, you will struggle to provide a consistent experience across organisations.
One more subtlety: pointer payloads should be designed for change. Real clinical records are updated, corrected, and sometimes withdrawn. If your producer publishes pointers that cannot be superseded cleanly (because identifiers are unstable, or references are inconsistent), you will accumulate stale entries and push complexity onto consumers. Conversely, if your consumer assumes pointers never change, you may show entries that have been superseded or entered in error. Good payload design anticipates this and encodes enough structure to support the lifecycle.
Consumer integrations usually begin with search, because discovery is the NRL’s core promise. Search is typically performed against DocumentReference and returns a searchset bundle containing zero or more pointers. The zero-result case is not “an error” in many workflows; it is a meaningful outcome that can represent “no pointers exist” or “no pointers match the filter”. Your consumer application should handle this outcome gracefully, both technically (no parsing errors) and clinically (clear UI messaging).
NRL search design is heavily influenced by query parameter construction. You will commonly search by patient subject, and optionally combine that with filters such as type coding or custodian. From a performance and user-experience standpoint, combination searches can be valuable: rather than retrieving every pointer for a patient and filtering locally, you reduce the returned set and simplify clinical navigation. But combination searches only work well if producers have coded type consistently and populated custodian correctly.
Read operations are more direct: they return a specific DocumentReference pointer. Consumers usually use read after they have selected an entry from a search result, or when they need to refresh a pointer’s current view. Even in read workflows, keep in mind that the pointer is metadata; the “real” content is retrieved from the producer system using the access details described in the pointer and the appropriate access controls.
Producer integrations tend to focus on pointer lifecycle. In mature integrations, you will likely implement flows for creating a new pointer, changing a pointer’s status when it is invalid, and publishing a newer pointer that supersedes an older one. This is where payload design becomes less about “fields” and more about transactional intent: you are telling the NRL how the new pointer relates to existing state, and how consumers should interpret continuity.
Supersede behaviour is particularly important. Clinically, superseding may represent a revised care plan, a corrected end-of-life document, or a replacement pointer when record storage changes. Technically, superseding is about preserving discoverability and auditability while ensuring consumers find the latest valid pointer. The payload pattern typically involves expressing a relationship from the new pointer to the previous pointer, enabling the NRL to manage version increments and retain a coherent history. The result should be that consumers, when searching, see only the current pointer state rather than a confusing series of old entries.
Update patterns commonly involve changing the pointer status to indicate it was entered in error. This is a critical safety mechanism: it allows organisations to withdraw incorrect pointers without pretending they never existed, supporting audit and governance while reducing clinical risk. Your operational processes should treat this as a controlled workflow, not a casual “delete”: it should be traceable, justified, and aligned to incident and data-quality management.
There is also a practical integration detail that teams often learn the hard way: you must design for idempotency and replay. Network retries, gateway timeouts, and transient failures are realities in national integration. If you do not have a stable identifier strategy, retries can create duplicates. If you do not store correlation details, you cannot reconcile what happened when a request times out after submission. The safest approach is to design create and supersede flows so that you can safely retry without generating contradictory pointer state, supported by stable identifiers and consistent reference formatting.
NRL integration does not exist in isolation: it sits in a wider ecosystem of identity, assurance, and operational controls. If you treat security and governance as “just headers and certificates”, you can end up with an integration that technically works but is not safe or supportable. A good implementation recognises that the NRL is part of a national trust fabric, and designs payloads, logging, and operational handling accordingly.
At the boundary, most integrations rely on assured transport and gateway components that enforce organisational and application identity. That identity is not merely for authentication; it also informs authorisation and routing. As a producer, your payload must align with the identity you present at the API layer—particularly around custodian. As a consumer, you should expect that access to pointers may be constrained by organisational relationships and policy, and you should design user experiences that reflect that: clear messaging when records are not available, and avoidance of “hard fail” behaviours that block broader clinical workflows.
Testing is another area that benefits from intentional design. You should plan for contract-level testing of payload structure and conformance, not only “happy path” connectivity. In NRL integration, many failures are caused by payload conformance issues: missing required fields, invalid reference formats, mismatched coding systems, or incorrect content metadata. These are best caught before you ever hit an integration environment, using automated validation aligned to the applicable profile and a suite of realistic test cases that cover create, search, read, update/entered-in-error, and supersede flows.
Operationally, invest in observability. You will need to support clinical users and service desks when something looks wrong: missing pointers, duplicate entries, stale data, or unexpected empty results. Without good logs, you cannot distinguish between “nothing published”, “published but not discoverable because of a reference format issue”, “published but filtered out by query parameters”, or “published but access restricted by policy”. Your monitoring should capture request identifiers, relevant headers (in line with your information governance approach), response status, and the structured content of error responses.
A robust implementation approach usually includes:
Finally, remember what the NRL is trying to achieve: making important patient information findable across organisational boundaries during direct care. Payload design is not just a developer concern; it directly affects clinical usability. If you publish pointers that are poorly coded, incomplete, or hard to interpret, clinicians waste time and lose confidence. If you design consumer workflows that treat the NRL as a definitive record rather than a locator, you risk unsafe assumptions. The best NRL integrations take FHIR seriously as a shared language, keep pointers purposeful and lean, and treat lifecycle management as a first-class capability rather than an afterthought.
When those principles are in place—strong identifiers, correct references, meaningful coding, resilient lifecycle flows, and operational readiness—you end up with an integration that does what it should: help people find the right information, quickly, safely, and consistently, across the NHS.
Is your team looking for help with NHS National Record Locator (NRL) API integration? Click the button below.
Get in touch