Sign in

v1

latestOpenAPI 3.0.02026-07-1480105.3 KB

Search for an organisation

Overview

Use this endpoint to search for organisations or sites. Site codes which are supported for certain organisations can also be accessed here, there is no separate endpoint for sites.

A FHIR Organization resource will be provided for each search result. Refer to our Implementation Guidance pages for profiles and other FHIR assets.

You can search for information about an organisation using one or more of their:

  • ODS code
  • last change date
  • name
  • active or inactive status
  • address, city or postcode
  • organisation's primary role using RoleID, such as RO197 (NHS Trust) or RO167 (Optical Site)
  • organisation's non-primary role using RoleID, such as RO7 (Hospice) or RO318 (Integrated Care Board)

This API returns the following details for an organisation:

  • organisation - ODS code, name, last change date, status if active or inactive, record class (organisation or site), record use type; A complete record or a reduced record included solely for referential integrity
  • address - house or flat number, line 1, line 2, line 3, town, postcode, Unique Property Reference Number (UPRN) and country
  • contacts - website and telephone (where available)
  • roles - primary and non-primary roles including legal and operational start and end dates

You can also request any related relations resources using the _revinclude parameter to return an OrganizationAffiliation Resource.

You can try out the sandbox using the 'Try this API' feature on this page.

Alternatively, you can try out the sandbox using our Postman collection:

Run in Postman

get/Organization

Query parameters

_idstring
Example:RR8

The organisation's ODS code.

If you already know the ODS code, use the Get organisation details endpoint instead.

identifierstring

The organisation's ODS code.

This parameter is similar to _id but can also explicitly include the CodeSystem for the ID - which must be ods-organization-code.

It's included for FHIR compatibility.

lastChangeDatestring

The date that the organisation record was last modified by ODS. Supports greater than, less and equal to. Can be compounded. For further information about the application of lastChangeDate and how it should be queried, please refer to the ODS Reference Data Catalogue page for LastChangeDate.

namestring
Example:Leeds

The start of the organisation's name. For example, Leeds would match Leeds Chest Clinic but not South Leeds Clinical Assessment Service.

To search anywhere in the organisation's name, use name:contains. To search for an exact match, use name:exact.

Not case sensitive.

Search expressions must:

  • contain a minimum of 3 characters and a maximum of 100 characters
  • only include the following characters: A-Z a-z 0-9 &()’+-_./:@ 'Space'
name:containsstring
Example:Leeds

Any part of the organisation's name. For example, Leeds would match Leeds Chest Clinic and South Leeds Clinical Assessment Service.

Not case sensitive.

Search expressions must:

  • contain a minimum of 3 characters and a maximum of 100 characters
  • only include the following characters: A-Z a-z 0-9 &()’+-_./:@ 'Space'
name:exactstring
Example:LEEDS TEACHING HOSPITALS NHS TRUST

The exact organisation name.

Case sensitive.

Search expressions must:

  • contain a minimum of 3 characters and a maximum of 100 characters
  • only include the following characters: A-Z a-z 0-9 &()’+-_./:@ 'Space'
activeboolean

Whether the organisation's record is still in active use.

address-postalcodestring
Example:LS1

The start of the organisation's postcode.

To search anywhere in the postcode, use address-postalcode:contains. To search for an exact match, use address-postalcode:exact.

Not case sensitive.

Search expressions must:

  • contain a minimum of 2 characters
  • only include alphanumeric characters and spaces
address-postalcode:containsstring
Example:4DZ

Any part of the organisation's postcode.

Not case sensitive.

Search expressions must:

  • contain a minimum of 2 characters
  • only include alphanumeric characters and spaces
address-postalcode:exactstring
Example:LS1 4DZ

The exact organisation postcode.

Case sensitive.

Search expressions must:

  • contain a minimum of 2 characters
  • only include alphanumeric characters and spaces
address-citystring
Example:Derby

The start of the organisation's city address.

To search anywhere in the city address, use address-city:contains. To search for an exact match, use address-city:exact.

Not case sensitive.

Search expressions must:

  • contain a minimum of 2 characters
  • only include alphanumeric characters and spaces
address-city:containsstring
Example:Derby

Any part of the organisation's city address.

Not case sensitive.

Search expressions must:

  • contain a minimum of 2 characters
  • only include alphanumeric characters and spaces
address-city:exactstring
Example:DERBY

The exact organisation city address.

Case sensitive.

Search expressions must:

  • contain a minimum of 2 characters
  • only include alphanumeric characters and spaces
address-countrystring
Example:ENGLAND

The start of the organisation's country.

Not case sensitive.

To search anywhere in the country address, use address-country:contains. To search for an exact match, use address-country:exact.

Search expressions must:

  • contain a minimum of 2 characters
  • only include alphanumeric characters and spaces
roleCodestring

The organisation's role, based on the ODSOrganisationRole CodeSystem.

An organisation in ODS can have one or many roles.

To exclude organisations with a specific role use roleCode:not

To search for organisations that have multiple roles (like an 'AND' operator), include the roleCode query parameter multiple times.

To search for organisations that have one of several roles (like an 'OR' operator), use a comma separator.

You may combine 'AND' and 'OR' searches.

To discover whether a role is primary or non-primary, refer to the ODSOrganisationRole CodeSystem

roleCode:notstring

Exclude organisations from the search results based on their role

activeRoleCodestring

Searches only active roles within the ODSOrganisationRole CodeSystem

To exclude organisations with a specific role use activeRoleCode:not To search for organisations that have multiple roles (like an 'AND' operator), include the activeRoleCode query parameter multiple times.

To search for organisations that have one of several roles (like an 'OR' operator), use a comma separator.

You may combine 'AND' and 'OR' searches.

To discover whether a role is primary or non-primary, refer to the ODSOrganisationRole CodeSystem

_countstring
Example:1000

Number of results to return. any search which generates a response larger than 5mb will generate an error. We recommend you use a an appropriate limit and use _offset to page through the data, until you have collected all results

By default the first 20 records will be returned

_summary'count'

Return a count of the matching resources, without returning the actual matches.

_offsetstring

When used with _count, enables paging through large result sets

Response

Valid request that returns a FHIR Organization resource(s) that match the search criteria (which may be 0).

All 8 operations