{"openapi":"3.0.1","info":{"title":"Directory of Services (DoS) REST API","description":"\n<div class=\"nhsd-m-emphasis-box nhsd-m-emphasis-box--emphasis nhsd-!t-margin-bottom-6\" aria-label=\"Highlighted Information\">\n <div class=\"nhsd-a-box nhsd-a-box--border-blue\">\n <div class=\"nhsd-m-emphasis-box__image-box\">\n <figure class=\"nhsd-a-image\">\n <picture class=\"nhsd-a-image__picture\">\n <img src=\"http://digital.nhs.uk/binaries/content/gallery/icons/info.svg?colour=231f20\" alt=\"\" style=\"object-fit:fill\">\n </picture>\n </figure>\n </div>\n <div class=\"nhsd-m-emphasis-box__content-box\">\n <div data-uipath=\"website.contentblock.emphasis.content\" class=\"nhsd-t-word-break\">\n <p class=\"nhsd-t-body\">This API will be deprecated on the 31st of May 2026 as we are re-platforming the DoS API and will be replacing it with a new FHIR based API</a>. </p></div></div></div></div>\n\n## Overview\n\nUse this API to access [Directory of Services (DoS)](https://digital.nhs.uk/services/directory-of-services-dos) information on a wide range of health and care services across England. \n\nYou can search for services based on a combination of parameters: \n\n* the patient’s age, sex, and current location\n* the patient’s clinical need\n\nYou can also search for services using similar parameters, such as by:\n\n* service type - find matching service type ID, location and optional patient details\n* clinical term - find matching symptoms, location and optional patient details\n* ODS code - find active services with a matching ODS code\n* service Id - find active services with a matching service identifier\n\nThis API is widely used in an urgent and emergency care context.\n\nIt is not currently suitable for referrals from services using [NHS Pathways](https://digital.nhs.uk/services/nhs-pathways) outcomes, such as NHS 111 - for this, use the [Directory of Services - Urgent and Emergency Care - SOAP API](https://digital.nhs.uk/developer/api-catalogue/directory-of-services-soap).\n\nYou need a valid DoS account to use this API.\n\nDuring the [onboarding](https://digital.nhs.uk/developer/api-catalogue/directory-of-services-urgent-and-emergency-care-soap#overview--onboarding) process, an account will be created for each connecting party's application for each environment, where authentication credentials will be granted.\n\n## Who can use this API\n\nThis API can only be used where there is a legal basis to do so. See our [acceptable use policy](https://digital.nhs.uk/services/directory-of-services-dos/api-acceptable-use-policy) for more details.\n\nYou must request to use this API before you go live. Please see the Onboarding section below for guidance.\n\n## Access modes\n\nThis API has one access mode:\n\n* application-restricted\n\nThis access mode means that we authenticate and authorise the connecting party's application but not the end user. \n\nDuring the onboarding process, an account will be created for each connecting party's application for each environment, where authentication credentials will be granted.\n\n## Roadmap \n\nWe're currently finalising our roadmap and we'll update this content in due course.\n\n## API status\n\nThis API is [in production](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).\n\n## Service Level\n\nThis API is a gold service, meaning it is operational and supported 24 hours a day, 365 days a year.\n\nFor more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).\n\n## Rate limits\n\nWe monitor the number of transactions a connecting party can make per unit of time. We do this to protect our service against excessive use and denial-of-service (DOS) attacks. \n\nIt is paramount to us that our APIs and services are available to all connecting parties at all times, and so it is important that we protect our APIs against rogue requests, DoS attacks and unfair usage (both intentional and unintentional).\n\nOur default rate limit for the production environment is 10 transactions per second (tps) per connecting party account. Rate limits are applied within a rolling minute window, not per individual second - so at the default limit of 10tps, a connecting party account can perform up to 600 transactions in any given (rolling) minute.\n\nWe will monitor the rate limit and traffic flows through our API and will raise concerns if we think the rate limit is too low. As well as us monitoring we encourage connecting parties to also let us know if the `429` occurs too frequently.\n\nWe also encourage connecting parties to let us know if the API response “429 - Too Many Requests” occurs too frequently. \n\nWe will work with and advise connecting parties on configuring the rate limit to meet the legitimate request demands and in helping us protect our APIs and services in making sure that they are always available.\n\n## Technology\n\nThis API is a [REST API](http://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#basic-rest).\n\nFor more details, see [Basic REST](http://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#basic-rest).\n\nWe also have a [Directory of Services - Urgent and Emergency Care - SOAP API](https://digital.nhs.uk/developer/api-catalogue/directory-of-services-soap) available.\n\n## Network access\n\nThis API is available on the internet and, indirectly, on the [Health and Social Care Network (HSCN)](https://digital.nhs.uk/services/health-and-social-care-network).\n\nWe're operating in a cloud setting and the expectation is that IPv4 addressing should vary.\n\nFor more details, see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).\n\n## Errors\n\nWe use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:\n\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\n* 400 to 499 if it failed because of a client error by your application\n\n* 500 to 599 if it failed because of an error on our server\n\nErrors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.\n\n## Open source\n\nThere are no open source resources currently available for this API.\n\n## Security and authorisation\n\nYou need a [valid DoS account](https://digital.nhs.uk/services/directory-of-services-dos/api-acceptable-use-policy) to use this API.\n\nThis API uses HTTP basic authentication. We use authentication to track API usage and to control which information is returned to a search.\n\nHTTP basic authentication is built in to all HTTP clients and requires the `Authorization` request header with the DoS `username` and `password` colon delimited and `base64` encoded.\n\n## Environments and testing\n\n| Environment | Base URL |\n|-------------|----------|\n| Integration testing | https://usertest.directoryofservices.nhs.uk/app/controllers/api |\n| Production | https://webservices.directoryofservices.nhs.uk/app/controllers/api |\n\n### Integration testing\n\nOur [integration testing environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing):\n\n* contains a snapshot of production-like data (but with itk/email integration points taken out to prevent test systems from invoking real live processes) \n* is for formal integration testing\n* includes application-restricted authentication (account credentials)\n* includes SSL certificate presentation from our server, signed by production CAs\n\nOur integration test environment is NOT suitable for any of the following without prior written agreement:\n\n* any form of performance, load, or stress testing\n* any form of penetration testing\n\nTo prevent the data in our integration test environment from going stale, we refresh its data from production from time to time. \n\nAll connecting parties currently onboarded onto our integration test environment will receive an email to inform as to when this process is due to take place. \n\n### Production\n\nOur production environment is suitable for live traffic only, and we will monitor calls through our production APIs.\n\n## Services\n\nA service represents some kind of health or care service that is provided by a healthcare provider. Services can be defined at a high level (e.g. High Street Pharmacy) or at a granular level (e.g. High Street Pharmacy - Flu Vaccination Service).\n\nAlthough a service may be created to represent an organisation, or a physical location - it is important to remember that services are not automatically equivalent to organisations and physical locations.\n\nYou may see references to 'profiling' when working with the DoS: the word 'profiling' is often used to describe the process of defining and configuring a service with detailed information ranging from administrative details (eg. name, address, phone number) to clinical capabilities (by way of clinical terminology).\n\nPlease note that you must provide clear labelling to distinguish Distant Selling Pharmacies to regular brick-and-mortar pharmacies.\n\nDistant Selling Pharmacies do not have physical premises for patients to visit and only offer online consultations. \n\nCertain conditions, such as otitis media, require a physical examination that can be carried out by regular brick-and-mortar pharmacies only.\n\n### Service types\n\nMost records within the DoS are a service record of some type.\n\nA comprehensive list of the different service types can be found on the Operations section [Service Type ID and Name Reference](https://digital.nhs.uk/developer/api-catalogue/directory-of-services-urgent-and-emergency-care-rest#get-/services/byServiceType/-caseId-/-postcode-/-searchDistance-/-gppracticeId-/-age-/-gender-/-disposition-/-serviceTypeIds-/-numberPerType-).\n\nMost service types behave in the same way, but there are a few which have special status or attributes. \n\nThese are:\n\n* commissioning organisation\n* region\n\n## Disposition codes\n\nA disposition code is an indication of the needs of the patient encompassing both the general category of service required and the timeframe within which that service is required.\n\nThere are hundreds of dispositions in the [full list](https://www.england.nhs.uk/statistics/statistical-work-areas/iucadc-new-from-april-2021/nhs-111-minimum-data-set/), but they tend to exist in groups. You may have several disposition codes representing a single category of service but covering a number of different timescales.\n\nBelow is an example of some disposition codes:\n\n| Disposition code | Descriptive name |\n|------|-------------|\n| Dx13 | Speak to a primary care service within 6 hours |\n| Dx17 | To contact a dental service within 1 hour |\n| Dx80 | Repeat prescription required within 6 hours |\n| Dx120 | Callback by healthcare professional within 4 hours | \n\n### Symptom groups / symptom discriminators (SG/SD codes)\n\nThis is a proprietary coding system developed to support the NHS Pathways triage product.\n\nThe codes are designed to be used in pairs to provide clinical context to a search. The Symptom Group (SG) describes the presenting issue and the Symptom Discriminator (SD) describes the clinical need. \n\nPlease note that combinations which do not search the DoS are not shown here.\n\nFor a full list of interactions for this API, see the DoS REST API `SG ID SG Description`\n\n| SG ID | SG Description | SD ID | SD Description |\n|-------|----------------|--------|----------------|\n| SG1011 | Ankle or foot injury, blunt | SD4003PC | PC full primary care assessment and prescribing capability |\n| SG1011 | Ankle or foot injury, blunt | SD4010 | ALL assault, sexual |\n| SG1011 | Ankle or foot injury, blunt | SD4052ED | ED full ED assessment and management capability |\n| SG1011 | Ankle or foot injury, blunt | SD4304 | ED unable to weigh to ear |\n| SG1010 | Allergic reaction | SD4003PC | PC full PC assessment and prescribing capability |\n| SG1010 | Allergic reaction | SD4020PC | PC Assessment and management capability, minor condition |\n| SG1010 | Allergic reaction | SD4052ED | ED full ED assessment and management capability |\n\n## Onboarding\n\nYou must get your software onboarded before it can go live. \n\nYou can express your interest in connecting to the DoS REST API by using the [Digital Onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding) online portal. This portal supports the onboarding for single or multiple APIs. \n\nAlternatively, if you need help and support connecting to our APIs, to get started with an onboarding process, or to discuss your requirements in more detail, please complete our [enquiry form](https://digital.nhs.uk/services/partner-onboarding/enquiry-form). \n\nOnboarding to the DoS REST API usually takes about 4 months, unless you, the connecting party, need more time to meet the required conformance requirements and complete your onboarding. \n\nOnce logged into [Digital Onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding), you’ll be asked to provide us with an outline of your product, organisation and the use case illustrating the purpose of using the DoS REST API for your product. \n\nPlease familiarise yourself with our [API Acceptable use policy](https://digital.nhs.uk/services/directory-of-services-dos/api-acceptable-use-policy), explaining what we prohibit when any party uses any API connecting to the Directory of Services (DoS), and the [Find the Right Service Onboarding Rules of Engagement](https://digital.nhs.uk/developer/api-catalogue/directory-of-services-urgent-and-emergency-care-rest/onboarding-guidance-and-downloadable-templates#:~:text=Find%20the%20Right%20Service%20Onboarding%20Rules%20of%20Engagement%2C%20v0.2.docx), providing more guidance on your commitment in completing the onboarding. \n\nPlease see the [Onboarding guidance page](https://digital.nhs.uk/developer/api-catalogue/directory-of-services-urgent-and-emergency-care-rest/onboarding-guidance-and-downloadable-templates) for detailed instructions on the whole onboarding process with links to downloadable templates and other useful resources.\n\n#### Operations \n\nThe [Operations](https://digital.nhs.uk/services/partner-onboarding/operations) Team is responsible for the ongoing maintenance and support of operational services.\n\n#### Health and Social Care Network (HSCN)\n\nThe [Health and Social Care Network (HSCN)](https://digital.nhs.uk/services/health-and-social-care-network) provides a reliable, efficient and flexible way for health and care organisations to access and exchange electronic information.\n\n## Related APIs\n\nThe following APIs are related to this one:\n\n* [Directory of Services - Urgent and Emergency Care - SOAP API](https://digital.nhs.uk/developer/api-catalogue/directory-of-services-soap) - use this API to access information on a wide range of health and care services across England.\n* [EPS Directory of Services - REST API](https://digital.nhs.uk/developer/api-catalogue/electronic-prescription-service-directory-of-services) - use this API to access information about dispensing services, including searching for dispensers who can provide services for a patient with a given location and urgency.\n* [Electronic Transmission of Prescriptions Web Services - SOAP API](https://digital.nhs.uk/developer/api-catalogue/electronic-transmission-of-prescriptions-web-services-soap) - use this API to access EPS dispenser (and dispensing appliance contractor) information for a patient via NHS UK Web Services.\n* [e-Referral Services - A010 Patient service search endpoint](https://digital.nhs.uk/developer/api-catalogue/e-referral-service-fhir#api-Default-a010-patient-service-search) - use this endpoint to find services that meet the referral needs of a patient.\n* [NHS UK service search](http://developer.api.nhs.uk/nhs-api) - use this API to search for services by [organisation](https://developer.api.nhs.uk/nhs-api/documentation/service-search-organisations), or [organisation type](https://developer.api.nhs.uk/nhs-api/documentation/service-search-organisation-types).\n","version":"1.0.0"},"servers":[{"url":"https://usertest.directoryofservices.nhs.uk/app/controllers/api/v1.0/"}],"paths":{"/services/byServiceType/{caseId}/{postcode}/{searchDistance}/{gppracticeId}/{age}/{gender}/{disposition}/{serviceTypeIds}/{numberPerType}":{"get":{"summary":"Get service details by Service Type","description":"## Overview\n\nThis search method allows users to search the DoS based on a set of service types, search location (postcode) and search distance, with optional patient details for finer filtering.\n\nThe search will return a set of services that match the searching criteria, up to the number of results specified per service type.\n\nThe search will group the services returned by their service type, ordering the groups containing the closest services to the search location first.\n\nServices that are not active will not be returned.\n\n## Search rules\n\n| Parameter | Rule |\n|---------------------|----------------------------------|\n| Username | Only services where the referral role matches the Search Role of the authenticated user are returned |\n| | Only active services are returned |\n| Search Distance | Use this value to calculate the **search area**, with the postcode passed in at the centre - only services within this box are returned. If zero, default value is used: 37.5 miles |\n| Postcode | Postcode is used to calculate the search distance, and the distance (in miles) between the postcode and each service is included in response |\n| Postcode | If no postcode is passed in, an error will be returned. If a postcode of zero is passed in, an error will not be returned but no services will match |\n| Age | Only services matching the age group provided are returned in the response. Where zero, age group is ignored |\n| Gender | Only services matching the gender code provided are returned in the response |\n| GP practice ID | Services which are restricted to patients of a specified GP practice will only return if the GP practice ID passed in is on the Service Referrals list of the service |\n| Number per type | Where there are more results per Service Type than the Number per type value, only the closest services (by distance) up to the total number requested are returned. If passed in zero, the default value is used: 5 | \n| Capacity status | The capacity status is always included in the response at the time of the request |\n","operationId":"getServiceType","parameters":[{"$ref":"#/components/parameters/caseId"},{"$ref":"#/components/parameters/postcode"},{"$ref":"#/components/parameters/searchDistance"},{"$ref":"#/components/parameters/gppracticeId"},{"$ref":"#/components/parameters/age"},{"$ref":"#/components/parameters/gender"},{"$ref":"#/components/parameters/disposition"},{"$ref":"#/components/parameters/serviceTypeIds"},{"$ref":"#/components/parameters/numberPerType"}],"responses":{"200":{"description":"## Response ordering\n\nA successful response, providing a set of services matching the search criteria, ordered in groups of service type **listing the closest service to the search location first.**\n\nServices are ordered by distance from the search location, with the following priority:\n\n* services where the provided GP practice ID matches the Service Referrals list appear first\n* all other services are ordered by ascending distance\n\n### Service Type ID and Name Reference\n\n| id | name |\n|-----|------|\n| -2 | Local Templates |\n| -1 | DoS Region |\n| 4 | Therapy |\n| 6 | Commissioning Cluster |\n| 7 | Mental Health |\n| 8 | Social Care |\n| 11 | Voluntary |\n| 12 | Dental Practice |\n| 13 | Pharmacy |\n| 14 | Optical |\n| 17 | Clinic |\n| 18 | Health Visitor |\n| 19 | Midwifery |\n| 20 | Community Based |\n| 21 | Retired |\n| 22 | Commissioning Organisation |\n| 24 | Care Home |\n| 25 | Integrated Urgent Care (IUC) Treatment |\n| 27 | Intermediate Care |\n| 28 | Community Hospital |\n| 29 | Sexual Health |\n| 38 | Community/District Nursing |\n| 40 | Emergency Department (ED) Catch-All |\n| 41 | Hospital Acute Assessment Unit (AAU) |\n| 46 | Urgent Care |\n| 47 | Dental Emergency |\n| 48 | Specialist |\n| 50 | Palliative Care |\n| 100 | GP Practice |\n| 105 | Emergency Department (ED) |\n| 107 | (Capacity) Critical Care (CC) |\n| 108 | (Capacity) Paediatrics Intensive Care Unit (PICU) |\n| 109 | (Capacity) Burns (B) |\n| 110 | (Capacity) Maternity and Neonate (MN) |\n| 111 | (Capacity) Paediatrics (PDR) |\n| 112 | Optical Enhanced |\n| 113 | Health Information |\n| 114 | (Capacity) Acute Hospital |\n| 115 | (Capacity) Provider Escalation/RAG |\n| 120 | Emergency Department (ED) Eye Casualty |\n| 121 | Primary Percutaneous Coronary Intervention (PPCI) |\n| 122 | Hyper-Acute Stroke Unit (HASU) |\n| 129 | Safeguarding |\n| 130 | Integrated Urgent Care (IUC) NHS 111 Call Handling Provider |\n| 131 | Pharmacy Urgent Medicines Supply |\n| 132 | Pharmacy Enhanced |\n| 133 | Integrated Urgent Care (IUC) Clinical Assessment Service (CAS) |\n| 134 | Pharmacy Distance Selling |\n| 135 | Urgent Treatment Centre (UTC) |\n| 136 | GP Access Hub |\n| 137 | Integrated Urgent Care (IUC) Pharmacy Clinical Assessment |\n| 138 | Emergency National Response |\n| 139 | Integrated Urgent Care (IUC) Validation |\n| 140 | Same Day Emergency Care (SDEC) |\n| 141 | Hospital Streaming |\n| 142 | Mental Health Crisis |\n| 143 | Sexual Assault Referral Centre (SARC) |\n| 144 | Integrated Urgent Care (IUC) Dental Clinical Assessment |\n| 145 | Integrated Urgent Care (IUC) Paediatric Clinical Assessment |\n| 146 | Urgent Community Response (UCR) |\n| 147 | Covid Medicines Delivery Unit (CMDU) |\n| 148 | Pharmacy Blood Pressure Check |\n| 149 | Pharmacy Contraception |\n| 150 | Urgent Treatment Centre (UTC) Co-Located with ED |\n| 151 | Primary Care Network (PCN) |\n| 152 | Primary Care Network (PCN) Enhanced Service |\n| 153 | Maternity and Neonatal |\n| 154 | Early Pregnancy Assessment Unit (EPAU) |\n| 155 | Virtual Ward |\n| 156 | Dental Urgent Care |\n| 157 | Infection Hub |\n| 158 | Ambulance Service Pathway |\n| 159 | Primary Care Clinic |\n| 160 | Care Transfer Hub |\n\n### Service Type and ODS Suffix Reference\n\n| ID | Service Type | Comments | ODS Code & suffix (Example ONLY) |\n|-----|-----|-----|-----|\n| 100 | GP Practice | Core GP Practice | A88131 |\n| 131 | Pharmacy Urgent Medicines Supply | Urgent Meds & Service Type used by BaRS (all those who delivery Pharmacy First deliver both service type 131 and 132) | FA123RPX OR FA123RPXDSP (if it is a distance selling) |\n| 132 | Pharmacy Enhanced | Pharmacy First Service Offer (all those who delivery Pharmacy First deliver both service type 131 and 132) | FA123PF / FA123PF+ / FA123PF++ OR with DSP on the end if it is a distance selling |\n| 13 | Pharmacy | This is the core pharmacy, this will have the 5-digit ODS code all others will include a suffix | FA123 |\n| 134 | Pharmacy Distance Selling | This is the core pharmacy, however the online version, this will have the 5-digit ODS code, all others will include a suffix plus DSP. Any Service under this service type OR under any of the others with DSP at the end must be displayed as an Online Pharmacy in your system | FA123 |\n| 148 | Pharmacy Blood Pressure Check | Blood Pressure Service | FA123BPS{} |\n| 149 | Pharmacy Contraception | Contraception Service | FA123CON |\n\n## Response fields\n\nEvery response includes:\n\n* status code\n* response code \n* transaction ID\n* catch-all flag\n* total service count\n\n## Catch-all behaviour\n\nNote: This catch-all flag is distinct from the Check Capacity Summary catch-all rule (which returns the 2 nearest EDs when ≤1 services are found). That rule does not apply here. \n\nThe catch-all flag indicates whether any matching services were found:\n\n* `false` = One or more services returned\n* `true` = No services returned \n\n# Response field definitions\n\n### Email\n\nThis is the email address of the service and is intended for use by clinicians and healthcare professionals only. \n\nNote: It should not be shared with the public or displayed on public-facing websites/applications. The email address can be used for clinical correspondence, referrals and other professional communications between healthcare providers.\n\n### Opening times\n\nYou may receive multiple types of opening times, and these should be treated in the following priority order.\n\n### Specified opening times\n\nThese allow services to register temporary exceptions or changes to their usual operating hours (e.g. for holidays, special events, or one-off circumstances). \n\nWhen specified opening times are present, they should take precedence and override any other session times that are returned for that date, including overriding the `Open all hours` flag if it is set. \n\nThis ensures the most up-to-date and accurate opening hours are displayed.\n\n### Open all hours\n\nIf the flag is set to `Open all hours = True` and there are no specified times for the given date, then the service should be treated as open 24 hours a day, 7 days a week, 365 days a year, including weekends and bank holidays. \n\nThis means the service operates continuously without any breaks or closures. \n\nThere should not be any Standard opening times defined for these services since they are always open, but if Standard opening times are present in the data, they should be ignored in favor of the `Open all hours` flag. \n\nThe `Open all hours` flag takes precedence over Standard opening times but can still be overridden by specified opening times for specific dates.\n\n### Public holidays\n\nServices can be profiled with a set of opening times for Public holidays, or can be configured to be closed for all Public holidays by default. \n\nWhen a service is set to be closed for all Public holidays, any exceptions to this rule (where the service is actually open on a specific public holiday) must be recorded as a specified opening time. \n\nIf the date being checked falls on a public holiday, the public holiday opening times or closure should take precedence and override any Standard opening times defined for that day of the week. \n\nThis ensures that special holiday hours or closures are properly reflected.\n\n### Standard opening times\n\nThese are the regular, recurring opening hours for the service that apply when no special circumstances (like holidays or temporary changes) are in effect. \n\nA service may have multiple opening sessions within a single day (for example, morning and afternoon sessions), but these session times must not overlap with each other to avoid ambiguity.\n\nDue to technical limitations, session times cannot span across midnight - they must end at 23:59 at the latest. For services that operate overnight, this means their hours will be split into two sessions:\n\n* one session ending at 23:59 on the first day\n* another session starting at 00:00 on the following day\n\nFor example, a service open from 8pm to 6am would be represented as:\n\n* Monday: 20:00-23:59\n* Tuesday: 00:00-06:00\n\n### Referral information\n\nAdditional information about the service is provided in two separate fields:\n\n`callHandler` field:\n\n* contains information intended for members of the public\n* includes general instructions about accessing or using the service\n* should be displayed on public-facing websites and applications\n* contains patient-friendly language and guidance\n\nexamples: \n\n* opening hours \n* booking instructions \n* walk-in information\n\n`other` field:\n\n* contains information intended for clinicians and healthcare professionals only\n* must not be displayed to the public\n* may contain sensitive or restricted information like:\n * direct clinical contact numbers\n * internal referral processes\n * clinical criteria\n * professional-only access details\n * staff-specific instructions\n* should only be visible to authenticated healthcare professionals\n* care must be taken to keep this information secure and restricted\n\n### Telephone numbers\n\nBoth public and non-public telephone numbers are included in the response:\n\n* Public telephone numbers:\n * should be displayed to all users including members of the public\n * used for general enquiries and patient contact\n * listed in the `public` field of the phone object\n* Non-public telephone numbers:\n * must only be displayed to authenticated clinicians and healthcare professionals \n * used for direct clinical communication between healthcare providers\n * contains priority/emergency contact numbers\n * must not be shared with or displayed to members of the public\n * listed in the `nonPublic` field of the phone object\n * care must be taken to properly restrict access based on user role \n\n### Capacity status\n\nService capacity is indicated using a traffic light system:\n\n* green (High): Default status indicating normal capacity\n* amber (Low): Limited capacity available\n* red (None): At capacity or temporarily closed\n\nCapacity status can be updated for up to 5 days. Services with Red status will still be returned in results,\nbut should be displayed with appropriate warnings since they have reported being at capacity or unable to accept new patients. \n\n### Distance from patient\n\nThe calculated straight-line (as-the-crow-flies) distance in miles between the search postcode and the service location.\n\n### Public name \n \nThe public-friendly name of the service that is commonly recognised by patients and the general public. \nThis may be different from the official registered name and is intended to be more familiar and easier to understand. \n\n### Professional referral information\n \nProfessional referral guidance specifically for NHS Service Finder users, providing detailed instructions on patient referral pathways, signposting options, and communication protocols.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthcareResponse"}}}},"4XX":{"description":"These error types are usually raised for requests containing\ninvalid parameters or payloads, or an event has occurred meaning\nthat the request cannot be fulfilled, as follows:\n\n\n| HTTP status | Description |\n| ----------- | --------------------------------------------- |\n| 400 | Bad Request: Search distance must be numeric |\n| 400 | Bad Request: Search distance must be greater than 0 |\n| 400 | Bad Request: Search distance must be less than or equal to 100 |\n| 400 | Bad Request: The gender must be one of the following: M, F, I |\n| 400 | Bad Request: The supplied service Id of the patient's practice does not exist in the system |\n| 400 | Bad Request: The age group ID must be one of the following: 1, 2, 3, 4, 8. |\n| 400 | Bad Request: Invalid post code | \n| 401 | Unauthorized: You are not authorized to access this resource. |\n| 404 | Not Found |\n| 408 | Request timed out |\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/4XXError"}}}},"5XX":{"description":"These error types are typically raised for server processing\nerrors, and should be reported back to our customer support team:\n\n| HTTP status | Description |\n| ----------- | --------------------------------------------- |\n| 500 | Internal Error |\n| 502 | Bad Gateway |\n| 504 | Gateway Timed Out |\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/5XXError"}}}}},"deprecated":false,"security":[{"BasicAuth":[]}]}},"/services/byClinicalTerm/{caseId}/{postcode}/{searchDistance}/{gppracticeId}/{age}/{gender}/{disposition}/{symptomGroupDiscriminatorCombos}/{numberPerType}":{"get":{"summary":"Get service details by clinical term","description":"# Overview\n\nResults are grouped by service type and ordered by distance from the search location, with the closest services appearing first. \n\nThis search method allows users to search the Directory of Services (DoS) based on clinical symptoms, search location and optional patient details. \n\nThe search returns a set of healthcare services that match the search criteria, up to the specified maximum number of results per service type. \n\nThe search only returns active services and filters results based on the user's referral permissions. \n\nOptional patient details like age, gender and registered GP practice can be provided to further refine the search results.\n\n# Search rules\n\n| Parameter | Rule |\n|---------------------|----------------------------------|\n| Username | Only services where the referral role matches the Search Role of the authenticated user are returned |\n| | Only active services are returned |\n| Search Distance | Use this value to calculate the **search area**, with the postcode passed in at the centre - only services within this area are returned. If zero, default value is used: 37.5 miles |\n| Postcode | Postcode is used to calculate the search distance, and the distance (in miles) between the postcode and each service is included in response |\n| Postcode | If no postcode is passed in, an error will be returned. If a postcode of zero is passed in, an error will not be returned but no services will match |\n| Age | Only services matching the age group provided are returned in the response. Where zero, age group is ignored |\n| Gender | Only services matching the gender code provided are returned in the response |\n| GP practice ID | Services which are restricted to patients of a specified GP practice will only return if the GP practice ID passed in is on the Service Referrals list of the service |\n| Symptom Group Discriminator Combos | Each search request must include exactly one valid symptom group discriminator combination. If no combination is provided, the request will return an error. If a combination value of zero is provided, the request will process but no services will be matched. Providing multiple combinations or invalid combinations will result in an error |\n| Number per type | Where there are more results per Service Type than the Number per type value, only the closest services (by distance) up to the total number requested are returned. If passed in zero, the default value is used: 5 | \n| Capacity status | The capacity status is always included in the response at the time of the request |\n","operationId":"getByClinicalTerm","parameters":[{"$ref":"#/components/parameters/caseId"},{"$ref":"#/components/parameters/postcode"},{"$ref":"#/components/parameters/searchDistance"},{"$ref":"#/components/parameters/gppracticeId"},{"$ref":"#/components/parameters/age"},{"$ref":"#/components/parameters/gender"},{"$ref":"#/components/parameters/disposition"},{"$ref":"#/components/parameters/symptomGroupDiscriminatorCombos"},{"$ref":"#/components/parameters/numberPerType"}],"responses":{"200":{"description":"# Response ordering\n\nServices are ordered by distance from the search location, with the following priority:\n\n* services where the provided GP practice ID matches the Service Referrals list appear first\n* all other services are ordered by ascending distance\n\n# Response fields\n\nEvery response includes:\n\n* status code\n* response code\n* transaction ID\n* catch-all flag\n* total service count\n\n# Catch-all behaviour\n\nThe catch-all flag indicates whether any matching services were found:\n\n* `false` = One or more services returned\n* `true` = No services returned\n\nNote: This catch-all flag is distinct from the Check Capacity Summary catch-all rule (which returns the 2 nearest EDs when ≤1 services are found). That rule does not apply here. \n\n# Response field definitions\n\n### Email\n\nThis is the email address of the service and is intended for use by clinicians and healthcare professionals only. \n\nIt should not be shared with the public or displayed on public-facing websites/applications. \n\nThe email address can be used for clinical correspondence, referrals and other professional communications between healthcare providers.\n\n### Opening times\n\nYou may receive multiple types of opening **times**, and these should be treated in the following priority order.\n\n### Specified opening times\n\nThese allow services to register temporary exceptions or changes to their usual operating hours (e.g. for holidays, special events, or one-off circumstances). \n\nWhen specified opening times are present, they should take precedence and override any other session times that are returned for that date, including overriding the `Open all hours` flag if it is set. \n\nThis ensures the most up-to-date and accurate opening hours are displayed.\n\n### Open all hours\n\nIf the flag is set to `Open all hours = True` and there are no specified times for the given date, then the service should be treated as open 24 hours a day, 7 days a week, 365 days a year, including weekends and bank holidays. \n\nThis means the service operates continuously without any breaks or closures. \n\nThere should not be any Standard opening times defined for these services since they are always open, but if Standard opening times are present in the data, they should be ignored in favour of the `Open all hours` flag. \n\nThe `Open all hours` flag takes precedence over Standard opening times but can still be overridden by specified opening times for specific dates.\n\n### Public holidays\n\nServices can be profiled with a set of opening times for Public holidays, or can be configured to be closed for all Public holidays by default. \n\nWhen a service is set to be closed for all Public holidays, any exceptions to this rule (where the service is actually open on a specific public holiday) must be recorded as a specified opening time. \n\nIf the date being checked falls on a public holiday, the public holiday opening times or closure should take precedence and override any Standard opening times defined for that day of the week. \n\nThis ensures that special holiday hours or closures are properly reflected.\n\n### Standard opening times\n\nThese are the regular, recurring opening hours for the service that apply when no special circumstances (like holidays or temporary changes) are in effect. \n\nA service may have multiple opening sessions within a single day (for example, morning and afternoon sessions), but these session times must not overlap with each other to avoid ambiguity.\n\nDue to technical limitations, session times cannot span across midnight - they must end at 23:59 at the latest. For services that operate overnight, this means their hours will be split into two sessions:\n\n* one session ending at 23:59 on the first day\n* another session starting at 00:00 on the following day\n\nFor example, a service open from 8pm to 6am would be represented as:\n\n* Monday: 20:00-23:59\n* Tuesday: 00:00-06:00\n\n### Referral information\n\nAdditional information about the service is provided in two separate fields:\n\n`callHandler` field:\n\n* contains information intended for members of the public\n* includes general instructions about accessing or using the service\n* should be displayed on public-facing websites and applications\n* contains patient-friendly language and guidance\n\nexamples: \n\n* opening hours \n* booking instructions \n* walk-in information\n\n`other` field:\n\n* contains information intended for clinicians and healthcare professionals only\n* must not be displayed to the public\n* may contain sensitive or restricted information like:\n * direct clinical contact numbers\n * internal referral processes\n * clinical criteria\n * professional-only access details\n * staff-specific instructions\n* should only be visible to authenticated healthcare professionals\n* care must be taken to keep this information secure and restricted\n\n### Telephone numbers\n\nBoth public and non-public telephone numbers are included in the response:\n\n* Public telephone numbers:\n * should be displayed to all users including members of the public\n * used for general enquiries and patient contact\n * listed in the `public` field of the phone object\n\n* Non-public telephone numbers:\n * must only be displayed to authenticated clinicians and healthcare professionals \n * used for direct clinical communication between healthcare providers\n * contains priority/emergency contact numbers\n * must not be shared with or displayed to members of the public\n * listed in the `nonPublic` field of the phone object\n * care must be taken to properly restrict access based on user role \n\n### Capacity status\n\nService capacity is indicated using a traffic light system:\n* green (High): Default status indicating normal capacity\n* amber (Low): Limited capacity available\n* red (None): At capacity or temporarily closed\n\nCapacity status can be updated for up to 5 days. Services with Red status will still be returned in results,\nbut should be displayed with appropriate warnings since they have reported being at capacity or unable to accept new patients. \n\n### Distance from patient\n\nThe calculated straight-line (as-the-crow-flies) distance in miles between the search postcode and the service location.\n\n### Public name \n \nThe public-friendly name of the service that is commonly recognised by patients and the general public. \nThis may be different from the official registered name and is intended to be more familiar and easier to understand. \n\n### Professional referral information\n \nProfessional referral guidance specifically for NHS Service Finder users, providing detailed instructions on patient referral pathways, signposting options, and communication protocols.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthcareResponse"}}}},"4XX":{"description":"These error types are usually raised for requests containing\ninvalid parameters or payloads, or an event has occurred meaning\nthat the request cannot be fulfilled, as follows:\n\n| HTTP status | Description |\n| ----------- | --------------------------------------------- |\n| 400 | Bad Request: Search distance must be numeric |\n| 400 | Bad Request: Search distance must be greater than 0 |\n| 400 | Bad Request: Search distance must be no more than 100 |\n| 400 | Bad Request: The gender must be one of the following: M, F, I |\n| 400 | Bad Request: The supplied service Id of the patient's practice does not exist in the system |\n| 400 | Bad Request: The age group ID must be one of the following: 1, 2, 3, 4, 8. |\n| 400 | Bad Request: Invalid \\\"SymptomGroupId=SymptomDiscriminatorId\\\" combination supplied |\n| 400 | Bad Request: Invalid post code | \n| 401 | Unauthorized: You are not authorized to access this resource |\n| 404 | Not Found |\n| 408 | Request timed out |\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/4XXError"}}}},"5XX":{"description":"These error types are typically raised for server processing\nerrors, and should be reported back to our customer support Team:\n\n| HTTP status | Description |\n| ----------- | ---------------- |\n| 500 | Internal Server Error |\n| 502 | Bad Gateway |\n| 504 | Gateway Timed Out |\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/5XXError"}}}}},"deprecated":false,"security":[{"BasicAuth":[]}]}},"/services/byServiceId/{serviceId}":{"get":{"summary":"Get service details by Service Id","description":"## Overview\n\nThis endpoint allows connecting parties to retrieve service details for a given Service Id. \n\nThe details returned contain a wider set of attributes than those returned by the clinical and service type endpoints, allowing connecting parties access to additional information about the service. \n\nThe Service Id uniquely identifies a service in the Directory of Services, and so a search using this endpoint will return details for **one service or no services only.**\n\n# Search rules\n\n| Parameter | Rule |\n|---------------------|----------------------------------|\n| Username | Only services where the referral role matches the Search Role of the authenticated user are returned |\n| | Only active services are returned |\n| Service Id | \tOnly the service with a matching Service Id is returned |\n| Capacity status | The capacity status is always included in the response at the time of the request |\n","operationId":"byServiceId","parameters":[{"$ref":"#/components/parameters/serviceId"}],"responses":{"200":{"description":"A successful response, providing details of a service that matches\nthe given Service Id.\n\n# Response fields\n\nEvery response includes:\n\n* status code\n* response code \n* transaction ID\n* catch-all flag\n* total service count\n\n# Catch-all behaviour\n\nThe catch-all flag indicates whether any matching services were found:\n\n* `false` = One or more services returned\n* `true` = No services returned\n\nNote: This catch-all flag is distinct from the Check Capacity Summary catch-all rule (which returns the 2 nearest EDs when ≤1 services are found). That rule does not apply here. \n\n# Response field definitions\n\n### Email\n\nThis is the email address of the service and is intended for use by clinicians and healthcare professionals only. \n\nIt should not be shared with the public or displayed on public-facing websites/applications. \n\nThe email address can be used for clinical correspondence, referrals and other professional communications between healthcare providers.\n\n### Opening times\n\nYou may receive multiple types of **opening times**, and these should be treated in the following priority order.\n\n### Specified opening times\n\nThese allow services to register temporary exceptions or changes to their usual operating hours (e.g. for holidays, special events, or one-off circumstances). \n\nWhen specified opening times are present, they should take precedence and override any other session times that are returned for that date, including overriding the `Open all hours` flag if it is set. \n\nThis ensures the most up-to-date and accurate opening hours are displayed.\n\n### Open all hours\n\nIf the flag is set to `Open all hours = True` and there are no specified times for the given date, then the service should be treated as open 24 hours a day, 7 days a week, 365 days a year, including weekends and bank holidays. \n\nThis means the service operates continuously without any breaks or closures. \n\nThere should not be any Standard opening times defined for these services since they are always open, but if Standard opening times are present in the data, they should be ignored in favor of the `Open all hours` flag. \n\nThe `Open all hours` flag takes precedence over Standard opening times but can still be overridden by specified opening times for specific dates.\n\n### Public holidays\n\nServices can be profiled with a set of opening times for Public holidays, or can be configured to be closed for all Public holidays by default. \n\nWhen a service is set to be closed for all Public holidays, any exceptions to this rule (where the service is actually open on a specific public holiday) must be recorded as a specified opening time. \n\nIf the date being checked falls on a public holiday, the public holiday opening times or closure should take precedence and override any Standard opening times defined for that day of the week. \n\nThis ensures that special holiday hours or closures are properly reflected.\n\n### Standard opening times\n\nThese are the regular, recurring opening hours for the service that apply when no special circumstances (like holidays or temporary changes) are in effect. \n\nA service may have multiple opening sessions within a single day (for example, morning and afternoon sessions), but these session times must not overlap with each other to avoid ambiguity.\n\nDue to technical limitations, session times cannot span across midnight - they must end at 23:59 at the latest. For services that operate overnight, this means their hours will be split into two sessions:\n\n* one session ending at 23:59 on the first day\n* another session starting at 00:00 on the following day\n\nFor example, a service open from 8pm to 6am would be represented as:\n\n* Monday: 20:00-23:59\n* Tuesday: 00:00-06:00\n\n### Referral information\n\nAdditional information about the service is provided in two separate fields:\n\n`callHandler` field:\n\n* contains information intended for members of the public\n* includes general instructions about accessing or using the service\n* should be displayed on public-facing websites and applications\n* contains patient-friendly language and guidance\n\nexamples: \n\n* opening hours \n* booking instructions \n* walk-in information\n\n`other` field:\n\n* contains information intended for clinicians and healthcare professionals only\n* must not be displayed to the public\n* may contain sensitive or restricted information like:\n * direct clinical contact numbers\n * internal referral processes\n * clinical criteria\n * professional-only access details\n * staff-specific instructions\n* should only be visible to authenticated healthcare professionals\n* care must be taken to keep this information secure and restricted\n\n### Telephone numbers\n\nBoth public and non-public telephone numbers are included in the response:\n\n* Public telephone numbers:\n * should be displayed to all users including members of the public\n * used for general enquiries and patient contact\n * listed in the `public` field of the phone object\n\n* Non-public telephone numbers:\n * must only be displayed to authenticated clinicians and healthcare professionals \n * used for direct clinical communication between healthcare providers\n * contains priority/emergency contact numbers\n * must not be shared with or displayed to members of the public\n * listed in the `nonPublic` field of the phone object\n * care must be taken to properly restrict access based on user role \n\n### Capacity status\n\nService capacity is indicated using a traffic light system:\n\n* green (High): Default status indicating normal capacity\n* amber (Low): Limited capacity available\n* red (None): At capacity or temporarily closed\n\nCapacity status can be updated for up to 5 days. Services with Red status will still be returned in results, but should be displayed with appropriate warnings since they have reported being at capacity or unable to accept new patients. \n \n### Capacity updated\n\nInformation relating to when the capacity was last updated in the DoS (Directory of Services).\n\n* date: Updated date of the service\n* time: Updated time of the service\n* by: The name of the person who updated capacity in DoS (Directory of Services).\n\n### Public name\n\nThe public-friendly name of the service that is commonly recognised by patients and the general public. This may be different from the official registered name and is intended to be more familiar and easier to understand. \n\n### Professional referral information\n \nProfessional referral guidance specifically for NHS Service Finder users, providing detailed instructions on patient referral pathways, signposting options, and communication protocols.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthcareResponse"}}}},"4XX":{"description":"These error types are usually raised for requests containing\ninvalid parameters or payloads, or an event has occurred meaning\nthat the request cannot be fulfilled, as follows:\n\n| HTTP status | Description |\n| ----------- | --------------------------------------------- |\n| 400 | Bad Request: Service Id must be a number \n| 401 | Unauthorized: You are not authorized to access this resource. |\n| 404 | Not Found |\n| 408 | Request timed out |\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/4XXError"},"example":{"error":{"code":400,"message":"Bad Request: Service Id must be a number"}}}}},"5XX":{"description":"These error types are typically raised for server processing\nerrors, and should be reported back to our customer support Team:\n\n| HTTP status | Description |\n| ----------- | --------------------------------------------- |\n| 500 | Internal server Error |\n| 502 | Bad Gateway |\n| 504 | Gateway Timed Out |\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/5XXError"},"example":{"error":{"code":500,"message":"Internal Server Error"}}}}}},"deprecated":false,"security":[{"BasicAuth":[]}]}},"/services/byOdsCode/{odsCode}":{"get":{"summary":"Get service details by ODS code","description":"## Overview\n\nThe ODS code identifies services in the Directory of Services associated with a given ODS code, and so a search using this endpoint will return details for zero or more services.\n\nThis endpoint allows connecting parties to retrieve service details for a given ODS code. \n\nThe details returned contain a wider set of attributes than those returned by the clinical and service type endpoints, allowing connecting parties access to additional information about the service. \n\n# Search rules\n\n| Parameter | Rule |\n|---------------------|----------------------------------|\n| Username | Only services where the referral role matches the Search Role of the authenticated user are returned |\n| | Only active services are returned |\n| ODS Code | All active services with a matching ODS code are returned |\n| Capacity status | The capacity status is always included in the response at the time of the request |\n","operationId":"byOdsCode","parameters":[{"$ref":"#/components/parameters/odsCode"}],"responses":{"200":{"description":"A successful response, providing details of services that matches\nthe given ODS code.\n\n# Response fields\n\nEvery response includes:\n\n* status code\n* response code \n* transaction ID\n* catch-all flag\n* total service count\n\n# Catch-all behaviour\n\nThe catch-all flag indicates whether any matching services were found:\n\n* `false` = One or more services returned\n* `true` = No services returned\n\nNote: This catch-all flag is distinct from the Check Capacity Summary catch-all rule (which returns the 2 nearest EDs when ≤1 services are found). That rule does not apply here. \n\n# Response field definitions\n\n### Email\n\nThis is the email address of the service and is intended for use by clinicians and healthcare professionals only. \n\nIt should not be shared with the public or displayed on public-facing websites/applications. \n\nThe email address can be used for clinical correspondence, referrals and other professional communications between healthcare providers.\n\n### Opening times\n\nYou may receive multiple types of opening **times**, and these should be treated in the following priority order.\n\n### Specified opening times\n\nThese allow services to register temporary exceptions or changes to their usual operating hours (e.g. for holidays, special events, or one-off circumstances). \n\nWhen specified opening times are present, they should take precedence and override any other session times that are returned for that date, including overriding the `Open all hours` flag if it is set. \n\nThis ensures the most up-to-date and accurate opening hours are displayed.\n\n### Open all hours\n\nIf the flag is set to `Open all hours = True` and there are no specified times for the given date, then the service should be treated as open 24 hours a day, 7 days a week, 365 days a year, including weekends and bank holidays. \n\nThis means the service operates continuously without any breaks or closures. \n\nThere should not be any Standard opening times defined for these services since they are always open, but if Standard opening times are present in the data, they should be ignored in favor of the `Open all hours` flag. \n\nThe `Open all hours` flag takes precedence over Standard opening times but can still be overridden by specified opening times for specific dates.\n\n### Public holidays\n\nServices can be profiled with a set of opening times for Public holidays, or can be configured to be closed for all Public holidays by default. \n\nWhen a service is set to be closed for all Public holidays, any exceptions to this rule (where the service is actually open on a specific public holiday) must be recorded as a specified opening time. \n\nIf the date being checked falls on a public holiday, the public holiday opening times or closure should take precedence and override any Standard opening times defined for that day of the week. \n\nThis ensures that special holiday hours or closures are properly reflected.\n\n### Standard opening times\n\nThese are the regular, recurring opening hours for the service that apply when no special circumstances (like holidays or temporary changes) are in effect. \n\nA service may have multiple opening sessions within a single day (for example, morning and afternoon sessions), but these session times must not overlap with each other to avoid ambiguity.\n\nDue to technical limitations, session times cannot span across midnight - they must end at 23:59 at the latest. For services that operate overnight, this means their hours will be split into two sessions:\n\n* one session ending at 23:59 on the first day\n* another session starting at 00:00 on the following day\n\nFor example, a service open from 8pm to 6am would be represented as:\n\n* Monday: 20:00-23:59\n* Tuesday: 00:00-06:00\n\n### Referral information\n\nAdditional information about the service is provided in two separate fields:\n\n`callHandler` field:\n\n* contains information intended for members of the public\n* includes general instructions about accessing or using the service\n* should be displayed on public-facing websites and applications\n* contains patient-friendly language and guidance\n\nExamples: \n\n* opening hours \n* booking instructions \n* walk-in information\n\n`other` field:\n\n* contains information intended for clinicians and healthcare professionals only\n* must not be displayed to the public\n\n* may contain sensitive or restricted information like:\n * direct clinical contact numbers\n * internal referral processes\n * clinical criteria\n * professional-only access details\n * staff-specific instructions\n* should only be visible to authenticated healthcare professionals\n\n* care must be taken to keep this information secure and restricted\n\n### Telephone numbers\n\nBoth public and non-public telephone numbers are included in the response:\n\n* Public telephone numbers:\n * should be displayed to all users including members of the public\n * used for general enquiries and patient contact\n * listed in the `public` field of the phone object\n\n* Non-public telephone numbers:\n * must only be displayed to authenticated clinicians and healthcare professionals \n * used for direct clinical communication between healthcare providers\n * contains priority/emergency contact numbers\n * must not be shared with or displayed to members of the public\n * listed in the `nonPublic` field of the phone object\n * care must be taken to properly restrict access based on user role \n\n### Capacity status\n\nService capacity is indicated using a traffic light system:\n\n* green (High): Default status indicating normal capacity\n* amber (Low): Limited capacity available\n* red (None): At capacity or temporarily closed\n\nCapacity status can be updated for up to 5 days. Services with Red status will still be returned in results,\n\nbut should be displayed with appropriate warnings since they have reported being at capacity or unable to accept new patients. \n\n### Capacity updated\n\nInformation relating to when the capacity was last updated in the DoS (Directory of Services).\n\n* date: Updated date of the service\n* time: Updated time of the service\n* by: The name of the person who updated capacity in DoS (Directory of Services).\n\n### Public name \n \nThe public-friendly name of the service that is commonly recognised by patients and the general public. \n\nThis may be different from the official registered name and is intended to be more familiar and easier to understand. \n\n### Professional referral information\n \nProfessional referral guidance specifically for NHS Service Finder users, providing detailed instructions on patient referral pathways, signposting options, and communication protocols.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthcareResponse"}}}},"4XX":{"description":"These error types are usually raised for requests containing\ninvalid parameters or payloads, or an event has occurred meaning\nthat the request cannot be fulfilled, as follows:\n\n| HTTP status | Description |\n| ----------- | --------------------------------------------- |\n| 401 | Unauthorized: You are not authorized to access this resource. |\n| 404 | Not Found |\n| 408 | Request timed out |\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/4XXError"},"example":{"error":{"code":404,"message":"Not Found"}}}}},"5XX":{"description":"These error types are typically raised for server processing\nerrors, and should be reported back to our customer support Team:\n\n| HTTP status | Description |\n| ----------- | --------------------------------------------- |\n| 500 | Internal Server Error |\n| 502 | Bad Gateway |\n| 504 | Gateway Timed Out |\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/5XXError"},"example":{"error":{"code":500,"message":"Internal Server Error"}}}}}},"deprecated":false,"security":[{"BasicAuth":[]}]}}},"components":{"schemas":{"HealthcareResponse":{"required":["success"],"type":"object","properties":{"success":{"required":["code","transactionId","servicesReturnedAreCatchAll","serviceCount","services"],"type":"object","properties":{"code":{"type":"integer","description":"The HTTP status code of the response.","example":200},"transactionId":{"type":"string","description":"A unique identifier for the transaction.","example":"A7F24C91-DE3B-491F-B8E5-926FDA438B12"},"servicesReturnedAreCatchAll":{"type":"string","description":"Indicates whether the returned services are catch-all services.","example":"TRUE"},"serviceCount":{"type":"integer","description":"The number of services returned in the response.","example":1},"services":{"type":"array","items":{"required":["id","name","type","odsCode","address","postcode","easting","northing","phone","web","openingTimes","referralInstructions","capacity","endpoints","publicName","professionalReferralInformation"],"type":"object","properties":{"parent":{"required":["id"],"type":"object","properties":{"id":{"type":"string","description":"The unique parent identifier for the service in DoS (Directory of\nServices). \n\nThis information is only available through the `ByODSCode` and `ByServiceId` endpoints.\n","example":"98654"}}},"id":{"type":"string","description":"The DoS unique identifier for the service.","example":"12345"},"name":{"type":"string","description":"The name of the service","example":"Pharmacy - Test Pharmacy"},"type":{"required":["id","name"],"type":"object","properties":{"id":{"type":"string","description":"The service type identifier.","example":"113"},"name":{"type":"string","description":"The service type in readable form.","example":"Pharmacy"}},"description":"The service type object represents one of many possible service\ntypes \n\nthat can be returned by the search. Each service type contains specific \n\nattributes and characteristics that define the nature of the service.\n"},"odsCode":{"type":"string","description":"The ODS code of the service.","example":"ODS123"},"isNational":{"type":"string","description":"Flag denoting whether this is a national service. This information is only available through the `ByODSCode` and `ByServiceId` endpoints.","example":"false"},"created":{"required":["date","time","by"],"type":"object","properties":{"date":{"type":"string","description":"Creation date of the service.","example":"6/10/2024"},"time":{"type":"string","description":"Creation time of the service.","example":"10:30"},"by":{"type":"string","description":"Created by","example":"manager"}},"description":"Contains metadata about the service's initial creation date in the\nDirectory of Services (DoS).\n\nThis information is only available through the `ByODSCode` and `ByServiceId` endpoints.\n"},"updated":{"required":["date","time","by"],"type":"object","properties":{"date":{"type":"string","description":"Updated date of the service.","example":"6/10/2024"},"time":{"type":"string","description":"Updated time of the service.","example":"10:30"},"by":{"type":"string","description":"Updated by","example":"manager xyz"}},"description":"Information relating to when the service was last updated in the\nDoS (Directory of Services). \n\nThis information is only available through the `ByODSCode` and `ByServiceId` endpoints.\n"},"address":{"type":"array","items":{"type":"string"},"description":"The address lines of the service.","example":["65 Test Avenue","Test Road","Some Place"]},"town":{"type":"string","description":"The town where the service is located. This information is only available through the `ByODSCode` and `ByServiceId` endpoints.","example":"Yorkshire test"},"country":{"type":"string","description":"The country where the service is located. This information is only available through the `ByODSCode` and `ByServiceId` endpoints.","example":"England"},"postcode":{"type":"string","description":"The postcode of the service.","example":"EX12 5SX"},"easting":{"type":"string","description":"The easting location coordinates of the service.","example":"123456"},"northing":{"type":"string","description":"The northing location coordinates of the service.","example":"54321"},"phone":{"required":["public","nonPublic"],"type":"object","properties":{"public":{"type":"string","description":"The public telephone number of the service.","example":"01111 222222"},"nonPublic":{"type":"string","description":"The non-public telephone number of the service.","example":"01111 222223"},"fax":{"type":"string","description":"The fax number of the service.","example":"01111 222224"}},"description":"The phone contact details object for the service."},"email":{"type":"string","description":"The email address of the service. This information is only available through the `ByODSCode` and `ByServiceId` endpoints.","example":"xyz@nhs.net"},"web":{"type":"string","description":"The web address of the service","example":"www.testpharmacy.co.uk"},"openingTimes":{"required":["allHours","days","specifiedDates"],"type":"object","properties":{"allHours":{"type":"boolean","description":"Flag to denote whether the service is Open all hours.","example":false},"days":{"type":"array","items":{"required":["day","sessions"],"type":"object","properties":{"day":{"type":"string","description":"The day of the week (Monday to Sunday, and can also include Bank Holiday for Bank Holiday opening times).","example":"Monday"},"sessions":{"type":"array","items":{"type":"object","properties":{"start":{"required":["hours","minutes"],"type":"object","properties":{"hours":{"type":"string","description":"The starting (opening) time in hours for the session or opening period.","example":"09"},"minutes":{"type":"string","description":"The starting time (opening) in minutes for the session or opening period.","example":"30"}},"description":"A starting (opening) time object for a session or opening period."},"end":{"required":["hours","minutes"],"type":"object","properties":{"hours":{"type":"string","description":"The ending (closing) time in hours for the session or opening period.","example":"18"},"minutes":{"type":"string","description":"The ending (closing) time in minutes for the session or opening period.","example":"00"}},"description":"An ending (closing) time object for a session or opening period."}}},"description":"An array of start (opening) and end (closing) time objects. An empty session object denotes that the service is not open at all during this day."},"specifiedDates":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"The date in which to declare specific opening or closing times.","example":"2025-03-15"},"sessions":{"type":"array","items":{"type":"object","properties":{"start":{"required":["hours","minutes"],"type":"object","properties":{"hours":{"type":"string","description":"The starting (opening) time in hours for the session or opening period.","example":"09"},"minutes":{"type":"string","description":"The starting time (opening) in minutes for the session or opening period.","example":"30"}},"description":"A starting (opening) time object for a session or opening period."},"end":{"required":["hours","minutes"],"type":"object","properties":{"hours":{"type":"string","description":"The ending (closing) time in hours for the session or opening period.","example":"18"},"minutes":{"type":"string","description":"The ending (closing) time in minutes for the session or opening period.","example":"00"}},"description":"An ending (closing) time object for a session or opening period."}}},"description":"An array of start (opening) and end (closing) time objects. An empty session object denotes that the service is not open at all during this day."}}},"description":"An array of specified date objects, used to denote special opening (or closing) hours on specific dates."}}},"description":"An array of Day objects."}},"description":"The opening times object for the service."},"region":{"required":["id","name"],"type":"object","properties":{"id":{"type":"string","description":"Id of the region.","example":"69234"},"name":{"type":"string","description":"Name of the region.","example":"Test"}},"description":"The region where the service is located. This information is only available through the `ByODSCode` and `ByServiceId` endpoints."},"referralInstructions":{"required":["callHandler","other"],"type":"object","properties":{"callHandler":{"type":"string","description":"This field is intended to provide information about the service to members of the public.","example":"Contact main reception"},"other":{"type":"string","description":"This field is intended for use by clinicians and care should be taken when displaying this, as it may contain non-public information such as contact methods.","example":"Walk-in service available"}},"description":"An object for holding a set of referral instructions for the patient for this service."},"capacity":{"required":["status","updated"],"type":"object","properties":{"status":{"required":["rag","human","hex"],"type":"object","properties":{"rag":{"type":"string","description":"The Red, Amber, Green (RAG) status of the service.","example":"Green"},"human":{"type":"string","description":"The human readable form of the RAG status.","example":"Available"},"hex":{"type":"string","description":"A hexadecimal encoding of the RAG status for colour.","example":"#00FF00"}},"description":"The capacity status object for the service encapsulating RAG status details."},"updated":{"required":["date","time","by"],"type":"object","properties":{"date":{"type":"string","description":"Updated date of the service.","example":"6/10/2024"},"time":{"type":"string","description":"Updated time of the service.","example":"10:30"},"by":{"type":"string","description":"Updated by.","example":"Test user"}},"description":"Information relating to when the capacity was last updated in the\nDoS (Directory of Services).\n\nThis information is only available through the `ByODSCode` and `ByServiceId` endpoints.\n"}},"description":"The capacity object for the service encapsulating capacity details. Note that this object will only be returned if the RAG status of the service has changed within the last 24 hours."},"symptomGroups":{"type":"array","items":{"required":["id","name","symptomDiscriminators"],"type":"object","properties":{"id":{"type":"string","description":"The id of the symptom group.","example":"100"},"name":{"type":"string","description":"The name of the symptom group.","example":"Accident or Emergency"},"symptomDiscriminators":{"type":"array","items":{"required":["id","name"],"type":"object","properties":{"id":{"type":"string","description":"The id of the symptom discriminators.","example":"10010"},"name":{"type":"string","description":"The name of the symptom discriminators.","example":"Animal Bite test"}}},"description":"Symptom discriminators details."}}},"description":"A list of symptom groups that this service is configured to handle\nand provide care for. \n\nEach symptom group represents a category of medical conditions or symptoms that the service specialises in treating. \n\nThis information is only available through the `ByODSCode` and `ByServiceId` endpoints.\n"},"dispositions":{"type":"array","items":{"required":["id","name"],"type":"object","properties":{"id":{"type":"string","description":"The id of the disposition.","example":"DX05AJHG"},"name":{"type":"string","description":"The name of the disposition.","example":"Test disposition name"}}},"description":"A list of dispositions (recommended actions or outcomes) associated\nwith this service. \n\nEach disposition represents a clinical recommendation for patient care or referral based on their presenting symptoms and needs. \n\nThis information is only available through the `ByODSCode` and `ByServiceId` endpoints.\n"},"referralRoles":{"type":"array","items":{"required":["id","name"],"type":"object","properties":{"id":{"type":"string","description":"The id of the referral role.","example":"10"},"name":{"type":"string","description":"The name of the referral role.","example":"Test Referral"}}},"description":"A list of roles that are authorised to refer patients to this\nservice. \n\nThis information is only available through the `ByODSCode` and `ByServiceId` endpoints.\n"},"serviceReferrals":{"required":["restricted","services"],"type":"object","properties":{"restricted":{"type":"string","description":"The restricted flag identifies whether the service will return or not for the patient.","example":"false"},"services":{"type":"array","items":{"required":["id","name"],"type":"object","properties":{"id":{"type":"string","description":"The id of the service.","example":"10231"},"name":{"type":"string","description":"The name of the service.","example":"Test Service"}}},"description":"A list of services that are returned based on the restricted flag. \n\nIf the restricted flag is 'true', the service will only return for patients registered with specific GP practices. \n\nIf the patient is not registered with one of these practices, the service will not be returned in the results.\n"}},"description":"A list of service referrals that define which GP practices can\nrefer patients to this service. \n\nUsed to restrict access to services based on the patient's registered GP practice.\n\nThis information is only available through the `ByODSCode` and `ByServiceId` endpoints.\n"},"ageGroups":{"type":"array","items":{"required":["id","name"],"type":"object","properties":{"id":{"type":"string","description":"The id of the age group.","example":"1"},"name":{"type":"string","description":"The name of the age group.","example":"Adult (16+)"}}},"description":"A list of age groups associated to the service. This information is only available through the `ByODSCode` and `ByServiceId` endpoints."},"genders":{"type":"array","items":{"required":["id","name"],"type":"object","properties":{"id":{"type":"string","description":"The id of the gender.","example":"M"},"name":{"type":"string","description":"The name of the gender.","example":"Male"}}},"description":"A list of gender options that this service is configured to support\nand provide care for. Each gender has an ID and display\nname. \n\nThis information is only available through the `ByODSCode` and `ByServiceId` endpoints.\n"},"endpoints":{"type":"array","items":{"required":["tag","name","order","value"],"type":"object","properties":{"tag":{"type":"string","description":"The type of endpoint. Supported endpoints include email and itk.","example":"itk"},"name":{"type":"string","description":"The name of the endpoint.","example":"Service itk point"},"order":{"type":"string","description":"The preferred order of endpoint contact. 1 being the most preferred.","example":"1"},"value":{"type":"string","description":"The actual callable value of the endpoint.","example":"https://example-endpoint"}}},"description":"An array of endpoint objects that define the communication channels\nand integration points supported by this\nservice.\n"},"patientDistance":{"type":"string","description":"The distance in miles this service is to the search (location) postcode. This information is only available through the `ByServiceType` and `ByClinicalTerm` endpoints.","example":"1.4"},"publicName":{"type":"string","description":"The public name of the service.","example":"GP Public"},"professionalReferralInformation":{"type":"string","description":"Professional Referral Info is referral info only for use by the NHS Service Finder product. It provides information to Service Finder users on how to refer/signpost/inform the patient.","example":"Professional patient referral instructions"}}},"description":"The list of healthcare services returned by the search, grouped by service type and ordered by closest distance from the search location first."}}}},"description":"Successful response schema."},"4XXError":{"required":["error"],"type":"object","properties":{"error":{"required":["code","message"],"type":"object","properties":{"code":{"type":"integer","description":"The HTTP status code of the error.","example":400},"message":{"type":"string","description":"A human-readable error message.","example":"Bad Request: Search distance must be numeric"}},"description":"The error object containing the HTTP status code and descriptive error message."}},"description":"4XX Error response schema."},"5XXError":{"required":["error"],"type":"object","properties":{"error":{"required":["code","message"],"type":"object","properties":{"code":{"type":"integer","description":"The HTTP status code of the error.","example":500},"message":{"type":"string","description":"A human-readable error message.","example":"Internal Server Error"}},"description":"The error object containing the HTTP status code and descriptive error message."}},"description":"5XX Error response schema."}},"parameters":{"caseId":{"name":"caseId","in":"path","description":"This is an optional field where the system supplier may add a case ID relating to the patient's case record, which would aid traceability of requests where required, specify \"0\" if you do not wish to use this.","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"0"}},"postcode":{"name":"postcode","in":"path","description":"The patient or search location supplied as a UK postcode. Coupled with the search distance parameter provides the search with the searching radius in which to return eligible services. The postcode must be a valid UK postcode.","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"W1A1AA"}},"searchDistance":{"name":"searchDistance","in":"path","description":"The distance in miles from the postcode (search location) to include services. The search distance can range from 0 up to a maximum of 100 miles. If set to 0, the search distance will default to 37.5 miles.","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"integer","example":30}},"gppracticeId":{"name":"gppracticeId","in":"path","description":"Services which are restricted to patients of a specified GP practice will only return if the GP practice ID passed in is on the Service Referrals list of the service. If set to 0, this filter will not be applied.","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"integer","example":0}},"age":{"name":"age","in":"path","description":"Services that are applicable to only a certain age group will only\nreturn if the age group passed in is eligible for those services. If set\nto 0, this filter will not be applied. age group ranges are:\n\n| age group ID | Range |\n|--------------|--------------------------------------|\n| 0 | Filter not applied. |\n| 4 | Neonate and Infant - 0 years |\n| 3 | Toddler - 1-4 years |\n| 2 | Child - 5-15 years |\n| 1 | Adult - 16+ (includes ages 16-129) |\n| 8 | Older People - 65+ (includes ages 65-129) |\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"1"}},"gender":{"name":"gender","in":"path","description":"If provided, only services matching the gender code will be\nreturned in the response. If set to 0, this filter will not be applied.\nGender types are:\n\n| Gender | Description |\n|--------------|--------------------------------------|\n| 0 | Filter not applied |\n| F | Female |\n| M | Male |\n| I | Indeterminate |\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"enum":["0","M","F","I"],"type":"string","example":"0"}},"disposition":{"name":"disposition","in":"path","description":"Deprecated, but still needs a value. Please pass through 0.","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"0"}},"serviceTypeIds":{"name":"serviceTypeIds","in":"path","description":"A comma separated list of all the service types to include in the search.","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"113,100"}},"symptomGroupDiscriminatorCombos":{"name":"symptomGroupDiscriminatorCombos","in":"path","description":"A comma separated list of symptom group discriminator combos to include in the search.","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"0=0"}},"numberPerType":{"name":"numberPerType","in":"path","description":"The number of services to return per service type that match the search criteria.","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"integer","example":6}},"serviceId":{"name":"serviceId","in":"path","description":"A unique identifier used to retrieve detailed information about a\nspecific service from the Directory of Services (DoS).\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"integer","example":11285}},"odsCode":{"name":"odsCode","in":"path","description":"The unique Organization Data Service (ODS) code used to identify\nand retrieve details for specific healthcare services.\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"L98362"}}},"securitySchemes":{"BasicAuth":{"type":"http","description":"Basic authentication using username and password.","scheme":"basic"}}}}