> 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/read-and-write-fhir-data-in-an-agentic-workflow.md).

# Read and Write FHIR Data in an Agentic Workflow

Add FHIR action steps to a Kizen Agentic Workflow to read, search, create, update, and patch FHIR data.

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

**Purpose:** Explains how to add FHIR action steps to <code class="expression">space.vars.automations</code> in <code class="expression">space.vars.Kizen\_company\_name</code> to read and write live FHIR data
{% endhint %}

## Overview

{% hint style="warning" %}
**Caution:** This setup reflects Kizen's default configuration. Your administrator may have customized your layout, so columns or navigation may appear differently. Trial accounts may have limited features.
{% endhint %}

Once you use the FHIR integration to authenticate to your FHIR® server, you can read and write live FHIR data directly from an <code class="expression">space.vars.automation</code>.

***

## Before You Begin

To read and write FHIR data in an <code class="expression">space.vars.automation</code>, you need:

* A connection from <code class="expression">space.vars.Kizen\_company\_name</code> to your FHIR server. For details, see [Set Up FHIR in Kizen](/docs/integrations-and-plugins/integrations/fhir-beta/set-up-fhir-in-kizen.md).
* A valid access token and base URL for your FHIR server. See [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) for more information.

***

## Read and Write FHIR in an Agentic Workflow

To read and write FHIR in an <code class="expression">space.vars.automation</code>:

{% stepper %}
{% step %}

#### Go to the Agentic Workflow builder

In the global navigation, select **Agentic Workflows**. Then, to open the builder, do one of the following:

* Select **New Agentic Workflow**.
* Select the name of an existing <code class="expression">space.vars.automation</code>.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FmGY4T9nPsz6M1Yixhckg%2Fglobal_newagenticworkflow.png?alt=media&amp;token=61f7db6e-276b-4535-b743-71a7d9ff234d" alt="The New Agentic Workflow button on the Agentic Workflows page" width="563"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

#### Add an action to the Agentic Workflow

In the builder, select **+**, and then select **Add Action**.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FRU6mGUYeAjXtxNh38YaX%2Fglobal_addaction.png?alt=media&amp;token=8824261c-9bd8-408d-966c-483cbf07a31a" alt="The Add Action context menu item in the Agentic Workflow builder" width="563"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

#### Select the FHIR action

In the Add Action modal that appears, scroll to the Integration section, and select the FHIR connection card.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2F5pYFHOFiv0zgLjSPE7ZB%2Ffhir_addfhiraction.png?alt=media&amp;token=bfc6359d-7632-422a-8b97-020273b1eac6" alt="The FHIR connection card on the Add Action modal" width="563"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

#### Choose the function to perform

In the Action Settings section of the Add Action modal, select the **Action** dropdown menu, and do one of the following:

