> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/docs/integrations-and-plugins/integrations/fhir-beta.md).

# FHIR - Beta

Connect your EHR system to Kizen Agentic Workflows. Read and write live FHIR data and synchronize that data back into Kizen Records.

{% hint style="success" %}
**Audience:** Admins, Developers, Solution Architects

**Purpose:** Explains what the FHIR integration is, when to use it, and how it works within your <code class="expression">space.vars.automations</code>
{% endhint %}

## Overview

Use the FHIR integration to connect <code class="expression">space.vars.Kizen\_company\_name</code> to your EHR system. Read and write clinical resource data directly from <code class="expression">space.vars.automations</code>, and then synchronize that data back into your <code class="expression">space.vars.Kizen\_company\_name</code> environment.

This integration is designed for EHR systems that comply with the HL7® FHIR® standard.

{% hint style="info" %}
**Note:** The FHIR integration is in Beta. It is not created by, affiliated with, or supported by Health Level Seven International.
{% endhint %}

### What Is the FHIR Integration?

The FHIR integration adds nine action steps to the <code class="expression">space.vars.automation</code> builder in <code class="expression">space.vars.Kizen\_company\_name</code>:

* **FHIR Authenticate:** Authenticates the integration to a FHIR server
* **FHIR Read:** Reads a FHIR resource
* **FHIR Search:** Searches FHIR resources and returns the results
* **FHIR Create:** Creates a new FHIR resource from data in <code class="expression">space.vars.Kizen\_company\_name</code>
* **FHIR Update:** Overwrites an existing FHIR resource with data from <code class="expression">space.vars.Kizen\_company\_name</code>
* **FHIR Patch:** Changes parts of an existing FHIR resource with data from <code class="expression">space.vars.Kizen\_company\_name</code> without replacing it completely
* **Create Kizen Record:** Creates a <code class="expression">space.vars.entity</code> in <code class="expression">space.vars.Kizen\_company\_name</code> from a FHIR resource
* **Parse FHIR Resource:** Prepares one or more FHIR resources for batch import into <code class="expression">space.vars.Kizen\_company\_name</code>
* **Batch Import via SmartConnector:** Uses a <code class="expression">space.vars.smartconnector</code> to import parsed FHIR resources into <code class="expression">space.vars.Kizen\_company\_name</code>

You configure the connection to your FHIR server once, as an integration secret in <code class="expression">space.vars.Kizen\_company\_name</code>.

The integration supports a single FHIR environment or multiple environments, each with its own connection credentials. If you have more than one environment, you specify which to query when you call a FHIR action from your <code class="expression">space.vars.automation</code>.

See [Set Up FHIR in Kizen](/docs/integrations-and-plugins/integrations/fhir-beta/set-up-fhir-in-kizen.md) for details.

#### Typical Agentic Workflow Sequences

The FHIR actions are designed for you to chain together in an <code class="expression">space.vars.automation</code>. Here are some examples of typical sequences:

* **To synchronize a single FHIR resource to a Kizen Record:** FHIR Authenticate → FHIR Read → Create <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.entity</code>
* **To batch-import FHIR resources through a SmartConnector:** FHIR Authenticate → FHIR Search → Parse FHIR Resource → Batch Import via <code class="expression">space.vars.smartconnector</code>
* **To write back data to your EHR system:** FHIR Authenticate → FHIR Create *or* FHIR Update *or* FHIR Patch

### When to Use the FHIR Integration

Use the FHIR integration when an <code class="expression">space.vars.automation</code> needs to read or write live data between FHIR and <code class="expression">space.vars.Kizen\_company\_name</code> before continuing to the next step. You don't need to duplicate your FHIR data in <code class="expression">space.vars.Kizen\_company\_name</code> to make use of this data in <code class="expression">space.vars.automations</code>. The integration handles the communication with your FHIR server and supplies live data at your request.

The integration is ideal for healthcare operations teams and solutions engineers building clinical workflows.

#### Common Use Cases

Here are some common use cases of the FHIR integration:

* Searching a FHIR server for patient resources, parsing the results, and batch-importing them into <code class="expression">space.vars.Kizen\_company\_name</code> on a regular schedule
* Reading patient and treatment data from an EHR system when new lab results arrive
* Confirming appointments with patients, capturing patient responses, and writing clinical notes back to the EHR system

***

## How the FHIR Integration Works

Before you configure the FHIR integration, it's important to understand how it functions at a conceptual level.

### FHIR Version

The integration is designed to work with FHIR R4, the industry default. It hasn't been tested with FHIR R5 or R6 servers, and it doesn't support FHIR STU3.

### Connection Model

The integration connects to your FHIR server over SMART Backend Services, an OAuth 2.0 Client Credentials Grant that uses signed JSON Web Tokens for authentication. The integration keeps track of your connection credentials as an integration secret.

A single secret can hold credentials for multiple FHIR environments, such as production and staging, as separate keys. You select which environment to use at each FHIR step of your <code class="expression">space.vars.automation</code>.

### Authentication

The integration obtains a new access token on every execution of the FHIR Authenticate action in your <code class="expression">space.vars.automation</code> and presents the token to subsequent FHIR actions on your behalf. To maximize security, the integration doesn't cache the token between runs of the <code class="expression">space.vars.automation</code>, so you need a fresh token each time.

Under normal conditions, the token shouldn't expire before your <code class="expression">space.vars.automation</code> completes, but if does, re-run the <code class="expression">space.vars.automation</code>.

