Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
description: "## Overview \nUse this API to find information about organisations that provide NHS healthcare services, NHS organisation types, and coronavirus (COVID-19) walk-in sites.\n\nYou can:\n* retrieve a list of organisation types, for example, GP practices or hospitals\n* search for NHS organisations that provide healthcare services listed in [NHS service near you](https://www.nhs.uk/nhs-services/services-near-you/), for example, Leeds General Infirmary\n* search for coronavirus (COVID-19) walk-in sites\n\nThis API does not support the FHIR standard.\n\n## Who can use this API\nThis API can only be used where there is a legal basis to do so. Make sure you have a valid use case before you go too far with your development. To do this, [contact us](https://digital.nhs.uk/developer/help-and-support). You must do this before you can go live (see ‘Onboarding’ below).\n\n## Related APIs\nThe following APIs are related to this API:\n\n* [Directory of Services - Urgent and Emergency Care - SOAP API](https://digital.nhs.uk/developer/api-catalogue/directory-of-services-soap) - use this SOAP API to access information on a wide range of health and care services across England\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) - use this REST 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 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 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\n## API status and roadmap\nThis API is [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses), meaning:\n * it is available for testing in the integration environment\n * we expect to make breaking changes based on developer feedback\n\n## Service level\nThis API is a bronze service, meaning it is operational and supported only during business hours (8am to 6pm), Monday to Friday excluding bank holidays.\nFor more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).\n\n## Technology\nThis API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#basic-rest).\n\nThis API does not support the FHIR standard.\n\n## Network access\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).\nFor more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).\n\n## Security and authorisation\nThis API is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis),\nmeaning we authenticate the calling application but not the end user.\n\nTo use this API, use the following security pattern:\n* [application-restricted RESTful API - API key authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-api-key-authentication)\n\n## Environments and testing\n\n| Environment | Base URL |\n| ----------------- |---------------------------------------------------------- |\n| Sandbox | `https://sandbox.api.service.nhs.uk/service-search-api/` |\n| Integration test | `https://int.api.service.nhs.uk/service-search-api/` |\n| Production | Not yet available |\n\n### Sandbox testing\nOur [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing):\n* is for early developer testing\n* only covers a limited set of scenarios\n* is open access, so does not allow you to test authorisation\n\nFor details of sandbox test scenarios, or to try out the sandbox using our 'Try this API' feature, see the documentation for each endpoint.\n\nOur [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing) is for formal integration testing.\n\n### Integration testing\nOur [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing):\n* is for formal integration testing\n* includes authorisation, with options for appliation-restricted access\n* test data is a close copy of the production data\n\nFor more details see [integration testing with our RESTful APIs](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing-with-our-restful-apis).\n\n### Rate Limiting\nRate limits apply to both integration test and production environments:\n* 7800 requests per minute per product\n* 6000 requests per minute per application\n\n## Onboarding\nThis API is not yet available for onboarding.\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\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\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## Examples\nThe Directory of Healthcare Services (Service Search) API can be used to search for services and sites based on a variety of filters. These filters can be passed as query parameters for a GET request or as part of the body for a POST request, examples of which are below.\n\n## Contact us\nFor help and support connecting to our APIs and to join our developer community, see [Help and support building healthcare software](https://digital.nhs.uk/developer/help-and-support).\n"
version: Computed and injected at build time by `scripts/set_version.py`
title: Directory of Healthcare Services API - version 3 Organisation API
contact:
name: Directory of Healthcare Services API - version 3
url: https://digital.nhs.uk/developer/help-and-support
email: api.management@nhs.net
servers:
- url: https://sandbox.api.service.nhs.uk/service-search-api
description: Sandbox environment.
- url: https://int.api.service.nhs.uk/service-search-api
description: Integration test environment.
- url: https://api.service.nhs.uk/service-search-api
description: Production environment.
security:
- OAuth_Token: []
tags:
- name: Organisation
paths:
/:
get:
summary: Search for organisations
tags:
- Organisation
operationId: search-GET
description: "## Overview\nUse this endpoint to find information about services provided by NHS organisations.\n\nFor more information on how to use search identifiers with this endpoint, see [DoHS API guide to search identifiers and service codes](https://digital.nhs.uk/developer/api-catalogue/directory-of-healthcare-services/guide-to-search-identifiers-and-service-codes).\n\n## Sandbox test scenarios\nYou can test the following scenarios in our sandbox environment:\n\n| Scenario | Request | Response |\n| -------------------------------------------------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---------------------------------------- |\n| All organisations | No parameters | HTTP status 200 with all organisations |\n| Single organisation | `search`=`Y02494` | HTTP status 200 with single organisation |\n| Search By ODS Code and Filter by EPS enabled | `searchFields`=`ODSCode` <br /> `$filter`=`IsEpsEnabled eq 'true'` | HTTP status 200 with filtered results |\n| Filtered by EPS enabled and organisation type | `search`=`pharmacy2u` <br /> `searchfields`=`OrganisationName` <br /> `$filter`=`IsEpsEnabled eq 'true' and OrganisationTypeId eq 'PHA' and OrganisationSubType eq 'DistanceSelling'` | HTTP status 200 with filtered results |\n| Search by location | `search`=`Bletchley` <br /> `searchfields`=`Address3,City,County` | HTTP status 200 with found organisations | \n| Filtered by EPS enabled, organisation type and ordered by geocode | `$filter`=`\"IsEpsEnabled eq 'true' and OrganisationTypeId eq 'PHA' and OrganisationSubType eq 'Community'\"` <br /> `$orderby`= `geo.distance(Geocode, geography'POINT(-0.76444095373153675 52.000820159912109)')` | HTTP status 200 with ordered results | \n| Filtered by postcode, EPS enabled and organisation type | `$filter`=`search.ismatch('B11', 'Postcode') and IsEpsEnabled eq 'true' and OrganisationTypeId eq 'PHA' and OrganisationSubType eq 'Community'` | Http status 200 with filtered results | \n| Filtered by closing time and location | `search`=`Bletchley` <br /> `searchFields`=`Address3` <br /> `$filter`=`OpeningTimes / any (x: x/ClosingTime eq '14:00')` | Http status 200 with filtered results | \n| Filtered by location, EPS enabled and wheelchair access | `search`=`Bletchley` <br /> `searchFields`=`Address3` <br /> `$filter`=`Facilities / any (x: x/Name eq 'Wheelchair access' and x/Value eq 'Yes') and IsEpsEnabled eq 'true'` | Http status 200 with filtered results | \n| No organisations found | `search`=`no-organisation` | HTTP status 200 with no organisations |\n| Invalid API version | No api-version parameter | HTTP status 404 with problem description |\n\nYou can try out the sandbox using the 'Try this API feature' on this page.\n"
parameters:
- name: api-version
description: 'The API version number can be supplied as a query parameter.
'
in: query
required: true
schema:
type: number
default: 3
- name: search
in: query
description: "The text to search for. All searchable fields are searched by default unless `searchFields` is specified. \n\nWhen searching searchable fields, the search text itself is tokenized, so multiple terms can be separated by white space, for example `search=hello world`. \n\nTo match any term, use `*` which can be useful for boolean filter queries. Omitting this parameter has the same effect as setting it to `*`.\n"
schema:
type: string
- name: searchMode
in: query
description: Defaults to any. Specifies whether any or all of the search terms must be matched in order to count the document as a match.
schema:
type: string
enum:
- any
- all
default: any
- name: searchFields
in: query
description: 'A comma-separated list of field names to search for the specified text. This field works in conjunction with the `search` field.
Example search field: `searchFields=ODSCode`
'
schema:
type: string
- name: queryType
description: "When set to simple, search text is interpreted using a simple query language that allows for symbols such as +, * and \"\".\n\nWhen the query type is set to full, search text is interpreted using the Lucene query language which allows field-specific and weighted searches.\n\nThe following example is a search over independent terms, with a requirement that all matching documents include `pool`.\n\nFor more information, see [Simple query syntax in Azure Cognitive Search](https://learn.microsoft.com/en-us/azure/search/query-simple-syntax).\n\nExample using simple query type:\n\n`queryType=simple`\n\n`search=budget hotel +pool`\n\n`searchMode=all` \n\nThis particular example shows in-field search and term boosting. It looks for hotels where the category field contains the term `budget`.\n\nAny documents containing the phrase `recently renovated` are ranked higher as a result of the term boost value.\n\nFor more information, see [Lucene query syntax in Azure Cognitive Search](https://learn.microsoft.com/en-us/azure/search/query-lucene-syntax).\n\nExample using full query type:\n\n`queryType=full`\n\n`search=category:budget AND \\'recently renovated\\'^3`\n\n`searchMode=all`\n"
in: query
schema:
type: string
enum:
- simple
- full
default: simple
- name: $skip
description: The number of search results to skip. For example, `$skip:25` returns the entries after the first 25 entries in the search results.
in: query
schema:
type: number
format: int32
- name: $top
description: The number of search results to retrieve. The default is 50.
in: query
schema:
type: number
format: int32
default: 50
- name: $count
description: "Optional, defaults to false. Specifies whether to fetch the total count of results. \n\nThis is the count of all documents that match the search and `$filter` parameters, ignoring `$top` and `$skip`. \n\nSetting this value to true may have a performance impact. The count returned is an approximation. \n\nIf you’d like to get only the count without any documents, you can use `$top=0`.\n"
in: query
schema:
type: boolean
default: false
- name: $orderBy
in: query
description: "A list of comma-separated expressions to sort the results by. Each expression can be either a field name or a call to the `geo.distance()` function. \n\nEach expression can be followed by `asc` to indicate ascending, and `desc` to indicate descending. The default is ascending order.\n\nThis `$orderBy` routine orders the results by the distance from the geography point included in the expression. \n\nThe geography point can be a position from where you are and the results are ordered by how local the results are.\n\nFor more information, see [Simple query syntax in Azure Cognitive Search](https://learn.microsoft.com/en-us/azure/search/search-query-odata-orderby).\n\nExample: \n`$orderby=geo.distance(Geocode, geography'POINT(-0.76444095373153675 52.000820159912109)')`\n"
schema:
type: string
- name: $select
in: query
description: "A list of comma-separated fields to include in the result set. \n\nIf unspecified or set to *, all fields marked as retrievable in the schema are included in the projection.\n\nExample: `$select=ODSCode,OrganisationName,Contacts,Address1,Address2,Address3,City,Postcode,OrganisationSubType`\n"
schema:
type: string
- name: $filter
in: query
description: 'A structured search expression in standard OData syntax.
The `$filter` parameter specifies inclusion or exclusion criteria for returning matches in search results.
For more information on using the `$filter`, see [OData $filter syntax in Azure Cognitive Search](https://learn.microsoft.com/en-us/azure/search/search-query-odata-filter).
Examples:
Filter results by Pharmacies that are EPS-enabled and classed as ''Community'', that is, `IsEpsEnabled` is `true`, `Organisation Type` is `PHA` and `Sub Type` is `Community`:
`$filter=IsEpsEnabled eq ''true'' and OrganisationTypeId eq ''PHA'' and OrganisationSubType eq ''Community''`
Filter results that match our postcode, that is `Postcode` field is `NG16`:
`$filter=search.ismatch(''NG16'', ''Postcode'')`
Filter results by `Postcode` is `CW9` and `OrganisationTypeId" is a dentist:
`$filter=search.ismatch(''CW9'', ''Postcode'') and OrganisationTypeId eq ''DEN''`
For details on organisation types and service codes, see [organisation and service codes](https://digital.nhs.uk/developer/api-catalogue/directory-of-healthcare-services/guide-to-search-identifiers-and-service-codes#organisation-and-service-codes).
'
schema:
type: string
responses:
'200':
$ref: '#/components/responses/SearchResponse'
4XX:
$ref: '#/components/responses/4XX-BARS'
post:
summary: Search for organisations
tags:
- Organisation
operationId: search-POST
description: '## Overview
Use this endpoint to find information about services provided by NHS organisations.
For more information on how to use search identifiers with this endpoint, see [DoHS API guide to search identifiers and service codes](https://digital.nhs.uk/developer/api-catalogue/directory-of-healthcare-services/guide-to-search-identifiers-and-service-codes).
## Sandbox test scenarios
You can test the following scenarios in our sandbox environment:
| Scenario | Request | Response |
| ---------------------- | -------------------------- | ---------------------------------------- |
| All organisations | No parameters | HTTP status 200 with all organisations |
| Single organisation | `search`=`Y02494` | HTTP status 200 with single organisation |
| No organisations found | `search`=`no-organisation` | HTTP status 200 with no organisations |
| Invalid API version | No api-version parameter | HTTP status 404 with problem description |
You can try out the sandbox using the ''Try this API feature'' on this page.
'
parameters:
- name: api-version
description: Specify the version of the API. MUST be 3.
in: query
required: true
schema:
type: number
default: 3
requestBody:
description: To generate a request body you can read Microsoft's search documentation at https://docs.microsoft.com/en-us/rest/api/searchservice/search-documents
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrganisationPostRequest'
examples:
organisationsByServiceCodeFiltered:
summary: Organisations filtering by EPS enabled
value:
search: FKH23
searchMode: all
searchFields: ODSCode
top: 10
count: true
select: ODSCode,OrganisationName,Contacts,Address1,Address2,Address3,City,Postcode,OrganisationType,OrganisationSubType
filter: IsEpsEnabled eq 'true'
organisationsByNameFilteredRequest:
summary: Organisations by name filtered by EPS enabled
value:
search: pharmacy2u
searchMode: all
searchFields: OrganisationName
top: 10
count: true
select: ODSCode,OrganisationName,Contacts,Address1,Address2,Address3,City,Postcode,OrganisationType,OrganisationSubType
filter: IsEpsEnabled eq 'true' and OrganisationTypeId eq 'PHA' and OrganisationSubType eq 'DistanceSelling'
organisationsByLocation:
summary: Organisations by location
value:
search: Bletchley
searchMode: all
searchFields: Address3,City,County
top: 10,
count: true,
select: Latitude,Longitude,Address3,City,County,Postcode
organisationsByGeocodeFiltered:
summary: Organisations filtered by EPS enabled and organisation type and ordered by geocode
value:
search: '*'
searchMode: all
searchFields: '*'
top: 10
count: true
select: ODSCode,OrganisationName,Contacts,Address1,Address2,Address3,City,Postcode,OrganisationSubType
filter: IsEpsEnabled eq 'true' and OrganisationTypeId eq 'PHA' and OrganisationSubType eq 'Community'
orderby": geo.distance(Geocode, geography'POINT(-0.76444095373153675 52.000820159912109)')
organisationsByLocationAndClosingTimeFiltered:
summary: Organisations searched by location, filtered by closing time
value:
search: Bletchley
searchFields: Address3
select: '*'
filter: 'OpeningTimes / any (x: x/ClosingTime eq ''14:00'')'
organisationsByLocationAndWheelchairAccessFiltered:
summary: Organisations search by location, filtered by available wheelchair access and EPS enabled
value:
search: Bletchley
searchFields: Address3
select: Facilities, ODSCode, IsEpsEnabled
filter: 'Facilities / any (x: x/Name eq ''Wheelchair access'' and x/Value eq ''Yes'') and IsEpsEnabled eq ''true'''
organisationsByPostcodeFiltered:
summary: Organisations by postcode, filtered by EPS enabled and organisation type
value:
search: '*'
searchMode: all
searchFields: '*'
top: 10
count: true
select: ODSCode, OrganisationType, OrganisationSubType, OrganisationName, Contacts, Address1, Address2, Address3, City, Postcode, Latitude, Longitude
filter: search.ismatch('B11', 'Postcode') and IsEpsEnabled eq 'true' and OrganisationTypeId eq 'PHA' and OrganisationSubType eq 'Community'
responses:
'200':
$ref: '#/components/responses/OrganisationSearchPostResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
SearchResults:
type: object
properties:
'@odata.context':
type: string
format: uri
'@odata.count':
type: number
format: int32
'@odata.next':
type: string
format: uri
value:
type: array
items:
$ref: '#/components/schemas/SearchResult'
OrganisationPostRequest:
description: Organisation post request
type: object
example:
$ref: examples/search-organisation-request-body_v3.json
Organisation:
description: Organisation v3
type: object
properties:
SearchKey:
type: string
description: Unique identifier for entity
ODSCode:
type: string
description: Unique code for an organisation, service or trust
OrganisationName:
type: string
description: Name for an organisation
Organisation Aliases:
type: object
description: Optional alias(es) for organisation
properties:
OrganisationAlias:
type: string
description: Legacy feature - where trading name might be different from legal registered name
OrganisationAliasId:
type: string
description: Alias ID for organisation
OrganisationTypeId:
type: string
description: identifies sector, e.g. DEN for dentist
OrganisationType:
type: string
description: Verbose representation of organisation type, identifying sector for org
OrganisationStatus:
type: string
description: ((Always should exist, should always have value of 'visible'))
Address 1:
type: string
description: Address line 1
Address 2:
type: string
description: Address line 2
Address 3:
type: string
description: Address line 3
City:
type: string
description: City or town
County:
type: string
description: County
Latitude:
type: number
description: Specific location latitude
Longitude:
type: number
description: Specific location longitude
Postcode:
type: string
description: Post code
Geocode:
type: number
description: Nested data - { type, coordinates, crs { type, properties { name } } }
ParentOrganisation:
type: object
description: Parent for NHS organisations. Potentially nullable based on sector. Generally parent trust for primary care organisations.
properties:
ODSCode:
type: string
description: Unique code for an organisation, service or trust
OrganisationName:
type: string
description: Name for an organisation
Services:
type: object
description: Medical services offered
properties:
ServiceName:
type: string
description: Name for a service, e.g. Urgent dental appointments
ServiceCode:
type: string
description: Code for a service, e.g. SRV0165
Contacts:
type: object
description: Contact service
properties:
ContactMethodType:
type: string
description: Medium for contact - telephone, email, web, fax
ContactValue:
type: string
description: Contact number, email, et c.
ServiceProvider:
type: object
description: Trust that provides service
properties:
ODSCode:
type: string
description: Unique code for an organisation, service or trust
OrganisationName:
type: string
description: Name for an organisation
Treatments:
type: object
description: bullet list of treatments provided
properties:
Name:
type: string
description: Name of treatment
OpeningTimes:
type: object
description: Contains subfields for service opening times
properties:
Weekday:
type: string
description: Day of the week
OpeningTime:
type: string
description: Opening time for service in 24hr clock
ClosingTime:
type: string
description: Closing time for service in 24hr clock
OffsetOpeningTime:
type: number
description: Opening time offset in minutes from midnight
OffsetClosingTime:
type: number
description: Closing time offset in minutes from midnight
OpeningTimeType:
type: string
description: General, Additional, Reception, Surgery - opening times for each
AdditionOpeningDate:
type: string
description: Temporary changes and bank holidays - bank holidays must be validated
IsOpen:
type: boolean
description: If set to true there should be opening times, if set to false there should be none.
FromAgeDays:
type: number
description: Age range based opening times - e.g. under 16s or over 60s
ToAgeDays:
type: number
description: Age range based opening times - e.g. under 16s or over 60s
AgeRange:
type: object
description: List of age ranges for service
properties:
FromAgeDays:
type: number
description: Age range based opening times - e.g. under 16s or over 60s
ToAgeDays:
type: number
description: Age range based opening times - e.g. under 16s or over 60s
Metrics:
type: object
description: Indicators of service health -
properties:
MetricID:
type: number
description: Id for Metric
MetricName:
type: string
description: Name for metric
Description:
type: string
description: Description of metric
Text:
type: string
description: Verbose description
BandingClassification:
type: string
description: representation of grading for metric in words - e.g. "good," "adequate," "yes," "no,"
KeyValueData:
type: object
description: Meta data about service
properties:
Key:
type: string
description: Key for meta data - e.g. "flu booking link"
Value:
type: string
description: Value for meta data - e.g. flu booking link url
OpeningTimes:
type: object
descr
# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nhs-england/refs/heads/main/openapi/nhs-england-organisation-api-openapi.yml