NHS England

NHS England Organization Affiliation API

The OrganizationAffiliation API from NHS England — 2 operation(s) for organizationaffiliation.

Documentation GitHub OpenAPI

Operations 2

GET /OrganizationAffiliation/{id} Get relationship details #

GET /Organizationaffiliation Search for a relationship #

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-england-organizationaffiliation-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: organisation-data-terminology-api Organization Affiliation…
  version: 1.0.1-alpha
  contact:
    name: ODS FHIR API Support
    url: https://digital.nhs.uk/developer/help-and-support
    email: api.management@nhs.net
  description: '## Overview

    Use this API to access a dataset of health and social care organisations, such as trusts or GP practices, using the Organisation Data Service (ODS).'
servers:
- url: https://beta.ods.dc4h.link/fhir/
  description: User acceptance test (UAT) environment.
- url: https://jenkins.ods.dc4h.link/fhir/
  description: Production environment.
tags:
- name: OrganizationAffiliation
paths:
  /OrganizationAffiliation/{id}:
    get:
      summary: Get relationship details
      operationId: get-single-organizationaffiliation
      description: '## Overview

        Use this endpoint to a retrieve a single relationship record based on its unique identifier. This record describes a relationship between a pair of organisations. The types of relationships which an organisation may have will vary depending on the primary role of the organisation. In some case there may be multiple relationships between the same two organisations, each having a different relationship type.


        A FHIR OrganizationAffiliation Resource will be returned when a valid id is provided.'
      parameters:
      - in: path
        name: id
        description: 'The relationship ID.

          '
        required: true
        schema:
          type: string
          example: '617400'
      responses:
        '200':
          description: Valid request that returns a FHIR OrganizationAffiliation resource
          content:
            application/fhir+json:
              example:
                resourceType: OrganizationAffiliation
                id: '617400'
                meta:
                  versionId: '3'
                  lastUpdated: '2024-01-23T16:51:55.472+00:00'
                  source: '#25caee48b2ce3432'
                  profile:
                  - https://fhir.hl7.org.uk/StructureDefinition/UKCore-OrganizationAffiliation
                  - https://fhir.nhs.uk/England/StructureDefinition/England-OrganizationAffiliation-ODS
                extension:
                - url: https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod
                  extension:
                  - url: dateType
                    valueCoding:
                      system: https://fhir.nhs.uk/England/CodeSystem/England-PeriodType
                      code: Legal
                      display: Legal
                  - url: period
                    valuePeriod:
                      start: '2019-10-01'
                - url: https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod
                  extension:
                  - url: dateType
                    valueCoding:
                      system: https://fhir.nhs.uk/England/CodeSystem/England-PeriodType
                      code: Operational
                      display: Operational
                  - url: period
                    valuePeriod:
                      start: '2019-10-01'
                identifier:
                - system: https://digital.nhs.uk/services/organisation-data-service/CodeSystem/organization-relationship-instance
                  value: '617400'
                active: true
                period:
                  start: '2019-10-01'
                organization:
                  reference: Organization/G81086
                  identifier:
                    system: https://fhir.nhs.uk/Id/ods-organization-code
                    value: G81086
                participatingOrganization:
                  reference: Organization/U36842
                  identifier:
                    system: https://fhir.nhs.uk/Id/ods-organization-code
                    value: U36842
                code:
                - coding:
                  - system: https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSRelationship
                    code: RE8
                    display: IS PARTNER TO
            application/xml:
              example: "<OrganizationAffiliation xmlns=\"http://hl7.org/fhir\">\n  <id value=\"617400\"/>\n  <meta>\n      <versionId value=\"3\"/>\n      <lastUpdated value=\"2024-01-23T16:51:55.472+00:00\"/>\n      <source value=\"#25caee48b2ce3432\"/>\n      <profile value=\"https://fhir.hl7.org.uk/StructureDefinition/UKCore-OrganizationAffiliation\"/>\n      <profile value=\"https://fhir.nhs.uk/England/StructureDefinition/England-OrganizationAffiliation-ODS\"/>\n  </meta>\n  <extension url=\"https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod\">\n      <extension url=\"dateType\">\n          <valueCoding>\n              <system value=\"https://fhir.nhs.uk/England/CodeSystem/England-PeriodType\"/>\n              <code value=\"Legal\"/>\n              <display value=\"Legal\"/>\n          </valueCoding>\n      </extension>\n      <extension url=\"period\">\n          <valuePeriod>\n              <start value=\"2019-10-01\"/>\n          </valuePeriod>\n      </extension>\n  </extension>\n  <extension url=\"https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod\">\n      <extension url=\"dateType\">\n          <valueCoding>\n              <system value=\"https://fhir.nhs.uk/England/CodeSystem/England-PeriodType\"/>\n              <code value=\"Operational\"/>\n              <display value=\"Operational\"/>\n          </valueCoding>\n      </extension>\n      <extension url=\"period\">\n          <valuePeriod>\n              <start value=\"2019-10-01\"/>\n          </valuePeriod>\n      </extension>\n  </extension>\n  <identifier>\n      <system value=\"https://digital.nhs.uk/services/organisation-data-service/CodeSystem/organization-relationship-instance\"/>\n      <value value=\"617400\"/>\n  </identifier>\n  <active value=\"true\"/>\n  <period>\n      <start value=\"2019-10-01\"/>\n  </period>\n  <organization>\n      <reference value=\"Organization/G81086\"/>\n      <identifier>\n          <system value=\"https://fhir.nhs.uk/Id/ods-organization-code\"/>\n          <value value=\"G81086\"/>\n      </identifier>\n  </organization>\n  <participatingOrganization>\n      <reference value=\"Organization/U36842\"/>\n      <identifier>\n          <system value=\"https://fhir.nhs.uk/Id/ods-organization-code\"/>\n          <value value=\"U36842\"/>\n      </identifier>\n  </participatingOrganization>\n  <code>\n      <coding>\n          <system value=\"https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSRelationship\"/>\n          <code value=\"RE8\"/>\n          <display value=\"IS PARTNER TO\"/>\n      </coding>\n  </code>\n</OrganizationAffiliation>              \n"
        '404':
          description: 'Invalid ODS Code provided, will return a 404 Not Found error

            '
          content:
            application/fhir+json:
              example:
                resourceType: OperationOutcome
                text:
                  status: generated
                  div: '<div xmlns="http://www.w3.org/1999/xhtml"><h1>Operation Outcome</h1><table border="0"><tr><td style="font-weight: bold;">ERROR</td><td>[]</td><td>HAPI-2001: Resource Organization/8J632648493 is not known</td></tr></table></div>'
                issue:
                - severity: error
                  code: processing
                  diagnostics: 'HAPI-2001: Resource Organization/8J632648493 is not known'
      tags:
      - OrganizationAffiliation
  /Organizationaffiliation:
    get:
      summary: Search for a relationship
      operationId: get-organizationaffiliation-resources
      description: '## Overview

        Use this endpoint to search for relationship records. Most commonly you would use this endpoint to get all the relationships for a given organisation, based on its ODS code.


        For relationships, this API returns the following details:


        * related organisation ODS code

        * relationship type and relationship name

        * relationship legal start and end dates

        * relationship operational start and end dates


        you can search using various combinations of:


        * Primary-Organisation - known within the ORD products as the Source Organisation

        * Participating-Organisation - known within the ORD products as the Target Organisation

        * relationship status


        It is also possible to return the relevant Organization Resources in these searches using the `_include` parameter'
      parameters:
      - in: query
        name: _id
        description: 'The organisation''s ID - also known as its ODS code. If you already know the ODS code, consider using the ''Get organsiation details'' endpoint instead.

          '
        required: false
        schema:
          type: string
          example: RTG
      - in: query
        name: primary-organisation
        description: "The ‘source’ organisation which has a relationship. \n\nreferred to as the SourceOrganisation in the ORD schema \n\nMust be a valid Organisation code with relationships to return results\n"
        required: false
        schema:
          type: string
          example: G81086
      - in: query
        name: participating-organization
        description: "The ‘Target’ or related organisation.  \n\nReferred to as the Target Organisation in the ORD schema \nMust be a valid Organisation code with relationships to return results \n"
        required: false
        schema:
          type: string
          example: 97R
      - in: query
        name: active
        description: Whether the organisation's relationship record is still in active use.
        required: false
        schema:
          type: boolean
          example: 'true'
      - in: query
        name: _count
        description: Number of results to return.
        required: false
        schema:
          type: string
          example: '1000'
      - in: query
        name: _include
        description: "Enables you return related resources.  \n\nOrganizationAffiliation:primary-organization will include Organization resource records for the ‘Source’ Organisations in the search results \n\nOrganizationAffiliation:participating-organization will include Organization resource records for all the ‘Target’ Organisations in the search results \n\nyou can include both primary and participating organization resources by including multiple `_include` parameters\n"
        required: false
        schema:
          type: string
        examples:
          primary-organization:
            summary: Include primary-organization
            value: OrganizationAffiliation:primary-organization
          participating-Organization:
            summary: Include participating-organization
            value: OrganizationAffiliation:participating-organization
      - in: query
        name: _summary
        description: Return a count of the matching resources, without returning the actual matches.
        required: false
        schema:
          type: string
          enum:
          - count
      responses:
        '200':
          description: Valid request that returns any FHIR OrganizationAffiliation resources that match the search criteria (which may be 0).
          content:
            application/fhir+json:
              example:
                resourceType: Bundle
                id: 3a286c55-83c9-4869-aaf1-c69186656ade
                meta:
                  lastUpdated: '2024-03-15T10:47:18.746+00:00'
                type: searchset
                total: 3
                link:
                - relation: self
                  url: https://jenkins.ods.dc4h.link/fhir/OrganizationAffiliation?primary-organization=FDC49
                entry:
                - fullUrl: https://jenkins.ods.dc4h.link/fhir/OrganizationAffiliation/383689
                  resource:
                    resourceType: OrganizationAffiliation
                    id: '383689'
                    meta:
                      versionId: '3'
                      lastUpdated: '2024-01-23T15:40:47.090+00:00'
                      source: '#72eb666ff3d30383'
                      profile:
                      - https://fhir.hl7.org.uk/StructureDefinition/UKCore-OrganizationAffiliation
                      - https://fhir.nhs.uk/England/StructureDefinition/England-OrganizationAffiliation-ODS
                    extension:
                    - url: https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod
                      extension:
                      - url: dateType
                        valueCoding:
                          system: https://fhir.nhs.uk/England/CodeSystem/England-PeriodType
                          code: Legal
                          display: Legal
                      - url: period
                        valuePeriod:
                          start: '2015-05-11'
                          end: '2020-03-31'
                    - url: https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod
                      extension:
                      - url: dateType
                        valueCoding:
                          system: https://fhir.nhs.uk/England/CodeSystem/England-PeriodType
                          code: Operational
                          display: Operational
                      - url: period
                        valuePeriod:
                          start: '2015-05-11'
                          end: '2020-03-31'
                    identifier:
                    - system: https://digital.nhs.uk/services/organisation-data-service/CodeSystem/organization-relationship-instance
                      value: '383689'
                    active: false
                    period:
                      start: '2015-05-11'
                      end: '2020-03-31'
                    organization:
                      reference: Organization/FDC49
                      identifier:
                        system: https://fhir.nhs.uk/Id/ods-organization-code
                        value: FDC49
                    participatingOrganization:
                      reference: Organization/Q72
                      identifier:
                        system: https://fhir.nhs.uk/Id/ods-organization-code
                        value: Q72
                    code:
                    - coding:
                      - system: https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSRelationship
                        code: RE5
                        display: IS LOCATED IN THE GEOGRAPHY OF
                  search:
                    mode: match
                - fullUrl: https://jenkins.ods.dc4h.link/fhir/OrganizationAffiliation/648449
                  resource:
                    resourceType: OrganizationAffiliation
                    id: '648449'
                    meta:
                      versionId: '3'
                      lastUpdated: '2024-01-23T17:00:12.326+00:00'
                      source: '#033821a3d00d51fe'
                      profile:
                      - https://fhir.hl7.org.uk/StructureDefinition/UKCore-OrganizationAffiliation
                      - https://fhir.nhs.uk/England/StructureDefinition/England-OrganizationAffiliation-ODS
                    extension:
                    - url: https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod
                      extension:
                      - url: dateType
                        valueCoding:
                          system: https://fhir.nhs.uk/England/CodeSystem/England-PeriodType
                          code: Legal
                          display: Legal
                      - url: period
                        valuePeriod:
                          start: '2020-04-01'
                          end: '2020-09-22'
                    - url: https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod
                      extension:
                      - url: dateType
                        valueCoding:
                          system: https://fhir.nhs.uk/England/CodeSystem/England-PeriodType
                          code: Operational
                          display: Operational
                      - url: period
                        valuePeriod:
                          start: '2020-04-01'
                          end: '2020-09-22'
                    identifier:
                    - system: https://digital.nhs.uk/services/organisation-data-service/CodeSystem/organization-relationship-instance
                      value: '648449'
                    active: false
                    period:
                      start: '2020-04-01'
                      end: '2020-09-22'
                    organization:
                      reference: Organization/FDC49
                      identifier:
                        system: https://fhir.nhs.uk/Id/ods-organization-code
                        value: FDC49
                    participatingOrganization:
                      reference: Organization/QWO
                      identifier:
                        system: https://fhir.nhs.uk/Id/ods-organization-code
                        value: QWO
                    code:
                    - coding:
                      - system: https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSRelationship
                        code: RE5
                        display: IS LOCATED IN THE GEOGRAPHY OF
                  search:
                    mode: match
                - fullUrl: https://jenkins.ods.dc4h.link/fhir/OrganizationAffiliation/716945
                  resource:
                    resourceType: OrganizationAffiliation
                    id: '716945'
                    meta:
                      versionId: '3'
                      lastUpdated: '2024-01-23T17:23:48.733+00:00'
                      source: '#8e8ca746678177d7'
                      profile:
                      - https://fhir.hl7.org.uk/StructureDefinition/UKCore-OrganizationAffiliation
                      - https://fhir.nhs.uk/England/StructureDefinition/England-OrganizationAffiliation-ODS
                    extension:
                    - url: https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod
                      extension:
                      - url: dateType
                        valueCoding:
                          system: https://fhir.nhs.uk/England/CodeSystem/England-PeriodType
                          code: Legal
                          display: Legal
                      - url: period
                        valuePeriod:
                          start: '2020-09-23'
                    - url: https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod
                      extension:
                      - url: dateType
                        valueCoding:
                          system: https://fhir.nhs.uk/England/CodeSystem/England-PeriodType
                          code: Operational
                          display: Operational
                      - url: period
                        valuePeriod:
                          start: '2020-09-23'
                    identifier:
                    - system: https://digital.nhs.uk/services/organisation-data-service/CodeSystem/organization-relationship-instance
                      value: '716945'
                    active: true
                    period:
                      start: '2020-09-23'
                    organization:
                      reference: Organization/FDC49
                      identifier:
                        system: https://fhir.nhs.uk/Id/ods-organization-code
                        value: FDC49
                    participatingOrganization:
                      reference: Organization/QF7
                      identifier:
                        system: https://fhir.nhs.uk/Id/ods-organization-code
                        value: QF7
                    code:
                    - coding:
                      - system: https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSRelationship
                        code: RE5
                        display: IS LOCATED IN THE GEOGRAPHY OF
                  search:
                    mode: match
        4XX:
          description: 'An error occurred as follows:


            | HTTP Code   | issue.severity | issue.code    | issue.details.code  | issue.details.display |

            |------------ |----------------|---------------|---------------------|---------------------  |

            |400          |error           |invalid        |HAPI-1940            |Invalid Date/Time/Quantity format |

            |400          |error           |invalid        |HAPI-0524            |Unknown Search Parameter|

            |404          |error           |invalid        |HAPI-2001             |Organization not found  |

            |405          |error           |method not allowed|HAPI-0427         |Method Not Allowed      |

            '
          content:
            application/fhir+json:
              example:
                resourceType: OperationOutcome
                id: 82c75580-1702-469e-aec1-43034b48f060
                meta:
                  profile: https://fhir.nhs.uk/STU3/StructureDefinition/Spine-OperationOutcome-1
                issue:
                - severity: error
                  code: invalid
                  details:
                    coding:
                      system: https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1
                      code: INVALID_PARAMETER
                      display: Invalid parameter
                  diagnostics: Unknown argument found - nam
      tags:
      - OrganizationAffiliation