NHS API

NHS API ValueSet API

The ValueSet API from NHS API — 2 operation(s) for valueset.

Documentation GitHub OpenAPI

Operations 2

POST /ValueSet/ Perform a ValueSet expansion #

GET /ValueSet/{id} Get value set #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/nhs-api-valueset-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Nhs Value Set API
  contact:
    name: ODS FHIR API Support
    url: https://digital.nhs.uk/developer/help-and-support
    email: api.management@nhs.net
  version: '1.0'
  description: 'Operations tagged ValueSet across 2 of this provider''s published API definitions: organisation-data-service-fhir-r4-api.yaml, organisation-data-service-fhir-stu3-api.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://beta.ods.dc4h.link/fhir/
  description: User acceptance test (UAT) environment.
- url: https://jenkins.ods.dc4h.link/fhir/
  description: Production environment.
- url: https://uat.directory.spineservices.nhs.uk/STU3/
  description: User acceptance test (UAT) environment.
- url: https://directory.spineservices.nhs.uk/STU3/
  description: Production environment.
tags:
- name: ValueSet
paths:
  /ValueSet/:
    post:
      summary: Perform a ValueSet expansion
      operationId: search-ods-organization-code
      description: '## Overview

        To retrieve a subset of records from an individual CodeSystem, you will need to perform a ''POST'' operation, in which you will provide the details of the CodeSystem you are searching, along with any filters to be applied and properties you wish to include in the results.


        When you make a ''POST'' operation, you perform an expansion on a ValueSet and provide a requestBody. The endpoint will return a successful (200) response code along with the search results, which may be an empty array if no records match your criteria. or an unsuccesful (4xx/5xx) response.'
      requestBody:
        content:
          application/fhir+json:
            example:
              resourceType: Parameters
              parameter:
              - name: valueSet
                resource:
                  resourceType: ValueSet
                  compose:
                    inactive: true
                    include:
                    - system: https://fhir.nhs.uk/Id/ods-organization-code
                      filter:
                      - property: lastChangeDate
                        op: '='
                        value: gt2024-02-01
              - name: activeOnly
                valueBoolean: false
              - name: property
                valueString: primaryRole
              - name: property
                valueString: country
              - name: count
                valueInteger: '2'
      responses:
        '200':
          description: a valid
          content:
            application/fhir+json:
              example:
                resourceType: ValueSet
                expansion:
                  identifier: urn:uuid:7799a8c4-2d2a-4d74-b647-2d50aad98904
                  timestamp: '2024-03-25T14:42:24+00:00'
                  total: 4725
                  offset: 0
                  parameter:
                  - name: version
                    valueUri: https://fhir.nhs.uk/Id/ods-organization-code|2024-03-07
                  - name: used-codesystem
                    valueUri: https://fhir.nhs.uk/Id/ods-organization-code|2024-03-07
                  - name: activeOnly
                    valueBoolean: false
                  - name: count
                    valueInteger: 2
                  contains:
                  - extension:
                    - url: http://hl7.org/fhir/5.0/StructureDefinition/extension-ValueSet.expansion.contains.property
                      extension:
                      - url: code
                        valueCode: primaryRole
                      - url: value
                        valueCoding:
                          system: https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole
                          code: RO104
                    - url: http://hl7.org/fhir/5.0/StructureDefinition/extension-ValueSet.expansion.contains.property
                      extension:
                      - url: code
                        valueCode: country
                      - url: value
                        valueString: ENGLAND
                    system: https://fhir.nhs.uk/Id/ods-organization-code
                    code: AT32
                    display: FORGET ME NOT CARING LTD
                  - extension:
                    - url: http://ontoserver.csiro.au/profiles/expansion
                      extension:
                      - url: inactive
                        valueBoolean: true
                    - url: http://hl7.org/fhir/5.0/StructureDefinition/extension-ValueSet.expansion.contains.property
                      extension:
                      - url: code
                        valueCode: primaryRole
                      - url: value
                        valueCoding:
                          system: https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole
                          code: RO172
                    - url: http://hl7.org/fhir/5.0/StructureDefinition/extension-ValueSet.expansion.contains.property
                      extension:
                      - url: code
                        valueCode: country
                      - url: value
                        valueString: ENGLAND
                    system: https://fhir.nhs.uk/Id/ods-organization-code
                    inactive: true
                    code: AT9
                    display: SOUTH EAST LAMBETH HEALTH PARTNERSHIP
        4XX:
          description: "An error occurred as follows:\n\n    | HTTP Code   | issue.severity | issue.code    | issue.details.code  | issue.details.display |\n    |------------ |----------------|---------------|---------------------|---------------------  |\n    |400          |error           |invalid        |HAPI-1940            |Invalid Date/Time/Quantity format |\n    |400          |error           |invalid        |HAPI-0524            |Unknown Search Parameter|\n    |404          |error           |invalid        |HAPI-2001             |Organization not found  |\n    |405          |error           |method not allowed|HAPI-0427         |Method Not Allowed      |\n    |422          |unprocessable   |too-costly     |Too many records requested (Use _count and _offset)|Invalid parameter  |\n    |422          |unprocessable   |processing |No declared filter on Codesystem |An input field has an invalid value for its type  |\n  \n"
      tags:
      - ValueSet
    servers:
    - url: https://beta.ods.dc4h.link/fhir/
      description: User acceptance test (UAT) environment.
    - url: https://jenkins.ods.dc4h.link/fhir/
      description: Production environment.
  /ValueSet/{id}:
    get:
      summary: Get value set
      operationId: get-valueset-specified-id
      description: '## Overview

        Use this endpoint to get a single ValueSet for the specified ID.'
      parameters:
      - in: path
        name: id
        description: 'The id for the ValueSet.

          '
        required: true
        schema:
          type: string
          example: ODSAPI-OrganizationRecordClass-1
      responses:
        '200':
          description: Valid request that returns a single ValueSet for the specied ID.
          content:
            application/json:
              example:
                resourceType: ValueSet
                id: ODSAPI-OrganizationRecordClass-1
                text:
                  status: generated
                url: https://fhir.nhs.uk/STU3/ValueSet/ODSAPI-OrganizationRecordClass-1
                version: 1.0.0
                name: ODS API Organization Record Class
                status: active
                date: '2018-04-03'
                publisher: NHS Digital
                contact:
                - name: Interoperability Team
                  telecom:
                  - value: interoperabilityteam@nhs.net
                    use: work
                description: A ValueSet that identifies the record class of the organization.
                copyright: Copyright © 2018 Health and Social Care Information Centre. NHS Digital is the trading name of the Health and Social Care Information Centre.
                compose:
                  include:
                  - system: https://fhir.nhs.uk/STU3/CodeSystem/ODSAPI-OrganizationRecordClass-1
            application/fhir+xml:
              example: <ValueSet xmlns='http://hl7.org/fhir'> <id value='ODSAPI-OrganizationRecordClass-1'></id> <text> <status value='generated'></status> </text> <url value='https://fhir.nhs.uk/STU3/ValueSet/ODSAPI-OrganizationRecordClass-1'></url> <version value='1.0.0'></version> <name value='ODS API Organization Record Class'></name> <status value='active'></status> <date value='2018-04-03'></date> <publisher value='NHS Digital'></publisher> <contact> <name value='Interoperability Team'></name> <telecom> <value value='interoperabilityteam@nhs.net'></value> <use value='work'></use> </telecom> </contact> <description value='A ValueSet that identifies the record class of the organization.'></description> <copyright value='Copyright © 2018 Health and Social Care Information Centre. NHS Digital is the trading name of the Health and Social Care Information Centre.'></copyright> <compose> <include> <system value='https://fhir.nhs.uk/STU3/CodeSystem/ODSAPI-OrganizationRecordClass-1'></system> </include> </compose> </ValueSet>
        4XX:
          description: "An error occurred as follows:\n\n| HTTP Code   | issue.severity  | issue.code    | issue.details.code        | issue.details.display |\n|------------ |---------------- |-----------    |-------------------------- |---------------------- |\n| 404         | error           | not-found     | NO_RECORD_FOUND           | No record found |\n       \n"
      tags:
      - ValueSet
    servers:
    - url: https://uat.directory.spineservices.nhs.uk/STU3/
      description: User acceptance test (UAT) environment.
    - url: https://directory.spineservices.nhs.uk/STU3/
      description: Production environment.
x-refined-from:
- organisation-data-service-fhir-r4-api.yaml
- organisation-data-service-fhir-stu3-api.yaml
x-nhsd-api-platform:
  meta:
    service_name: e-referrals-service-api
    short_service_name: ers
    service_base_path: referrals
    product_display_name: e-Referrals-Service
    product_description: The NHS e-RS vision is to enable local innovation and adoption of paperless referrals. To support this vision NHS Digital have created a set of APIs which provide a well-defined, simple to use data interface to the NHS e-Referral Service (e-RS). See https://digital.nhs.uk/developer/api-catalogue/e-referral-service-fhir
    pipeline_name_prefix: E-Referrals-Service