Value Sets - GraphQL1.0.1

IMO Precision Sets GraphQL API

In this tutorial, we will leverage the IMO Precision Sets GraphQL API to create, update, publish, and query custom value sets from the Value Set Editor (VSE).

The IMO Precision Sets GraphQL API is designed for authoring workflows: creating custom value sets, editing their rules and metadata, adjusting expansion settings, and publishing new versions. It complements the read-focused FHIR REST endpoints by exposing a single, strongly-typed GraphQL surface where a client can shape a request to return exactly the fields it needs. The API provides a solution for users who need to: 

• Create a new value set and iterate on its draft version
• Add or remove rules, modify output codes, and update expansion settings
• Update value set metadata, attributes, output-code attributes, code systems, and billable-status selections
• Publish a value set version and create a new draft from a published version
• Retrieve a value set (with paged mapped rules, modified rules, and output) in a single request tailored to the caller's needs
   

How to call the API

To utilize the Precision Sets GraphQL API, you'll need to first authenticate using an Auth0 access token. Once authenticated, you can proceed to make requests to the single GraphQL endpoint.

Authentication

The GraphQL endpoint is protected by the same Auth0 tenant that guards the REST API. The following Auth0 flow is supported:

• Client-credentials (M2M)

For a client-credentials flow, once you have your Client ID and Client Secret from IMO, send a POST request to:

https://api.imohealth.com/oauth/token

with body:

{
   "client_id":"CLIENT_ID",
   "client_secret":"CLIENT_SECRET",
   "audience":"https://api.imohealth.com",
   "grant_type":"client_credentials"
}

and header: 

content-type: application/json

The response will give you the access_token. Use it to construct the header on every GraphQL request:

Authorization: "Bearer ACCESS_TOKEN_HERE"

Please contact IMO Customer Support at CustomerSupport@imo-online.com if you do not know your Client ID/Secret or need help provisioning the correct Auth0 permissions.

Making a request

Every GraphQL operation is a POST to the same endpoint:

POST https://api.imohealth.com/v1/value-sets/graphql

with headers:

Authorization: Bearer ACCESS_TOKEN_HERE
Content-Type: application/json

and a JSON body of the form:

{
  "query": "query QueryValueSet($valueSetId: Int!) { valueSet(valueSetId: $valueSetId) { valueSetId domain } }",
  "variables": { "valueSetId": 12345 }
}

The query body will be different depending on the request being made. The response is a JSON object with a data field (the requested fields) and, on failure, an errors array.

Errors

Errors surface through the standard GraphQL errors array. Each entry includes a message derived from the underlying exception. For example, attempting to modify rules while an expansion job is running returns:

{
  "errors": [
    {
      "message": "Cannot modify rules while expansion is in progress.",
      "path": ["updateValueSetVersionRules"]
    }
  ],
  "data": null
}

A partially successful response can return both data and errors; inspect both fields.

*Note: for large response payloads an "Accept-Encoding" header should be sent with the values "gzip, deflate, br" for compression purposes. 

 

Queries

The GraphQL API exposes queries to retrieve wanted value set information.

 

valueSet — retrieve a value set and its latest version

Returns the value set with the given ID along with its latest version. Nested fields such as valueSetVersion, comments, mappedRules, modifiedRules, and output can be selected in the same request. You only need to specify fields in the query that you want returned. If you query for a value set but don't want the comments, modified rules or outputs, just omit from the query.

query QueryValueSet($valueSetId: Int!) {
  valueSet(valueSetId: $valueSetId) {
    valueSetId
    domain
    createdBy
    createdDateTime
    valueSetVersion {
      valueSetVersionId
      valueSetId
      name
      scope
      inclusionCriteria
      exclusionCriteria
      version
      versionStatus
      createdDateTime
      createdBy
      expansionJobStatus
      expansionMethod
      mappedRules {
        rules {
          ruleId
          codeSystem
          mapType
          code
          codeDescription
          isRetired
          isSupported
          migratedDate
        }
        page
        pageSize
        totalCount
      }
      modifiedRules {
        modifiedRules {
          valueSetVersionRemovedCodeId
          codeSystem
          code
          description
          isRetired
          createdDateTime
          codeChangeType
          migratedDate
        }
        page
        pageSize
        totalCount
      }
      output {
        outputCodes {
          codeSystem
          code
          description
          attributes {
            attributeKey
            attributeValue
          }
          outputReasons
        }
        page
        pageSize
        totalCount
      }
      valueSetAttributes { attributeKey attributeValue displayOrder }
      codeAttributes { attributeKey displayOrder }
    }
    comments {
      valueSetCommentId
      valueSetId
      valueSetVersionId
      commentText
      createdBy
      createdDateTime
    }
  }
}

