Locating and Managing IAS Connections

This workflow demonstrates how to enable Record Locator Service (RLS) to locate health records across healthcare networks and establish connections for data retrieval through Individual Access Service (IAS). The RLS queries designated Qualified Health Information Networks (QHINs) to discover where a user's health records exist, then facilitates connection establishment for automated data retrieval.

Prerequisites

health.network - This workflow requires health.network to be enabled for access to b.well's network connections.
Identity Verification - Verification at IAL2 (Identity Assurance Level 2) must be completed
End-User Authentication - User must be authenticated
Account Creation and Consent - User account and consent must be completed

Environment URL:

Client-Sandbox: https://api.client-sandbox.icanbwell.com/v1/graphql

Workflow Steps

Step 1: Enable Record Locator Service

Use the createConsent mutation to enable the network record locator service (RLS). This consent initiates a query to designated QHINs to locate the user's health records across participating healthcare organizations.

GraphQL Mutation:

mutation createConsent($consentInput: ConsentInput!) {
  createConsent(consentInput: $consentInput) {
    id
    provision {
      type
    }
    category {
      coding {
        code
      }
    }
    status
    patient {
      resource {
        id
      }
    }
  }
}

Example Variables:

{
  "consentInput": {
    "category": [
      {
        "coding": [
          {
            "system": "http://www.icanbwell.com/consent-category",
            "code": "IAS_IMPORT_RECORDS"
          }
        ]
      }
    ],
    "provision": {
      "type": "PERMIT"
    },
    "status": "ACTIVE"
  }
}

Example Response:

{
  "data": {
    "createConsent": {
      "id": "4b56d8a7-4f24-46f8-918b-34fdfe432976",
      "provision": {
        "type": "PERMIT"
      },
      "category": [
        {
          "coding": [
            {
              "code": "ias:import:records"
            }
          ]
        }
      ],
      "status": "active",
      "patient": {
        "resource": {
          "id": "a600e122-04b2-59e0-b922-d2e09afbf2d2"
        }
      }
    }
  }
}

Step 2: Check Network Search Status (Optional)

Use the tasks query to monitor the status of the network record location service and data retrieval. This step is optional but useful for determining when to proceed to Step 3.

Task Status Values:

Status	Description
`Ready`	Network search not started, but consent has been granted
`In Progress`	Network search in progress
`Completed`	Network search completed successfully
`Failed`	Network search encountered an issue
`Rejected`	User has revoked consent, no further network searches will occur

GraphQL Query:

query tasks($code: SearchToken) {
  tasks(code: $code) {
    entry {
      resource {
        resourceType
        id
        code {
          coding {
            system
            code
            display
          }
        }
        status
        executionPeriod {
          start
          end
        }
      }
    }
  }
}

Example Variables:

{
  "code": { 
    "value": {
      "code": "network-data-retrieval"
    }
  }
}

Example Response:

{
  "data": {
    "tasks": {
      "entry": [
        {
          "resource": {
            "resourceType": "Task",
            "id": "e34c4f9c-10a6-5cfc-acd7-e095fd59f366",
            "code": {
              "coding": [
                {
                  "system": "https://www.icanbwell.com/activityType",
                  "code": "network-data-retrieval",
                  "display": "Retrieve user data from the network"
                }
              ]
            },
            "status": "completed",
            "executionPeriod": {
              "start": "2025-11-27T12:07:56.635100Z",
              "end": "2025-11-27T12:19:56.871151Z"
            }
          }
        }
      ]
    }
  }
}

Step 3: Retrieve Recommended Connections

Use the careTeams query to retrieve data sources found by the network record locator service that require additional user authentication.

Note: Records located that meet one of the following criteria will have connections established automatically without additional user intervention. These connections will be available in the getMemberConnections response and will NOT appear in the careTeams response:

The data source has already been connected through Patient Right of Access (PROA)

The data source accepts an IAL2 token without additional user authentication

GraphQL Query:

query careTeams($categoryCode: SearchToken) {
  careTeams(category: $categoryCode) {
    id
    entry {
      resource {
        category {
          coding {
            code
          }
        }
        participant {
          id
          member {
            resource {
              ... on Organization {
                alias
                name
              }
            }
          }
          role {
            coding {
              code
              system
            }
          }
        }
      }
    }
  }
}

Example Variables:

{
  "categoryCode": { 
    "value": {
      "code": "tefca-ias-recommendations"
    }
  }
}

Example Response:

Extract the participant.member.alias value to use as the connectionId in Step 4.