* To read a single FHIR resource, select **FHIR Read**, and set up the action. For more information, see [Set Up a FHIR Read Action](#set-up-a-fhir-read-action) below.
* To search FHIR resources and return results, select **FHIR Search**, and set up the action. For more information, see [Set Up a FHIR Search Action](#set-up-a-fhir-search-action) below.
* To create a new FHIR resource, select **FHIR Create**, and set up the action. For more information, see [Set Up a FHIR Create Action](#set-up-a-fhir-create-action) below.
* To update an existing FHIR resource in its entirety, select **FHIR Update**, and set up the action. For more information, see [Set Up a FHIR Update Action](#set-up-a-fhir-update-action) below.
* To update certain fields of an existing FHIR resource, select **FHIR Patch**, and set up the action. For more information, see [Set Up a FHIR Patch Action](#set-up-a-fhir-patch-action) below.

{% hint style="info" %}
**Note:** Each of these actions depends on the access token and base URL that the FHIR Authenticate action obtains. If you haven't added FHIR Authenticate to your <code class="expression">space.vars.automation</code>, you should do so now. See [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) for details.
{% endhint %}
{% endstep %}

{% step %}

#### Configure error handling

In the Error Handling section of the modal, specify how to handle errors in this step of the <code class="expression">space.vars.automation</code>.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FGzhPBGaxlzsW1tWJMZYU%2FScreenshot%202026-07-16%20at%209.13.52%E2%80%AFAM.png?alt=media&amp;token=5dc5daed-6009-44f6-8120-e7124eb6aee8" alt="The error handling options in the Add Action modal" width="563"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

#### Save the FHIR action

Select **Save**.
{% endstep %}
{% endstepper %}

***

## Set Up a FHIR Read Action

The FHIR Read action reads a single FHIR resource by its type and ID.

To set up a FHIR Read action:

{% stepper %}
{% step %}

#### Configure the sources for the script inputs

For each of the fields in the Script Inputs section of the Add Action modal, select the source of the field's value from the **Input Source** dropdown menu, and then configure the source with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FijOQN51tyec03ntLjMWX%2Ffhir_fhirread_inputs.png?alt=media&amp;token=a12a4221-b075-4c77-8f32-48d188436a6e" alt="The script inputs for the FHIR Read action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

| Field             | Type     | Description                                                                                  | Required? |
| ----------------- | -------- | -------------------------------------------------------------------------------------------- | --------- |
| **Access Token**  | `String` | The access token from the FHIR Authenticate action                                           | Yes       |
| **FHIR Base URL** | `String` | The base URL of the FHIR server from the FHIR Authenticate action                            | Yes       |
| **Resource ID**   | `String` | The ID of the FHIR resource to read                                                          | Yes       |
| **Resource Type** | `String` | The type of the FHIR resource to read in PascalCase, such as `Patient` or `PractitionerRole` | Yes       |
| {% endstep %}     |          |                                                                                              |           |

{% step %}

#### Configure the destinations for the script outputs

For each of the fields in the Script Outputs section of the modal, select the destination of the field's value from the **Output Destination** dropdown menu, and then configure the destination with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FGPhHs45dahajmzukU5Mq%2Ffhir_fhirread_outputs.png?alt=media&amp;token=8c92ed6a-54b7-4c41-8858-09ed310f5bd3" alt="The script outputs for the FHIR Read action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

| Field                | Type     | Description                                           | Required? |
| -------------------- | -------- | ----------------------------------------------------- | --------- |
| **HTTP Status Code** | `Number` | The HTTP status code that the read operation returned | No        |
| **Result**           | `String` | The result of the read operation in JSON format       | No        |
| {% endstep %}        |          |                                                       |           |
| {% endstepper %}     |          |                                                       |           |

***

## Set Up a FHIR Search Action

The FHIR Search action runs a search on FHIR resources of the specified type and returns the results for use in your <code class="expression">space.vars.automation</code>.

{% hint style="info" %}
**Note:** The FHIR Search action returns the first page of results only. For large results sets, use `_count` in the search parameters to control page size and handle pagination manually in the <code class="expression">space.vars.automation</code>.
{% endhint %}

To set up a FHIR Search action:

{% stepper %}
{% step %}

#### Configure the sources for the script inputs

For each of the fields in the Script Inputs section of the Add Action modal, select the source of the field's value from the **Input Source** dropdown menu, and then configure the source with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FI7ikUIlEggAP7ryw9Tkg%2Ffhir_fhirsearch_inputs.png?alt=media&amp;token=f3047497-f0f5-480e-a529-1b2fbec2d109" alt="The script inputs for the FHIR Search action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

| Field                 | Type     | Description                                                                                    | Required? |
| --------------------- | -------- | ---------------------------------------------------------------------------------------------- | --------- |
| **Access Token**      | `String` | The access token from the FHIR Authenticate action                                             | Yes       |
| **FHIR Base URL**     | `String` | The base URL of the FHIR server from the FHIR Authenticate action                              | Yes       |
| **Resource Type**     | `String` | The type of the FHIR resource to search in PascalCase, such as `Patient` or `PractitionerRole` | Yes       |
| **Search Parameters** | `String` | The parameters of the search, like this: `_count=10&_lastUpdated=gt2026-02-10T00:00:00Z`       | No        |

{% hint style="info" %}
**Note:** If you don't specify search parameters, the integration returns all FHIR resources of that type.
{% endhint %}
{% endstep %}

{% step %}

#### Configure the destinations for the script outputs

For each of the fields in the Script Outputs section of the modal, select the destination of the field's value from the **Output Destination** dropdown menu, and then configure the destination with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2F6V6ImMPSM4nfUHa527Hs%2Ffhir_fhirsearch_outputs.png?alt=media&amp;token=46774f42-2518-4642-897e-69357e037294" alt="The script outputs for the FHIR Search action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

| Field                | Type     | Description                                                                                                                              | Required? |
| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| **HTTP Status Code** | `Number` | The HTTP status code that the search operation returned.                                                                                 | No        |
| **Result**           | `String` | The result set as a JSON string.                                                                                                         | No        |
| **Total Count**      | `Number` | The total number of entries on the first page of results. Note that this isn't necessarily the same as the total number of FHIR bundles. | No        |

{% hint style="info" %}
**Note:** Large search results might cause timeouts. Consider streamlining the search by providing targeted search parameters.
{% endhint %}
{% endstep %}
{% endstepper %}

***

## Set Up a FHIR Create Action

The FHIR Create action creates a new FHIR resource of the specified type from data in <code class="expression">space.vars.Kizen\_company\_name</code>.

{% hint style="info" %}
**Note:** The FHIR Create action can't consume a FHIR Search result directly. You must parse the result with the Parse FHIR Resource action first.
{% endhint %}

To set up a FHIR Create action:

{% stepper %}
{% step %}

#### Configure the sources for the script inputs

For each of the fields in the Script Inputs section of the Add Action modal, select the source of the field's value from the **Input Source** dropdown menu, and then configure the source with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FRnbfo3eyhBxE8T6z3YIS%2Ffhir_fhircreate_inputs.png?alt=media&amp;token=2e4bcefc-0802-47b9-b39a-3635a309baf2" alt="The script inputs for the FHIR Create action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

| Field             | Type     | Description                                                                                        | Required? |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------- | --------- |
| **Access Token**  | `String` | The access token from the FHIR Authenticate action                                                 | Yes       |
| **FHIR Base URL** | `String` | The base URL of the FHIR server from the FHIR Authenticate action                                  | Yes       |
| **Resource Body** | `String` | The FHIR resource to create as a JSON string. Take this value from the output of a FHIR Read step. | Yes       |
| **Resource Type** | `String` | The type of the FHIR resource to create in PascalCase, such as `Patient` or `PractitionerRole`.    | Yes       |
| {% endstep %}     |          |                                                                                                    |           |

{% step %}

#### Configure the destinations for the script outputs

For each of the fields in the Script Outputs section of the modal, select the destination of the field's value from the **Output Destination** dropdown menu, and then configure the destination with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FHuXgnKnSxXse7JUeX36B%2Ffhir_fhircreate_outputs.png?alt=media&amp;token=878f3191-6f88-4f15-bafb-b184497734ab" alt="The script outputs for the FHIR Create action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

| Field                   | Type     | Description                                             | Required? |
| ----------------------- | -------- | ------------------------------------------------------- | --------- |
| **Created Resource ID** | `String` | The ID of the created FHIR resource                     | No        |
| **HTTP Status Code**    | `Number` | The HTTP status code that the create operation returned | No        |
| **Result**              | `String` | The JSON string of the created FHIR resource            | No        |
| {% endstep %}           |          |                                                         |           |
| {% endstepper %}        |          |                                                         |           |

***

## Set Up a FHIR Update Action

The FHIR Update action replaces an existing FHIR resource of the specified type by overwriting it completely with data from <code class="expression">space.vars.Kizen\_company\_name</code>.

To set up a FHIR Update action:

{% stepper %}
{% step %}

#### Configure the sources for the script inputs

For each of the fields in the Script Inputs section of the Add Action modal, select the source of the field's value from the **Input Source** dropdown menu, and then configure the source with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FOghdBurM7I9jjVQGpqTN%2Ffhir_fhirupdate_inputs.png?alt=media&amp;token=e29a7e69-ebcb-4836-bd3a-8163dea86332" alt="The script inputs for the FHIR Update action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

| Field             | Type     | Description                                                                                    | Required? |
| ----------------- | -------- | ---------------------------------------------------------------------------------------------- | --------- |
| **Access Token**  | `String` | The access token from the FHIR Authenticate action                                             | Yes       |
| **FHIR Base URL** | `String` | The base URL of the FHIR server from the FHIR Authenticate action                              | Yes       |
| **Resource Body** | `String` | The FHIR resource to update as a JSON string                                                   | Yes       |
| **Resource ID**   | `String` | The ID of the FHIR resource to update                                                          | Yes       |
| **Resource Type** | `String` | The type of the FHIR resource to update in PascalCase, such as `Patient` or `PractitionerRole` | Yes       |
| {% endstep %}     |          |                                                                                                |           |

{% step %}

#### Configure the destinations for the script outputs

For each of the fields in the Script Outputs section of the modal, select the destination of the field's value from the **Output Destination** dropdown menu, and then configure the destination with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FGlbasQi1AJ2s5zMWszqG%2Ffhir_fhirupdate_outputs.png?alt=media&amp;token=e06a5b4f-9455-4869-aa67-4add723932ad" alt="The script outputs for the FHIR Update action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

| Field                | Type     | Description                                             | Required? |
| -------------------- | -------- | ------------------------------------------------------- | --------- |
| **HTTP Status Code** | `Number` | The HTTP status code that the update operation returned | No        |
| **Result**           | `String` | The JSON string of the updated FHIR resource            | No        |
| {% endstep %}        |          |                                                         |           |
| {% endstepper %}     |          |                                                         |           |

***

## Set Up a FHIR Patch Action

The FHIR Patch action partially updates a FHIR resource of the specified type with data from <code class="expression">space.vars.Kizen\_company\_name</code>. Unlike FHIR Update, this action doesn't overwrite the resource completely.

To set up a FHIR Patch action:

{% stepper %}
{% step %}

#### Configure the sources for the script inputs

For each of the fields in the Script Inputs section of the Add Action modal, select the source of the field's value from the **Input Source** dropdown menu, and then configure the source with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2F5lOjfDdzH7vv5j7oI4bD%2Ffhir_fhirpatch_inputs.png?alt=media&amp;token=9c23f52c-6425-49d2-bebb-c3c51bbd7999" alt="The script inputs for the FHIR Patch action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

| Field                  | Type     | Description                                                                                       | Required? |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------- | --------- |
| **Access Token**       | `String` | The access token from the FHIR Authenticate action                                                | Yes       |
| **FHIR Base URL**      | `String` | The base URL of the FHIR server from the FHIR Authenticate action                                 | Yes       |
| **Patch Body**         | `String` | The JSON Patch or FHIR Patch string to apply to the FHIR resource.                                | Yes       |
| **Patch Content Type** | `String` | The technical content type of the patch body. The default value is `application/json-patch+json`. | No        |
| **Resource ID**        | `String` | The ID of the FHIR resource to patch.                                                             | Yes       |
| **Resource Type**      | `String` | The type of the FHIR resource to patch in PascalCase, such as `Patient` or `PractitionerRole`.    | Yes       |

{% hint style="info" %}
**Note:** Give the patch body in either the JSON Patch format (RFC 6902) or the FHIR Patch format.
{% endhint %}
{% endstep %}

{% step %}

#### Configure the destinations for the script outputs

For each of the fields in the Script Outputs section of the modal, select the destination of the field's value from the **Output Destination** dropdown menu, and then configure the destination with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FnlH1OFo8uCnkmr9TDKaP%2Ffhir_fhirpatch_outputs.png?alt=media&amp;token=1e64e7c2-f0be-4520-ad99-a3bda25174e4" alt="The script outputs for the FHIR Patch action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

| Field                | Type     | Description                                            | Required? |
| -------------------- | -------- | ------------------------------------------------------ | --------- |
| **HTTP Status Code** | `Number` | The HTTP status code that the patch operation returned | No        |
| **Result**           | `String` | The JSON string of the patched FHIR resource           | No        |
| {% endstep %}        |          |                                                        |           |
| {% endstepper %}     |          |                                                        |           |

***

## What's Next

Continue to [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) to learn how to use <code class="expression">space.vars.automations</code> to keep your FHIR data in <code class="expression">space.vars.Kizen\_company\_name</code> up to date.

<details>

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

* [FHIR - Beta](/docs/integrations-and-plugins/integrations/fhir-beta.md)
* [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)
* [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/read-and-write-fhir-data-in-an-agentic-workflow.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.