Variables:

{ "valueSetId": 12345 }

If you don't want or need a specific field from the query above, you can omit it from the query and only have the fields you wanted returned. Example trimmed response:

{
  "data": {
    "valueSet": {
      "valueSetId": 12345,
      "domain": "Problem",
      "createdBy": "user@imohealth.com",
      "createdDateTime": "2026-01-15T14:32:00Z",
      "valueSetVersion": {
        "valueSetVersionId": 67890,
        "name": "Type 2 Diabetes Mellitus",
        "version": "1",
        "versionStatus": "Published",
        "expansionMethod": "Broad"
      },
      "comments": []
    }
  }
}

 

valueSetMappedRules — page through the version's mapped rules

Returns the mapped rules (the rules a user has authored on a version) for a specific value-set version, paged.

Arguments:

Name	Type	Required	Default	Description
valueSetId	Int!	Yes	—	Identifier of the value set.
versionId	Int!	Yes	—	Identifier of the value-set version.
page	Int	No	1	1-based page number. Omit to use the default.
pageSize	Int	No	100	Number of items per page. Omit to use the default.

query ValueSetMappedRules($valueSetId: Int!, $versionId: Int!) {
  valueSetMappedRules(valueSetId: $valueSetId, versionId: $versionId) {
    rules {
      ruleId
      codeSystem
      mapType
      code
      codeDescription
      isRetired
      isSupported
      migratedDate
    }
    page
    pageSize
    totalCount
  }
}

Variables:

{ "valueSetId": 12345, "versionId": 67890 }

To page through large result sets, declare the optional page and pageSize variables and pass them explicitly:

query ValueSetMappedRules(
  $valueSetId: Int!,
  $versionId: Int!,
  $page: Int,
  $pageSize: Int
) {
  valueSetMappedRules(
    valueSetId: $valueSetId,
    versionId: $versionId,
    page: $page,
    pageSize: $pageSize
  ) {
    rules {
      ruleId
      codeSystem
      mapType
      code
      codeDescription
      isRetired
      isSupported
      migratedDate
    }
    page
    pageSize
    totalCount
  }
}

Variables:

{ "valueSetId": 12345, "versionId": 67890, "page": 2, "pageSize": 50 }

Example trimmed response:

{
  "data": {
    "valueSetMappedRules": {
      "rules": [
        {
          "ruleId": 111,
          "codeSystem": "IMO_PROBLEM",
          "mapType": "Include",
          "code": "502376",
          "codeDescription": "Type 2 diabetes mellitus",
          "isRetired": false,
          "isSupported": true,
          "migratedDate": null
        }
      ],
      "page": 1,
      "pageSize": 100,
      "totalCount": 1
    }
  }
}

 

valueSetModifiedRules — page through the version's modified rules

Returns the codes that were added to or removed from a version's expanded output (i.e. modifications applied on top of the mapped rules), paged.

Arguments:

Name	Type	Required	Default	Description
valueSetId	Int!	Yes	—	Identifier of the value set.
versionId	Int!	Yes	—	Identifier of the value-set version.
page	Int	No	1	1-based page number. Omit to use the default.
pageSize	Int	No	100	Number of items per page. Omit to use the default.

query ValueSetModifiedRules($valueSetId: Int!, $versionId: Int!) {
  valueSetModifiedRules(valueSetId: $valueSetId, versionId: $versionId) {
    modifiedRules {
      valueSetVersionRemovedCodeId
      codeSystem
      code
      description
      isRetired
      createdDateTime
      codeChangeType
      migratedDate
    }
    page
    pageSize
    totalCount
  }
}

