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\nTo 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.\n\nWhen 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.\n\n    \n \n"
      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