validated-relationships-service-api.yaml

# This is an OpenAPI Specification (https://swagger.io/specification/)
# for validated-relationships owned by NHS Digital (https://digital.nhs.uk/)
openapi: "3.0.0"
info:
  title: "Validated Relationships Service API"
  version: "1.20.0"
  description: |
    ## Overview
    This service underpins the National Proxy Programme whose core objective is to allow Patients to be supported with
    their healthcare by someone they trust (a Proxy) as part of a digitally-enabled journey. The service has two core
    uses. Firstly, it surfaces verified candidate relationships (i.e. indicates suitable Proxies for a Patient such as
    Birth Mothers) to support GP’s decision-making when granting Proxy access. Secondly, it supports the subsequent
    creation, use and management of Proxy roles which are stored in a central, national database. The Proxy roles held
    by the database are strictly for the purpose of enabling access to healthcare services, initially in Primary Care.

    With this service you can:

    - Create a new Proxy access request (Submit an online application via NHS App)
    - View Pending Proxy access requests
    - Get verified candidate relationships (to support decision making when granting proxy access)
    - Create a Proxy role
    - Get Proxy roles
    - Get a Proxy role by ID
    - Update (or revoke) a Proxy role

    ## Who can use this API
    This API can only be used where there is a legal basis to do so. Make sure you have this and a valid use case before
    you go too far with your development by [contacting us](https://digital.nhs.uk/developer/help-and-support).

    You must do this before you can go live (see the 'Onboarding' section below).

    ## Related APIs
    The following APIs are related to this API:

    - [Personal Demographics Service - FHIR API](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir) - we use the data held in PDS as a source of data to verify relationships.

    ## API status and roadmap
    This API is [in production, beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses), meaning:
    - we might make breaking changes, but only if we cannot avoid it, and we will give advance notice

    ## Service level
    This API is a bronze service, meaning it is operational and supported only during business hours (8am to 6pm), Monday to Friday excluding bank holidays.

    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 are built against [FHIR UK Core](https://digital.nhs.uk/services/fhir-uk-core), specifically [UK.core.r4 1.0.0](https://simplifier.net/packages/uk.core.r4/1.0.0).

    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, for example `/RelatedPerson` not `/relatedpersons`
    - array names are singular, for example `name` not `names` for the recorded names of a patient

    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.

    ## Guidance for developers

    Supplementary documentation and guidance for developers:

    - National Proxy Service developer documentation (link to be added)

    ## Network access
    This API is available on the internet.

    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 supports both [user-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis) and [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis) access types with the following access modes:

    | Access mode                   | Access type            |
    |-------------------------------|------------------------|
    | Patient access                | User-restricted        |
    | Healthcare worker access      | User-restricted        |
    | Application-restricted access | Application-restricted |

    For more information on access modes and how to use them, see the developer [security and authorisation guide](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation).

    Each API operation section of this documentation indicates the access modes that the endpoint supports.

    ### User-restricted access

    User-restricted access meaning an end user must be present, authenticated and authorised.

    #### Patient access mode
    If the end user is a patient then you must use this access mode.

    [Review all patient access modes](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#patient-access-mode)

    All API endpoints that support this access mode require that the user has proven their identity to a high level
    and authenticated using strong authentication credentials. The combination of these forms a [Vector of Trust](https://nhsconnect.github.io/nhslogin/vectors-of-trust/) profile.

    Allowed vectors of trust are:
    - `P9.Cp.Cd`
    - `P9.Cp.Ck`
    - `P9.Cm`

    #### Healthcare worker access mode
    If the end user is a healthcare worker then you must use this access mode. All API endpoints that support this
    access mode require that the user has been authenticated with a "very high confidence" authenticator ([AAL3](https://digital.nhs.uk/services/care-identity-service/applications-and-services/cis2-authentication/integrate/design-and-build/authenticator-guidance-for-developers)).

    [Review all CIS2 healthcare worker access modes](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#healthcare-worker-access-mode)

    ### Application-restricted access

    This API is application-restricted, meaning we authenticate the calling application but not the end user. This
    should only be utilised where user-restrcited access modes are not feasible or practical.

    [Review all application-restricted access modes](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis)

    ## Headers
    This API is case-insensitive when processing request headers, meaning it will accept headers regardless of the letter casing used. (e.g. X-Request-Id, x-request-id are treated the same). When sending headers back in the response, we preserve the exact casing as received in the original request.

    ## 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 Operations section. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more information 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                                                                                                                                                          |
    | -------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Validated Relationships FHIR API | Source code for the API proxy, sandbox and specification.                                                    | [GitHub repo](https://github.com/NHSDigital/validated-relationships-service-api)                                                                               |
    | FHIR libraries and SDKs          | Various open source libraries for integrating with FHIR APIs.                                                | [FHIR libraries and SDKs](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks)                   |
    | nhs-number                       | Python package containing utilities for NHS numbers including validity checks, normalisation and generation. | [GitHub repo](https://github.com/uk-fci/nhs-number) \| [Python Package index](https://pypi.org/project/nhs-number/) \| [Docs](https://nhs-number.uk-fci.tech/) |

    We currently don't have any open source client libraries or sample code for this API and the source code for the Validated Relationship Service FHIR application is not currently in the open. If you think this would be useful, [contact us](https://digital.nhs.uk/developer/help-and-support).

    ## Environments and testing
    | Environment       | Base URL                                                                             |
    | ----------------- | ------------------------------------------------------------------------------------ |
    | Sandbox           | `https://sandbox.api.service.nhs.uk/validated-relationships/FHIR/R4/`                |
    | Integration test  | `https://int.api.service.nhs.uk/validated-relationships/FHIR/R4/`                    |
    | Production        | `https://api.service.nhs.uk/validated-relationships/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

    [![Import Postman Collection](https://img.shields.io/badge/Import-Postman%20Collection-orange?logo=postman)](https://raw.githubusercontent.com/NHSDigital/validated-relationships-service-api/master/postman/validated_relationship_service.sandbox.postman_collection.json)

    Import the  postman collection to run requests against sandbox.

    ### Integration testing

    Our [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing)

    * is for formal integration testing
    * requires authorisation using a supported access mode

    [<img src="https://run.pstmn.io/button.svg" alt="Run In Postman" style="width: 128px; height: 32px;">](https://app.getpostman.com/run-collection/50544839-b6783b4e-de59-42c6-a80e-72cf64fa5ec9?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D50544839-b6783b4e-de59-42c6-a80e-72cf64fa5ec9%26entityType%3Dcollection%26workspaceId%3D082e43b8-9a51-4a16-af66-0d2b233cd69c#?env%5BINT%5D=W3sia2V5IjoiY2lzMl90b2tlbiIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6InNlY3JldCIsInNlc3Npb25WYWx1ZSI6InFNQnZnNVVId0kxc3k3UWx4WUtQc1VxekZoQXIiLCJjb21wbGV0ZVNlc3Npb25WYWx1ZSI6InFNQnZnNVVId0kxc3k3UWx4WUtQc1VxekZoQXIiLCJzZXNzaW9uSW5kZXgiOjB9LHsia2V5IjoibG9naW5fdG9rZW4iLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJzZWNyZXQiLCJzZXNzaW9uVmFsdWUiOiJqOXcxNUxMa1VjbWtzOU15c0FHbGpmTW9LMGdGIiwiY29tcGxldGVTZXNzaW9uVmFsdWUiOiJqOXcxNUxMa1VjbWtzOU15c0FHbGpmTW9LMGdGIiwic2Vzc2lvbkluZGV4IjoxfSx7ImtleSI6ImFwaV9iYXNlX3VybCIsInZhbHVlIjoiaHR0cHM6Ly9pbnQuYXBpLnNlcnZpY2UubmhzLnVrL3ZhbGlkYXRlZC1yZWxhdGlvbnNoaXBzL0ZISVIvUjQiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCIsInNlc3Npb25WYWx1ZSI6Imh0dHBzOi8vaW50LmFwaS5zZXJ2aWNlLm5ocy51ay92YWxpZGF0ZWQtcmVsYXRpb25zaGlwcy9GSElSL1I0IiwiY29tcGxldGVTZXNzaW9uVmFsdWUiOiJodHRwczovL2ludC5hcGkuc2VydmljZS5uaHMudWsvdmFsaWRhdGVkLXJlbGF0aW9uc2hpcHMvRkhJUi9SNCIsInNlc3Npb25JbmRleCI6Mn0seyJrZXkiOiJ2cnNfYXBpX3ByaXZhdGVfa2V5IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoic2VjcmV0Iiwic2Vzc2lvblZhbHVlIjoiLS0tLS1CRUdJTiBQUklWQVRFLi4uIiwiY29tcGxldGVTZXNzaW9uVmFsdWUiOiItLS0tLUJFR0lOIFBSSVZBVEUgS0VZLS0tLS1cXG5NSUlKUVFJQkFEQU5CZ2txaGtpRzl3MEJBUUVGQUFTQ0NTc3dnZ2tuQWdFQUFvSUNBUURVMDhhUGJWckxRR0R3XFxuTGE2NlNYeVNzc1hTZ0VWa3V5cW9XVGJGbWVlV0ZVaWx5d0xLMGp1aTRpcjI5V1VadWpqNmt0NWg5MFdaMER5Slxcbml3SU9lOWJQdVlnbXR2am9RY2lWZ1J2UUJ4UlZYYzhJUnlveUVnV0pYZVgxUXVPVFVVWEZwT2VzZUFyOXJXeXhcXG5iVTUwek1NTFo3REtId1llUGlNZG1zaExoUGI2bWdScEdQaXpseFJDUXF6RGJxVzh0REM1YWhaYUN5UG1xYWhKXFxuYXFpSzgyQWNpbW5PL1FnZTFjd1JKMGtMU2d0ZG5tS3hGVFpvbm5WOWJJc2wwNUhrczM3R096S3B6ZEt0cFBZdlxcbmFCaGhZVUZzY24yR3grUmxocGo2UWdSS2VwNUpDUXN1UzExbUJKM2E2ZVZDRXlZa3VOdHl0WVh4aVB2YXJYVk5cXG5VZFpIQ0tNb3pjcUpNTHpXZlVKQW9UWGtwMVJ3RURkbDVzTHlPOWxuZlhOdHZKYkx2OGhBalNJT08vY0VCOGJLXFxuVmVyV2I5bnBLMTl4cXhSRjNEdTJiOFdweW5HMEVpZ21NK0lVbkVYQjZMVUNxWWpiVjl0ejMzVDBSM1BkaHg0WFxcbkY4dktzWHY2V0NYVXlVWktNSi9BVTAyc3ZvYlltV3JwOTFEdEdidy9YZ0pFZjBhSVUySzNaTGRUNzV5RWRPWHpcXG4rK2FZNW03VjIzbEpBQjgzU3o4T1R1QW1iMkdkY3IvV2xYRUh6NG5xdms0bVBSU3pzcWFVenBXOEpyS1dBR0JMXFxuU1J0bVU4dWFIZ1kweWFoRnpINWtNNy9oa1NTQTZoeURpaDFxeTkwSjJRN0s0Q1crbE9LbmROYTZaQTh0ZVNBY1xcbm53dHB5aDBWSS9yd3A3TURuZVZ5L0x1Q1dRU0dOd0lEQVFBQkFvSUNBRTc3SElmam5Ec3JkQTROMWZiNkNJbmtcXG5ZRGVETkwxeUhCMkhwaVRrdmFYYjFpNzR6TnQ1ODNtNkZ4bTQ3Y0VEYzl2Qm4xZVp6VEdNcnJxWVpMWDlUVFdmXFxuYzZCeWJLSzhydlNVaWo3RU1jNlFWcUdLejJUdmZUQ0NNVEc0bGYzNHZqemZ1cjR0ZWw2eitrOUo4a0MwTUhuT1xcbkREU21HTDRtYngrd2JqNWdaTXVSVnF1dUFiV2NEbitjZ01LeUVEMmNYU3loNnhPVmFNaFVFOGpURlNNanVIbytcXG4vNDg2SmNaVHJ6eDZhTWdRdlhFTHN6Sm1YZCtyVm95cU9HVmNRNXNzNVpJcEs5OEtLL0lXOHVtYTV0bFVuMVBnXFxubFNic2paMER1MGU4TWgxMXJjSUs0aVJYQVowM2YyRmJSYUlrdXhZTHFCekVzcVYxSVlvQXJ6UjNkMTY3SE5qOVxcbmJCYmF4SVdPcDRBUmpzU1ByM3JDMmVNSXR2bzh4OGVjVG5pZ2llS2ViSXJVcy9xMS9BNGFiZVl6Yk9Ob1JZWGRcXG5wWUc4QTB5RVNHWGpDeUd2bXZDL1krQ0hpSmJVNXB2SkNDUU8vVHNlR21Ed0N6Nk1JTldOK3NKWlpHaU5idTJ6XFxuejJGM0ZUVlJ4VTlTOFdRV3NiZmxFMjgyWmJ5VDNYNzV1TVMzZG5ZTjNta3A1NmsvRkJkWXZmUzhTN0VtLzNOWlxcbk5kbUtuMi83QnB5ZEVaSk9RYitISHVSbWFua09YVEVmUU9aUE5SbXhFU1NWUHJEaWZMaVhLOFMyK1lvb0F2RERcXG4vandvOG1rcU5lVWNEOTlhWWthTk52NHJLaDZpRitSZmhvSm85aHFIOVFCR2swUGZ6TW5yN0w0QWFNcHRkS1duXFxuK0NLLzJuR1VXcWZtZUhZamF2TmhBb0lCQVFEc0JBSFNPaFdDQnlFQU9ZNGdub3hPZ29yeDJCOUdGT1J0TmpRK1xcbnhtMXV4Z3B5ams1RGFUKzRBQ1daRVMvdXNrYkhTV0NuVStlMXlNWjFTdFE5ZlpHcGNyVmpuZ0ZJOXRMVG13VmdcXG5zcmxwUGpWQ2lHS1QzR3MyQ0NodjZwenlidGN3U0RCVjVYbEVkTXJ2ZkVBRFBEaURCZ2Q1ck5QVUZhQjNJVDJjXFxuaVJHMlN6VDFGRWNmME1UNHg3MmQvMVFIbWhoVFowT2tMREkyc0hOODlXcjRrQ1MrUXhOWGY2WHpzUXlDWnBqK1xcbk93ZElnM3V5aVJEaHgvR213UDBVdGJzdXJSZ3dLcVVaZitpa3R3WnRHYmp6QytZWmphTU9zWDdkWTNhSFUyNDdcXG52Q29GZzltZG1nZ1d0Mzd0d1JZMGxjSnpzemIwL1c2bjAzTXBqeXJ1SE50bCtIS1JBb0lCQVFEbTJTQUhEc2xwXFxuSnZMSEJ5aEgvektmcGY1MFJSTFFCWWxvM2NGcGZsd1Bob0lyK25wbjNoRmdoY2x5MU15N214U3Q0Ulh2YjZaVVxcbm9IM2MyV2wrb2NGUWxsNStncGhyaU1ibC9RclJ4bS8wK2lmM3BRK0RjK1M1ZW1OSDdaN3hmSDA5TGdsRFFkMmpcXG5WU1V5SU56OVA2d1cwbm9vOWZna0Nucy9tQVo1QnRyWklHZE92QjhBejdZMm1oWWlSOEZNMTFqZGxLRHlvMWZVXFxuZFc0L0NXdjhLTmxnU1ZFemlMMVBNcHRPUloyYUFybTZZMTl3ZnVwa0crR1o4VEswQ0FTME5QNUFROGwyZUVaMFxcbmZhUEFvNU5RMUZzSWYxamdJVk9wY00xd1ZQVE1xSEk4Q0FRRm5uVEhFL0N1ZW9KSWFSa1drc0tCS0ZITk5jOE5cXG4wcThvSkNWQU1NQkhBb0lCQUhSd2dhbURLSXRQRXhQMlVVMThpMEpNbTFvM3d5NGpMcE5HODcyb3plS2g2Qk9lXFxuYTdSTVg3aGFzakh6VGMrWXV0eWxNZjg3b1F5SmNvZjVrLzZHVGUvb2ZOOFozQTV3WDVFd1lSWFU5eTZhRjFLc1xcbjBOMmNHSFMrejV4dmhtRUJHRDlremh3Q3E3Si9ZSU9JckZnc1JNRTNuMGFEWXJxMnRNVXhiQ0VuYXNxaURnMS9cXG5wSnRvdDFUNXptMzl3eXBBOXhGbTEvTk9MclBXbUJPbFROSTI0em5QQStMZVFqU1pPOCsxNkhNOUVoblBiSjZuXFxuaXVHcGNHcFJ1a3FXWWpQa0NCUHpaaUxQZlNxT2RhZ3IwWmh2WFdWc0FHOUdXSTNHL1hwRVNoVkVmd0xiaXVoN1xcblR0Uk9VVnZoTUNCZlptRUlvT3Q3Z1RWaFYrYkFFSEVMWVo3TVZWRUNnZ0VBZkgvakx3dEJnczEzcC9GclB4RWFcXG5LMUhwM3FrV0VVeTdJK3hkRUZrT3EyemVyWHRFSXRwNFFyZEV3d0tUZkNhU1M0aVdQUERaSXREL3NHa3M1UmUxXFxuMjVHTld1dHg2cVQwcURzRlo4ZCt2LzllS01oRGlxQ3BYWUx0SW5DOEJQOGZ5Q3dZNE1ZWUU2dXJDTk1DZkM2blxcbjBCTXB3UWVQRVZqNXlYMWpHRWlqSlBDOTVvKzhwTUpoUWlkdUFvVHljays5NUpyeEJvc2pwampEQVlwQ1M5ZDRcXG5ETjdkeFU1YzB1YTNMY3FMeWZEb1crYVdKV1M5WXNwS3JLeVJyTmlhT05wUHVUY1Y0eWZRejZpbTlSRUROVmVoXFxuMVA1aFgxZDUrR3NXMFJ0d2Z5UGxvQXl1cHAwajIrNGNJdTE5Y0RJR1RzOU55VHlHaVljWXFSclVUbkRZQ2p1QVxcbnB3S0NBUUFXeFF4V0J6TnZ4L1pNZFlQK0o3eTd3VDlTY1JYZHR5MlRpbFJ0dWxTTGpGZmx1bnRCcUF1ZTVlWTZcXG41Y0hNRGp3N09lajhmaFFXdDN2Yi9xUHBEeXdoOXRTS0hCR0JxWXRJK3NCRXY3bktqNUcvTnVWWUhYOEVuOHBvXFxuc1pTUnphL3FxeHdSTDZtaHppNDlGOEo5ZGdZWHJLUzl6OUpDaTFZRUlCVzA1Y0xpVFk5ZFZiOGZFbTByMllNOFxcbkJOZjQ1NExlNG1TWnJSTjRoMG5ETDdMZzdMTFp5eW85S1Zjc1lDSG5rQ2FGVTNNS0NlTnp5ZEY4YXpyZ2FkU29cXG5xQzMybkxiSDFZMFN5UmhFM1EzOVlDVWVGek5Zbzl3d3luemVmakZ1cHNyckNxaEFPZTFnQytRMTEyNHRGTVp1XFxuS0VIdzJBQkJFT1crTU4ydkZXcEZ5WnBlVHg5Tlxcbi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0iLCJzZXNzaW9uSW5kZXgiOjN9LHsia2V5IjoibmhzX2RldmVsb3Blcl9hY2NvdW50X2FwaV9rZXkiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJzZWNyZXQiLCJzZXNzaW9uVmFsdWUiOiI0aHdpdnBKQVpJcXZwSmxBV09jdFJYQ1NnVU1sd1p1SyIsImNvbXBsZXRlU2Vzc2lvblZhbHVlIjoiNGh3aXZwSkFaSXF2cEpsQVdPY3RSWENTZ1VNbHdadUsiLCJzZXNzaW9uSW5kZXgiOjR9LHsia2V5IjoiY29uc2VudF9hcHBfYXV0aF9oZWFkZXJfdmFsdWUiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJzZWNyZXQiLCJzZXNzaW9uVmFsdWUiOiJDU1ZjYm90QVFHYmhMcUdabjFWVEZHY1FudEFFIiwiY29tcGxldGVTZXNzaW9uVmFsdWUiOiJDU1ZjYm90QVFHYmhMcUdabjFWVEZHY1FudEFFIiwic2Vzc2lvbkluZGV4Ijo1fSx7ImtleSI6InRwcF85Njc0OTk4NTM1X2FjY2Vzc190b2tlbiIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6InNlY3JldCIsInNlc3Npb25WYWx1ZSI6IntcIkFjY291bnRJZFwiOlwiNTUyODY5ODM0XCIsXCJQYXNzcGhyYXNlXCI6XCJ2UkpxdTEzOWQ3ZHZlclpnKzhlVzd2V0ZTQ2FTbndBV0ZSNlk0dFlYalA3L3VGU2d0djdrMklPd0E0NzhPV3A3WkRxNE1CWUM2aGNUSVRFcm5Od2dieFZtN1ZaOGYzUVVuTC4uLiIsImNvbXBsZXRlU2Vzc2lvblZhbHVlIjoie1wiQWNjb3VudElkXCI6XCI1NTI4Njk4MzRcIixcIlBhc3NwaHJhc2VcIjpcInZSSnF1MTM5ZDdkdmVyWmcrOGVXN3ZXRlNDYVNud0FXRlI2WTR0WVhqUDcvdUZTZ3R2N2sySU93QTQ3OE9XcDdaRHE0TUJZQzZoY1RJVEVybk53Z2J4Vm03Vlo4ZjNRVW5MUFdoKzRLN0VQNWkvNEswQWRHWjBJSzBVdzcrQzdYWmM3RkhnOFJTY0lqaCsyTXFGN3Z1WjQ0dW1lUHZnOGVTTTQ4V1I4SzRYRT1cIixcIlByb3ZpZGVySWRcIjpcImI4OTFmYzNiNTFkNWU3YzFcIixcIkltMUNhY2hlS2V5XCI6XCJ6OEVsQ0RJM2Uxc2xXTGJac0lSVXdpaHk4V1pGc2NyMmRQbVRmVXVpK2dBcVE3WmgwV1BWSVhvL005RHVFVnpPM1hhRk9wYkIzd2M5eWhBVWhBWmhVZz09XCJ9Iiwic2Vzc2lvbkluZGV4Ijo2fSx7ImtleSI6InRwcF85Njc0OTk4NDU0X2FjY2Vzc190b2tlbiIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6InNlY3JldCIsInNlc3Npb25WYWx1ZSI6IntcIkFjY291bnRJZFwiOlwiODU4ODAzMjAzXCIsXCJQYXNzcGhyYXNlXCI6XCJKVzRIc3JXTWw0SEhNamx4OUJJVW5zUzV1QkpmcUFsWnk0L2VZbUt3a3U5VUZRL0xBQ21PR21tWGJkOG95VUZiMHY3NE14bkVmKzl6UVdPQTQ0QUtPSXQ3bEtFdlJJbzVNYy4uLiIsImNvbXBsZXRlU2Vzc2lvblZhbHVlIjoie1wiQWNjb3VudElkXCI6XCI4NTg4MDMyMDNcIixcIlBhc3NwaHJhc2VcIjpcIkpXNEhzcldNbDRISE1qbHg5QklVbnNTNXVCSmZxQWxaeTQvZVltS3drdTlVRlEvTEFDbU9HbW1YYmQ4b3lVRmIwdjc0TXhuRWYrOXpRV09BNDRBS09JdDdsS0V2UklvNU1jQjVOanZaTkJCaWhMTE82N09xNm9KY0x5bHpDRzFaZUhqTEl4MTJrUnQwblZEc3ZqQ2IyMTZuRm5EYk9mNWkxQWFYbXBTdFVIY1xcdTAwM2RcIixcIlByb3ZpZGVySWRcIjpcImI4OTFmYzNiNTFkNWU3YzFcIixcIkltMUNhY2hlS2V5XCI6XCJrMFlPWVdzVHRteGdrVlpTWXA1YXkraEd6eUYyWUhTcEE2YnpxQTZHODdiOWtxbitHTy9XQ3E0RFRiQ2RISGhkUmZCRVhhZThUU2hHa2lpOEt1Qnd3QVxcdTAwM2RcXHUwMDNkXCJ9Iiwic2Vzc2lvbkluZGV4Ijo3fSx7ImtleSI6ImVtaXNfOTY5MjExMzY5OF9hY2Nlc3NfdG9rZW4iLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJzZWNyZXQiLCJzZXNzaW9uVmFsdWUiOiJ7XCJJbTFDYWNoZUtleVwiOlwiV3VqUGxITDNGK0p4SUpReDdGUER3aWNvKzZWamVEYXp3Zjd2eW91a1M0b2c2RnllZXFxSUlVSkVVdS8zRHZZRkljQUVBenFEdk5hMXk2UGY3Rlg5Q3c9PVwiLFwiQWNjZXNzSWRlbnRpdHlHdWlkXCI6XCI3OWU4MzkyOS0uLi4iLCJjb21wbGV0ZVNlc3Npb25WYWx1ZSI6IntcIkltMUNhY2hlS2V5XCI6XCJXdWpQbEhMM0YrSnhJSlF4N0ZQRHdpY28rNlZqZURhendmN3Z5b3VrUzRvZzZGeWVlcXFJSVVKRVV1LzNEdllGSWNBRUF6cUR2TmExeTZQZjdGWDlDdz09XCIsXCJBY2Nlc3NJZGVudGl0eUd1aWRcIjpcIjc5ZTgzOTI5LWFiNzctNDI2Ni1iMWI5LWZjN2I4MjNjMTUyNVwifSIsInNlc3Npb25JbmRleCI6OH0seyJrZXkiOiJlbWlzXzk2OTIxMTM2MTJfYWNjZXNzX3Rva2VuIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoic2VjcmV0Iiwic2Vzc2lvblZhbHVlIjoie1wiSW0xQ2FjaGVLZXlcIjpcIkM4QXZheEp0YjZaMlFlemNSelEzWUprbFRlSVVtU2N6Y0F6Mno1a2tDazlPNjQ0dlVqV20veUJzRWF6c0htZmxPT0V1MDBlc3IvbGxDT2g4RzQzbWNBPT1cIixcIkFjY2Vzc0lkZW50aXR5R3VpZFwiOlwiMjE3ZWY2ZjEtLi4uIiwiY29tcGxldGVTZXNzaW9uVmFsdWUiOiJ7XCJJbTFDYWNoZUtleVwiOlwiQzhBdmF4SnRiNloyUWV6Y1J6UTNZSmtsVGVJVW1TY3pjQXoyejVra0NrOU82NDR2VWpXbS95QnNFYXpzSG1mbE9PRXUwMGVzci9sbENPaDhHNDNtY0E9PVwiLFwiQWNjZXNzSWRlbnRpdHlHdWlkXCI6XCIyMTdlZjZmMS0xZDcwLTRhOGUtYjcyOC02NjQzMTZjNzU2NTRcIn0iLCJzZXNzaW9uSW5kZXgiOjl9XQ==)
    ## 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 your technical conformance to the requirements for this API.

    You also need to demonstrate that you can manage risks. This might impact the design of your software.

    To understand how our online digital onboarding process works, see [digital onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding).

    ## Contact us

    For help and support connecting to our APIs and to join our developer community, see [Help and support building healthcare software](https://digital.nhs.uk/developer/help-and-support).

  contact:
    name: "Validated Relationships Service API Support"
    url: "https://digital.nhs.uk/developer/help-and-support"
    email: api.management@nhs.net
servers:
  - url: "https://sandbox.api.service.nhs.uk/validated-relationships/FHIR/R4"
    description: Sandbox environment.
  - url: "https://int.api.service.nhs.uk/validated-relationships/FHIR/R4"
    description: Integration test environment.
  - url: "https://api.service.nhs.uk/validated-relationships/FHIR/R4"
    description: Production environment.
paths:
  /QuestionnaireResponse:
    post:
      summary: New Access request
      description: |
        ## Overview
        For any new access request, the necessary details should be collected from a user facing service e.g.
        Proxy Access Service and submitted as a QuestionnaireResponse.

        ## Access modes

        This endpoint supports the following access modes:

        - Patient access

        ## Sandbox test scenarios:

        You can test the following scenarios in our sandbox environment:

        | Scenario               | Request                                                                                     | Response                                       |
        | ---------------------- | ------------------------------------------------------------------------------------------- | -----------------------------------------------|
        | Successful request     | Valid request with performer identifier value of `9000000009` or `9000000017`               | HTTP Status 200 Success response               |
        | Duplicate proxy role   | Request for proxy role that already exists, with performer identifier value of `9000000049` | HTTP Status 409 and DUPLICATE error response   |


        ### Sandbox constraints

        The sandbox environment has the following constraints for this endpoint:

        - QuestionnaireResponse is not validated.
        - Request headers are not tested. `X-Request-ID` and `X-Correlation-ID` are disregarded.
        - No access request is created.

      operationId: new-access-request
      parameters:
        - $ref: "#/components/parameters/BearerAuthorization"
        - $ref: "#/components/parameters/RequestID"
        - $ref: "#/components/parameters/CorrelationID"
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: "#/components/schemas/QuestionnaireResponse"
            examples:
              questionnaireResponseMotherChildRequest:
                $ref: "./examples/requests/POST_QuestionnaireResponse/mother-child.yaml#/QuestionnaireResponseMotherChildRequest"
              questionnaireResponseAdultToAdultWithoutCapacityRequest:
                $ref: "./examples/requests/POST_QuestionnaireResponse/adult-to-adult-without-capacity.yaml#/QuestionnaireResponseAdultToAdultWithoutCapacityRequest"
              questionnaireResponseAdultToAdultWithCapacityRequest:
                $ref: "./examples/requests/POST_QuestionnaireResponse/adult-to-adult-with-capacity.yaml#/QuestionnaireResponseAdultToAdultWithCapacityRequest"
              questionnaireResponseAdultNominatesAdultRequest:
                $ref: "./examples/requests/POST_QuestionnaireResponse/adult-nominates-adult.yaml#/QuestionnaireResponseAdultNominatesAdultRequest"
              questionnaireResponseDuplicateRelationship:
                $ref: "./examples/requests/POST_QuestionnaireResponse/duplicate_relationship.yaml#/QuestionnaireResponseDuplicateRelationship"
          application/fhir+json; charset=utf-8:
            schema:
              $ref: "#/components/schemas/QuestionnaireResponse"
      responses:
        "200":
          description: Request was received successfully for processing
          headers:
            location:
              schema:
                type: string
                example: https://sandbox.api.service.nhs.uk/validated-relationships/FHIR/R4/QuestionnaireResponse/156e1560-e532-4e2a-85ad-5aeff03dc43e
              description: URL for the newly created access request
          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              examples:
                postQuestionnaireResponseSuccess:
                  $ref: "./examples/responses/POST_QuestionnaireResponse/success.yaml#/PostQuestionnaireResponseSuccess"
        "4XX":
          description: |
            Errors will be returned for the first error encountered in the request. An error occurred as follows:

            | HTTP status | Error code               | Description                                                                                                                               |
            | ----------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
            | 400         | `MISSING_VALUE`          | Missing header or parameter. For details, see the `diagnostics` field.                                                                    |
            | 400         | `INVALID_VALUE`          | Invalid Parameter or Invalid operation.                                                                                                   |
            | 400         | `BAD_REQUEST`            | Failed questionnaire response validation                                                                                                  |
            | 401         | `ACCESS_DENIED`          | Missing or invalid OAuth 2.0 bearer token in request.                                                                                     |
            | 403         | `FORBIDDEN`              | Access denied to resource.                                                                                                                |
            | 405         | `METHOD_NOT_ALLOWED`     | The method is not allowed.                                                                                                                |
            | 408         | `TIMEOUT`                | Request timed out.                                                                                                                        |
            | 409         | `DUPLICATE_RELATIONSHIP` | A proposed proxy role already exists for this proxy/patient relationship.                                                                 |
            | 415         | `UNSUPPORTED_MEDIA`      | Unsupported media type.                                                                                                     |
            | 429         | `THROTTLED`              | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |

          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              examples:
                accessDeniedError:
                  $ref: "./examples/responses/errors/access-denied.yaml#/AccessDeniedError"
                postQuestionnaireResponseDuplicateRelationshipError:
                  $ref: "./examples/responses/POST_QuestionnaireResponse/errors/duplicate_relationship_error.yaml#/PostQuestionnaireResponseDuplicateRelationshipError"
        "5XX":
          description: |
            Errors will be returned for the first error encountered in the request. An error occurred as follows:

            | HTTP status | Error code                 | Description                                                  |
            | ----------- | -------------------------- | ------------------------------------------------------------ |
            | 500         | `SERVER_ERROR`             | An unexpected internal server error has occurred.            |
            | 502         | `BAD_GATEWAY`              | Connection to the backend service failed.                    |

          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              examples:
                internalServerError:
                  $ref: "./examples/responses/errors/internal-server-error.yaml#/InternalServerError"

  /QuestionnaireResponse/{id}:
    get:
      summary: Get a proxy access request
      description: |
        ## Overview
        Retrieve a QuestionnaireResponse using its unique access request ID. This endpoint returns the full
        QuestionnaireResponse document that was previously submitted.

        ## Request Requirements
        A valid access request ID must be provided as a path parameter.

        ## Access modes

        This endpoint supports the following access modes:
        - Patient access
        - Healthcare worker access
        - Application-restricted access

        ## Sandbox test scenarios

        You can test the following scenarios in our sandbox environment:

        | Scenario                         | Request                                          | Response                                                      |
        | -------------------------------- | ------------------------------------------------ | ------------------------------------------------------------- |
        | Valid access request ID          | ID value: `156e1560-e532-4e2a-85ad-5aeff03dc43e` | HTTP Status 200 with QuestionnaireResponse                    |
        | Invalid access request ID        | ID value:  `INVALID`                             | HTTP Status 400 with INVALID_IDENTIFIER_VALUE message         |
        | Missing access request ID        | No ID path parameter                             | HTTP Status 405 with METHOD_NOT_ALLOWED message               |
        | Non-existent access request ID   | ID value: `60d09b82-f4bb-41f9-b41e-767999b4ac9b` | HTTP Status 404 with QUESTIONNAIRE_RESPONSE_NOT_FOUND message |

        ### Sandbox constraints

        The sandbox environment has the following constraints for this endpoint:

          - Request headers are not tested. For example, `X-Request-ID` and `X-Correlation-ID` are disregarded.

      operationId: get-questionnaire-response
      parameters:
        - $ref: "#/components/parameters/BearerAuthorization"
        - $ref: "#/components/parameters/RequestID"
        - $ref: "#/components/parameters/CorrelationID"
        - $ref: "#/components/parameters/AccessRequestID"
      responses:
        "200":
          description: QuestionnaireResponse successfully retrieved.
          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/QuestionnaireResponse"
              examples:
                getQuestionnaireResponseSuccess:
                  $ref: "./examples/responses/GET_QuestionnaireResponse/success.yaml#/GetQuestionnaireResponseSuccess"
        "4XX":
          description: |
            Errors will be returned for the first error encountered in the request. An error occurred as follows:

            | HTTP status | Error code                         | Description                                                                                                                               |
            | ----------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
            | 400         | `INVALID_IDENTIFIER_VALUE`         | The access request ID must be a valid uuid.                                                                                               |
            | 400         | `INVALID_VALUE`                    | Invalid Parameter or Invalid operation.                                                                                                   |
            | 400         | `BAD_REQUEST`                      | The access request ID is required but was not provided in the request.                                                                    |
            | 400         | `MISSING_VALUE`                    | Missing header or parameter. For details, see the `diagnostics` field.                                                                    |
            | 401         | `ACCESS_DENIED`                    | Missing or invalid OAuth 2.0 bearer token in request.                                                                                     |
            | 403         | `FORBIDDEN`                        | Access denied to resource.                                                                                                                |
            | 404         | `QUESTIONNAIRE_RESPONSE_NOT_FOUND` | No questionnaire response was found for the provided access request ID.                                                                   |
            | 405         | `METHOD_NOT_ALLOWED`               | The method is not allowed.                                                                                                                |
            | 408         | `TIMEOUT`                          | Request timed out.                                                                                                                        |
            | 429         | `THROTTLED`                        | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |

          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              examples:
                invalidAccessRequestID:
                  $ref: "./examples/responses/GET_QuestionnaireResponse/errors/invalid_access_request_id.yaml#/InvalidAccessRequestID"
                missingAccessRequestID:
                  $ref: "./examples/responses/errors/method-not-allowed.yaml#/MethodNotAllowedError"
                questionnaireResponseNotFound:
                  $ref: "./examples/responses/GET_QuestionnaireResponse/errors/questionnaire_response_not_found.yaml#/QuestionnaireResponseNotFound"
        "5XX":
          description: |
            Errors will be returned for the first error encountered in the request. An error occurred as follows:

            | HTTP status | Error code                 | Description                                                  |
            | ----------- | -------------------------- | ------------------------------------------------------------ |
            | 500         | `SERVER_ERROR`             | An unexpected internal server error has occurred.            |
            | 501         | `NOT_IMPLEMENTED`          | API Endpoint not implemented.                                |
            | 502         | `BAD_GATEWAY`              | Connection to the backend service failed.                    |
            | 503         | `DOWNSTREAM_SERVICE_ERROR` | Failed to generate response                                  |

          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              examples:
                internalServerError:
                  $ref: "./examples/responses/errors/internal-server-error.yaml#/InternalServerError"

  /RelatedPerson:
    get:
      summary: Get verified candidate relationships
      description: |
        ## Overview
        Use this endpoint to get verified relationship information for a user with a given NHS Number. This endpoint should NOT be used to retrieve established proxy roles; these should be queried from the GET /Consent endpoints.

        You can query for RelatedPerson's in the following ways:

        | Outcome                                                                             | Query string value                                                      |
        | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
        | Search for patient relationships for a candidate proxy                              | `identifier={proxy identifier}`                                         |
        | Search for candidate proxy relationships for a patient                              | `patient:identifier={patient identifier}`                               |
        | Search for a specific verified candidate relationship for a given proxy and patient | `identifier={proxy identifier}&patient:identifier={patient identifier}` |

        You must provide either the `identifier={identifier}` or `patient:identifier={identifier}` query string, or both, in your request.

        ## Access modes

        This endpoint supports the following access modes:
        - Patient access
        - Healthcare worker access

        ## Sandbox test scenarios

        You can test the following scenarios in our sandbox environment:

        | Scenario                                                                    | Request                                                                                              | Response                                                                                       |
        | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
        | List Relationship                                                           | `identifier=9000000017`                                                                              | HTTP Status 200 List of relationships for the proxy                                            |
        | List Relationship and include patient's details                             | `identifier=9000000017&_include=RelatedPerson:patient`                                               | HTTP Status 200 List of relationships for the proxy and includes patient data                  |
        | List Patient Relationship                                                   | `patient:identifier=9000000042`                                                                      | HTTP Status 200 List of relationships for the patient                                          |
        | List Patient Relationship and include patient's details                     | `patient:identifier=9000000042&_include=RelatedPerson:patient`                                       | HTTP Status 200 List of relationships for the patient and includes patient data                  |
        | List Relationship and no relationships returned                             | `identifier=9000000033`                                                                              | HTTP Status 200 Empty bundle                                                                   |
        | Verify Relationship between proxy and patient                               | `identifier=9000000017&patient:identifier=9000000009`                                                | HTTP Status 200 Verified relationship between patient and proxy                                |
        | Verify Relationship between proxy and patient and include patient's details | `identifier=9000000017&patient:identifier=9000000009&_include=RelatedPerson:patient`                 | HTTP Status 200 Verified relationship between patient and proxy and includes patient's details |
        | Missing identifier                                                          | ``                                                                                                   | HTTP Status 400 and MISSING_IDENTIFIER_VALUE error response                                    |
        | Invalid identifier                                                          | `identifier=900000000` Note: This identifier is 9 characters long, too short to be NHS Number        | HTTP Status 400 and INVALID_IDENTIFIER_VALUE error response                                    |
        | Malformed identifier & system                                               | `identifier=https://fhir.nhs.uk/Id/nhs-number/9730675929`                                            | HTTP Status 400 and INVALID_IDENTIFIER_SYSTEM error response                                   |

        ### Sandbox constraints

        The sandbox environment has the following constraints for this endpoint:

          - Request headers are not tested. For example, `X-Request-ID` and `X-Correlation-ID` are disregarded.

      operationId: get-validated-relationships
      parameters:
        - $ref: "#/components/parameters/BearerAuthorization"
        - $ref: "#/components/parameters/RelatedPersonIdentifier"
        - $ref: "#/components/parameters/PatientIdentifier"
        - $ref: "#/components/parameters/RelatedPersonBundleIncludes"
        - $ref: "#/components/parameters/RequestID"
        - $ref: "#/components/parameters/CorrelationID"
      responses:
        "200":
          description: Information successfully returned.
          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/RelatedPersonBundle"
              examples:
                listRelationship:
                  $ref: "./examples/responses/GET_RelatedPerson/list_relationship_9000000017.yaml#/ListRelationship9000000017"
                listRelationshipIncludePatient:
                  $ref: "./examples/responses/GET_RelatedPerson/list_relationship_9000000017_include.yaml#/ListRelationship9000000017Include"
                listChildRelationship:
                  $ref: "./examples/responses/GET_RelatedPerson/list_relationship_9000000042.yaml#/ListRelationship9000000042"
                listChildRelationshipIncludePatient:
                  $ref: "./examples/responses/GET_RelatedPerson/list_relationship_9000000042_include.yaml#/ListRelationship9000000042Include"
                verifyRelationshipExample1:
                  $ref: "./examples/responses/GET_RelatedPerson/verify_relationship_9000000009.yaml#/VerifyRelationship9000000009"
                verifyRelationshipExample1Include:
                  $ref: "./examples/responses/GET_RelatedPerson/verify_relationship_9000000009_include.yaml#/VerifyRelationship9000000009Include"
                verifyRelationshipExample2:
                  $ref: "./examples/responses/GET_RelatedPerson/verify_relationship_9000000025.yaml#/VerifyRelationship9000000025"
                verifyRelationshipExample2Include:
                  $ref: "./examples/responses/GET_RelatedPerson/verify_relationship_9000000025_include.yaml#/VerifyRelationship9000000025Include"
                relatedEmptyResponse:
                  $ref: "./examples/responses/GET_RelatedPerson/empty_response_9000000033.yaml#/RelatedEmptyResponse"

        "4XX":
          description: |
            Errors will be returned for the first error encountered in the request. An error occurred as follows:

            | HTTP status | Error code                         | Description                                                                                                                               |
            | ----------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
            | 400         | `MISSING_IDENTIFIER_VALUE`         | Missing RelatedPerson NHS number.                                                                                                         |
            | 400         | `INVALID_IDENTIFIER_SYSTEM`        | Invalid identifier system.                                                                                                                |
            | 400         | `INVALID_VALUE`                    | Invalid Parameter or Invalid operation.                                                                                                   |
            | 400         | `INVALID_PATIENT_IDENTIFIER_VALUE` | Malformed Patient NHS number.                                                                                                             |
            | 400         | `INVALID_IDENTIFIER_VALUE`         | Malformed RelatedPerson NHS number.                                                                                                       |
            | 401         | `ACCESS_DENIED`                    | Missing or invalid OAuth 2.0 bearer token in request.                                                                                     |
            | 403         | `FORBIDDEN`                        | Access denied to resource.                                                                                                                |
            | 404         | `INVALIDATED_RESOURCE`             | Resource that has been marked as invalid was requested - invalid resources cannot be retrieved                                            |
            | 405         | `METHOD_NOT_ALLOWED`               | The method is not allowed.                                                                                                                |
            | 408         | `TIMEOUT`                          | Request timed out.                                                                                                                        |
            | 429         | `THROTTLED`                        | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |

          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              examples:
                AccessDeniedError:
                  $ref: "./examples/responses/errors/access-denied.yaml#/AccessDeniedError"
                RelatedPersonInvalidIdentifierMissing:
                  $ref: "./examples/responses/GET_RelatedPerson/errors/invalid-identifier-missing.yaml#/RelatedPersonInvalidIdentifierMissing"
                RelatedPersonInvalidIdentifierError:
                  $ref: "./examples/responses/GET_RelatedPerson/errors/invalid-identifier.yaml#/RelatedPersonInvalidIdentifierError"
                InvalidIdentifierPatientError:
                  $ref: "./examples/responses/GET_RelatedPerson/errors/invalid-identifier-patient.yaml#/InvalidIdentifierPatientError"
                RelatedPersonInvalidIdentifierSystem:
                  $ref: "./examples/responses/GET_RelatedPerson/errors/invalid-identifier-system.yaml#/RelatedPersonInvalidIdentifierSystem"

        "5XX":
          description: |
            Errors will be returned for the first error encountered in the request. An error occurred as follows:

            | HTTP status | Error code                 | Description                                                  |
            | ----------- | -------------------------- | ------------------------------------------------------------ |
            | 500         | `SERVER_ERROR`             | An unexpected internal server error has occurred.            |
            | 501         | `NOT_IMPLEMENTED`          | API Endpoint not implemented.                                |
            | 502         | `BAD_GATEWAY`              | Connection to the backend service failed.                    |

          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              examples:
                InternalServerError:
                  $ref: "./examples/responses/errors/internal-server-error.yaml#/InternalServerError"

  /Consent:
    get:
      summary: Get proxy roles
      description: |
        ## Overview
        Use this endpoint to get the details about proxy roles, including current status, based on a provided NHS Number.

        Either `performer:identifier` or `patient:identifier` request parameters must be provided. `performer:identifier` and `patient:identifier` can be used together.

        You can (optionally) include a `status={status}` query string parameter to filter the response to records with a given status bound to the http://hl7.org/fhir/consent-state-codes CodeSystem e.g. `status=active` or `status=proposed,active`.

        You can (optionally) include the `_include=Consent:performer` request parameter to include the proxy's details in the response.

        You can (optionally) include the `_include=Consent:patient` request parameter to include the patient's details in the response.

        ## Access modes

        This endpoint supports the following access modes:
        - Patient access
        - Healthcare worker access
        - Application-restricted access

        ## Sandbox test scenarios

        You can test the following scenarios in our sandbox environment:

        | Scenario                                                                          | Request                                                                                                                                          | Response                                                                                                          |
        | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
        | Multiple proxy relationships filtered by 'active' status including details        | `performer:identifier=9000000017&_include=Consent:patient&_include=Consent:performer&status=active`                                  | HTTP Status 200 Bundle containing a multiple active proxy relationships including performer and patient details   |
        | Multiple proxy relationships filtered by 'inactive' status                        | `performer:identifier=9000000017&status=inactive`                                                                                                | HTTP Status 200 Bundle containing a multiple inactive proxy relationships                                         |
        | Multiple proxy relationships filtered by 'proposed' and 'active' status           | `performer:identifier=9000000017&status=proposed,active`                                                                                         | HTTP Status 200 Bundle containing a multiple proposed and active proxy relationships                              |
        | Multiple proxy relationships without filtering and details                        | `performer:identifier=9000000022`                                                                                                                | HTTP Status 200 Bundle containing a multiple proxy relationships without details                                  |
        | Multiple proxy relationships including performer details                          | `performer:identifier=9000000022&_include=Consent:performer`                                                                                     | HTTP Status 200 Bundle containing a multiple proxy relationships including performer details                      |
        | Multiple proxy relationships including patient details                            | `performer:identifier=9000000022&_include=Consent:patient`                                                                                       | HTTP Status 200 Bundle containing a multiple proxy relationships including patient details                        |
        | Multiple proxy relationships including performer and patient details              | `performer:identifier=9000000022&_include=Consent:patient&_include=Consent:performer`                                                            | HTTP Status 200 Bundle containing a multiple proxy relationships including performer and patient details          |
        | Multiple proxy relationships, single patient                                      | `patient:identifier=9000000100`                                                                                                                  | HTTP Status 200 Bundle containing a multiple proxy relationships including performer and patient details          |
        | Multiple proxy relationships, single patient, including proxy details             | `patient:identifier=9000000100&_include=Consent:performer`                                                                                       | HTTP Status 200 Bundle containing a multiple proxy relationships including proxy details                          |
        | Multiple proxy relationships, single patient, including patient details           | `patient:identifier=9000000100&_include=Consent:patient`                                                                                         | HTTP Status 200 Bundle containing a multiple proxy relationships including patient details                        |
        | Multiple proxy relationships, single patient, including proxy and patient details | `patient:identifier=9000000100&_include=Consent:patient&_include=Consent:performer`                                                              | HTTP Status 200 Bundle containing a multiple proxy relationships including proxy and patient details              |
        | No proxy relationships                                                            | `performer:identifier=9000000025&_include=Consent:patient&_include=Consent:performer&status=active`                                              | HTTP Status 200 empty bundle                                                                                      |
        | A single proxy relationship between consenting adults                             | `performer:identifier=9000000010` and/or `patient:identifier=9000000005`                                                                         | HTTP Status 200 Bundle containing a single proxy relationship                                                     |
        | A single proxy relationship between consenting adults including details           | `performer:identifier=9000000010` and/or `patient:identifier=9000000005&_include=Consent:patient&_include=Consent:performer`                         | HTTP Status 200 Bundle containing a single proxy relationship including performer and patient details             |
        | A single proxy relationship between a mother and child                            | `performer:identifier=9000000019` and/or `patient:identifier=9000000009`                                                                         | HTTP Status 200 Bundle containing a single proxy relationship                                                     |
        | A single proxy relationship between a mother and child including details          | `performer:identifier=9000000019` and/or `patient:identifier=9000000009&_include=Consent:patient&_include=Consent:performer`                         | HTTP Status 200 Bundle containing a single proxy relationship including performer and patient details             |
        | A single proxy relationship between a mother and child with legal basis unknown   | `performer:identifier=9000000111` and/or `patient:identifier=9000000119`                                                                         | HTTP Status 200 Bundle containing a single proxy relationship with legal basis unknown                            |
        | Invalid status parameter                                                          | `performer:identifier=9000000019` and/or `patient:identifier=9000000009&status=test`                                                             | HTTP Status 422 and INVALID_PARAMETER error response                                                              |
        | Invalid include parameter                                                         | `performer:identifier=9000000019` and/or `patient:identifier=9000000009&_include=test`                                                           | HTTP Status 422 and INVALID_PARAMETER error response                                                              |
        | Missing identifier                                                                | `patient:identifier=9000000009`                                                                                                                  | HTTP Status 400 and MISSING_IDENTIFIER_VALUE error response                                                       |
        | Invalid identifier                                                                | `identifier=900000000` Note: This identifier is 9 characters long, too short to be NHS Number                                                    | HTTP Status 422 and INVALID_IDENTIFIER_VALUE error response                                                       |
        | Invalid identifier system                                                         | `identifier=https://fhir.nhs.uk/Id/nhs-number/9730675929`                                                                                        | HTTP Status 422 and INVALID_IDENTIFIER_SYSTEM error response                                                      |
        | No performer record found                                                         | `identifier=9000000999`                                                                                                                          | HTTP Status 404 and INVALIDATED_RESOURCE error response                                                           |
        | GP Practice not found                                                             | `identifier=9000000012`                                                                                                                          | HTTP Status 404 and GP_PRACTICE_NOT_FOUND error response                                                          |

        ### Sandbox constraints

        The sandbox environment has the following constraints for this endpoint:

          - Request headers are not tested. `X-IM1-Connection-Params`, `X-Request-ID` and `X-Correlation-ID` are disregarded.

      operationId: get-consent
      parameters:
        - $ref: "#/components/parameters/BearerAuthorization"
        - $ref: "#/components/parameters/ConsentBundlePerformerIdentifier"
        - $ref: "#/components/parameters/ConsentBundlePatientIdentifier"
        - $ref: "#/components/parameters/ConsentStatus"
        - $ref: "#/components/parameters/ConsentBundleIncludes"
        - $ref: "#/components/parameters/RequestID"
        - $ref: "#/components/parameters/CorrelationID"
        - $ref: "#/components/parameters/Im1ConnectionParams"
      responses:
        "200":
          description: Information successfully returned.
          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/ConsentBundle"
              examples:
                ConsentMultipleRelationshipsStatusActiveBundle:
                  $ref: "./examples/responses/GET_Consent/filtered-relationships-status-active-include-details.yaml#/ConsentMultipleRelationshipsStatusActiveIncludeDetailsBundle"
                ConsentMultipleRelationshipsStatusInactiveBundle:
                  $ref: "./examples/responses/GET_Consent/filtered-relationships-status-inactive.yaml#/ConsentMultipleRelationshipsStatusInactiveBundle"
                ConsentMultipleRelationshipsStatusProposedActiveBundle:
                  $ref: "./examples/responses/GET_Consent/filtered-relationships-status-proposed-active.yaml#/ConsentMultipleRelationshipsStatusProposedActiveBundle"
                ConsentMultipleRelationshipsBundle:
                  $ref: "./examples/responses/GET_Consent/multiple-relationships.yaml#/ConsentMultipleRelationshipsBundle"
                ConsentMultipleRelationshipsIncludePatientBundle:
                  $ref: "./examples/responses/GET_Consent/multiple-relationships-include-patient.yaml#/ConsentMultipleRelationshipsIncludePatientBundle"
                ConsentMultipleRelationshipsIncludePerformerBundle:
                  $ref: "./examples/responses/GET_Consent/multiple-relationships-include-performer.yaml#/ConsentMultipleRelationshipsIncludePerformerBundle"
                ConsentMultipleRelationshipsIncludePerformerPatientBundle:
                  $ref: "./examples/responses/GET_Consent/multiple-relationships-include-performer-patient.yaml#/ConsentMultipleRelationshipsIncludePerformerPatientBundle"
                ConsentNoRelationshipsEmptyBundle:
                  $ref: "./examples/responses/GET_Consent/no-relationships.yaml#/ConsentNoRelationshipsEmptyBundle"
                ConsentSingleConsentingAdultRelationshipBundle:
                  $ref: "./examples/responses/GET_Consent/single-consenting-adult-relationship.yaml#/ConsentSingleConsentingAdultRelationshipBundle"
                ConsentSingleConsentingAdultRelationshipIncludePerformerPatientBundle:
                  $ref: "./examples/responses/GET_Consent/single-consenting-adult-relationship-include-performer-patient.yaml#/ConsentSingleConsentingAdultRelationshipIncludePerformerPatientBundle"
                ConsentSingleAdultChildRelationshipBundle:
                  $ref: "./examples/responses/GET_Consent/single-mother-child-relationship.yaml#/ConsentSingleAdultChildRelationshipBundle"
                ConsentSingleAdultChildRelationshipIncludePerformerPatientBundle:
                  $ref: "./examples/responses/GET_Consent/single-mother-child-relationship-include-performer-patient.yaml#/ConsentSingleAdultChildRelationshipIncludePerformerPatientBundle"
                ConsentMultipleRelationshipsSinglePatientBundle:
                  $ref: "./examples/responses/GET_Consent/multiple-relationships-single-patient.yaml#/ConsentMultipleRelationshipsSinglePatientBundle"

        "4XX":
          description: |
            Errors will be returned for the first error encountered in the request. An error occurred as follows:

            | HTTP status | Error code                       | Description                                                                                                                               |
            | ----------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
            | 401         | `ACCESS_DENIED`                  | Missing or invalid OAuth 2.0 bearer token in request.                                                                                     |
            | 404         | `INVALIDATED_RESOURCE`           | Resource that has been marked as invalid was requested - invalid resources cannot be retrieved                                            |
            | 404         | `GP_PRACTICE_NOT_FOUND`          | GP Practice not found.                                                                                                                    |
            | 405         | `METHOD_NOT_ALLOWED`             | The method is not allowed.                                                                                                                |
            | 408         | `TIMEOUT`                        | Request timed out.                                                                                                                        |
            | 422         | `INVALID_PARAMETER`              | Invalid parameter. For details, see the `diagnostics` field.                                                                              |
            | 429         | `THROTTLED`                      | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |

          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              examples:
                AccessDeniedError:
                  $ref: "./examples/responses/errors/access-denied.yaml#/AccessDeniedError"
                ConsentInvalidIdentifierError:
                  $ref: "./examples/responses/GET_Consent/errors/invalid-identifier.yaml#/ConsentInvalidIdentifierError"
                ConsentInvalidIdentifierSystemError:
                  $ref: "./examples/responses/GET_Consent/errors/invalid-identifier-system.yaml#/ConsentInvalidIdentifierSystemError"
                ConsentIdentifierMissingError:
                  $ref: "./examples/responses/GET_Consent/errors/missing-identifier.yaml#/ConsentIdentifierMissingError"
                InvalidatedResourceError:
                  $ref: "./examples/responses/errors/invalidated-resource.yaml#/InvalidatedResourceError"
                ConsentInvalidStatusParameterError:
                  $ref: "./examples/responses/GET_Consent/errors/invalid-status-parameter.yaml#/ConsentInvalidStatusParameterError"
                GPPracticeNotFoundError:
                  $ref: "./examples/responses/GET_Consent/errors/gp-practice-not-found.yaml#/GPPracticeNotFoundError"
                InvalidIncludeParameterError:
                  $ref: "./examples/responses/errors/invalid-include-parameter.yaml#/InvalidIncludeParameterError"
        "5XX":
          description: |
            Errors will be returned for the first error encountered in the request. An error occurred as follows:

            | HTTP status | Error code                 | Description                                                   |
            | ----------- | -------------------------- | ------------------------------------------------------------- |
            | 500         | `SERVER_ERROR`             | An unexpected internal server error has occurred.             |
            | 502         | `BAD_GATEWAY`              | Connection to the backend service failed.                     |
            | 503         | `DOWNSTREAM_SERVICE_ERROR` | A downstream service has failed, request cannot be completed. |

          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              examples:
                InternalServerError:
                  $ref: "./examples/responses/errors/internal-server-error.yaml#/InternalServerError"
                DownstreamServiceError:
                  $ref: "./examples/responses/errors/downstream-service-error.yaml#/DownstreamServiceError"
    post:
      summary: Create a proxy role
      description: |
        ## Overview
        Use this endpoint to create a new proxy role between a patient and a related person (proxy).

        ## Access modes

        This endpoint supports the following access modes:
        - Healthcare worker access
        - Application-restricted access

        ## Sandbox test scenarios

        You can test the following scenarios in our sandbox environment:

        | Scenario                                | Request                                                                                                     | Response                                                    |
        | --------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
        | Successful parent-child proxy creation  | Valid request with a legal basis of parental responsibility, with performer identifier value of `9000000009`| HTTP Status 201 and OperationOutcome response               |
        | Successful adult-adult proxy creation   | Valid request with legal basis of consent, with performer identifier value of `9000000017`                  | HTTP Status 201 and OperationOutcome response               |
        | Valid OTHER reason code with free text  | Request with reason code 'OTHER' and free text provided, performer identifier `9000000051`                  | HTTP Status 201 and OperationOutcome response               |
        | Non-OTHER reason code without free text | Request with a reason code other than 'OTHER', no free text, performer identifier `9000000052`              | HTTP Status 201 and OperationOutcome response               |
        | Non-OTHER reason code with free text    | Request with a reason code other than 'OTHER', with free text, performer identifier `9000000053`            | HTTP Status 201 and OperationOutcome response               |
        | Missing free text for OTHER reason code | Request with reason code 'OTHER' but missing free text, performer identifier `9000000050`                   | HTTP Status 400 and MISSING_FREE_TEXT_FOR_OTHER error response |
        | Missing grantor                         | Valid request with status 'active' but no grantor extension, performer identifier `9000000054`              | HTTP Status 400 and MISSING_GRANTOR error response          |
        | Missing grantor valueReference     | Request with grantor extension but missing valueReference, performer identifier `9000000057` | HTTP Status 400 and MISSING_GRANTOR_REFERENCE error response             |
        | Missing grantor valueIdentifier     | Request with grantor extension but missing valueIdentifier, performer identifier `9000000058` | HTTP Status 400 and MISSING_GRANTOR_IDENTIFIER error response             |
        | Invalid grantor ODS code value                | Request with grantor extension but missing/empty/invalid ODS code, performer identifier `9000000055`       | HTTP Status 422 and INVALID_GRANTOR_VALUE error response                 |
        | Invalid grantor identifier system             | Request with grantor extension but wrong/missing identifier system, performer identifier `9000000056`      | HTTP Status 422 and INVALID_GRANTOR_SYSTEM error response                |
        | Duplicate relationship                  | Request for relationship that already exists, with performer identifier value of `9000000049`               | HTTP Status 409 and DUPLICATE_RELATIONSHIP error response   |

        ### Sandbox constraints

        The sandbox environment has the following constraints for this endpoint:

        - `patient.identifier.value` is disregarded. The returned response is based on the `performer.identifier.value` only.
        - Request body is not validated.
        - Request headers are not tested. `X-Request-ID` and `X-Correlation-ID` are disregarded.
        - No proxy role is created.

      operationId: create-proxy-role
      parameters:
        - $ref: "#/components/parameters/BearerAuthorization"
        - $ref: "#/components/parameters/RequestID"
        - $ref: "#/components/parameters/CorrelationID"
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: "#/components/schemas/Consent"
            examples:
              parentConsentRequest:
                $ref: "./examples/requests/POST_Consent/parent_child_proxy_creation.yaml#/ConsentParentChildProxyCreationRequest"
              guardianConsentRequest:
                $ref: "./examples/requests/POST_Consent/adult_to_adult_proxy_creation.yaml#/ConsentAdultToAdultGuardianRequest"
      responses:
        "201":
          description: Consent resource successfully created
          headers:
            location:
              schema:
                type: string
                example: https://sandbox.api.service.nhs.uk/validated-relationships/FHIR/R4/Consent/90b9863e-e33c-4895-a333-fd0ea0e23205
              description: URL for the newly created proxy role
          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              examples:
                postConsentSuccess:
                  $ref: "./examples/responses/POST_Consent/success.yaml#/PostConsentSuccess"
        "4XX":
          description: |
            Errors will be returned for the first error encountered in the request. For details, see the `diagnostics` field of error. An error occurred as follows:

            | HTTP status | Error code                  | Description                                                                                                                               |
            | ----------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
            | 400         | `MISSING_IDENTIFIER_VALUE`  | Missing performer or patient identifier.                                                                                                    |
            | 400         | `MISSING_IDENTIFIER_SYSTEM` | Missing performer or patient identifier system.                                                                                             |
            | 400         | `MISSING_PATIENT`           | Missing patient.                                                                                                                          |
            | 400         | `MISSING_PERFORMER`           | Missing performer.                                                                                                                          |
            | 400         | `MISSING_GRANTOR`           | Grantor extension is required when creating or activating an active proxy role.                                                           |
            | 400         | `MISSING_GRANTOR_REFERENCE` | Grantor extension is present but missing valueReference.                                                                                  |
            | 400         | `MISSING_GRANTOR_IDENTIFIER`| Grantor extension is present but missing valueIdentifier.                                                                                 |
            | 400         | `MISSING_VALUE`             | Missing header or parameter. For details, see the `diagnostics` field.                                                                    |
            | 400         | `MISSING_STATUS`            | Missing status.                                                                                                                           |
            | 400         | `MISSING_SCOPE`             | Missing scope.                                                                                                                            |
            | 400         | `MISSING_CATEGORY`          | Missing category.                                                                                                                         |
            | 400         | `MISSING_DATETIME`          | Missing datetime.                                                                                                                         |
            | 400         | `BAD_REQUEST`               | Invalid request. For details, see the `diagnostics` field.                                                                                |
            | 401         | `ACCESS_DENIED`             | Missing or invalid OAuth 2.0 bearer token in request.                                                                                     |
            | 403         | `FORBIDDEN`                 | Access denied to resource.                                                                                                                |
            | 405         | `METHOD_NOT_ALLOWED`        | The method is not allowed.                                                                                                                |
            | 408         | `TIMEOUT`                   | Request timed out.                                                                                                                        |
            | 409         | `DUPLICATE_RELATIONSHIP`    | Conflict with requested proxy role.                                                                                                       |
            | 422         | `INVALID_IDENTIFIER_VALUE`  | Invalid performer or patient identifier value.                                                                                              |
            | 422         | `INVALID_IDENTIFIER_SYSTEM` | Invalid performer or patient identifier system.                                                                                             |
            | 422         | `INVALID_PATIENT`           | Invalid patient.                                                                                                                          |
            | 422         | `INVALID_PERFORMER`           | Invalid performer.                                                                                                                          |
            | 422         | `INVALID_STATUS`            | Invalid status.                                                                                                                           |
            | 422         | `INVALID_SCOPE`             | Invalid scope.                                                                                                                            |
            | 422         | `INVALID_CATEGORY`          | Invalid category.                                                                                                                         |
            | 422         | `INVALID_DATETIME`          | Invalid datetime.                                                                                                                         |
            | 422         | `INVALID_PROVISION`         | Invalid provision.                                                                                                                        |
            | 422         | `INVALID_EXTENSION`         | Invalid extension.                                                                                                                        |
            | 422         | `INVALID_GRANTOR_VALUE`     | Grantor ODS code is missing, empty, whitespace-only or invalid format.                                                                    |
            | 422         | `INVALID_PERFORMER`         | Invalid performer.                                                                                                                        |
            | 422         | `INVALID_GRANTOR_SYSTEM`    | Grantor identifier system is invalid (must be 'https://fhir.nhs.uk/Id/ods-organization-code').                                            |
            | 429         | `THROTTLED`                 | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |

          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              examples:
                postConsentDuplicateRelationship:
                  $ref: "./examples/responses/POST_Consent/errors/duplicate_relationship_error.yaml#/PostConsentDuplicateRelationshipError"
                postConsentInvalidIdentifierValue:
                  $ref: "./examples/responses/POST_Consent/errors/invalid_identifier_value.yaml#/PostConsentInvalidIdentifierValueError"
                postConsentInvalidStatus:
                  $ref: "./examples/responses/POST_Consent/errors/invalid_status.yaml#/PostConsentInvalidStatusError"
                postConsentMissingIdentifierSystem:
                  $ref: "./examples/responses/POST_Consent/errors/missing_identifier_system.yaml#/PostConsentMissingIdentifierSystemError"
                postConsentMissingScope:
                  $ref: "./examples/responses/POST_Consent/errors/missing_scope.yaml#/PostConsentMissingScopeError"
                postConsentInvalidRequest:
                  $ref: "./examples/responses/POST_Consent/errors/invalid_request.yaml#/PostConsentInvalidRequestError"
                postConsentInvalidFHIRRequest:
                  $ref: "./examples/responses/POST_Consent/errors/invalid_request.yaml#/PostConsentInvalidFHIRRequestError"
                postConsentMissingFreeTextForOther:
                  $ref: "./examples/responses/POST_Consent/errors/missing_free_text_for_other.yaml#/PostConsentMissingFreeTextForOtherError"
                postConsentMissingGrantorError:
                  $ref: "./examples/responses/POST_Consent/errors/missing_grantor.yaml#/PostConsentMissingGrantorError"
                postConsentMissingGrantorReferenceError:
                  $ref: "./examples/responses/POST_Consent/errors/missing_grantor_reference.yaml#/PostConsentMissingGrantorReferenceError"
                postConsentMissingGrantorIdentifierError:
                  $ref: "./examples/responses/POST_Consent/errors/missing_grantor_identifier.yaml#/PostConsentMissingGrantorIdentifierError"
                postConsentInvalidGrantorIdentifierSystemError:
                  $ref: "./examples/responses/POST_Consent/errors/invalid_grantor_identifier_system.yaml#/PostConsentInvalidGrantorIdentifierSystemError"
                postConsentInvalidGrantorIdentifierValueError:
                  $ref: "./examples/responses/POST_Consent/errors/invalid_grantor_identifier_value.yaml#/PostConsentInvalidGrantorIdentifierValueError"

        "5XX":
          description: |
            Errors will be returned for the first error encountered in the request. An error occurred as follows:

            | HTTP status | Error code                 | Description                                                   |
            | ----------- | -------------------------- | ------------------------------------------------------------- |
            | 500         | `SERVER_ERROR`             | An unexpected internal server error has occurred.             |
            | 501         | `NOT_IMPLEMENTED`          | API Endpoint not implemented.                                 |
            | 502         | `BAD_GATEWAY`              | Connection to the backend service failed.                     |
            | 503         | `DOWNSTREAM_SERVICE_ERROR` | A downstream service has failed, request cannot be completed. |

          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              examples:
                InternalServerError:
                  $ref: "./examples/responses/errors/internal-server-error.yaml#/InternalServerError"
                DownstreamServiceError:
                  $ref: "./examples/responses/errors/downstream-service-error.yaml#/DownstreamServiceError"

  /Consent/{id}:
    get:
      summary: Get proxy role
      description: |
        ## Overview
        Use this endpoint to get the details of a proxy role, including current status, based on a provided id.

        You can (optionally) include the `_include=Consent:performer` request parameter to include the proxy's details in the response.

        You can (optionally) include the `_include=Consent:patient` request parameter to include the patient's details in the response.

        ## Access modes

        This endpoint supports the following access modes:
        - Healthcare worker access
        - Application-restricted access

        ## Sandbox test scenarios

        You can test the following scenarios in our sandbox environment:

        | Scenario                                                                         | Request                                                                                                                                  | Response                                                                                                         |
        | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
        | Retrieve single consenting adult relationship                                    | Valid request with ID `74eed847-ca25-4e76-8cf2-f2c2d7842a7a`                                                                             | HTTP Status 200 Bundle containing a single active proxy relationship                                             |
        | Retrieve single consenting adult relationship with patient details               | Valid request with ID `74eed847-ca25-4e76-8cf2-f2c2d7842a7a?_include=Consent:patient`                                                    | HTTP Status 200 Bundle containing a single active proxy relationship with patient details                        |
        | Retrieve single consenting adult relationship with performer details             | Valid request with ID `74eed847-ca25-4e76-8cf2-f2c2d7842a7a?_include=Consent:performer`                                                  | HTTP Status 200 Bundle containing a single active proxy relationship with performer details                      |
        | Retrieve single consenting adult relationship with performer and patient details | Valid request with ID `74eed847-ca25-4e76-8cf2-f2c2d7842a7a?_include=Consent:performer&_include=Consent:patient`                         | HTTP Status 200 Bundle containing a single active proxy relationship with performer and patient details  |
        | Retrieve single mother-child relationship                                        | Valid request with ID `39df03a2-1b14-4d19-b1dc-d5d8cbf96948`                                                                             | HTTP Status 200 Bundle containing a single active proxy relationship                                             |
        | Retrieve single mother-child relationship with patient details                   | Valid request with ID `39df03a2-1b14-4d19-b1dc-d5d8cbf96948?_include=Consent:patient`                                                    | HTTP Status 200 Bundle containing a single active proxy relationship with patient details                        |
        | Retrieve single mother-child relationship with performer details                 | Valid request with ID `39df03a2-1b14-4d19-b1dc-d5d8cbf96948?_include=Consent:performer`                                                  | HTTP Status 200 Bundle containing a single active proxy relationship with performer details                      |
        | Retrieve single mother-child relationship with performer and patient details     | Valid request with ID `39df03a2-1b14-4d19-b1dc-d5d8cbf96948?_include=Consent:performer&_include=Consent:patient`                       | HTTP Status 200 Bundle containing a single active proxy relationship with performer and patient details  |

        ### Sandbox constraints

        The sandbox environment has the following constraints for this endpoint:

        - Request headers are not tested. `X-Request-ID` and `X-Correlation-ID` are disregarded.

      operationId: get-consent-by-id
      parameters:
        - $ref: "#/components/parameters/BearerAuthorization"
        - $ref: "#/components/parameters/ConsentID"
        - $ref: "#/components/parameters/ConsentBundleIncludes"
        - $ref: "#/components/parameters/RequestID"
        - $ref: "#/components/parameters/CorrelationID"
      responses:
        "200":
          description: Information successfully returned.
          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/ConsentBundle"
              examples:
                ConsentSingleConsentingAdultRelationshipBundle:
                  $ref: "./examples/responses/GET_Consent/single-consenting-adult-relationship.yaml#/ConsentSingleConsentingAdultRelationshipBundle"
                ConsentSingleConsentingAdultRelationshipIncludePatientBundle:
                  $ref: "./examples/responses/GET_Consent/single-consenting-adult-relationship-include-patient.yaml#/ConsentSingleConsentingAdultRelationshipIncludePatientBundle"
                ConsentSingleConsentingAdultRelationshipIncludePerformerBundle:
                  $ref: "./examples/responses/GET_Consent/single-consenting-adult-relationship-include-performer.yaml#/ConsentSingleConsentingAdultRelationshipIncludePerformerBundle"
                ConsentSingleConsentingAdultRelationshipIncludePerformerPatientBundle:
                  $ref: "./examples/responses/GET_Consent/single-consenting-adult-relationship-include-performer-patient.yaml#/ConsentSingleConsentingAdultRelationshipIncludePerformerPatientBundle"
                ConsentSingleAdultChildRelationshipBundle:
                  $ref: "./examples/responses/GET_Consent/single-mother-child-relationship.yaml#/ConsentSingleAdultChildRelationshipBundle"
                ConsentSingleAdultChildRelationshipIncludePatientBundle:
                  $ref: "./examples/responses/GET_Consent/single-mother-child-relationship-include-patient.yaml#/ConsentSingleAdultChildRelationshipIncludePatientBundle"
                ConsentSingleAdultChildRelationshipIncludePerformerBundle:
                  $ref: "./examples/responses/GET_Consent/single-mother-child-relationship-include-performer.yaml#/ConsentSingleAdultChildRelationshipIncludePerformerBundle"
                ConsentSingleAdultChildRelationshipIncludePerformerPatientBundle:
                  $ref: "./examples/responses/GET_Consent/single-mother-child-relationship-include-performer-patient.yaml#/ConsentSingleAdultChildRelationshipIncludePerformerPatientBundle"

        "4XX":
          description: |
            Errors will be returned for the first error encountered in the request. An error occurred as follows:

            | HTTP status | Error code                       | Description                                                                                                                               |
            | ----------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
            | 401         | `ACCESS_DENIED`                  | Missing or invalid OAuth 2.0 bearer token in request.                                                                                     |
            | 404         | `INVALIDATED_RESOURCE`           | Resource that has been marked as invalid was requested - invalid resources cannot be retrieved                                            |
            | 405         | `METHOD_NOT_ALLOWED`             | The method is not allowed.                                                                                                                |
            | 408         | `TIMEOUT`                        | Request timed out.                                                                                                                        |
            | 429         | `THROTTLED`                      | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |

          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              examples:
                AccessDeniedError:
                  $ref: "./examples/responses/errors/access-denied.yaml#/AccessDeniedError"
                InvalidatedResourceError:
                  $ref: "./examples/responses/errors/invalidated-resource.yaml#/InvalidatedResourceError"
                InvalidIdError:
                  $ref: "./examples/responses/GET_Consent/ID/errors/invalid-id.yaml#/ConsentInvalidIDError"
                InvalidIncludeParameterError:
                  $ref: "./examples/responses/errors/invalid-include-parameter.yaml#/InvalidIncludeParameterError"
        "5XX":
          description: |
            Errors will be returned for the first error encountered in the request. An error occurred as follows:

            | HTTP status | Error code                 | Description                                                   |
            | ----------- | -------------------------- | ------------------------------------------------------------- |
            | 500         | `SERVER_ERROR`             | An unexpected internal server error has occurred.             |
            | 501         | `NOT_IMPLEMENTED`          | API Endpoint not implemented.                                 |
            | 502         | `BAD_GATEWAY`              | Connection to the backend service failed.                     |

          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              examples:
                InternalServerError:
                  $ref: "./examples/responses/errors/internal-server-error.yaml#/InternalServerError"
                DownstreamServiceError:
                  $ref: "./examples/responses/errors/downstream-service-error.yaml#/DownstreamServiceError"
    patch:
      summary: Update a proxy role
      description: |
        ## Overview
        Use this endpoint to update an existing proxy role.

        Supported update scenarios include:

        * Update the status and status reason, (optionally) providing an additional free text description
        * Update the policy rule
        * Update the end date, for time-bound access

        ## Request Requirements
        * The proxy role must exist and be identified by a valid ID
        * JSON Patch operations must be valid according to RFC 6902
        * Status changes must use valid status codes from <http://hl7.org/fhir/consent-state-codes>

        ### IMPORTANT: Business Rule Enforcement for `/status` updates

        If you update the `/status` of a role, you **MUST** also provide a corresponding update to the `/extension` path in the same patch array to provide the `statusReason`. An error will be returned if a request for a change of `/status` does not include a status reason.

        The values for `/status` and `statusReason` are validated against a proxy role lifecycle to ensure that the transition between the existing and requested status is valid. An error will be returned if the requested transition is not valid.

        ## Access modes

        This endpoint supports the following access modes:
        - Patient access
        - Healthcare worker access
        - Application-restricted access

        ## Sandbox test scenarios

        You can test the following scenarios in our sandbox environment:

        | Scenario                        | Request                                                                                         | Response                                                      |
        | ------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
        | Successful status update        | Valid patch changing status to 'active', request with id '74eed847-ca25-4e76-8cf2-f2c2d7842a7a' | HTTP Status 200 and OperationOutcome                          |
        | Successful access level update  | Valid patch modifying the role end date, request with id '6b71ac92-baa3-4b76-b0f5-a601257e2722' | HTTP Status 200 and OperationOutcome                          |
        | Multiple valid changes          | Valid patch with multiple operations, request with id '43003db8-ffcd-4bd6-ab2f-b49b9656f9e5'    | HTTP Status 200 and OperationOutcome                          |
        | Valid OTHER reason code with free text   | Patch with reason code 'OTHER' and free text, id='a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7'| HTTP Status 200 and OperationOutcome                          |
        | Non-OTHER reason code without free text  | Patch with a reason code other than 'OTHER', no free text, id='b2c3d4e5-f6a7-4890-b1c2-d3e4f5a6b7c8' | HTTP Status 200 and OperationOutcome                          |
        | Non-OTHER reason code with free text     | Patch with a reason code other than 'OTHER', with free text, id='c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9' | HTTP Status 200 and OperationOutcome                          |
        | Invalid patch format            | Malformed JSON patch document, request with id '849ea584-2318-471b-a24c-cee1b5ad0137'           | HTTP Status 400 and INVALID_PATCH_FORMAT error response       |
        | Invalid path                    | Patch targeting non-existent element, request with id '01abb0c5-b1ac-499d-9655-9cd0b8d3588f'    | HTTP Status 400 and INVALID_PATCH_PATH error response         |
        | Invalid status code             | Patch with invalid status value, request with id '78c35330-fa2f-4934-a5dd-fff847f38de5'         | HTTP Status 422 and INVALID_STATUS_CODE error response        |
        | Invalid status reason           | Patch with invalid status reason value, request with id '51fb4df5-815a-45cd-8427-04d6558336b7'  | HTTP Status 422 and INVALID_STATUS_REASON error response      |
        | Resource not found              | Patch for non-existent Consent, request with an id not listed here                              | HTTP Status 404 and RESOURCE_NOT_FOUND error response         |
        | Invalid state transition        | Patch attempting invalid status change, request with id '7b7f47b8-96e5-43eb-b733-283bf1449f2c'  | HTTP Status 422 and INVALID_STATE_TRANSITION error response   |
        | Missing free text for OTHER reason code  | Patch with reason code 'OTHER' but missing free text, id='d4e8a6f2-1c3b-4a7e-9d2f-8b5c7e9f1a3d' | HTTP Status 400 and MISSING_FREE_TEXT_FOR_OTHER error response |
        | Missing grantor                 | Patch attempting to set status to 'active' without grantor extension, id='90957744-b971-496e-b7c3-ab971868ce14' | HTTP Status 400 and MISSING_GRANTOR error response            |
        | Missing grantor valueReference     | Request with grantor extension but missing valueReference, id='7e764160-38b6-41eb-9012-a3e476cbc517'  | HTTP Status 400 and MISSING_GRANTOR_REFERENCE error response             |
        | Missing grantor valueIdentifier     | Request with grantor extension but missing valueIdentifier, id='faefd8c5-5e24-4415-8252-96e9241c7e78' | HTTP Status 400 and MISSING_GRANTOR_IDENTIFIER error response             |
        | Invalid grantor ODS code value                | Request with grantor extension but missing/empty/invalid ODS code, id='b68cbfc8-ccc2-48ad-b97b-b7410d773dc1'       | HTTP Status 422 and INVALID_GRANTOR_VALUE error response                 |
        | Invalid grantor identifier system             | Request with grantor extension but wrong/missing identifier system, id='fd189522-68e5-42dc-b44c-989be0eaa2bf'     | HTTP Status 422 and INVALID_GRANTOR_SYSTEM error response                |

        ### Sandbox constraints

        The sandbox environment has the following constraints for this endpoint:

        - Request body is not validated.
        - Request headers are not tested.
        - No proxy role is updated.

      parameters:
        - $ref: "#/components/parameters/ConsentID"
      requestBody:
        required: true
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/PatchOperation"
            examples:
              statusUpdate:
                $ref: "./examples/requests/PATCH_Consent/replace_status.yaml#/StatusUpdate"
              updateProvisionEndDate:
                $ref: "./examples/requests/PATCH_Consent/replace_provision_end_date.yaml#/UpdateProvisionEndDate"
              multipleUpdates:
                $ref: "./examples/requests/PATCH_Consent/multiple_updates.yaml#/MultipleUpdates"
              policyRule:
                $ref: "./examples/requests/PATCH_Consent/replace_policy_rule.yaml#/ReplacePolicyRuleRequest"
      responses:
        "200":
          description: Consent resource successfully updated
          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              examples:
                patchConsentSuccess:
                  $ref: "./examples/responses/PATCH_Consent/success.yaml#/PatchConsentSuccess"

        "4XX":
          description: |
            Errors will be returned for the first error encountered in the request. For details, see the `diagnostics` field of error. An error occurred as follows:

            | HTTP status | Error code                  | Description                                                                                                                               |
            | ----------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
            | 400         | `MISSING_VALUE`             | Missing header or parameter. For details, see the `diagnostics` field.                                                                    |
            | 400         | `MISSING_GRANTOR`           | Grantor extension is required when creating or activating a consent with status "active". For details, see the `diagnostics` field.       |
            | 400         | `MISSING_GRANTOR_REFERENCE` | Grantor extension reference is required when creating or activating a consent with status "active". For details, see the `diagnostics` field.       |
            | 400         | `MISSING_GRANTOR_IDENTIFIER`| Grantor extension identifier is required when creating or activating a consent with status "active". For details, see the `diagnostics` field.       |
            | 400         | `INVALID_PATCH`             | Invalid patch.                                                                                                                            |
            | 400         | `INVALID_VALUE`             | Invalid Parameter or Invalid operation.                                                                                                   |
            | 401         | `ACCESS_DENIED`             | Missing or invalid OAuth 2.0 bearer token in request.                                                                                     |
            | 403         | `FORBIDDEN`                 | Access denied to resource.                                                                                                                |
            | 405         | `METHOD_NOT_ALLOWED`        | The method is not allowed.                                                                                                                |
            | 408         | `TIMEOUT`                   | Request timed out.                                                                                                                        |
            | 409         | `DUPLICATE_PATCHES`         | Two or more patches use same path.                                                                                                        |
            | 415         | `UNSUPPORTED_MEDIA`         | Unsupported media type.                                                                                                                   |
            | 422         | `INVALID_EXTENSION`         | Invalid extension.                                                                                                                        |
            | 422         | `INVALID_PATCH_PATH`        | Invalid patch path.                                                                                                                       |
            | 422         | `INVALID_STATUS_CODE`       | Invalid status code.                                                                                                                      |
            | 422         | `INVALID_STATUS_REASON`     | Invalid status reason.                                                                                                                    |
            | 422         | `INVALID_STATE_TRANSITION`  | Invalid state transition.                                                                                                                 |
            | 422         | `INVALID_LEGAL_BASIS_CODE`  | Invalid legal basis code.                                                                                                                 |
            | 422         | `INVALID_END_DATE`          | End date is invalid.                                                                                                                      |
            | 422         | `INVALID_GRANTOR_VALUE`     | Invalid grantor identifier value. For details, see the `diagnostics` field.                                                               |
            | 422         | `INVALID_GRANTOR_SYSTEM`    | Invalid grantor system value. For details, see the `diagnostics` field.                                                                   |
            | 429         | `THROTTLED`                 | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |

          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              examples:
                patchConsentInvalidPatchFormatError:
                  $ref: "./examples/responses/PATCH_Consent/errors/invalid_patch_format.yaml#/PatchConsentInvalidPatchFormatError"
                patchConsentInvalidPathError:
                  $ref: "./examples/responses/PATCH_Consent/errors/invalid_path.yaml#/PatchConsentInvalidPathError"
                patchConsentInvalidStatusCodeError:
                  $ref: "./examples/responses/PATCH_Consent/errors/invalid_status_code.yaml#/PatchConsentInvalidStatusCodeError"
                PatchConsentInvalidStatusReasonError:
                  $ref: "./examples/responses/PATCH_Consent/errors/invalid_status_reason.yaml#/PatchConsentInvalidStatusReasonError"
                patchConsentInvalidStateTransitionError:
                  $ref: "./examples/responses/PATCH_Consent/errors/invalid_state_transition.yaml#/PatchConsentInvalidStateTransitionError"
                patchConsentMissingFreeTextForOther:
                  $ref: "./examples/responses/PATCH_Consent/errors/missing_free_text_for_other.yaml#/PatchConsentMissingFreeTextForOtherError"
                patchConsentMissingGrantorError:
                  $ref: "./examples/responses/PATCH_Consent/errors/missing_grantor.yaml#/PatchConsentMissingGrantorError"
                patchConsentMissingGrantorReferenceError:
                  $ref: "./examples/responses/PATCH_Consent/errors/missing_grantor_reference.yaml#/PatchConsentMissingGrantorReferenceError"
                patchConsentMissingGrantorIdentifierError:
                  $ref: "./examples/responses/PATCH_Consent/errors/missing_grantor_identifier.yaml#/PatchConsentMissingGrantorIdentifierError"
                patchConsentInvalidGrantorIdentifierSystemError:
                  $ref: "./examples/responses/PATCH_Consent/errors/invalid_grantor_identifier_system.yaml#/PatchConsentInvalidGrantorIdentifierSystemError"
                patchConsentInvalidGrantorIdentifierValueError:
                  $ref: "./examples/responses/PATCH_Consent/errors/invalid_grantor_identifier_value.yaml#/PatchConsentInvalidGrantorIdentifierValueError"

        "5XX":
          description: |
            Errors will be returned for the first error encountered in the request. An error occurred as follows:

            | HTTP status | Error code                 | Description                                                   |
            | ----------- | -------------------------- | ------------------------------------------------------------- |
            | 500         | `SERVER_ERROR`             | An unexpected internal server error has occurred.             |
            | 501         | `NOT_IMPLEMENTED`          | API Endpoint not implemented.                                 |
            | 502         | `BAD_GATEWAY`              | Connection to the backend service failed.                     |

          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/OperationOutcome"
              examples:
                InternalServerError:
                  $ref: "./examples/responses/errors/internal-server-error.yaml#/InternalServerError"
                DownstreamServiceError:
                  $ref: "./examples/responses/errors/downstream-service-error.yaml#/DownstreamServiceError"

components:
  schemas:
    QuestionnaireResponse:
      type: object
      description: A FHIR QuestionnaireResponse
      required:
        - status
        - authored
        - source
        - subject
        - questionnaire
      properties:
        resourceType:
          type: string
          description: The FHIR resource type
          enum: ["QuestionnaireResponse"]
        status:
          type: string
          description: The position of the questionnaire response within its overall lifecycle.
          enum: ["completed"]
        authored:
          type: string
          format: date-time
          description: The date time that this set of answers were last changed.
        source:
          type: object
          description: The person who answered the questions about the subject.
          properties:
            type:
              type: string
              enum: [Patient, RelatedPerson]
            identifier:
              description: |
                The person who answered the questions about the subject NHS number. The primary identifier of a patient, unique within NHS England and Wales. Always 10 digits and must be a valid NHS number - see:
                https://www.datadictionary.nhs.uk/attributes/nhs_number.html
              properties:
                system:
                  type: string
                  description: Codesystem URL for source's NHS number.
                  enum: ["https://fhir.nhs.uk/Id/nhs-number"]
                value:
                  type: string
                  description: The source's NHS number.
        subject:
          type: object
          description: The person who is the subject.
          properties:
            type:
              type: string
              enum: [Patient]
            identifier:
              description: |
                The patient's NHS number. The primary identifier of a patient, unique within NHS England and Wales. Always 10 digits and must be a valid NHS number - see:
                https://www.datadictionary.nhs.uk/attributes/nhs_number.html
              properties:
                system:
                  type: string
                  description: Codesystem URL for the subject's NHS number.
                  enum: ["https://fhir.nhs.uk/Id/nhs-number"]
                value:
                  type: string
                  description: The subject's NHS number.
        questionnaire:
          type: string
          description: The Questionnaire that defines and organizes the questions for which answers are being provided.
        item:
          type: array
          description: A group or question item from the original questionnaire for which answers are provided.
          items:
            oneOf:
              - $ref: "#/components/schemas/QuestionnaireResponseItem_RelatedPerson"
              - $ref: "#/components/schemas/QuestionnaireResponseItem_ParentalApplicationSupplementaryDetails"
              - $ref: "#/components/schemas/QuestionnaireResponseItem_Patient"
              - $ref: "#/components/schemas/QuestionnaireResponseItem_RequestedAccess"

    QuestionnaireResponseItem_RelatedPerson:
      type: object
      required:
        - linkId
        - text
        - item
      properties:
        linkId:
          type: string
          enum: ["relatedPerson"]
        text:
          type: string
        item:
          type: array
          items:
            oneOf:
              - type: object
                required:
                  - linkId
                  - text
                  - answer
                properties:
                  linkId:
                    type: string
                    enum: ["relatedPerson_identifier"]
                  text:
                    type: string
                  answer:
                    type: array
                    minItems: 1
                    maxItems: 1
                    items:
                      oneOf:
                        - type: object
                          properties:
                            valueString:
                              type: string

              - type: object
                properties:
                  linkId:
                    type: string
                    enum: ["relatedPerson_name"]
                  text:
                    type: string
                  item:
                    type: array
                    minItems: 2
                    maxItems: 2
                    items:
                      oneOf:
                        - type: object
                          required:
                            - linkId
                            - text
                            - answer
                          properties:
                            linkId:
                              type: string
                              enum: ["relatedPerson_name_first"]
                            text:
                              type: string
                            answer:
                              type: array
                              minItems: 1
                              maxItems: 1
                              items:
                                oneOf:
                                  - type: object
                                    properties:
                                      valueString:
                                        type: string

                        - type: object
                          required:
                            - linkId
                            - text
                            - answer
                          properties:
                            linkId:
                              type: string
                              enum: ["relatedPerson_name_family"]
                            text:
                              type: string
                            answer:
                              type: array
                              minItems: 1
                              maxItems: 1
                              items:
                                oneOf:
                                  - type: object
                                    properties:
                                      valueString:
                                        type: string

              - type: object
                properties:
                  linkId:
                    type: string
                    enum: ["relatedPerson_birthDate"]
                  text:
                    type: string
                  answer:
                    type: array
                    minItems: 1
                    maxItems: 1
                    items:
                      oneOf:
                        - type: object
                          properties:
                            valueDate:
                              type: string
                              format: date

              - type: object
                required:
                  - linkId
                  - text
                  - answer
                properties:
                  linkId:
                    type: string
                    enum: ["relatedPerson_basisForAccess"]
                  text:
                    type: string
                  answer:
                    type: array
                    minItems: 1
                    maxItems: 1
                    items:
                      oneOf:
                        - type: object
                          properties:
                            valueCoding:
                              type: object
                              properties:
                                system:
                                  type: string
                                  enum:
                                    [
                                      "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                      "https://fhir.hl7.org.uk/CodeSystem/UKCore-AdditionalPersonRelationshipRole",
                                      "https://fhir.nhs.uk/STU3/CodeSystem/RARecord-ProxyRole-1",
                                    ]
                                code:
                                  type: string
                                  enum: ["PRN", "Personal", "002"]
                                display:
                                  type: string
                                  description: FHIR relationship type.
                                  enum:
                                    [
                                      "Parent",
                                      "Personal relationship with the patient",
                                      "Best interest decision made on behalf of the patient (Mental Capacity Act 2005)",
                                    ]

              - type: object
                required:
                  - linkId
                  - text
                  - answer
                properties:
                  linkId:
                    type: string
                    enum: ["relatedPerson_relationship"]
                  text:
                    type: string
                  answer:
                    type: array
                    description: The directionality of the relationship is from the RelatedPerson (proxy) to the Patient. For example, if the Patient is a child, and the RelatedPerson is the mother, the relationship would be PRN (parent). Crucially, the relationship type is defined by the role that the proxy plays in the relationship.
                    minItems: 1
                    maxItems: 1
                    items:
                      oneOf:
                        - type: object
                          properties:
                            valueCoding:
                              type: object
                              properties:
                                system:
                                  type: string
                                  enum:
                                    [
                                      "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                                      "http://terminology.hl7.org/CodeSystem/v3-RoleClass",
                                      "https://fhir.hl7.org.uk/CodeSystem/UKCore-AdditionalPersonRelationshipRole",
                                    ]
                                code:
                                  type: string
                                  enum:
                                    [
                                      "PRN",
                                      "CHILD",
                                      "SPS",
                                      "FAMMEMB",
                                      "FRND",
                                      "CAREGIVER",
                                      "SIGOTHR",
                                    ]
                                display:
                                  type: string
                                  description: FHIR relationship type.
                                  enum:
                                    [
                                      "Parent",
                                      "Child",
                                      "Partner, wife or husband",
                                      "Other family member",
                                      "Friend, neighbour or housemate",
                                      "Paid carer or support worker",
                                      "Other",
                                    ]

              - type: object
                properties:
                  linkId:
                    type: string
                    enum: ["relatedPerson_relationshipMoreinfo"]
                  text:
                    type: string
                  answer:
                    type: array
                    maxItems: 1
                    items:
                      oneOf:
                        - type: object
                          properties:
                            valueString:
                              type: string

    QuestionnaireResponseItem_ParentalApplicationSupplementaryDetails:
      type: object
      properties:
        linkId:
          type: string
          enum: ["parentalApplicationSupplementaryDetails"]
        text:
          type: string
        item:
          type: array
          items:
            oneOf:
              - type: object
                required:
                  - linkId
                  - text
                  - answer
                properties:
                  linkId:
                    type: string
                    enum:
                      [
                        "parentalApplicationSupplementaryDetails_evidenceOfResponsibility",
                      ]
                  text:
                    type: string
                  answer:
                    type: array
                    description: Evidence of responsibility
                    maxItems: 1
                    items:
                      oneOf:
                        - type: object
                          properties:
                            valueCoding:
                              type: object
                              properties:
                                system:
                                  type: string
                                  enum:
                                    [
                                      "https://fhir.nhs.uk/CodeSystem/Proxy-Placeholder-EvidenceOfResponsibility",
                                    ]
                                code:
                                  type: string
                                  enum:
                                    [
                                      "BRTH",
                                      "ADPT",
                                      "PRNA",
                                      "SPRNA",
                                      "PORD",
                                      "SGORD",
                                      "OTHCOURT",
                                      "OTHR",
                                    ]
                                display:
                                  type: string
                                  description: Evidence of responsibility type.
                                  enum:
                                    [
                                      "Birth certificate",
                                      "Adoption certificate",
                                      "Court-witnessed parental responsibility agreement",
                                      "Court-witnessed step-parent parental responsibility agreement",
                                      "Parental order",
                                      "Special guardianship order",
                                      "Other court order",
                                      "Other",
                                    ]

              - type: object
                properties:
                  linkId:
                    type: string
                    enum:
                      [
                        "parentalApplicationSupplementaryDetails_evidenceOfResponsibilityMoreinfo",
                      ]
                  text:
                    type: string
                  answer:
                    type: array
                    items:
                      oneOf:
                        - type: object
                          properties:
                            valueString:
                              type: string
              - type: object
                required:
                  - linkId
                  - text
                  - answer
                properties:
                  linkId:
                    type: string
                    enum:
                      [
                        "parentalApplicationSupplementaryDetails_isCurrentAddressConfirmed",
                      ]
                  text:
                    type: string
                  answer:
                    type: array
                    items:
                      oneOf:
                        - type: object
                          properties:
                            valueString:
                              type: string

              - type: object
                properties:
                  linkId:
                    type: string
                    enum: ["parentalApplicationSupplementaryDetails_newAddress"]
                  text:
                    type: string
                  item:
                    type: array
                    items:
                      oneOf:
                        - type: object
                          properties:
                            linkId:
                              type: string
                              enum:
                                [
                                  "parentalApplicationSupplementaryDetails_line1",
                                ]
                            text:
                              type: string
                            answer:
                              type: array
                              items:
                                oneOf:
                                  - type: object
                                    properties:
                                      valueString:
                                        type: string
                        - type: object
                          properties:
                            linkId:
                              type: string
                              enum:
                                [
                                  "parentalApplicationSupplementaryDetails_line2",
                                ]
                            text:
                              type: string
                            answer:
                              type: array
                              items:
                                oneOf:
                                  - type: object
                                    properties:
                                      valueString:
                                        type: string
                        - type: object
                          properties:
                            linkId:
                              type: string
                              enum:
                                [
                                  "parentalApplicationSupplementaryDetails_line3",
                                ]
                            text:
                              type: string
                            answer:
                              type: array
                              items:
                                oneOf:
                                  - type: object
                                    properties:
                                      valueString:
                                        type: string

                        - type: object
                          properties:
                            linkId:
                              type: string
                              enum:
                                ["parentalApplicationSupplementaryDetails_city"]
                            text:
                              type: string
                            answer:
                              type: array
                              items:
                                oneOf:
                                  - type: object
                                    properties:
                                      valueString:
                                        type: string
                        - type: object
                          properties:
                            linkId:
                              type: string
                              enum:
                                [
                                  "parentalApplicationSupplementaryDetails_district",
                                ]
                            text:
                              type: string
                            answer:
                              type: array
                              items:
                                oneOf:
                                  - type: object
                                    properties:
                                      valueString:
                                        type: string
                        - type: object
                          properties:
                            linkId:
                              type: string
                              enum:
                                [
                                  "parentalApplicationSupplementaryDetails_postalCode",
                                ]
                            text:
                              type: string
                            answer:
                              type: array
                              items:
                                oneOf:
                                  - type: object
                                    properties:
                                      valueString:
                                        type: string

              - type: object
                required:
                  - linkId
                  - text
                  - answer
                properties:
                  linkId:
                    type: string
                    enum:
                      [
                        "parentalApplicationSupplementaryDetails_liveAtSameAddress",
                      ]
                  text:
                    type: string
                  answer:
                    type: array
                    items:
                      oneOf:
                        - type: object
                          properties:
                            valueString:
                              type: string

              - type: object
                required:
                  - linkId
                  - text
                  - answer
                properties:
                  linkId:
                    type: string
                    enum:
                      [
                        "parentalApplicationSupplementaryDetails_canChildConsent",
                      ]
                  text:
                    type: string
                  answer:
                    type: array
                    items:
                      oneOf:
                        - type: object
                          properties:
                            valueString:
                              type: string
              - type: object
                properties:
                  linkId:
                    type: string
                    enum:
                      [
                        "parentalApplicationSupplementaryDetails_reasonNoChildConsent",
                      ]
                  text:
                    type: string
                  answer:
                    type: array
                    items:
                      oneOf:
                        - type: object
                          properties:
                            valueString:
                              type: string

    QuestionnaireResponseItem_Patient:
      type: object
      required:
        - linkId
        - text
        - item
      properties:
        linkId:
          type: string
          enum: ["patient"]
        text:
          type: string
        item:
          type: array
          items:
            oneOf:
              - type: object
                required:
                  - linkId
                  - text
                  - answer
                properties:
                  linkId:
                    type: string
                    enum: ["patient_identifier"]
                  text:
                    type: string
                  answer:
                    type: array
                    minItems: 1
                    maxItems: 1
                    items:
                      oneOf:
                        - type: object
                          properties:
                            valueString:
                              type: string

              - type: object
                properties:
                  linkId:
                    type: string
                    enum: ["patient_name"]
                  text:
                    type: string
                  item:
                    type: array
                    minItems: 2
                    maxItems: 2
                    items:
                      oneOf:
                        - type: object
                          required:
                            - linkId
                            - text
                            - answer
                          properties:
                            linkId:
                              type: string
                              enum: ["patient_name_first"]
                            text:
                              type: string
                            answer:
                              type: array
                              minItems: 1
                              maxItems: 1
                              items:
                                oneOf:
                                  - type: object
                                    properties:
                                      valueString:
                                        type: string

                        - type: object
                          required:
                            - linkId
                            - text
                            - answer
                          properties:
                            linkId:
                              type: string
                              enum: ["patient_name_family"]
                            text:
                              type: string
                            answer:
                              type: array
                              minItems: 1
                              maxItems: 1
                              items:
                                oneOf:
                                  - type: object
                                    properties:
                                      valueString:
                                        type: string

              - type: object
                properties:
                  linkId:
                    type: string
                    enum: ["patient_birthDate"]
                  text:
                    type: string
                  answer:
                    type: array
                    minItems: 1
                    maxItems: 1
                    items:
                      oneOf:
                        - type: object
                          properties:
                            valueDate:
                              type: string
                              format: date

    QuestionnaireResponseItem_RequestedAccess:
      type: object
      required:
        - linkId
        - text
        - item
      properties:
        linkId:
          type: string
          enum: ["requestedAccess"]
        text:
          type: string
        item:
          type: array
          items:
            oneOf:
              - type: object
                required:
                  - linkId
                  - text
                  - answer
                properties:
                  linkId:
                    type: string
                    enum: ["requestedAccess_accessLevel"]
                  text:
                    type: string
                  answer:
                    type: array
                    minItems: 1
                    description: A multiple option selection where multiple access levels can be selected
                    items:
                      oneOf:
                        - type: object
                          properties:
                            valueCoding:
                              type: object
                              properties:
                                system:
                                  type: string
                                  enum:
                                    [
                                      "https://fhir.nhs.uk/CodeSystem/Proxy-Placeholder-RequestedAccess",
                                    ]
                                code:
                                  type: string
                                  enum:
                                    - "PRESCR"
                                    - "APPT"
                                    - "RECRD"
                                    - "TEST"
                                    - "VACC"
                                    - "COND"
                                    - "CONSULT"
                                    - "DOCS"
                                display:
                                  type: string
                                  description: FHIR Requested access level.
                                  enum:
                                    - "Request and manage repeat prescriptions"
                                    - "Appointment Booking"
                                    - "GP Health Records Access"
                                    - "Test Results"
                                    - "Vaccination Records"
                                    - "Health Conditions"
                                    - "Consultations and Events"
                                    - "Documents"

              - type: object
                required:
                  - linkId
                  - text
                  - answer
                properties:
                  linkId:
                    type: string
                    enum: ["requestedAccess_reasonsForAccess"]
                  text:
                    type: string
                  answer:
                    type: array
                    minItems: 1
                    description: A multiple option selection where multiple reasons can be selected
                    items:
                      oneOf:
                        - type: object
                          properties:
                            valueCoding:
                              type: object
                              properties:
                                system:
                                  type: string
                                  enum:
                                    [
                                      "https://fhir.nhs.uk/CodeSystem/Proxy-Placeholder-ReasonForAccess",
                                    ]
                                code:
                                  type: string
                                  enum:
                                    - "COMB"
                                    - "MHEA"
                                    - "PHYS"
                                    - "PRAC"
                                    - "TECH"
                                    - "NEUR"
                                    - "LRN"
                                    - "OTHR"
                                    - "NotSpecified"
                                display:
                                  type: string
                                  description: FHIR Reason for access.
                                  enum:
                                    - "Communication Barriers"
                                    - "Mental Health Condition"
                                    - "Physical Condition"
                                    - "Practical Reasons"
                                    - "Technical Barriers"
                                    - "Neurodiverse"
                                    - "Learning Disability"
                                    - "Other"
                                    - "Prefer not to say"

              - type: object
                properties:
                  linkId:
                    type: string
                    enum: ["requestedAccess_reasonsForAccessMoreinfo"]
                  text:
                    type: string
                  answer:
                    type: array
                    items:
                      oneOf:
                        - type: object
                          properties:
                            valueString:
                              type: string

    BaseBundle:
      type: object
      description: A FHIR Bundle.
      properties:
        resourceType:
          type: string
          description: FHIR resource type.
          enum: [Bundle]
        timestamp:
          type: string
          format: date-time
          description: The UTC date and time the search results were returned.
        total:
          type: number
          description: |
            The number of resources contained within the Bundle.

    Searchset:
      allOf:
        - $ref: "#/components/schemas/BaseBundle"
        - type: object
          properties:
            type:
              type: string
              description: Denotes that the Bundle is a collection of resources returned as a result of a search.
              enum: [searchset]

    Link:
      type: object
      properties:
        link:
          type: array
          description: Links related to the entry
          items:
            type: object
            properties:
              relation:
                type: string
                description: |
                  A name which details the functional use for this link - see:
                  http://www.iana.org/assignments/link-relations/link-relations.xhtml#link-relations-1
              url:
                type: string
                format: uri
                description:  The reference details for the link.

    RelatedPersonBundle:
      allOf:
        - $ref: "#/components/schemas/Searchset"
        - type: object
          properties:
            link:
              type: array
              items:
                type: object
                properties:
                  relation:
                    type: string
                    description: |
                      Links related to this Bundle - see:
                      http://www.iana.org/assignments/link-relations/link-relations.xhtml
                  url:
                    type: string
                    format: uri
            entry:
              type: array
              description: |
                A collection of resources contained within the Bundle.

                An empty bundle suggests that no candidate proxy/patient links were identified.
              items:
                anyOf:
                  - $ref: "#/components/schemas/RelatedPersonWithDetailsBundleEntry"
                  - $ref: "#/components/schemas/PatientBundleEntry"

    ConsentBundle:
      allOf:
        - $ref: "#/components/schemas/Searchset"
        - $ref: "#/components/schemas/Link"
        - type: object
          properties:
            entry:
              type: array
              description: |
                A collection of resources contained within the Bundle.

                An empty bundle suggests that the proxy has no proxy relationships.
              items:
                anyOf:
                  - $ref: "#/components/schemas/RelatedPersonBundleEntry"
                  - $ref: "#/components/schemas/PatientBundleEntry"
                  - $ref: "#/components/schemas/ConsentBundleEntry"

    RelatedPersonWithDetailsBundleEntry:
      type: object
      allOf:
        - $ref: "#/components/schemas/RelatedPersonBundleEntry"
        - type: object
          description: A RelatedPerson bundle entry with patient name and birthDate.
          properties:
            resource:
              allOf:
                - $ref: "#/components/schemas/RelatedPerson"
                - type: object
                  properties:
                    name:
                      $ref: "#/components/schemas/PDSName"
                    birthDate:
                      $ref: "#/components/schemas/PDSBirthDate"

    RelatedPersonBundleEntry:
      type: object
      description: A RelatedPerson bundle entry.
      properties:
        fullUrl:
          type: string
          description: The canonical URL of the resource in the entry
        resource:
          $ref: "#/components/schemas/RelatedPerson"
        search:
          type: object
          properties:
            mode:
              type: string
              enum:
                - match
                - include
              example: match

    PatientBundleEntry:
      type: object
      description: A Patient bundle entry.
      properties:
        fullUrl:
          type: string
          description: The canonical URL of the resource in the entry
        resource:
          $ref: "#/components/schemas/Patient"
        search:
          type: object
          properties:
            mode:
              type: string
              enum:
                - match
                - include
              example: match

    ConsentBundleEntry:
      type: object
      description: A Consent bundle entry.
      properties:
        fullUrl:
          type: string
          description: The canonical URL of the resource in the entry
        resource:
          $ref: "#/components/schemas/ReadConsent"
        search:
          type: object
          properties:
            mode:
              type: string
              enum:
                - match
                - include
              example: match

    RelatedPerson:
      type: object
      description: The proxy's details. This includes their relationship to the referenced patient.
      properties:
        resourceType:
          type: string
          description: FHIR resource type.
          enum: [RelatedPerson]
          default: RelatedPerson
        id:
          type: string
          description: Unique identifier of the RelatedPerson resource.
        identifier:
          type: array
          description: The proxy's NHS number. The primary identifier of a patient, unique within NHS England and Wales. Always 10 digits and must be a [valid NHS number](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).
          items:
            type: object
            properties:
              system:
                type: string
                description: Codesystem URL for the proxy's NHS number.
                enum:
                  [
                    "https://fhir.nhs.uk/Id/nhs-number",
                  ]
              value:
                type: string
                description: The proxy's NHS number.
        patient:
          type: object
          description: A reference to a patient the proxy is related to.
          properties:
            type:
              type: string
              description: FHIR resource type.
              enum: ["Patient"]
            identifier:
              type: object
              description: The patient's NHS number. The primary identifier of a patient, unique within NHS England and Wales. Always 10 digits and must be a [valid NHS number](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).
              properties:
                system:
                  type: string
                  description: Codesystem URL for the patient's NHS number.
                  enum: ["https://fhir.nhs.uk/Id/nhs-number"]
                value:
                  type: string
                  description: The patient's NHS number.
        relationship:
          type: array
          description: How the proxy is related to the patient.
          items:
            type: object
            properties:
              coding:
                type: array
                description: FHIR coding array.
                items:
                  type: object
                  properties:
                    system:
                      type: string
                      description: FHIR codesystem.
                      default: "http://terminology.hl7.org/CodeSystem/v3-RoleCode"
                      enum:
                        [
                          "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                          "https://fhir.hl7.org.uk/CodeSystem/UKCore-AdditionalPersonRelationshipRole",
                        ]
                    code:
                      type: string
                      description: FHIR relationship type code.
                      enum:
                        - "MTH"
                        - "PRN"
                        - "Personal"
                        - "CHILD"
                    display:
                      type: string
                      description: FHIR relationship type.
                      enum:
                        - "mother"
                        - "parent"
                        - "Personal relationship with the patient"
                        - "child"

    Patient:
      type: object
      description: The patient's details.
      properties:
        resourceType:
          type: string
          description: FHIR resource type.
          enum: [Patient]
          default: Patient
        id:
          type: string
          description: Unique identifier of the Patient resource
        meta:
          type: object
          description: Metadata about a resource
          properties:
            security:
              type: array
              description: Security Labels applied to this resource
              items:
                $ref: "#/components/schemas/Coding"
        identifier:
          type: array
          description: The primary identifier of a patient. Possible identifiers include the NHS number or local GP patient identifier. If it is an NHS number, it will always 10 digits and must be a [valid NHS number](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).
          items:
            type: object
            properties:
              system:
                type: string
                description: Codesystem URL for the identifier.
                enum:
                  [
                    "https://fhir.nhs.uk/Id/nhs-number"
                  ]
              value:
                type: string
                description: The identifier value (e.g. NHS number).
        name:
          $ref: "#/components/schemas/PDSName"
        birthDate:
          $ref: "#/components/schemas/PDSBirthDate"
        generalPractitioner:
          type: array
          description: Patient's nominated primary care provider, each a Reference(Organization | Practitioner | PractitionerRole).
          items:
            $ref: "#/components/schemas/Reference"

    Consent:
      type: object
      required:
        - id
        - status
        - scope
        - category
        - patient
        - dateTime
        - extension
      description: The details of the consent including who the patient and care "performer" are, status of the relationship and whether consent was given by a patient with capacity.
      properties:
        resourceType:
          type: string
          description: FHIR resource type.
          enum:
            - Consent
          default: Consent
        id:
          type: string
          description: Unique identifier of the Consent resource
        status:
          type: string
          description: "The status of the consent, following the ConsentStateCodes value set. See more information about this codesystem in the [FHIR specification](http://hl7.org/fhir/R4/codesystem-consent-state-codes.html)."
          enum:
            - proposed
            - active
            - rejected
            - inactive
            - entered-in-error
        scope:
          $ref: "#/components/schemas/CodeableConcept"
          description: "The scope of the consent, bound to http://terminology.hl7.org/CodeSystem/consentscope"
        category:
          type: array
          items:
            $ref: "#/components/schemas/CodeableConcept"
          description: "Classification of the type of consent, bound to http://terminology.hl7.org/CodeSystem/v3-ActCode."
        patient:
          $ref: "#/components/schemas/Reference"
          description: "The patient who is the subject of the consent."
        dateTime:
          type: string
          format: date-time
          description: "Date and time when the consent was created."
        performer:
          type: array
          maxItems: 1
          items:
            $ref: "#/components/schemas/Reference"
          description: "Individuals or organizations that agreed to the consent."
        policy:
          type: array
          items:
            $ref: "#/components/schemas/Policy"
        policyRule:
          type: array
          items:
            $ref: "#/components/schemas/CodeableConcept"
        provision:
          $ref: "#/components/schemas/Provision"
        extension:
          type: array
          items:
            anyOf:
              - $ref: "#/components/schemas/StatusReasonExtension"
              - $ref: "#/components/schemas/GrantorExtension"
          description: "Additional content. For active proxy roles, grantor is required."

    ReadConsent:
      allOf: # Extends the Consent model
        - $ref: "#/components/schemas/Consent"
        - type: object
          properties:
            meta:
              type: object
              description: "Metadata about a resource"
              properties:
                lastUpdated:
                  type: string
                  format: date-time
                  description: "When the resource version last changed"

    Policy:
      type: object
      properties:
        authority:
          type: string
          description: "Entity or Organization having regulatory jurisdiction or accountability for enforcing policies pertaining to Consent Directives."
          format: uri
        uri:
          type: string
          description: "The references to the policies that are included in this consent scope. Policies may be organizational, but are often defined jurisdictionally, or in law."
          format: uri

    Provision:
      type: object
      description: "Constraints to the base Consent policy rule, which may be enforced over time."
      properties:
        type:
          type: string
          description: "Action to take for this provision of the consent."
          enum:
            - permit
            - deny
        period:
          type: object
          description: "The start date on which the proxy role was granted, and (optionally) an end date for time-bound access."
          properties:
            start:
              type: string
              description: "Starting time with inclusive boundary"
              format: date-time
            end:
              type: string
              description: "End time with inclusive boundary, if not ongoing"
              format: date-time
        actor:
          type: array
          description: "Individuals or organisations involved in the provision"
          items:
            type: object
            properties:
              reference:
                $ref: "#/components/schemas/Reference"
                description: "Individuals or organizations that agreed to the consent"
              role:
                $ref: "#/components/schemas/CodeableConcept"
                description: "Deprecated. Instead use policyRule."
                deprecated: true

    StatusReasonExtension:
      type: object
      properties:
        url:
          type: string
          enum:
          - "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-Consent-Status-Reason"
        valueCodeableConcept:
          $ref: "#/components/schemas/CodeableConcept"
          description: Classification of the status.

    GrantorExtension:
      type: object
      properties:
        url:
          type: string
          enum:
            - "https://hl7.org/fhir/5.0/StructureDefinition/extension-Consent.grantor"
        valueReference:
          type: object
          properties:
            identifier:
              $ref: "#/components/schemas/Identifier"
              description: "The ODS code of the GP practice that granted the proxy role"

    OperationOutcome:
      type: object
      description: |
        Outcome of an operation that does not result in a resource or bundle being returned, for example an error or an async/batch submission.
        There are a number of possible error codes that can be returned along with a more detailed description in the `display` field.
      properties:
        resourceType:
          type: string
          description: FHIR Resource Type.
          default: OperationOutcome
        issue:
          type: array
          description: List of issues that have occurred.
          minItems: 1
          items:
            type: object
            required:
              - severity
              - code
            properties:
              severity:
                type: string
                enum: [fatal, error, warning, information]
                description: Severity of the error.
              code:
                type: string
                description: FHIR error code.
                enum:
                  - exception
                  - forbidden
                  - informational
                  - invalid
                  - not-found
                  - not-supported
                  - processing
                  - required
              details:
                type: object
                description: Internal error code.
                properties:
                  coding:
                    type: array
                    items:
                      type: object
                      properties:
                        system:
                          type: string
                          description: URI of the coding system specification.
                        version:
                          type: string
                          description: Version of the coding system in use.
                        code:
                          type: string
                          description: Symbol in syntax defined by the system.
                        display:
                          type: string
                          description: Representation defined by the system.
              diagnostics:
                type: string
                description: Additional diagnostic information about the issue. This information is subject to change.
              expression:
                type: array
                description: FHIRPath of element(s) related to the error.
                items:
                  type: string

    Reference:
      type: object
      required:
        - identifier
      properties:
        identifier:
          $ref: "#/components/schemas/Identifier"

    Identifier:
      type: object
      required:
        - system
        - value
      properties:
        system:
          type: string
          description: "The namespace for the identifier."
        value:
          type: string
          description: "The value that is unique."

    CodeableConcept:
      type: object
      properties:
        coding:
          type: array
          items:
            $ref: "#/components/schemas/Coding"
        text:
          type: string
          description: "Plain text representation of the concept."

    Coding:
      type: object
      properties:
        system:
          type: string
          description: "The identification of the code system that defines the meaning of the code."
        code:
          type: string
          description: "The actual code from the code system."
        display:
          type: string
          description: "A human-readable representation of the code."

    PatchOperation:
      type: object
      required:
        - op
        - path
      properties:
        op:
          type: string
          enum: [add, remove, replace]
        path:
          type: string
          oneOf:
            - description: "Static paths that do not require an index."
              enum:
                - /status
                - /extension/-
                - /provision/period/end
                - /provision/actor
        value:
          oneOf:
            - type: string
            - type: array
              items:
                type: object

    PDSName:
      type: array
      description: List of names associated with the patient.
      items:
        type: object
        required:
          - use
        additionalProperties: false
        properties:
          id:
            type: string
            description: Unique object identifier for this name.
          use:
            type: string
            description: |
              How this name should be used.
              * usual - Known as, conventional or the one patient normally uses. A patient always has a usual name.
              * temp - An alias or temporary name. This may also be used for temporary names assigned at birth or in emergency situations.
              * nickname - A name that the patient prefers to be addressed by, but is not part of their usual name.
              * old - This name is no longer in use (or was never correct, but retained for records).
              * maiden - Name changed for Marriage. A name used prior to changing name because of marriage. This term is not gender specific. The use of this term does not imply any particular history for a person's name.

              The following use codes are included in the [name-use](https://www.hl7.org/fhir/valueset-name-use.html) value set, but should not be used and is not be returned as part of a retrieval.
              * official - The formal name as registered in an official (government) registry, but which name might not be commonly used. May be called "legal name".
              * anonymous - Anonymous assigned name, alias, or pseudonym (used to protect a person's identity for privacy reasons).
            enum: [usual, temp, nickname, old, maiden]
          period:
            type: object
            description: |
              Business effective period when the name was, is, or will be in use.
            required:
              - start
            properties:
              start:
                type: string
                format: date
                description: Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.
              end:
                type: string
                format: date
                description: End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.
          given:
            type: array
            maxItems: 5
            description: |
              Given names, including any middle names.

              Each name(s) should be a separate item in the list. The first given name may include multiple names, separated by a space.
              Subsequent names must be broken down into list items. For example, the input `[Jane Marie Anne, Jo Adele]` returns `[Jane Marie Anne, Jo, Adele]`.

            items:
              type: string
              maxLength: 35
          family:
            type: string
            maxLength: 35
            description: Family name (often called Surname).
          prefix:
            type: array
            description: Name prefixes, titles, and prenominals.
            items:
              type: string
          suffix:
            type: array
            description: Name suffices and postnominals.
            items:
              type: string
          text:
            type: string
            description: Text representation of the full name

    PDSBirthDate:
      description: |
        The date on which the patient was born or is officially deemed to have been born.

        It is a date in the format `yyyy-mm-dd`. Due to data quality issues on a small number of patients `yyyy-mm` and `yyyy` format may also be returned.
      type: string
      format: date

  parameters:
    RelatedPersonIdentifier:
      in: query
      name: identifier
      description: |
        The proxy's NHS number. For more information on FHIR tokens in general, [see here](https://build.fhir.org/search.html#token).
      required: false
      schema:
        type: string
        format: token
      examples:
        withoutSystem:
          value: 9000000017
          summary: NHS number specified without system.
        withSystem:
          value: https://fhir.nhs.uk/Id/nhs-number|9000000017
          summary: System and NHS number specified

    PatientIdentifier:
      in: query
      name: patient:identifier
      description: |
        The patient's NHS number. For more information on FHIR tokens in general, [see here](https://build.fhir.org/search.html#token).
      required: false
      schema:
        type: string
        format: token
      examples:
        withoutSystem:
          value: 9000000009
          summary: NHS number specified without system
        withSystem:
          value: https://fhir.nhs.uk/Id/nhs-number|9000000009
          summary: System and NHS number specified

    ConsentBundlePerformerIdentifier:
      in: query
      name: performer:identifier
      description: |
        The performer's (Proxy) NHS number. For more information on FHIR tokens in general, [see here](https://build.fhir.org/search.html#token).
      required: false
      schema:
        type: string
        format: token
      examples:
        withoutSystem:
          value: 9000000017
          summary: NHS number specified without system
        withSystem:
          value: https://fhir.nhs.uk/Id/nhs-number|9000000017
          summary: System and NHS number specified

    ConsentBundlePatientIdentifier:
      in: query
      name: patient:identifier
      description: |
        The patient's NHS number. For more information on FHIR tokens in general, [see here](https://build.fhir.org/search.html#token).
      required: false
      schema:
        type: string
        format: token
      examples:
        withoutSystem:
          value: 9000000017
          summary: NHS number specified without system
        withSystem:
          value: https://fhir.nhs.uk/Id/nhs-number|9000000017
          summary: System and NHS number specified

    RelatedPersonBundleIncludes:
      in: query
      name: _include
      description: |
        Include referenced resources in the bundle response by specifying one or more `_include` parameters. Further info [here](https://www.hl7.org/fhir/search.html#_include).
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
          enum:
            - "RelatedPerson:patient"
      examples:
        IncludePatient:
          summary: Include the patient in the bundle
          value:
            - "RelatedPerson:patient"

    ConsentBundleIncludes:
      in: query
      name: _include
      description: Include referenced resources in the bundle response by specifying one or more `_include` parameters. Further info [here](https://www.hl7.org/fhir/search.html#_include).
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
          enum:
            - "Consent:performer"
            - "Consent:patient"
        default:
          - "Consent:performer"
          - "Consent:patient"
      examples:
        FullInclude:
          summary: Include the performer (proxy) and patient in the bundle
          value:
            - "Consent:performer"
            - "Consent:patient"
        IncludePerformer:
          summary: Include the performer (proxy) in the bundle
          value: Consent:performer
        IncludePatient:
          summary: Include the patient in the bundle
          value: Consent:patient

    ConsentStatus:
      in: query
      name: status
      description: >
        Specify one or more `status` values to filter the records returned in the bundle.


        Supports FHIR search conventions:

        - **OR** — comma-separated values within a single parameter, e.g. `status=active,proposed` returns records with status `active` _or_ `proposed`.

        - **AND** — repeated parameters, e.g. `status=active&status=proposed`. For a single-valued field like `status`, AND groups are intersected; disjoint groups will return no results.

        - **AND of ORs** — e.g. `status=active,proposed&status=inactive`.


        Valid status values are bound to the http://hl7.org/fhir/consent-state-codes CodeSystem: `proposed`, `active`, `rejected`, `inactive`, `entered-in-error`.
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
          description: >
            A single status value, or a comma-separated list of status values representing an OR group.
            Valid values are: `proposed`, `active`, `rejected`, `inactive`, `entered-in-error`.
      examples:
        Active:
          summary: Only active authorised proxy relationships
          value: active
        Revoked:
          summary: Only revoked proxy relationships
          value: inactive
        ActiveOrProposed:
          summary: Active OR proposed (but not yet authorised) proxy relationships
          value:
            - proposed,active

    BearerAuthorization:
      in: header
      name: Authorization
      description: |
        An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis).
      required: true
      schema:
        type: string
        format: '^Bearer\ [[:ascii:]]+$'
        example: "Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"

    RequestID:
      in: header
      name: X-Request-ID
      required: true
      description: |
        A globally unique identifier (GUID) for the request, which we use to correlate logs through different components.
        Must be a universally unique identifier (UUID) (ideally version 4).
        Mirrored back in a response header.
      schema:
        type: string
        format: uuid
        pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
        example: 60E0B220-8136-4CA5-AE46-1D97EF59D068

    CorrelationID:
      in: header
      name: X-Correlation-ID
      required: false
      description: |
        An optional ID which you can use to track transactions across multiple systems.
        Must be a universally unique identifier (UUID) (ideally version 4).
        Mirrored back in a response header.
      schema:
        type: string
        format: uuid
        pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
        example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA

    Im1ConnectionParams:
      in: header
      name: X-IM1-Connection-Params
      required: false
      description: |
        An optional `;` delimited string containing parameters required to refresh proxy relationships from GPIT supplier systems. Parameters that comprise this string are:

        - IM1 User Connection token
        - ODS Code
      schema:
        type: string
        pattern: "^[^;]+;[^;]+$"
        example: NiV3CyMJH3xYV26ghlVpbbjT7pDVEA8HpFczAjRLTs1VezC4CYzupZ3XxXAWM7ELuseqrV8r0Ill7EL7G2tXUaVHCPWgg4q10+MxFjnRPrjDvckBRSZazqZcp0K2VBdUV0rZ7RUYJNJsjVAeefWhiK/Y4R+GFO86QDpt41JS9xA=;G123456

    ConsentID:
      in: path
      name: id
      required: true
      description: The logical id of the Consent resource
      schema:
        type: string
        format: uuid
        pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
        example: 74eed847-ca25-4e76-8cf2-f2c2d7842a7a

    AccessRequestID:
      in: path
      name: id
      required: true
      description: The unique access request ID of the QuestionnaireResponse to retrieve
      schema:
        type: string
        format: uuid
        pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
        example: "156e1560-e532-4e2a-85ad-5aeff03dc43e"