DTR $expand FHIR API Specification

Service Overview

InterSystems DTR (Documentation Template and Rules) FHIR APIs are designed in compliance with the CMS-0057-F regulationsOpens in a new tab.

Refer to the Getting Started section for information on connectivity, authentication and how to get help. To use the FHIR APIs, you will need to know the base URL of the FHIR server you will be connecting to. You can also retrieve the capability statement for the service.

As part of the DTR APIs, a client application can use the $expand API to run an expansion to create a collection of codes in a value set returned in a questionnaire package. Note that when using the DTR $questionnaire-package API, value sets will be expanded automatically.

Workflow

A typical workflow involving the $expand operation might be:

A provider’s electronic health record (EHR) system is configured for DTR application connectivity.
The EHR and DTR app are configured for payer connectivity.
The EHR, via the DTR app, uses pre-defined payer information to send a documentation request to the payer.
The payer organization returns a bundle of one or more questionnaires.
The DTR app sends a request to run an expansion on one value set. The value set may consist of additional filters that include or exclude codes.
The payer organization returns the expanded value set.
The DTR app may repeat expansion requests for additional value sets
The DTR app continues using the questionnaire with expanded code(s).

Prerequisites

None.

Available endpoints

The expansion functionality available with this service can be called in one of two ways:

<BaseURL>/ValueSet/$expand
<BaseURL>/ValueSet/<id>/$expand

Endpoint: $expand

URL

The URL for this API is either :

<BaseURL>/ValueSet/$expand

<BaseURL>/ValueSet/<id>/$expand.

Optional Capabilities

None.

Endpoint Prerequisites

None.

Required Header Settings

Content-Type: application/json+fhir
Accept: application/json+fhir

Request Methods

GET <BaseURL>/ValueSet/$expand

Invokes $expand with a specified valueSet URL.

POST <BaseURL>/ValueSet/$expand

Invokes $expand with a specified valueSet. A valueSet URL can also be passed in through the request body.

GET <BaseURL>/ValueSet/<id>/$expand

Invokes $expand with an instance of the ValueSet.

Parameters

The operation currently supports the following Input Parameters:

url
valueSet
valueSetVersion

Making Requests

To call the $expand operation you need either a valueSet id or canonical URL, or a valueSet Parameters resource. Value set expansion can be performed using a GET or a POST request.

A GET request is an instance operation using ValueSet/$expand where you need to specify a valueSet id or canonical URL. An example using URL is:

GET <BaseURL>/ValueSet/$expand?url=http://hl7.org/fhir/ValueSet/condition-questionnaire-purposeOpens in a new tab

For a POST request, the expand operation requires the pattern value of the name parameter of the Parameters resource in the input body to be valueSet.

When using different Input Parameters, valueSet is included in the POST request body, as shown in the first POST sample. url and valueSetVersion should be passed in as query parameters, as shown in the second POST sample.

A request can generally be expected to return the requested value set expansion.

Sample Request: POST With Specified valueSet

The following shows sample request body content for a POST request with a specific valueSet included:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "valueSet",
      "resource": {
        "resourceType": "ValueSet",
        "id": "8",
        "meta": {
          "lastUpdated": "2024-05-01T15:01:33Z",
          "profile": [
            "http://hl7.org/fhir/StructureDefinition/shareablevalueset"
          ],
          "versionId": "1"
        },
        "text": {
          "status": "generated",
          "div": "<div>!-- Snipped for brevity --></div>""
        },
        "extension": [
          {
            "url": "http://hl7.org/fhir/StructureDefinition/structuredefinition-wg",
            "valueCode": "oo"
          },
          {
            "url": "http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status",
            "valueCode": "trial-use"
          },
          {
            "url": "http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm",
            "valueInteger": 2
          }
        ],
        "url": "http://hl7.org/fhir/ValueSet/task-status",
        "identifier": [
          {
            "system": "urn:ietf:rfc:3986",
            "value": "urn:oid:2.16.840.1.113883.4.642.3.790"
          }
        ],
        "version": "4.0.1",
        "name": "TaskStatus",
        "title": "TaskStatus",
        "status": "draft",
        "experimental": false,
        "date": "2019-11-01T09:29:23+11:00",
        "publisher": "HL7 (FHIR Project)",
        "contact": [
          {
            "telecom": [
              {
                "system": "url",
                "value": "http://hl7.org/fhir"
              },
              {
                "system": "email",
                "value": "fhir@lists.hl7.org"
              }
            ]
          }
        ],
        "description": "The current status of the task.",
        "immutable": true,
        "compose": {
          "include": [
            {
              "system": "http://hl7.org/fhir/task-status"
            }
          ]
        }
      }
    }
  ]
}