{
  "data": {
    "careTeams": {
      "id": "ed582cc3-e0ed-451a-a8e6-7d6b8272b8c6",
      "entry": [
        {
          "resource": {
            "category": [
              {
                "coding": [
                  {
                    "code": "tefca-ias-recommendations"
                  }
                ]
              }
            ],
            "participant": [
              {
                "id": "1.2.840.114350.1.13.0.1.7.3.688884.100",
                "member": {
                  "resource": {
                    "alias": "c5296ea5-c1f3-5a75-8e41-21a760fb08bf",
                    "name": "FHIR Sandbox"
                  }
                },
                "role": [
                  {
                    "coding": [
                      {
                        "code": "indirect",
                        "system": "https://www.icanbwell.com/connection-type"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  }
}

Step 4: Retrieve OAuth Authorization URL

Using the participant.member.alias from Step 3 as the connectionId, query getOauthUrl to retrieve the OAuth authorization URL for the recommended connection.

GraphQL Query:

query getOauthUrl($connectionId: String!) {
  getOauthUrl(connectionId: $connectionId) {
    redirectUrl
  }
}

Example Variables:

{
  "connectionId": "c5296ea5-c1f3-5a75-8e41-21a760fb08bf"
}

Example Response:

{
  "data": {
    "getOauthUrl": {
      "redirectUrl": "[OAuth_URL]"
    }
  }
}

Step 5: Launch Authentication Flow

Direct the user to the redirectUrl returned by getOauthUrl. This URL initiates the OAuth authentication flow where the user securely logs into the healthcare provider's portal and authorizes b.well to access their health records.

Once the user completes the OAuth flow, they will be redirected back to your application, and the connection will be established for automatic data retrieval.

Re-Connect a Disconnected or Deleted IAS Connection

IAS connections with a status of EXPIRED, DISCONNECTED, or DELETED can be re-established using one of two methods, depending on the connection's integrationType.

Method A: OAuth Re-Authentication (INDIRECT_IAS connections)

For connections with integrationType of INDIRECT_IAS, use the connection id as the connectionId in the getOauthUrl query to generate a new OAuth authorization URL. Direct the user to this URL to re-authenticate and re-establish the connection.

See Steps 3 & 4 in the Search for & Establish Connections workflow guide for complete OAuth re-authentication details.

Method B: Direct Activation (direct_ias connections)

For IAS connections with integrationType of direct_ias and a status of DISCONNECTED or DELETED, use the activateDirectConnection mutation to automatically re-establish the connection without user interaction.

GraphQL Mutation:

mutation activateDirectConnection($connectionId: String!) {
  activateDirectConnection(connectionId: $connectionId) {
    status
    statusUpdated
  }
}

Example Variables:

{
  "connectionId": "2.16.840.1.113883.3.9504.1.1"
}

Example Response:

{
  "data": {
    "activateDirectConnection": {
      "status": "CONNECTED",
      "statusUpdated": "2025-11-22T10:30:15.123000"
    }
  }
}

Revoke & Re-enable Individual Access Service (IAS) Consent

Use the createConsent mutation to revoke (DENY) or re-enable (PERMIT) the user's consent for Record Locator Service and Individual Access Service (IAS) connections [2]. See the Account Creation and Consent page for additional details regarding the createConsent GraphQL mutation.

Revoking IAS consent will update all IAS connections to a status of ACCESS_ENDED [2]. Re-enabling IAS consent by setting provision.type to PERMIT will automatically re-establish all ACCESS_ENDED connections.

Note: Connections individually disconnected by the user maintain a status of DISCONNECTED and are not automatically re-enabled when IAS consent is restored. Only connections with ACCESS_ENDED status are automatically reinstated.

GraphQL Mutation:

mutation createConsent($consentInput: ConsentInput!) {
  createConsent(consentInput: $consentInput) {
    id
    provision {
      type
    }
    category {
      coding {
        code
      }
    }
    status
    patient {
      resource {
        id
      }
    }
  }
}

Example Variables (Revoke IAS Consent):

{
  "consentInput": {
    "category": [
      {
        "coding": [
          {
            "system": "http://www.icanbwell.com/consent-category",
            "code": "IAS_IMPORT_RECORDS"
          }
        ]
      }
    ],
    "provision": {
      "type": "DENY"
    },
    "status": "ACTIVE"
  }
}

Example Response:

{
  "data": {
    "createConsent": {
      "id": "4b56d8a7-4f24-46f8-918b-34fdfe432976",
      "provision": {
        "type": "DENY"
      },
      "category": [
        {
          "coding": [
            {
              "code": "ias:import:records"
            }
          ]
        }
      ],
      "status": "active",
      "patient": {
        "resource": {
          "id": "a600e122-04b2-59e0-b922-d2e09afbf2d2"
        }
      }
    }
  }
}

To re-enable IAS connections, use the same mutation with "type": "PERMIT" in the provision object.