{"openapi":"3.0.3","info":{"title":"Directory of Services Search API","description":"## Overview\nUse this API to access healthcare services details profiled in the Directory of Services. This API provides read-only access to the data held in the directory.\n\nYou can:\n- obtain Organisation details (including endpoints managed by the Organisation) for a given Organisation ODS Code\n\nIn the future you will be able to:\n- obtain Organisation details (including endpoints managed by the Organisation) for a given service Identifier\n\n## Who can use this API\nThis API can only be used where you have a valid use case to do so. Please [contact us](https://digital.nhs.uk/developer/help-and-support) before you go too far with your development.\nYou must do this before you can go live (see 'Onboarding' below).\n\n## Access modes\nThis API supports the following access modes:\n- restricted access\n\n### Restricted access\nThis is the only access mode supported by the API and it is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis), meaning we authenticate and authorise the calling application but not the end user. This mode is used as part of a back-end process to retrieve healthcare service details.\n\nThis access mode adopts the following security/authentication patterns:\n- JWT Private Key authentication\n\n## Roadmap\nOver 2026 and 2027, we will be making further endpoints available covering the functionality of:\n\n- [Directory of Services - Urgent and Emergency Care - SOAP API](https://digital.nhs.uk/developer/api-catalogue/directory-of-services-urgent-and-emergency-care-soap)\n- [Directory of Services - Urgent and Emergency Care - REST API](https://digital.nhs.uk/developer/api-catalogue/directory-of-services-urgent-and-emergency-care-rest)\n- [Electronic Prescription Service Directory of Services API](https://digital.nhs.uk/developer/api-catalogue/electronic-prescription-service-directory-of-services)\n\n## Service level\nBusiness hours support between 8am and 6pm, Monday to Friday, but not bank holidays.\n\nFor more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels)\n\n## Rate limits\nThe default rate limit is 10TPS (Transactions Per Second), per app.\n\nIf you exceed this limit, you will receive a 429 'Too Many Requests' response. For more information, see [rate limits](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits)\n\n## Technology\nThis API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest).\n\nIt conforms to the FHIR UK Core STU3 v0.0.6, based on FHIR R4 v4.0.1\n\nYou do not need to know much about [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir) to use this API - FHIR APIs are just RESTful APIs that follow specific rules. In particular:\n- resource names are capitalised and singular, for example /Patient not /patients\n- array names are singular, for example entry not entries for Bundle entries\n- data items that are country-specific and thus not included in the FHIR global base resources are usually wrapped in an extension object.\n\nThere 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.\n\n## Data Dictionary\n\n| Field Name | Type | Description |\n|------------|------|-------------|\n| `Organization.id` | `string` | Internal UUID identifying the Organisation |\n| `Organization.identifier` | `string` | Stores the ODS (Organisation Data Service) code identifying the Organisation |\n| `Organization.active` | `boolean` | Whether the Organisation's record is still in active use |\n| `Organization.name` | `string` | Name used for the Organisation |\n| `Endpoint.id` | `string` | Internal UUID identifying the Endpoint |\n| `Endpoint.extension Extension-England-OrganizationEndpointOrder` | `integer` | When multiple endpoints are returned for an Organisation, we need to know the order so that we communicate with the right system first. |\n| `Endpoint.extension Extension-England-EndpointCompression` | `boolean` | Whether the Endpoint uses compression. Compression reduces bandwidth requirements and can reduce messaging delays and/or failure. |\n| `Endpoint.extension Extension-England-EndpointBusinessScenario` | `enum` | Indicates the business scenario for which an Endpoint is intended, particularly distinguishing between primary message recipients and copy recipients for NHS England messaging scenarios. Possible values: |\n| `Endpoint.status` | `enum` | The status of the Endpoint. This tells you if the Endpoint is currently in use. Possible values: |\n| `Endpoint.connectionType` | `enum` | Protocol/Profile/Standard to be used with this Endpoint connection. Values include: |\n| `Endpoint.managingOrganization` | `string` | A FHIR reference to the Organisation that manages this Endpoint (might not be the Organisation that exposes the Endpoint) |\n| `Endpoint.payloadType` | `enum` | The type of content that may be used at this Endpoint (e.g. XDS Discharge summaries). Values include: |\n| `Endpoint.payloadMimeType` | `enum` | The mime type of the payload to be delivered to this Endpoint. Values include: |\n| `Endpoint.address` | `string` | The technical base address for connecting to this Endpoint |\n\n## Network access\nThis API is available over the internet.\n\nThis API is accessible from the public internet using standard HTTPS connections. See access mode section for authentication methods.\n\nThis API does not support static IP hosting. The IP addresses that host this API are dynamic and subject to change without notice.\n\n## Errors\nWe use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:\n- 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action\n- 400 to 499 if it failed because of a client error by your application\n- 500 to 599 if it failed because of an error on our server.\n\n- Errors specific to each API endpoint are shown in the Endpoints section under Response.\n- See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.\n- For 404 errors, see [404 resource not found](https://digital.nhs.uk/developer/guides-and-documentation/troubleshooting-4xx-status-codes#404-resource_not_found).\n- For 5xx errors, see [trouble shooting 5xx status codes](https://digital.nhs.uk/developer/guides-and-documentation/troubleshooting-5xx-status-codes).\n- Your API-calling application should automatically retry failed requests where appropriate (for example, by giving status information to your end user before giving up).\n- See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#error-handling) for more information about error handling.\n\n## Environments and testing\n\n### Sandbox testing\nOur [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, and is open access, so does not allow you to test authorisation.\nLink to sandbox test environment: `https://sandbox.api.service.nhs.uk/dos-search/FHIR/R4`\n\n### Integration testing\nOur [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing) is for formal integration testing and includes authorisation via JWT Private Key.\nLink to integration test environment: `https://int.api.service.nhs.uk/dos-search/FHIR/R4`\n\n## Onboarding\nYou 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.\n\nFor more information about the onboarding process, see [digital onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding).\n\n## Open source\nYou might find it useful to know that the [FHIR specification](https://www.hl7.org/fhir/) is open source and available on GitHub.\n\n## Related APIs\nThe following APIs are related to this API:\n- [Directory of Services - Urgent and Emergency Care - SOAP API](https://digital.nhs.uk/developer/api-catalogue/directory-of-services-urgent-and-emergency-care-soap)\n- [Directory of Services - Urgent and Emergency Care - REST API](https://digital.nhs.uk/developer/api-catalogue/directory-of-services-urgent-and-emergency-care-rest)\n- [Electronic Prescription Service - Directory of Services API](https://digital.nhs.uk/developer/api-catalogue/electronic-prescription-service-directory-of-services)\n\n## Contact us\nFor support or to provide feedback on this API, please [contact us](https://digital.nhs.uk/developer/help-and-support).\n","version":"1.0.0"},"servers":[{"url":"https://sandbox.api.service.nhs.uk/dos-search/FHIR/R4","description":"Sandbox"},{"url":"https://int.api.service.nhs.uk/dos-search/FHIR/R4","description":"Integration"},{"url":"https://ref.api.service.nhs.uk/dos-search/FHIR/R4","description":"Reference"},{"url":"https://api.service.nhs.uk/dos-search/FHIR/R4","description":"Production"}],"paths":{"/Organization":{"get":{"summary":"Search for organisations by ODS code to return Organisation details (including endpoints managed by the Organisation)","description":"## Overview\nRetrieve an Organisation identified by an ODS code (including endpoints managed by the Organisation).\n\n## Request requirements\nA valid ODS code must be provided as a query parameter. An ODS code is deemed valid if it meets the following criteria:\n- it has a minimum of 5 alpha-numeric characters\n- it has a maximum of 12 alpha-numeric characters\n","operationId":"searchOrganizations","parameters":[{"name":"Authorization","in":"header","description":"An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis).\nRequired in all environments except sandbox.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","format":"^Bearer\\ [[:ascii:]]+$","example":"Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"}},{"name":"version","in":"header","description":"The major version increment of this API to query.\nMust be a valid non-negative integer representing a supported major version increment of this API.\nThis is a mandatory header.\nIf you receive repeated 400 Bad Requests marking an invalid header, check that you are correctly sending a valid entry for this value.\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"enum":[1],"type":"integer","one":{"example":1,"summary":"A sample value representing the latest deployed version of the API under major version 1 (v1.x.x)"}}},{"name":"X-Request-ID","in":"header","description":"A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.\nMust be a UUIDv4 (GUID).\nMirrored back in a response header.\nThis is a mandatory header. Please make a note of this value if you might need to raise a support ticket, as this value, as well as the value of X-Correlation-ID will be required. *If you re-send a failed request, use the same value in this header.*\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","type":"string","example":"60E0B220-8136-4CA5-AE46-1D97EF59D068"}},{"name":"X-Correlation-ID","in":"header","description":"An optional ID which you can use to track transactions across multiple systems. This header may be a GUID or any other caller-defined value.\nMirrored back in a response header.\nPlease make a note of this value if you might need to raise a support ticket, as this value as well as the value of X-Request-ID will be required.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}},{"name":"identifier","in":"query","description":"ODS code in the format \"https://fhir.nhs.uk/Id/ods-organization-code|{CODE}\"","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"pattern":"^https:\\/\\/fhir\\.nhs\\.uk\\/Id\\/ods-organization-code\\|[A-Za-z0-9]{5,12}$","type":"string","example":"https://fhir.nhs.uk/Id/ods-organization-code|ABC123"}},{"name":"_revinclude","in":"query","description":"Include relevant Endpoint resources for requested Organization resource matches in the returned Bundle.\n\nMust be set to `Endpoint:organization`.\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"enum":["Endpoint:organization"],"type":"string","default":"Endpoint:organization","example":"Endpoint:organization"}}],"responses":{"200":{"description":"Successful response","headers":{"X-Request-ID":{"name":"","in":"header","description":"This header's name is X-Request-ID. A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.\nMust be a UUIDv4 (GUID).\nMirrored back in a response header.\nThis is a mandatory header. Please make a note of this value if you might need to raise a support ticket, as this value, as well as the value of X-Correlation-ID will be required. *If you re-send a failed request, use the same value in this header.*\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","type":"string","example":"60E0B220-8136-4CA5-AE46-1D97EF59D068"}},"X-Correlation-ID":{"name":"","in":"header","description":"This header's name is X-Correlation-ID. An optional ID which you can use to track transactions across multiple systems. This header may be a GUID or any other caller-defined value.\nMirrored back in a response header.\nPlease make a note of this value if you might need to raise a support ticket, as this value as well as the value of X-Request-ID will be required.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}},"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/Bundle"},"example":{"resourceType":"Bundle","id":"87c5f637-cca3-4ddd-97a9-a3f6e6746bbe","type":"searchset","link":[{"relation":"self","url":"https://api.service.nhs.uk/FHIR/R4/Organization?identifier=https://fhir.nhs.uk/Id/ods-organization-code|ABC123&_revinclude=Endpoint:organization"}],"entry":[{"fullUrl":"https://api.service.nhs.uk/FHIR/R4/Organization/04393ec4-198f-42dd-9507-f4fa5e9ebf96","resource":{"resourceType":"Organization","id":"04393ec4-198f-42dd-9507-f4fa5e9ebf96","identifier":[{"use":"official","system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"ABC123"}],"active":true,"name":"Example Organization"},"search":{"mode":"match"}},{"fullUrl":"https://api.service.nhs.uk/FHIR/R4/Endpoint/1b62110d-4db5-4230-bf37-cbe948aecf76","resource":{"resourceType":"Endpoint","id":"1b62110d-4db5-4230-bf37-cbe948aecf76","extension":[{"url":"https://fhir.nhs.uk/England/StructureDefinition/Extension-England-OrganizationEndpointOrder","valueInteger":1},{"url":"https://fhir.nhs.uk/England/StructureDefinition/Extension-England-EndpointCompression","valueBoolean":false},{"url":"https://fhir.nhs.uk/England/StructureDefinition/Extension-England-EndpointBusinessScenario","valueCode":"primary-recipient"}],"status":"active","connectionType":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-EndpointConnection","code":"email"},"managingOrganization":{"reference":"Organization/04393ec4-198f-42dd-9507-f4fa5e9ebf96"},"payloadType":[{"coding":[{"system":"http://hl7.org/fhir/ValueSet/endpoint-payload-type","code":"urn:nhs-itk:interaction:primaryGeneralPractitionerRecipientNHS111CDADocument-v2-0"}]}],"payloadMimeType":["application/pdf"],"address":"dummy-endpoint-email@nhs.net"},"search":{"mode":"include"}},{"fullUrl":"https://api.service.nhs.uk/FHIR/R4/Endpoint/5df57f63-7f48-5754-b056-ba362834c1e7","resource":{"resourceType":"Endpoint","id":"5df57f63-7f48-5754-b056-ba362834c1e7","extension":[{"url":"https://fhir.nhs.uk/England/StructureDefinition/Extension-England-OrganizationEndpointOrder","valueInteger":2},{"url":"https://fhir.nhs.uk/England/StructureDefinition/Extension-England-EndpointCompression","valueBoolean":false},{"url":"https://fhir.nhs.uk/England/StructureDefinition/Extension-England-EndpointBusinessScenario","valueCode":"copy-recipient"}],"status":"active","connectionType":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-EndpointConnection","code":"email"},"managingOrganization":{"reference":"Organization/04393ec4-198f-42dd-9507-f4fa5e9ebf96"},"payloadType":[{"coding":[{"system":"http://hl7.org/fhir/ValueSet/endpoint-payload-type","code":"urn:nhs-itk:interaction:copyRecipientNHS111CDADocument-v2-0"}]}],"payloadMimeType":["application/pdf"],"address":"dummy-endpoint-email@nhs.net"},"search":{"mode":"include"}}]}}}},"400":{"description":"Bad request","headers":{"X-Request-ID":{"name":"","in":"header","description":"This header's name is X-Request-ID. A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.\nMust be a UUIDv4 (GUID).\nMirrored back in a response header.\nThis is a mandatory header. Please make a note of this value if you might need to raise a support ticket, as this value, as well as the value of X-Correlation-ID will be required. *If you re-send a failed request, use the same value in this header.*\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","type":"string","example":"60E0B220-8136-4CA5-AE46-1D97EF59D068"}},"X-Correlation-ID":{"name":"","in":"header","description":"This header's name is X-Correlation-ID. An optional ID which you can use to track transactions across multiple systems. This header may be a GUID or any other caller-defined value.\nMirrored back in a response header.\nPlease make a note of this value if you might need to raise a support ticket, as this value as well as the value of X-Request-ID will be required.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}},"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"},"examples":{"missing-headers":{"$ref":"#/components/examples/MissingHeaders"},"missing-query-parameters":{"$ref":"#/components/examples/MissingQueryParameters"},"invalid-version-header":{"$ref":"#/components/examples/InvalidVersionHeader"},"invalid-identifier-value":{"$ref":"#/components/examples/InvalidIdentifierValue"},"invalid-identifier-system":{"$ref":"#/components/examples/InvalidIdentifierSystem"},"unexpected-header":{"$ref":"#/components/examples/UnexpectedHeader"},"unexpected-query-param":{"summary":"Unexpected query parameter","value":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"value","details":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-SpineErrorOrWarningCode","version":"1.0.0","code":"INVALID_SEARCH_DATA","display":"Invalid search data"}]},"diagnostics":"Unexpected query parameter(s): foo. Only 'identifier' and '_revinclude' are allowed."}]}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","headers":{"X-Request-ID":{"name":"","in":"header","description":"This header's name is X-Request-ID. A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.\nMust be a UUIDv4 (GUID).\nMirrored back in a response header.\nThis is a mandatory header. Please make a note of this value if you might need to raise a support ticket, as this value, as well as the value of X-Correlation-ID will be required. *If you re-send a failed request, use the same value in this header.*\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","type":"string","example":"60E0B220-8136-4CA5-AE46-1D97EF59D068"}},"X-Correlation-ID":{"name":"","in":"header","description":"This header's name is X-Correlation-ID. An optional ID which you can use to track transactions across multiple systems. This header may be a GUID or any other caller-defined value.\nMirrored back in a response header.\nPlease make a note of this value if you might need to raise a support ticket, as this value as well as the value of X-Request-ID will be required.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}},"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"},"example":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"security","diagnostics":"Invalid or missing authentication token","details":{"coding":[{"system":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode","version":"1","code":"UNAUTHORIZED","display":"Unauthorized"}]}}]}}}},"403":{"description":"Forbidden - Insufficient permissions","headers":{"X-Request-ID":{"name":"","in":"header","description":"This header's name is X-Request-ID. A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.\nMust be a UUIDv4 (GUID).\nMirrored back in a response header.\nThis is a mandatory header. Please make a note of this value if you might need to raise a support ticket, as this value, as well as the value of X-Correlation-ID will be required. *If you re-send a failed request, use the same value in this header.*\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","type":"string","example":"60E0B220-8136-4CA5-AE46-1D97EF59D068"}},"X-Correlation-ID":{"name":"","in":"header","description":"This header's name is X-Correlation-ID. An optional ID which you can use to track transactions across multiple systems. This header may be a GUID or any other caller-defined value.\nMirrored back in a response header.\nPlease make a note of this value if you might need to raise a support ticket, as this value as well as the value of X-Request-ID will be required.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}},"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"},"example":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"forbidden","diagnostics":"Insufficient permissions to access this resource","details":{"coding":[{"system":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode","version":"1","code":"FORBIDDEN","display":"Forbidden"}]}}]}}}},"429":{"description":"Too many requests – Rate limit exceeded","headers":{"X-Request-ID":{"name":"","in":"header","description":"This header's name is X-Request-ID. A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.\nMust be a UUIDv4 (GUID).\nMirrored back in a response header.\nThis is a mandatory header. Please make a note of this value if you might need to raise a support ticket, as this value, as well as the value of X-Correlation-ID will be required. *If you re-send a failed request, use the same value in this header.*\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","type":"string","example":"60E0B220-8136-4CA5-AE46-1D97EF59D068"}},"X-Correlation-ID":{"name":"","in":"header","description":"This header's name is X-Correlation-ID. An optional ID which you can use to track transactions across multiple systems. This header may be a GUID or any other caller-defined value.\nMirrored back in a response header.\nPlease make a note of this value if you might need to raise a support ticket, as this value as well as the value of X-Request-ID will be required.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}},"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"},"example":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"throttled","details":{"coding":[{"system":"https://fhir.nhs.uk/Codesystem/http-error-codes","version":"0.1.0","code":"SEND_TOO_MANY_REQUESTS","display":"429: Too many requests have been made by this source to the API in a given amount of time."}]},"diagnostics":"You have exceeded the agreed rate limits for this endpoint. Please retry. If problems persist please contact support."}]}}}},"500":{"$ref":"#/components/responses/ServerError"}},"deprecated":false,"security":[{"app-level3":[]}]}}},"components":{"schemas":{"Bundle":{"required":["resourceType","type","entry"],"type":"object","properties":{"resourceType":{"enum":["Bundle"],"type":"string"},"id":{"type":"string","format":"uuid"},"type":{"enum":["searchset"],"type":"string"},"link":{"type":"array","items":{"type":"object","properties":{"relation":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"entry":{"type":"array","items":{"type":"object","properties":{"fullUrl":{"type":"string","format":"uri"},"resource":{"oneOf":[{"$ref":"#/components/schemas/Organization"},{"$ref":"#/components/schemas/Endpoint"}]},"search":{"type":"object","properties":{"mode":{"enum":["match","include"],"type":"string"}}}}}}},"description":"A FHIR resource for the collection of FHIR resources returned in a contained manner."},"Organization":{"required":["resourceType","identifier","active","name"],"type":"object","properties":{"resourceType":{"enum":["Organization"],"type":"string"},"id":{"type":"string","format":"uuid"},"identifier":{"type":"array","items":{"type":"object","properties":{"use":{"enum":["official"],"type":"string"},"system":{"type":"string"},"value":{"type":"string"}}}},"active":{"type":"boolean"},"name":{"type":"string"},"endpoint":{"type":"array","items":{"type":"object","properties":{"reference":{"type":"string"}}}}},"description":"A FHIR resource that returns the included components."},"Endpoint":{"required":["resourceType","status","connectionType","payloadType","address"],"type":"object","properties":{"resourceType":{"enum":["Endpoint"],"type":"string"},"id":{"type":"string","format":"uuid"},"identifier":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string"},"value":{"type":"string"}}}},"status":{"enum":["active","off"],"type":"string"},"connectionType":{"type":"object","properties":{"system":{"type":"string"},"code":{"type":"string"}}},"payloadType":{"type":"array","items":{"type":"object","properties":{"coding":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string"},"code":{"type":"string"}}}}}}},"payloadMimeType":{"type":"array","items":{"type":"string"}},"address":{"type":"string","format":"uri"},"extension":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"valueInteger":{"type":"integer"},"valueBoolean":{"type":"boolean"},"valueCode":{"type":"string"}}}},"managingOrganization":{"type":"object","properties":{"reference":{"type":"string"}}}},"description":"A FHIR resource that returns the included components."},"OperationOutcome":{"required":["resourceType","issue"],"type":"object","properties":{"resourceType":{"enum":["OperationOutcome"],"type":"string"},"issue":{"type":"array","items":{"required":["severity","code","diagnostics"],"type":"object","properties":{"severity":{"enum":["error","fatal"],"type":"string"},"code":{"enum":["code-invalid","value","security","forbidden","exception","not-supported","required"],"type":"string"},"diagnostics":{"type":"string"},"details":{"type":"object","properties":{"coding":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string"},"version":{"type":"string"},"code":{"type":"string"},"display":{"type":"string"}}}}}}}}}}}},"responses":{"Unauthorized":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"},"example":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"security","diagnostics":"Invalid or missing authentication token","details":{"coding":[{"system":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode","version":"1","code":"UNAUTHORIZED","display":"Unauthorized"}]}}]}}}},"ServerError":{"description":"Internal server error","headers":{"X-Request-ID":{"name":"","in":"header","description":"This header's name is X-Request-ID. A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.\nMust be a universally unique identifier (UUID) (ideally version 4).\nMirrored back in a response header.\nThis is a mandatory header. Please make a note of this value if you might need to raise a support ticket, as this value, as well as the value of X-Correlation-ID will be required. *If you re-send a failed request, use the same value in this header.*\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"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}$","type":"string","example":"60E0B220-8136-4CA5-AE46-1D97EF59D068"}},"X-Correlation-ID":{"name":"","in":"header","description":"This header's name is X-Correlation-ID. An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding `.` characters.\nMirrored back in a response header.\nPlease make a note of this value if you might need to raise a support ticket, as this value as well as the value of X-Request-ID will be required.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}},"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"},"example":{"resourceType":"OperationOutcome","issue":[{"severity":"fatal","code":"exception","diagnostics":"Internal server error"}]}}}}},"parameters":{"Authorization":{"name":"Authorization","in":"header","description":"An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis).\nRequired in all environments except sandbox.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","format":"^Bearer\\ [[:ascii:]]+$","example":"Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"}},"Version":{"name":"version","in":"header","description":"The major version increment of this API to query.\nMust be a valid non-negative integer representing a supported major version increment of this API.\nThis is a mandatory header.\nIf you receive repeated 400 Bad Requests marking an invalid header, check that you are correctly sending a valid entry for this value.\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"enum":[1],"type":"integer","one":{"example":1,"summary":"A sample value representing the latest deployed version of the API under major version 1 (v1.x.x)"}}},"XRequestID":{"name":"X-Request-ID","in":"header","description":"A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.\nMust be a universally unique identifier (UUID) (ideally version 4).\nMirrored back in a response header.\nThis is a mandatory header. Please make a note of this value if you might need to raise a support ticket, as this value, as well as the value of X-Correlation-ID will be required. *If you re-send a failed request, use the same value in this header.*\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"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}$","type":"string","example":"60E0B220-8136-4CA5-AE46-1D97EF59D068"}},"XCorrelationID":{"name":"X-Correlation-ID","in":"header","description":"An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding `.` characters.\nMirrored back in a response header.\nPlease make a note of this value if you might need to raise a support ticket, as this value as well as the value of X-Request-ID will be required.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}}},"examples":{"MissingHeaders":{"summary":"Missing required headers","value":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"required","details":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-SpineErrorOrWarningCode","version":"1.0.0","code":"REC_BAD_REQUEST","display":"400: The Receiver was unable to process the request."}]},"diagnostics":"Missing required header(s): 'version', 'x-request-id'"}]}},"MissingQueryParameters":{"summary":"Missing required query parameter","value":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"required","details":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-SpineErrorOrWarningCode","version":"1.0.0","code":"INVALID_SEARCH_DATA","display":"Invalid search data"}]},"diagnostics":"Missing required query parameter(s): 'identifier', '_revinclude'"}]}},"InvalidVersionHeader":{"summary":"Invalid Version header","value":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"value","details":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-SpineErrorOrWarningCode","version":"1.0.0","code":"REC_BAD_REQUEST","display":"400: The Receiver was unable to process the request."}]},"diagnostics":"Invalid version found in supplied headers: version must be '1'"}]}},"InvalidIdentifierValue":{"summary":"Invalid ODS code format","value":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"value","details":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-SpineErrorOrWarningCode","version":"1.0.0","code":"INVALID_SEARCH_DATA","display":"Invalid search data"}]},"diagnostics":"Invalid identifier value: ODS code 'ABC' must follow format ^[A-Za-z0-9]{5,12}$"}]}},"InvalidIdentifierSystem":{"summary":"Invalid identifier system","value":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"code-invalid","details":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-SpineErrorOrWarningCode","version":"1.0.0","code":"INVALID_SEARCH_DATA","display":"Invalid search data"}]},"diagnostics":"Invalid identifier system 'foo' - expected 'https://fhir.nhs.uk/Id/ods-organization-code'"}]}},"UnexpectedHeader":{"summary":"Unexpected header","value":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"value","details":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-SpineErrorOrWarningCode","version":"1.0.0","code":"REC_BAD_REQUEST","display":"400: The Receiver was unable to process the request."}]},"diagnostics":"Unexpected header(s): foo."}]}},"UnexpectedQueryParam":{"summary":"Unexpected query parameter","value":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"value","details":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-SpineErrorOrWarningCode","version":"1.0.0","code":"INVALID_SEARCH_DATA","display":"Invalid search data"}]},"diagnostics":"Unexpected query parameter(s): foo. Only 'identifier' and '_revinclude' are allowed."}]}}},"securitySchemes":{"app-level3":{"$ref":"https://proxygen.prod.api.platform.nhs.uk/components/securitySchemes/app-level3"}}},"security":[{"app-level3":[]}]}