Sample Request: POST With valueSet URL and valueSetVersion

The resource in the POST request body may also include a valueSet URL and valueSetVersion. The following shows request body content with a url value:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "url",
      "value": "http://hl7.org/fhir/ValueSet/task-status"
    }
  ]
}

Success Responses

Status code 200

The request succeeded. A ValueSet resource is returned. Example body content:

{
    "resourceType": "ValueSet",
    "id": "8",
    "meta": {
        "lastUpdated": "2024-05-01T15:01:33Z",
        "profile": [
            "http://hl7.org/fhir/StructureDefinition/shareablevalueset"
        ],
        "versionId": "1"
    },
    "url": "http://hl7.org/fhir/ValueSet/task-status",
    "status": "draft",
    "compose": {
        "include": [
            {
                "system": "http://hl7.org/fhir/task-status"
            }
        ]
    },
    "expansion": {
        "identifier": "d3732f9f-4695-4e5c-b6f7-86a363ac8734",
        "timestamp": "2024-05-07 04:18:03.820",
        "total": 12,
        "contains": [
            {
                "system": "http://hl7.org/fhir/task-status",
                "code": "draft",
                "display": "Draft"
            },
            {
                "system": "http://hl7.org/fhir/task-status",
                "code": "requested",
                "display": "Requested"
            },
            {
                "system": "http://hl7.org/fhir/task-status",
                "code": "received",
                "display": "Received"
            },
            {
                "system": "http://hl7.org/fhir/task-status",
                "code": "accepted",
                "display": "Accepted"
            },
            {
                "system": "http://hl7.org/fhir/task-status",
                "code": "rejected",
                "display": "Rejected"
            },
            {
                "system": "http://hl7.org/fhir/task-status",
                "code": "ready",
                "display": "Ready"
            },
            {
                "system": "http://hl7.org/fhir/task-status",
                "code": "cancelled",
                "display": "Cancelled"
            },
            {
                "system": "http://hl7.org/fhir/task-status",
                "code": "in-progress",
                "display": "In Progress"
            },
            {
                "system": "http://hl7.org/fhir/task-status",
                "code": "on-hold",
                "display": "On Hold"
            },
            {
                "system": "http://hl7.org/fhir/task-status",
                "code": "failed",
                "display": "Failed"
            },
            {
                "system": "http://hl7.org/fhir/task-status",
                "code": "completed",
                "display": "Completed"
            },
            {
                "system": "http://hl7.org/fhir/task-status",
                "code": "entered-in-error",
                "display": "Entered in Error"
            }
        ]
    }
}

Error Responses

The following response error codes are possible when using the expand operation:

Status code 400

Bad Request. Possible causes include:

Invalid JSON structure.

Example response body content when a valueSetVersion parameter is passed in with no url provided:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "exception",
            "diagnostics": "<HSFHIRErr>PayloadMissing",
            "details": {
                "text": "$expand operation at the type level (no ID specified) requires a url or a valueSet as a part of the request"
            }
        }
    ]
}

Status code 404

Not Found. Possible causes include:

A value set with the given canonical URL was not found.

Example response body content:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "not-found",
            "diagnostics": "<HSFHIRErr>ResourceNotFound"
            "details": {
                "text": "Unknown ValueSet from query: url=http://hl7.org/fhir/us/core/ValueSet/detailed-race&version=4.0.1"
            }
        }
    ]
}

Status code 501

Unable to perform expansion for the value set requested. Possible causes include:

The resource is not supported.

Example response body content:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "not-found",
            "diagnostics": "<HSFHIRErr>ResourceNotSupported",
            "details": {
                "text": "Unable to perform expansion for ValueSet: url=http://hl7.org/fhir/us/core/ValueSet/detailed-race"
            }
        }
    ]
}

Status code 503

Service unavailable. Possible causes and error messages include:

The $expand endpoint is not properly set, the error includes a no-store message.
An unregistered operation or resource is requested, the error message includes The handler for operation '[operation]' for resource type '[resource type]/[resource id]' is not registered.