-
Notifications
You must be signed in to change notification settings - Fork 0
/
consumer.yaml
1656 lines (1562 loc) · 87 KB
/
consumer.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
openapi: 3.0.0
# This is an OpenAPI Specification (https://swagger.io/specification/)
# for the National Record Locator Consumer FHIR API
# owned by NHS Digital (https://digital.nhs.uk/)
info:
title: National Record Locator Consumer - FHIR API
description: |
## Overview
The National Record Locator (NRL) enables organisations to share patient data nationwide. Rather than storing the
data itself, it is used to share pointers to the data, held in provider systems. It acts as an index and not a data
repository. Each document pointer is defined using the
[FHIR R4 DocumentReference](https://hl7.org/fhir/R4/documentreference.html) standard.
Users of the service fall into the categories of:
* producers - capable of creating and managing pointers
* consumers - capable of searching and reading pointers
The service removes the need for organisations to create duplicate copies of information across systems and
organisations, by enabling access to up-to-date information directly from the source.
It can be used to store and publish pointers to patient data held in health systems across England and to look up
where relevant patient data is held.
There is a growing list of health and social care organisations authorised to share records using NRL, and presently
the pointers are classified into the following types:
* [Mental health crisis plan](http://snomed.info/sct/736253002)
* [Royal College of Physicians NEWS2 (National Early Warning Score 2) chart](http://snomed.info/sct/1363501000000100)
* [ReSPECT (Recommended Summary Plan for Emergency Care and Treatment) form](http://snomed.info/sct/1382601000000107)
* [Contingency plan](http://snomed.info/sct/325691000000100)
* [End of life care plan](http://snomed.info/sct/736373009)
* [End of Life Care Coordination Summary](http://snomed.info/sct/861421000000109)
* [Emergency health care plan](http://snomed.info/sct/887701000000100)
* [Lloyd George record folder](http://snomed.info/sct/16521000000101)
* [Advanced care plan](http://snomed.info/sct/736366004)
* [Treatment escalation plan](http://snomed.info/sct/735324008)
* [Summary record]("http://snomed.info/sct|824321000000109")
* [Personalised Care and Support Plan]("http://snomed.info/sct|2181441000000107")
You can also retrieve booking and referal pointers however you can not currently do this by directly integrating with
the National Record Locator, you must instead onboard to the [Booking and Referral - FHIR API](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir)
### As a Consumer
Consumers can use this API to:
* search for pointers, restricted to a single Patient at a time
* read a specific pointer
* operations are restricted to document types agreed during the [onboarding](#api-description__onboarding) process
### What has changed?
This service is a replacement for the existing
[National Record Locator (NRL)](https://digital.nhs.uk/services/national-record-locator), and has the following
changes:
* upgraded from FHIR STU3 to R4.
* improved performance and scalability.
* improved onboarding experience.
* authenticated using [signed JWT](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) rather than mTLS.
* greater flexibility, by wider support of the [FHIR R4 DocumentReference](https://hl7.org/fhir/R4/documentreference.html) resource.
* the application only supports json type FHIR, not XML (which is also valid FHIR)
### Data availability, timing and quality
Pointers are available to be consumed almost immediately after they have been produced by the provider.
## Who can use this API
This API can only be used where there is a legal basis to do so. Make sure you have a valid use case before you go
too far with your development. You must demonstrate you have a valid use case as part of digital onboarding.
You must have the capability to verify NHS numbers by one of the following mechanisms:
* full PDS Spine compliant system
* Spine Mini Service PDS (SMSP)
Connecting parties must have an appointed Clinical Safety Officer and undertake a Clinical Safety Assessment.
You can not use this API to retrieve documents, however you should be prepared to retrieve in PDF or Unstructured
formats.
In order to retrieve a document, consumers must be able to interact with the National Record Locator and the Spine
Secure Proxy (SSP).
You can only use this API if your consuming application is only accessible using a valid NHS Smartcard for all users
or a system that uses an authentication method supported by
[NHS Care NHS Care Identity Service 2 (NHS CIS2)](https://digital.nhs.uk/services/identity-and-access-management/nhs-care-identity-service-2).
You must do this before you can go live (see ‘[Onboarding](#api-description__onboarding)’ below).
## API status and roadmap
This API is [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).
To see our roadmap, or to suggest, comment or vote on features for this API, see our
[interactive product backlog](https://nhs-digital-api-management.featureupvote.com/?tag=national-record-locator-api).
If you have any other queries, [contact us](https://digital.nhs.uk/developer/help-and-support).
## Service level
This API is a gold service, meaning it is operational and supported 24 hours a day, 365 days a year.
For more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).
## Technology
This API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest).
It conforms to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir)
global standard for health care data exchange, specifically to [FHIR R4 (v4.0.1)](https://hl7.org/fhir/r4/), except
that it does not support the [capabilities](http://hl7.org/fhir/R4/http.html#capabilities) interaction.
It includes some country-specific FHIR extensions, which conform to
[FHIR UK Core](https://digital.nhs.uk/services/fhir-uk-core), specifically
[fhir.r4.ukcore.stu1 0.5.1](https://simplifier.net/packages/fhir.r4.ukcore.stu1/0.5.1).
You do not need to know much about FHIR to use this API - FHIR APIs are just RESTful APIs that follow specific rules.
In particular:
* resource names are capitalised and singular, and use US spellings, for example `Organization` not `organisations`
* array names are singular, for example `entry` not `entries` for address lines
* data items that are country-specific and thus not included in the FHIR global base resources are usually wrapped in an `extension` object
There are [libraries and SDKs available](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) to help with FHIR API integration.
## Network access
This API is available on the internet and, indirectly, on the [Health and Social Care Network (HSCN)](https://digital.nhs.uk/services/health-and-social-care-network).
For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).
## Security and authorisation
This API uses the following access modes:
* [Application-restricted RESTful API - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication)
## Errors
We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:
* 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
* 400 to 499 if it failed because of a client error by your application
* 500 to 599 if it failed because of an error on our server
Errors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.
## Open source
You might find the following [open source](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source) resources useful:
| Resource | Description | Links |
|---------------------------|-----------------------------------------------------------|----------------------------------------------------------------------------|
| NRL v3 API | Source code for the core API and sandbox | [GitHub repo](https://github.com/NHSDigital/nrlf) |
| NRL v3 Producer API | Source code for the producer API proxy and specification. | [GitHub repo](https://github.com/NHSDigital/nrl-producer-api) |
| NRL v3 Consumer API | Source code for the consumer API proxy and specification. | [GitHub repo](https://github.com/NHSDigital/nrl-consumer-api) |
| Lambda Pipeline Package | Source code for the lambda pipeline utility | [GitHub repo](https://github.com/NHSDigital/nrlf-lambda-pipeline) |
| Lambda Logging Package | Source code for the lambda logging utility | [GitHub repo](https://github.com/NHSDigital/nrlf-lambda-logging) |
We currently don't have any open source client libraries or sample code for this API. If you think this would be useful, you can [upvote the suggestion on our Interactive Product Backlog](https://nhs-digital-api-management.featureupvote.com/suggestions/107439/client-libraries-and-reference-implementations).
The source code for the PDS FHIR back end (the Core Spine source code) is not currently in the open. If you think this would be useful, you can [upvote the suggestion on our Interactive Product Backlog](https://nhs-digital-api-management.featureupvote.com/suggestions/466692/open-source-core-spine-including-pds-eps-scr-and-more).
## Environments and testing
| Environment | Base URL |
| ----------------- | ---------------------------------------------------------------------- |
| Sandbox | `https://sandbox.api.service.nhs.uk/record-locator/consumer/FHIR/R4/` |
| Integration test | `https://int.api.service.nhs.uk/record-locator/consumer/FHIR/R4/` |
| Production | `https://api.service.nhs.uk/record-locator/consumer/FHIR/R4/` |
### Sandbox testing
Our [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing):
* is for early developer testing
* only covers a limited set of scenarios
* is open access, so does not allow you to test authorisation
For details of sandbox test scenarios, or to try out the sandbox using our 'Try this API' feature, see the
documentation for each endpoint.
Alternatively, you can try out the sandbox using our Postman collection:
Right click the icon and save link as... to save the Postman collection to your device
[](https://github.com/NHSDigital/NRLF/raw/main/postman_collection.json)
### Integration testing
Our [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing):
* is for formal integration testing
* includes authorisation
It also includes ready-to-use test data and scenarios. For details [contact us](https://digital.nhs.uk/developer/help-and-support).
For more details see [integration testing with our RESTful APIs](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing-with-our-restful-apis).
## Onboarding
You need to get your software approved by us before it can go live with this API. We call this onboarding. The onboarding process can sometimes be quite long, so it’s worth planning well ahead.
As part of this process, you need to demonstrate that you can manage risks and that your software conforms technically with the requirements for this API.
Information on this page might impact the design of your software. For details, see [Onboarding support information](https://digital.nhs.uk/developer/api-catalogue/national-record-locator-consumer-fhir/onboarding-support-information).
To understand how our online digital onboarding process works, see [digital onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding#using-the-digital-onboarding-portal).
<div class="nhsd-m-emphasis-box nhsd-m-emphasis-box--emphasis nhsd-!t-margin-bottom-6" aria-label="Highlighted Information">
<div class="nhsd-a-box nhsd-a-box--border-blue">
<div class="nhsd-m-emphasis-box__image-box">
<figure class="nhsd-a-image">
<picture class="nhsd-a-image__picture">
<img src="http://digital.nhs.uk/binaries/content/gallery/icons/play-circle.svg?colour=231f20" alt="" style="object-fit:fill">
</picture>
</figure>
</div>
<div class="nhsd-m-emphasis-box__content-box">
<div data-uipath="website.contentblock.emphasis.content" class="nhsd-t-word-break"><p class="nhsd-t-body">To get started, sign in or create a <a href="https://onboarding.prod.api.platform.nhs.uk/">developer account</a>, then select 'product onboarding'.</p></div>
</div>
</div>
</div>
## Change log
For details of how this API has changed over time, see the [change log](https://github.com/NHSDigital/NRLF/blob/main/CHANGELOG.md).
version: 1.0.0
license:
name: MIT
contact:
name: NHS Digital API Management
url: "https://digital.nhs.uk/developer/help-and-support"
email: [email protected]
servers:
- url: https://sandbox.api.service.nhs.uk/record-locator/consumer/FHIR/R4
description: Sandbox environment.
- url: https://int.api.service.nhs.uk/record-locator/consumer/FHIR/R4
description: Integration test environment.
- url: https://api.service.nhs.uk/record-locator/consumer/FHIR/R4
description: Production environment.
paths:
/DocumentReference:
get:
summary: Retrieve patient's document pointers (GET)
operationId: searchDocumentReference
parameters:
- $ref: "#/components/parameters/subject"
- $ref: "#/components/parameters/custodian"
- $ref: "#/components/parameters/type"
- $ref: "#/components/parameters/nextPageToken"
- $ref: "#/components/parameters/odsCode"
- $ref: "#/components/parameters/odsCodeExtension"
- $ref: "#/components/parameters/requestId"
- $ref: "#/components/parameters/correlationId"
responses:
"200":
description: Successful response
content:
application/fhir+json;version=1:
schema:
$ref: "#/components/schemas/Bundle"
example:
resourceType: Bundle
type: searchset
total: 1
entry:
- resource:
resourceType: DocumentReference
id: Y05868-1634567890
meta:
profile:
- http://fhir.nhs.net/StructureDefinition/nrls-documentreference-1-0
masterIdentifier:
system: urn:ietf:rfc:3986
value: urn:oid:1.3.6.1.4.1.21367.2005.3.7
identifier:
- system: urn:ietf:rfc:3986
value: urn:oid:1.3.6.1.4.1.21367.2005.3.7.1234
status: current
docStatus: preliminary
type:
coding:
- system: http://snomed.info/sct
code: "736253002"
display: Mental health crisis plan
category:
- coding:
- system: http://loinc.org
code: 34108-1
display: Outpatient Note
subject:
identifier:
system: https://fhir.nhs.uk/Id/nhs-number
value: "4409815415"
date: "2022-12-20T09:45:41+11:00"
author:
- identifier:
value: Practitioner/A985657ZA
authenticator:
identifier:
value: Organization/Y05868
custodian:
identifier:
system: https://fhir.nhs.uk/Id/ods-organization-code
value: Y05868
description: Physical
securityLabel:
- coding:
- system: http://terminology.hl7.org/CodeSystem/v3-Confidentiality
code: V
display: very restricted
content:
- attachment:
contentType: application/pdf
language: en-US
url: https://spine-proxy.national.ncrs.nhs.uk/p1.nhs.uk/EPAACS/MentalHealthCrisisPlan.pdf
hash: 2jmj7l5rSw0yVb/vlWAYkK/YBwk=
title: Physical
creation: "2022-12-20T09:45:41+11:00"
format:
system: urn:oid:1.3.6.1.4.1.19376.1.2.3
code: urn:ihe:pcc:handp:2008
display: History and Physical Specification
context:
encounter:
- identifier:
value: Encounter/4409815415
event:
- coding:
- system: http://snomed.info/sct
code: "305625009"
display: Seen by mental health counselor
period:
start: "2022-12-20T09:00:41+11:00"
end: "2022-12-20T09:45:41+11:00"
facilityType:
coding:
- system: http://snomed.info/sct
code: "390826005"
display: Mental health caregiver support
practiceSetting:
coding:
- system: http://snomed.info/sct
code: "390826005"
display: Mental health caregiver support
sourcePatientInfo:
identifier:
value: Patient/4409815415
related:
- identifier:
system: https://fhir.nhs.uk/Id/ods-organization-code
value: MENTAL HEALTH OUTREACH
- identifier:
system: https://fhir.nhs.uk/Id/nhsSpineASID
value: "012345678910"
headers:
X-Correlation-Id:
$ref: "#/components/headers/CorrelationId"
X-Request-Id:
$ref: "#/components/headers/RequestId"
"4XX":
description: |
An error occurred as follows:
| HTTP status | Error code | Description |
| ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 400 | BAD_REQUEST | Bad Request |
| 400 | VALIDATION_ERROR | A parameter or value has resulted in a validation error |
| 401 | ACCESS_DENIED | Access Denied |
| 403 | ACCESS_DENIED | Forbidden |
| 404 | RESOURCE_NOT_FOUND | Resource not found |
| 409 | INVALID_VALUE | Invalid value |
The Error Code comes from https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1
content:
application/fhir+json;version=1:
schema:
$ref: "#/components/schemas/OperationOutcome"
example:
resourceType: OperationOutcome
issue:
- severity: error
code: value
details:
coding:
- system: "https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1"
version: "1"
code: VALIDATION_ERROR
display: A parameter or value has resulted in a validation error
diagnostics: "The requested document pointer cannot be read because it belongs to another organisation"
description: |
Retrieve the document pointers for a single patient. Your request is constrained by the document pointer types
agreed during onboarding. The results can also be filtered to return documents by a given `type` and/or created
by a given producer (`custodian`).
This operation is also available as a http POST, which is the preferred method (see below).
/DocumentReference/_search:
post:
summary: Retrieve patient's document pointers (POST)
operationId: searchPostDocumentReference
parameters:
- $ref: "#/components/parameters/odsCode"
- $ref: "#/components/parameters/requestId"
- $ref: "#/components/parameters/correlationId"
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/RequestParams"
responses:
"200":
description: Search successful response
content:
application/fhir+json;version=1:
schema:
$ref: "#/components/schemas/Bundle"
example:
resourceType: Bundle
type: searchset
total: 1
entry:
- resource:
resourceType: DocumentReference
id: Y05868-1234567895
meta:
profile:
- http://fhir.nhs.net/StructureDefinition/nrls-documentreference-1-0
masterIdentifier:
system: urn:ietf:rfc:3986
value: urn:oid:1.3.6.1.4.1.21367.2005.3.9
identifier:
- system: urn:ietf:rfc:3986
value: urn:oid:1.3.6.1.4.1.21367.2005.3.7.1239
status: current
docStatus: final
type:
coding:
- system: http://snomed.info/sct
code: "736253002"
display: Mental Health Crisis Plan
category:
- coding:
- system: http://loinc.org
code: 55112-7
display: Document summary
subject:
identifier:
system: https://fhir.nhs.uk/Id/nhs-number
value: "4409815415"
date: "2022-12-21T10:45:41+11:00"
author:
- identifier:
value: Practitioner/A985657ZA
authenticator:
identifier:
value: Organization/Y05868
custodian:
identifier:
system: https://fhir.nhs.uk/Id/ods-organization-code
value: Y05868
description: Physical
securityLabel:
- coding:
- system: http://terminology.hl7.org/CodeSystem/v3-Confidentiality
code: V
display: very restricted
content:
- attachment:
contentType: application/pdf
language: en-US
url: https://spine-proxy.national.ncrs.nhs.uk/p1.nhs.uk/EPAACS/EOLSummaryReport.pdf
size: 4000
hash: 2jmj7l5rSw0yVb/vlWAYkK/YBwk=
title: Physical
creation: "2021-12-21T10:45:41+11:00"
format:
system: urn:oid:1.3.6.1.4.1.19376.1.2.3
code: urn:ihe:pcc:cm:2008
display: Care Management
context:
encounter:
- identifier:
value: Encounter/4409815415
event:
- coding:
- system: http://snomed.info/sct
code: "861421000000109"
display: End of life care coordination summary
period:
start: "2022-12-21T09:00:41+11:00"
end: "2022-12-21T10:45:41+11:00"
facilityType:
coding:
- system: http://snomed.info/sct
code: "14866005"
display: Hospital outpatient mental health center
sourcePatientInfo:
identifier:
value: Patient/4409815415
related:
- identifier:
system: https://fhir.nhs.uk/Id/ods-organization-code
value: TRAFFORD GENERAL HOSPITAL
- identifier:
system: https://fhir.nhs.uk/Id/nhsSpineASID
value: "012345678910"
headers:
X-Correlation-Id:
$ref: "#/components/headers/CorrelationId"
X-Request-Id:
$ref: "#/components/headers/RequestId"
"4XX":
description: |
An error occurred as follows:
| HTTP status | Error code | Description |
| ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 400 | BAD_REQUEST | Bad Request |
| 400 | VALIDATION_ERROR | A parameter or value has resulted in a validation error |
| 401 | ACCESS_DENIED | Access Denied |
| 403 | ACCESS_DENIED | Forbidden |
| 403 | ACCESS_DENIED_LEVEL | Access has been denied because you need higher level permissions |
| 404 | RESOURCE_NOT_FOUND | Resource not found |
| 409 | INVALID_VALUE | Invalid value |
The Error Code comes from https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1
content:
application/fhir+json;version=1:
schema:
$ref: "#/components/schemas/OperationOutcome"
example:
resourceType: OperationOutcome
issue:
- severity: error
code: value
details:
coding:
- system: "https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1"
version: "1"
code: VALIDATION_ERROR
display: A parameter or value has resulted in a validation error
diagnostics: "The requested document pointer cannot be read because it belongs to another organisation"
description: |
Retrieve the document pointers for a single patient. Your request is constrained by the document pointer types
agreed during onboarding. The results can also be filtered to return documents by a given `type` and/or created
by a given `custodian`.
This operation is also available as a http GET for convenience (see above), but POST is preferred for the
following reasons.
* query string parameters are visible on the network and in logs, and may have privacy implications for consumers.
* GET operations can be cached by intermediary network infrastructure, such as CDNs, routers and proxies.
* URLs have a maximum length of 2,048 characters which complex searches can exceed. NRL does not currently
exceed this limit, but may evolve in the future.
/DocumentReference/{id}:
get:
summary: Get a single document pointer
operationId: readDocumentReference
parameters:
- $ref: "#/components/parameters/id"
- $ref: "#/components/parameters/odsCode"
- $ref: "#/components/parameters/odsCodeExtension"
- $ref: "#/components/parameters/requestId"
- $ref: "#/components/parameters/correlationId"
responses:
"200":
description: Search successful response
content:
application/fhir+json;version=1:
schema:
$ref: "#/components/schemas/DocumentReference"
example:
resourceType: DocumentReference
id: Y05868-1234567892
status: current
docStatus: final
type:
coding:
- system: http://snomed.info/sct
code: "887701000000100"
display: Emergency health care plan
category:
- coding:
- system: http://loinc.org
code: 68552-9
display: Emergency medicine Emergency department Admission evaluation note
subject:
identifier:
system: https://fhir.nhs.uk/Id/nhs-number
value: "4409815415"
date: "2022-12-22T11:45:41+11:00"
author:
- identifier:
value: Practitioner/A985657ZA
authenticator:
identifier:
value: Organization/Y05868
custodian:
identifier:
system: https://fhir.nhs.uk/Id/ods-organization-code
value: Y05868
securityLabel:
- coding:
- system: http://terminology.hl7.org/CodeSystem/v3-Confidentiality
code: V
display: very restricted
content:
- attachment:
contentType: application/pdf
language: en-US
url: https://spine-proxy.national.ncrs.nhs.uk/p1.nhs.uk/EPAACS/EmergencyHealthPlan.pdf
creation: "2022-12-22T09:45:41+11:00"
format:
system: urn:oid:1.3.6.1.4.1.19376.1.2.3
code: urn:ihe:pcc:handp:2008
display: History and Physical Specification
context:
encounter:
- identifier:
value: Encounter/4409815415
event:
- coding:
- system: http://snomed.info/sct
code: "702779007"
display: Emergency health care plan agreed
period:
start: "2022-12-20T09:00:41+11:00"
end: "2022-12-20T09:45:41+11:00"
facilityType:
coding:
- system: http://snomed.info/sct
code: "453121000124107"
display: Emergency department healthcare professional
related:
- identifier:
system: https://fhir.nhs.uk/Id/ods-organization-code
value: EMERGENCY DEPT PRIMARY CARE STREAMING
- identifier:
system: https://fhir.nhs.uk/Id/nhsSpineASID
value: "012345678910"
headers:
X-Correlation-Id:
$ref: "#/components/headers/CorrelationId"
X-Request-Id:
$ref: "#/components/headers/RequestId"
"4XX":
description: |
An error occurred as follows:
| HTTP status | Error code | Description |
| ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 400 | BAD_REQUEST | Bad Request |
| 400 | VALIDATION_ERROR | A parameter or value has resulted in a validation error |
| 401 | ACCESS_DENIED | Access Denied |
| 403 | ACCESS_DENIED | Forbidden |
| 404 | RESOURCE_NOT_FOUND | Resource not found |
| 409 | INVALID_VALUE | Invalid value |
The Error Code comes from https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1
content:
application/fhir+json;version=1:
schema:
$ref: "#/components/schemas/OperationOutcome"
example:
resourceType: OperationOutcome
issue:
- severity: error
code: value
details:
coding:
- system: "https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1"
version: "1"
code: VALIDATION_ERROR
display: A parameter or value has resulted in a validation error
diagnostics: "The requested document pointer cannot be read because it belongs to another organisation"
description: |
Read a single document pointer by specifying the `DocumentReference.id`. Note that you will only be able to
retrieve document pointers that have the `type` that was agreed during the [onboarding](#api-description__onboarding) process.
/DocumentReference/_count:
get:
summary: Count document pointers
operationId: countDocumentReference
parameters:
- $ref: "#/components/parameters/subject"
- $ref: "#/components/parameters/odsCode"
- $ref: "#/components/parameters/odsCodeExtension"
- $ref: "#/components/parameters/requestId"
- $ref: "#/components/parameters/correlationId"
responses:
"4XX":
description: |
An error occurred as follows:
| HTTP status | Error code | Description |
| ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 400 | BAD_REQUEST | Bad Request |
| 400 | VALIDATION_ERROR | A parameter or value has resulted in a validation error |
| 401 | ACCESS_DENIED | Access Denied |
| 403 | ACCESS_DENIED | Forbidden |
The Error Code comes from https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1
content:
application/fhir+json;version=1:
schema:
$ref: "#/components/schemas/OperationOutcome"
example:
resourceType: OperationOutcome
issue:
- severity: error
code: value
details:
coding:
- system: "https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1"
version: "1"
code: VALIDATION_ERROR
display: A parameter or value has resulted in a validation error
diagnostics: "The requested document pointer cannot be read because it belongs to another organisation"
"200":
description: Count DocumentReference operation successful
headers:
X-Correlation-Id:
$ref: "#/components/headers/CorrelationId"
X-Request-Id:
$ref: "#/components/headers/RequestId"
content:
application/fhir+json;version=1:
schema:
$ref: "#/components/schemas/Bundle"
components:
requestBodies:
DocumentReference:
content:
application/fhir+json;version=1:
schema:
$ref: "#/components/schemas/DocumentReference"
required: true
schemas:
OperationOutcome:
type: object
properties:
resourceType:
type: string
enum:
- OperationOutcome
id:
type: string
pattern: "[A-Za-z0-9\\-\\.]{1,64}"
description: The logical id of the resource, as used in the URL for the resource. Once assigned, this value never changes.
meta:
$ref: "#/components/schemas/Meta"
description: The metadata about the resource. This is content that is maintained by the infrastructure. Changes to the content might not always be associated with version changes to the resource.
implicitRules:
type: string
pattern: \S*
description: A reference to a set of rules that were followed when the resource was constructed, and which must be understood when processing the content. Often, this is a reference to an implementation guide that defines the special rules along with other profiles etc.
language:
type: string
pattern: "[^\\s]+(\\s[^\\s]+)*"
description: The base language in which the resource is written.
text:
$ref: "#/components/schemas/Narrative"
description: A human–readable narrative that contains a summary of the resource and can be used to represent the content of the resource to a human. The narrative need not encode all the structured data, but is required to contain sufficient detail to make it "clinically safe" for a human to just read the narrative. Resource definitions may define what content should be represented in the narrative to ensure clinical safety.
issue:
type: array
items:
$ref: "#/components/schemas/OperationOutcomeIssue"
description: An error, warning, or information message that results from a system action.
minItems: 1
required:
- resourceType
- issue
OperationOutcomeIssue:
type: object
properties:
id:
type: string
pattern: "[A-Za-z0-9\\-\\.]{1,64}"
description: Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.
severity:
type: string
pattern: "[^\\s]+(\\s[^\\s]+)*"
description: Indicates whether the issue indicates a variation from successful processing.
code:
type: string
pattern: "[^\\s]+(\\s[^\\s]+)*"
description: Describes the type of the issue. The system that creates an OperationOutcome SHALL choose the most applicable code from the IssueType value set, and may additional provide its own code for the error in the details element.
details:
$ref: "#/components/schemas/CodeableConcept"
description: Additional details about the error. This may be a text description of the error or a system code that identifies the error.
diagnostics:
type: string
pattern: "[ \\r\\n\\t\\S]+"
description: Additional diagnostic information about the issue.
location:
type: array
items:
type: string
pattern: "[ \\r\\n\\t\\S]+"
description: "This element is deprecated because it is XML specific. It is replaced by issue.expression, which is format independent, and simpler to parse. \n\nFor resource issues, this will be a simple XPath limited to element names, repetition indicators and the default child accessor that identifies one of the elements in the resource that caused this issue to be raised. For HTTP errors, will be \"http.\" + the parameter name."
expression:
type: array
items:
type: string
pattern: "[ \\r\\n\\t\\S]+"
description: A [simple subset of FHIRPath](fhirpath.html#simple) limited to element names, repetition indicators and the default child accessor that identifies one of the elements in the resource that caused this issue to be raised.
required:
- severity
- code
DocumentReference:
type: object
properties:
resourceType:
type: string
enum:
- DocumentReference
id:
type: string
pattern: "[A-Za-z0-9\\-\\.]{1,64}"
description: The logical id of the resource, as used in the URL for the resource. Once assigned, this value never changes.
meta:
$ref: "#/components/schemas/Meta"
description: The metadata about the resource. This is content that is maintained by the infrastructure. Changes to the content might not always be associated with version changes to the resource.
implicitRules:
type: string
pattern: \S*
description: A reference to a set of rules that were followed when the resource was constructed, and which must be understood when processing the content. Often, this is a reference to an implementation guide that defines the special rules along with other profiles etc.
language:
type: string
pattern: "[^\\s]+(\\s[^\\s]+)*"
description: The base language in which the resource is written.
text:
$ref: "#/components/schemas/Narrative"
description: A human–readable narrative that contains a summary of the resource and can be used to represent the content of the resource to a human. The narrative need not encode all the structured data, but is required to contain sufficient detail to make it "clinically safe" for a human to just read the narrative. Resource definitions may define what content should be represented in the narrative to ensure clinical safety.
masterIdentifier:
$ref: "#/components/schemas/Identifier"
description: Document identifier as assigned by the source of the document. This identifier is specific to this version of the document. This unique identifier may be used elsewhere to identify this version of the document.
identifier:
type: array
items:
$ref: "#/components/schemas/Identifier"
description: Other identifiers associated with the document, including version independent identifiers.
status:
type: string
pattern: "[^\\s]+(\\s[^\\s]+)*"
description: The status of this document reference.
docStatus:
type: string
pattern: "[^\\s]+(\\s[^\\s]+)*"
description: The status of the underlying document.
type:
$ref: "#/components/schemas/CodeableConcept"
description: Specifies the particular kind of document referenced (e.g. History and Physical, Discharge Summary, Progress Note). This usually equates to the purpose of making the document referenced.
category:
type: array
items:
$ref: "#/components/schemas/CodeableConcept"
description: A categorization for the type of document referenced – helps for indexing and searching. This may be implied by or derived from the code specified in the DocumentReference.type.
subject:
$ref: "#/components/schemas/Reference"
description: Who or what the document is about. The document can be about a person, (patient or healthcare practitioner), a device (e.g. a machine) or even a group of subjects (such as a document about a herd of farm animals, or a set of patients that share a common exposure).
date:
type: string
pattern: ([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-9]000)-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])T([01][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))
description: When the document reference was created.
author:
type: array
items:
$ref: "#/components/schemas/Reference"
description: Identifies who is responsible for adding the information to the document.
authenticator:
$ref: "#/components/schemas/Reference"
description: Which person or organization authenticates that this document is valid.
custodian:
$ref: "#/components/schemas/Reference"
description: Identifies the organization or group who is responsible for ongoing maintenance of and access to the document.
relatesTo:
type: array
items:
$ref: "#/components/schemas/DocumentReferenceRelatesTo"
description: Relationships that this document has with other document references that already exist.
description:
type: string
pattern: "[ \\r\\n\\t\\S]+"
description: Human–readable description of the source document.
securityLabel:
type: array
items:
$ref: "#/components/schemas/CodeableConcept"
description: A set of Security–Tag codes specifying the level of privacy/security of the Document. Note that DocumentReference.meta.security contains the security labels of the "reference" to the document, while DocumentReference.securityLabel contains a snapshot of the security labels on the document the reference refers to.
content:
type: array
items:
$ref: "#/components/schemas/DocumentReferenceContent"
description: The document and format referenced. There may be multiple content element repetitions, each with a different format.
minItems: 1
context:
$ref: "#/components/schemas/DocumentReferenceContext"
description: The clinical context in which the document was prepared.
required:
- resourceType
- status
- content
Bundle:
type: object
properties:
resourceType:
type: string
enum:
- Bundle
id:
type: string
pattern: "[A-Za-z0-9\\-\\.]{1,64}"
description: The logical id of the resource, as used in the URL for the resource. Once assigned, this value never changes.
meta:
$ref: "#/components/schemas/Meta"
description: The metadata about the resource. This is content that is maintained by the infrastructure. Changes to the content might not always be associated with version changes to the resource.
implicitRules:
type: string
pattern: \S*
description: A reference to a set of rules that were followed when the resource was constructed, and which must be understood when processing the content. Often, this is a reference to an implementation guide that defines the special rules along with other profiles etc.
language:
type: string
pattern: "[^\\s]+(\\s[^\\s]+)*"
description: The base language in which the resource is written.
identifier:
$ref: "#/components/schemas/Identifier"
description: A persistent identifier for the bundle that won't change as a bundle is copied from server to server.
type:
type: string
pattern: "[^\\s]+(\\s[^\\s]+)*"
description: Indicates the purpose of this bundle – how it is intended to be used.
timestamp:
type: string
pattern: ([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-9]000)-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])T([01][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))
description: The date/time that the bundle was assembled – i.e. when the resources were placed in the bundle.
total:
type: integer
format: int32
description: If a set of search matches, this is the total number of entries of type 'match' across all pages in the search. It does not include search.mode = 'include' or 'outcome' entries and it does not provide a count of the number of entries in the Bundle.
link:
type: array
items:
$ref: "#/components/schemas/BundleLink"
description: A series of links that provide context to this bundle.
entry:
type: array
items:
$ref: "#/components/schemas/BundleEntry"
description: An entry in a bundle resource – will either contain a resource or information about a resource (transactions and history only).
signature:
$ref: "#/components/schemas/Signature"
description: Digital Signature – base64 encoded. XML–DSig or a JWT.
required:
- resourceType
- type
BundleEntry:
type: object
properties:
id:
type: string
pattern: "[A-Za-z0-9\\-\\.]{1,64}"
description: Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.
link:
type: array
items:
$ref: "#/components/schemas/BundleLink"
description: A series of links that provide context to this entry.
fullUrl:
type: string
pattern: \S*
description: "The Absolute URL for the resource. The fullUrl SHALL NOT disagree with the id in the resource – i.e. if the fullUrl is not a urn:uuid, the URL shall be version–independent URL consistent with the Resource.id. The fullUrl is a version independent reference to the resource. The fullUrl element SHALL have a value except that: \n* fullUrl can be empty on a POST (although it does not need to when specifying a temporary id for reference in the bundle)\n* Results from operations might involve resources that are not identified."
resource:
$ref: "#/components/schemas/DocumentReference"
description: The Resource for the entry. The purpose/meaning of the resource is determined by the Bundle.type.
search:
$ref: "#/components/schemas/BundleEntrySearch"
description: Information about the search process that lead to the creation of this entry.
request:
$ref: "#/components/schemas/BundleEntryRequest"
description: Additional information about how this entry should be processed as part of a transaction or batch. For history, it shows how the entry was processed to create the version contained in the entry.
response:
$ref: "#/components/schemas/BundleEntryResponse"
description: Indicates the results of processing the corresponding 'request' entry in the batch or transaction being responded to or what the results of an operation where when returning history.
BundleEntryResponse:
type: object
properties:
id:
type: string
pattern: "[A-Za-z0-9\\-\\.]{1,64}"
description: Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.
status:
type: string
pattern: "[ \\r\\n\\t\\S]+"