Variables:

{ "valueSetId": 12345, "versionId": 67890 }

To page through large result sets, declare the optional page and pageSize variables and pass them explicitly:

query ValueSetModifiedRules(
  $valueSetId: Int!,
  $versionId: Int!,
  $page: Int,
  $pageSize: Int
) {
  valueSetModifiedRules(
    valueSetId: $valueSetId,
    versionId: $versionId,
    page: $page,
    pageSize: $pageSize
  ) {
    modifiedRules {
      valueSetVersionRemovedCodeId
      codeSystem
      code
      description
      isRetired
      createdDateTime
      codeChangeType
      migratedDate
    }
    page
    pageSize
    totalCount
  }
}

Variables:

{ "valueSetId": 12345, "versionId": 67890, "page": 2, "pageSize": 50 }

Example trimmed response:

{
  "data": {
    "valueSetModifiedRules": {
      "modifiedRules": [
        {
          "valueSetVersionRemovedCodeId": 222,
          "codeSystem": "SNOMED_CT",
          "code": "217701002",
          "description": "Accidental fall from horse",
          "isRetired": false,
          "createdDateTime": "2026-02-01T10:00:00Z",
          "codeChangeType": "Removed",
          "migratedDate": null
        }
      ],
      "page": 1,
      "pageSize": 100,
      "totalCount": 1
    }
  }
}

 

valueSetOutput — page through the version's expanded output codes

Returns the expanded output codes for a specific value-set version, paged.

Arguments:

Name	Type	Required	Default	Description
valueSetId	Int!	Yes	—	Identifier of the value set.
versionId	Int!	Yes	—	Identifier of the value-set version.
page	Int	No	1	1-based page number. Omit to use the default.
pageSize	Int	No	100	Number of items per page. Omit to use the default.

query ValueSetOutput($valueSetId: Int!, $versionId: Int!) {
  valueSetOutput(valueSetId: $valueSetId, versionId: $versionId) {
    outputCodes {
      codeSystem
      code
      description
      isRetired
      outputReasons
      attributes { attributeKey attributeValue }
    }
    page
    pageSize
    totalCount
  }
}

Variables:

{ "valueSetId": 12345, "versionId": 67890 }

To page through large result sets, declare the optional page and pageSize variables and pass them explicitly:

query ValueSetOutput(
  $valueSetId: Int!,
  $versionId: Int!,
  $page: Int,
  $pageSize: Int
) {
  valueSetOutput(
    valueSetId: $valueSetId,
    versionId: $versionId,
    page: $page,
    pageSize: $pageSize
  ) {
    outputCodes {
      codeSystem
      code
      description
      isRetired
      outputReasons
      attributes { attributeKey attributeValue }
    }
    page
    pageSize
    totalCount
  }
}

Variables:

{ "valueSetId": 12345, "versionId": 67890, "page": 2, "pageSize": 50 }

Example trimmed response:

{
  "data": {
    "valueSetOutput": {
      "outputCodes": [
        {
          "codeSystem": "ICD_10_CM",
          "code": "E11.9",
          "description": "Type 2 diabetes mellitus without complications",
          "isRetired": false,
          "outputReasons": ["MappedFromRule"],
          "attributes": []
        }
      ],
      "page": 1,
      "pageSize": 100,
      "totalCount": 1
    }
  }
}

 

Mutations

The GraphQL API exposes mutations to make edits to your value set(s). Mutations will respond with an error if the current value set version is undergoing expansion or is flagged for maintenance and will be unable to be edited until the value set is both marked as Completed for expansion and Reviewed for the maintenance status

 

createNewValueSet — create a new value set

Creates a brand-new value set and its initial draft version. Throws if a value set version with the same name already exists in the org.

mutation CreateNewValueSet($input: CreateNewValueSetInput!) {
  createNewValueSet(input: $input) {
    valueSet {
      valueSetId
      domain
      valueSetVersion {
        valueSetVersionId
        valueSetId
        name
        scope
        inclusionCriteria
        exclusionCriteria
        version
        versionStatus
        createdDateTime
        createdBy
        expansionJobStatus
      }
    }
  }
}