### Field Mapping

To synchronize data between FHIR and <code class="expression">space.vars.Kizen\_company\_name</code>, you create <code class="expression">space.vars.objects</code> in <code class="expression">space.vars.Kizen\_company\_name</code> and then map the <code class="expression">space.vars.fields</code> of these <code class="expression">space.vars.objects</code> to the corresponding fields in the FHIR resource. The integration uses a mapping syntax to describe the path to the desired field. This directive goes in the description of the <code class="expression">space.vars.field</code> in <code class="expression">space.vars.Kizen\_company\_name</code>.

Most of the available FHIR actions don't require this additional setup. But for those that do, namely Create <code class="expression">space.vars.Kizen\_company\_name</code> <code class="expression">space.vars.entity</code> and Parse FHIR Resource, properly mapped <code class="expression">space.vars.fields</code> are necessary for the action to work.

For more information, see [Set Up FHIR in Kizen](/docs/integrations-and-plugins/integrations/fhir-beta/set-up-fhir-in-kizen.md).

### Scheduled Synchronization

The integration doesn't include a built-in scheduled synchronization feature, where FHIR data in <code class="expression">space.vars.Kizen\_company\_name</code> automatically updates itself upon changes. However, you can achieve a similar effect by running a batch-import sequence as a scheduled, recurring <code class="expression">space.vars.automation</code>.

### Step Execution

Each FHIR action step executes synchronously, so the <code class="expression">space.vars.automation</code> waits at the step until it completes. The step times out on the <code class="expression">space.vars.Kizen\_company\_name</code> side after 30 seconds.

{% hint style="info" %}
**Note:** If you experience regular timeouts, try adjusting either the frequency of synchronization or the batch size per run. For example, if synchronizing once per day causes timeout issues because of the number of <code class="expression">space.vars.entities</code> to synchronize, synchronizing more often or with smaller, paginated batches can help.
{% endhint %}

### Rate Limiting

Rate limits are subject to your FHIR server and EHR system. If the FHIR server returns HTTP status code **429 Too Many Requests** in a step of your <code class="expression">space.vars.automation</code>, the integration retries the step three times before failing.

### Failure Handling

If a connection or action fails, for example because of invalid credentials, network difficulties, or improper configuration, the step fails immediately and results in an error message. <code class="expression">space.vars.Kizen\_company\_name</code> doesn't automatically retry a failed step, so after you correct the underlying issue, rerun the step manually.

For more information, see [Troubleshoot FHIR](/docs/integrations-and-plugins/integrations/fhir-beta/troubleshoot-fhir.md).

### Data Integrity

If your <code class="expression">space.vars.automation</code> writes data back to FHIR, be sure to validate its behavior thoroughly on non-production data first. You can't roll back a write operation after it executes, and the operation might partially apply if an error occurs during execution.

***

## Available FHIR Actions and Topics

For step-by-step instructions on using the FHIR integration, see the following topics:

* [Set Up FHIR in Kizen](/docs/integrations-and-plugins/integrations/fhir-beta/set-up-fhir-in-kizen.md)
* [Authenticate to a FHIR Server in an Agentic Workflow](/docs/integrations-and-plugins/integrations/fhir-beta/authenticate-to-a-fhir-server-in-an-agentic-workflow.md)
* [Read and Write FHIR Data in an Agentic Workflow](/docs/integrations-and-plugins/integrations/fhir-beta/read-and-write-fhir-data-in-an-agentic-workflow.md)
* [Synchronize Data Between FHIR and Kizen in an Agentic Workflow](/docs/integrations-and-plugins/integrations/fhir-beta/synchronize-data-between-fhir-and-kizen-in-an-agentic-workflow.md)
* [Troubleshoot FHIR](/docs/integrations-and-plugins/integrations/fhir-beta/troubleshoot-fhir.md)

***

## What's Next

To configure your FHIR server to work <code class="expression">space.vars.Kizen\_company\_name</code> and enter your connection credentials as an integration secret, continue to [Set Up FHIR in Kizen](/docs/integrations-and-plugins/integrations/fhir-beta/set-up-fhir-in-kizen.md).

<details>

<summary><strong>Related Topics</strong></summary>

* [Set Up FHIR in Kizen](/docs/integrations-and-plugins/integrations/fhir-beta/set-up-fhir-in-kizen.md)
* [Authenticate to a FHIR Server in an Agentic Workflow](/docs/integrations-and-plugins/integrations/fhir-beta/authenticate-to-a-fhir-server-in-an-agentic-workflow.md)
* [Read and Write FHIR Data in an Agentic Workflow](/docs/integrations-and-plugins/integrations/fhir-beta/read-and-write-fhir-data-in-an-agentic-workflow.md)
* [Synchronize Data Between FHIR and Kizen in an Agentic Workflow](/docs/integrations-and-plugins/integrations/fhir-beta/synchronize-data-between-fhir-and-kizen-in-an-agentic-workflow.md)
* [Troubleshoot FHIR](/docs/integrations-and-plugins/integrations/fhir-beta/troubleshoot-fhir.md)

</details>

***

*HL7, FHIR, and the FHIR FLAME DESIGN are the registered trademarks of Health Level Seven International, and their use does not constitute endorsement by HL7.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.kizen.com/docs/integrations-and-plugins/integrations/fhir-beta.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.