--- title: "Create new or update existing document pointer" method: POST path: "/DocumentReference" tags: ["DocumentReference"] --- # Create new or update existing document pointer `POST /DocumentReference` Create new pointers. To create a document pointer you must ensure: * the body must be a valid [FHIR R4 DocumentReference](http://hl7.org/fhir/documentreference.html) * `subject` MUST be a `Patient` reference using a valid NHS number. e.g. ```json "subject": { "identifier": { "system": "https://fhir.nhs.uk/Id/nhs-number", "value": "3495456481" } }, ``` * `custodian` MUST contain an `Organization` reference using a valid ODS code, agreed during onboarding. e.g. ```json "custodian": { "identifier": { "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "Y05868" } } ``` * `type` MUST match one of the Document Types defined for BaRS, this is either a Appointment (booking) or a Patient referral. ```json "type": { "coding": [ { "system": "http://snomed.info/sct", "code": "749001000000101", "display": "Appointment (record artifact)" } ] } ``` * `category` MUST indicate the broader class of the Document Type as agreed during onboarding, e.g. ```json "category": [ { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/document-reference-category", "code": "clinical", "display": "Clinical" } ] } ] ``` * `content` MUST have at least one entry. * `content[].format[]` SHOULD indicate the document is structured or not, e.g. ```json "format": [ { "system": "https://fhir.nhs.uk/England/CodeSystem/England-NRLFormatCode", "code": "urn:nhs-ic:structured", "display": "Structured Document" } ] ``` * `content[].attachment.url` MUST contain the direct URL, e.g. ```json "attachment": { "url": "https://server.fire.ly/r4/Appointment/GL0-DZOqD39" } ``` * `author` SHOULD contain an `Organization` reference using a valid ODS code, agreed during onboarding. e.g. ```json "author": [ { "identifier": { "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "Y05868" } } ] ``` * `context.period` SHOULD indicate Appointment date and time, e.g. ```json "context": { "period": { "start": "2025-02-01T06:45:00+00:00", "end": "2025-02-01T07:00:00+00:00" }, ``` * `identifier.[]` MUST contain the correct identifiers for BaRS including service-id AND product-id, e.g. ```json { "system": "https://fhir.nhs.uk/Id/BaRS-Identifier", "value": "GL0-DZOqD39" }, { "system": "https://fhir.nhs.uk/Id/dos-service-id", "value": "2000072491" }, { "system": "https://fhir.nhs.uk/id/product-id", "value": "P.GH7-4TY" } ``` ## Headers - `X-Request-Id` string, uuid, required - `X-Correlation-Id` string, uuid, required - `Accept` string, required - `use-context` string, required ## Response `201` Create / Supersede successful response ## Other responses - `4XX` — Below are examples of potential HTTP status codes and their associated error codes, which could be returned in the event of a fault. Guidance on error handling within BaRS can be found [here](https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Core/1-5-0/Error-Handling). | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 400 | SEND_BAD_REQUEST | The API was unable to process the request. | | 400 | REC_BAD_REQUEST | The Receiver has responded stating the message was malformed. | | 401 | SEND_UNAUTHORIZED | The API deemed you unauthorized to make this request. | | 401 | REC_UNAUTHORIZED | The receiver deemed you unauthorized to make request. | | 403 | SEND_FORBIDDEN | Missing or Expired Token. | | 404 | PROXY_NOT_FOUND | No related people exist for given NHS number. | | 404 | REC_NOT_FOUND | Patient record for given NHS number has been invalidated and not superseded by another NHS number. | | 405 | SEND_METHOD_NOT_ALLOWED | HTTP Verb is not correct for this scenario.| | 405 | REC_METHOD_NOT_ALLOWED | Receiver does not allow this.| | 405 | PROXY_METHOD_NOT_ALLOWED | Proxy does not allow this.| | 406 | SEND_NOT_ACCEPTABLE | Senders message had an incorrect content type defined for a response.| | 408 | REC_TIMEOUT | The downstream domain processing has not completed within the configured timeout period. | | 409 | SEND_CONFLICT | | | 409 | REC_CONFLICT | | | 409 | PROXY_CONFLICT | | | 422 | SEND_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. | | 422 | REC_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. | | 422 | PROXY_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. | | 429 | SEND_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time| | 429 | REC_TOO_MANY_REQUESTS | The user has sent too many requests in a given amount of time| - `5XX` — Below are examples of potential HTTP status codes and their associated error codes, which could be returned in the event of a fault. Guidance on error handling within BaRS can be found [here](https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Core/1-5-0/Error-Handling). | HTTP status | Error code | Description | | ----------- | -------------------------- | --------------------------------------------- | | 500 | REC_SERVER_ERROR | The receiver server has encountered an Error processing the request. | | 500 | PROXY_SERVER_ERROR | Proxy Error. | | 501 | SEND_NOT_IMPLEMENTED | The Request was not recognized. | | 501 | REC_NOT_IMPLEMENTED | The Receiver did not recognize the request. | | 501 | PROXY_NOT_IMPLEMENTED | The Proxy did not recognize the request. | | 503 | REC_UNAVAILABLE | The Receiver was unavailable to service the request.| | 503 | PROXY_UNAVAILABLE | The Proxy was unavailable to service the request. | --- [API](https://skmtc.net/nhs/apis/booking-and-referral-api.md) · [All operations](https://skmtc.net/nhs/apis/booking-and-referral-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nhs/booking-and-referral-api/revisions/560941e2db70/schema)