Variables:

{
  "input": {
    "name": "New value set name",
    "domain": "Problem",
    "scope": "the scope",
    "inclusionCriteria": "the inclusion criteria",
    "exclusionCriteria": "the exclusion criteria"
  }
}

 

updateValueSetVersionMetadata — update draft metadata

Updates name, scope, inclusionCriteria, and/or exclusionCriteria on a draft version. Omit a field or set the value to null to leave it unchanged; pass an empty string or whitespace to clear it.

mutation UpdateValueSetVersionMetadata($input: UpdateValueSetVersionMetadataInput!) {
  updateValueSetVersionMetadata(input: $input) {
    valueSet {
      valueSetId
      valueSetVersion {
        valueSetVersionId
        name
        scope
        inclusionCriteria
        exclusionCriteria
      }
    }
  }
}

Variables:

{
  "input": {
    "valueSetId": 12345,
    "valueSetVersionId": 67890,
    "scope": "updated scope",
    "inclusionCriteria": "updated inclusion criteria",
    "exclusionCriteria": ""
  }
}

 

updateValueSetVersionRules — add, update, or remove rules

Adds new rules, updates existing rules' map types, or removes rules from a draft version. Triggers an asynchronous expansion job

mutation UpdateValueSetVersionRules($input: UpdateValueSetVersionRulesInput!) {
  updateValueSetVersionRules(input: $input) {
    valueSet {
      valueSetId
      valueSetVersion {
        valueSetVersionId
        expansionJobStatus
      }
    }
  }
}

Variables (add a rule):

{
  "input": {
    "valueSetId": 12345,
    "valueSetVersionId": 67890,
    "rulesToAddOrUpdate": [
      { "codeSystem": "IMO_PROBLEM", "code": "502376", "mapType": "Include" }
    ],
    "rulesToDelete": []
  }
}

Variables (remove a rule):

{
  "input": {
    "valueSetId": 12345,
    "valueSetVersionId": 67890,
    "rulesToAddOrUpdate": [],
    "rulesToDelete": [
      { "codeSystem": "IMO_PROBLEM", "code": "502376" }
    ]
  }
}

 

updateModifiedRules — add or remove output codes

Adds codes to or removes codes from the expanded output of a draft version, on top of what the mapped rules produce.

mutation UpdateModifiedRules($input: UpdateModifiedRulesInput!) {
  updateModifiedRules(input: $input) {
    valueSet {
      valueSetId
      valueSetVersion { valueSetVersionId }
    }
  }
}

Variables:

{
  "input": {
    "valueSetId": 12345,
    "valueSetVersionId": 67890,
    "codesToAddToOutput": [
      { "codeSystem": "SNOMED_CT", "code": "283112002" }
    ],
    "codesToRemoveFromOutput": [
      { "codeSystem": "SNOMED_CT", "code": "217701002" }
    ]
  }
}

 

addValueSetComment — add a comment

Adds a free-text comment to a value set (optionally scoped to a specific version).

mutation AddValueSetComment($input: AddValueSetCommentInput!) {
  addValueSetComment(input: $input) {
    comment {
      valueSetCommentId
      valueSetId
      valueSetVersionId
      commentText
      createdBy
      createdDateTime
    }
  }
}

Variables:

{
  "input": {
    "valueSetId": 12345,
    "valueSetVersionId": 67890,
    "commentText": "Lorem ipsum dolor sit amet"
  }
}

 

updateExpansionSetting — change how rules expand

Changes the expansion method for a draft version (e.g. Broad, Narrow). Triggers an asynchronous re-expansion.

mutation UpdateExpansionSetting($input: UpdateExpansionSettingInput!) {
  updateExpansionSetting(input: $input) {
    valueSet {
      valueSetId
      valueSetVersion {
        valueSetVersionId
        expansionJobStatus
        expansionMethod
      }
    }
  }
}

Variables:

{
  "input": {
    "valueSetId": 12345,
    "valueSetVersionId": 67890,
    "expansionMethod": "Broad"
  }
}

 

