Use case for reading an organisation resource

Prerequisites

Consumer

The consumer system:

• SHALL have previously resolved the organisation’s FHIR endpoint Base URL through the Spine Directory Service
• MAY have previously resolved the logical ID of the organisation from the ODS Organisation Code.

API use case

This specification describes a single use cases. For complete details and background please see the Foundations Capability Bundle.

Security

• GP Connect utilises TLS Mutual Authentication for system level authorization.
• GP Connect utilises a JSON Web Tokens (JWT) to transmit clinical audit & provenance details.

API usage

Request operation

FHIR relative request

GET /Organization/[id]

FHIR absolute request

GET https://[proxy_server]/https://[provider_server]/[fhir_base]/Organization/[id]

Request headers

Consumers SHALL include the following additional HTTP request headers:

Header	Value
Ssp-TraceID	Consumer’s TraceID (i.e. GUID/UUID)
Ssp-From	Consumer’s ASID
Ssp-To	Provider’s ASID
Ssp-InteractionID	urn:nhs:names:services:gpconnect:fhir:rest:read:organization-1

Payload request body

N/A

Error handling

Provider systems SHALL return a GPConnect-OperationOutcome-1 resource that provides additional detail when one or more data fields are corrupt or a specific business rule/constraint is breached.

For example, the:

• Logical identifier of the resource is not valid/can’t be found on the server.

Refer to Development - FHIR API Guidance - Error Handling for details of error codes.

Request response

Response headers

Provider systems are not expected to add any specific headers beyond that described in the HTTP and FHIR® standards.

Payload response body

Provider systems:

• SHALL return a 200 OK HTTP status code on successful execution of the operation.

• SHALL return Organization resources that conform to the CareConnect-GPC-Organization-1 profile.

• SHALL populate the following Organization fields:
  • meta.profile with the profile URI
  • versionId with the current version of the Organization resource.
  • identifier with relevant business identifiers (for example, ODS code) for each Organization resource.
  • name
  • address where available
  • telecom where available

• SHALL meet General FHIR resource population requirements populating all fields where data is available, excluding those listed below

• SHALL NOT populate the following fields:
  • contact
  • endpoint

{
  "resourceType": "Organization",
  "id": "23",
  "meta": {
    "versionId": "636064088098730113",
    "profile": [
      "https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Organization-1"
    ]
  },
  "identifier": [
    {
      "system": "https://fhir.nhs.uk/Id/ods-organization-code",
      "value": "A00001"
    }
  ],
  "name": "The Trevelyan Practice",
  "address": [
    {
      "line": [
        "Trevelyan Square",
        "Boar Ln"
      ],
      "city": "Leeds",
      "district": "West Yorkshire",
      "postalCode": "LS1 6AE"
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "03003035678",
      "use": "work"
    }
  ]
}