updateSelectedCodeSystems — pick which code systems to output

Sets the list of code systems included in the version's output (e.g. ICD_10_CM, SNOMED_CT, etc.).

mutation UpdateSelectedCodeSystems($input: UpdateSelectedCodeSystemsInput!) {
  updateSelectedCodeSystems(input: $input) {
    selectedCodeSystems
    valueSet {
      valueSetId
      valueSetVersion { valueSetVersionId }
    }
  }
}

Variables:

{
  "input": {
    "valueSetId": 12345,
    "valueSetVersionId": 67890,
    "selectedCodeSystems": ["ICD_10_CM", "SNOMED_CT"]
  }
}

 

updateSelectedBillableStatuses — pick which billable statuses to output

Sets the list of billable statuses to include in the version's output (e.g. Billable, NonBillable, etc.).

mutation UpdateSelectedBillableStatuses($input: UpdateSelectedBillableStatusesInput!) {
  updateSelectedBillableStatuses(input: $input) {
    selectedBillableStatuses
    valueSet {
      valueSetId
      valueSetVersion { valueSetVersionId }
    }
  }
}

Variables:

{
  "input": {
    "valueSetId": 12345,
    "valueSetVersionId": 67890,
    "selectedBillableStatuses": ["Billable", "NonBillable"]
  }
}

 

updateValueSetVersionAttributes — set version-level custom attributes

Replaces the version's custom attributes and its output-attribute definitions.

mutation UpdateValueSetVersionAttributes($input: UpdateValueSetVersionAttributesInput!) {
  updateValueSetVersionAttributes(input: $input) {
    valueSetAttributes { attributeKey attributeValue displayOrder }
    outputAttributes { attributeKey displayOrder }
  }
}

Variables:

{
  "input": {
    "valueSetId": 12345,
    "valueSetVersionId": 67890,
    "valueSetAttributes": [
      { "attributeKey": "Ping", "attributeValue": "Ping Value", "displayOrder": 0 },
      { "attributeKey": "Pong", "attributeValue": "Pong Value", "displayOrder": 0 }
    ],
    "outputAttributes": [
      { "attributeKey": "Foo", "displayOrder": 0 },
      { "attributeKey": "Bar", "displayOrder": 0 }
    ]
  }
}

 

updateValueSetOutputCodeAttributes — set per-output-code attribute values

Sets attribute values on individual output codes. The attributeKey must already be defined via updateValueSetVersionAttributes' outputAttributes.

mutation UpdateValueSetOutputCodeAttributes($input: UpdateValueSetOutputCodeAttributesInput!) {
  updateValueSetOutputCodeAttributes(input: $input) {
    valueSet { valueSetId }
  }
}

Variables:

{
  "input": {
    "valueSetId": 12345,
    "valueSetVersionId": 67890,
    "attributes": [
      { "codeSystem": "IMO_PROBLEM", "code": "502376", "attributeKey": "Foo", "attributeValue": "foo val" },
      { "codeSystem": "IMO_PROBLEM", "code": "502376", "attributeKey": "Bar", "attributeValue": "bar val" },
      { "codeSystem": "SNOMED_CT",   "code": "217701002", "attributeKey": "Foo", "attributeValue": "applesauce" }
    ]
  }
}

 

publishValueSet — publish the latest draft

Publishes the latest version of the given value set.

mutation PublishValueSet($valueSetId: Int!) {
  publishValueSet(valueSetId: $valueSetId) {
    valueSet {
      valueSetId
      valueSetVersion { valueSetVersionId }
    }
  }
}

Variables:

{ "valueSetId": 12345 }

 

createValueSetDraft — start a new draft from a published version

Creates a new draft version starting from the specified published version — this is how editing resumes after a publish.

mutation CreateValueSetDraft($valueSetId: Int!, $versionId: Int!) {
  createValueSetDraft(valueSetId: $valueSetId, versionId: $versionId) {
    valueSet {
      valueSetId
      valueSetVersion { valueSetVersionId }
    }
  }
}

Variables:

{ "valueSetId": 12345, "versionId": 67890 }