> For the complete documentation index, see [llms.txt](https://docs.middle.app/middle-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.middle.app/middle-docs/product/accounts/workflow-steps/create-or-update.md).

# Create or update

Save data from a workflow as a record in Middle

The **Create or Update Record** step writes a record to Middle's storage under an app connection and record type. Use it to standardize data, store calculated summaries, or capture business events for other workflows to use.

For example, one workflow could prepare a standardized member record, while a scheduled workflow exports those prepared records to another system.

This step changes the record stored in Middle. To send that change to an external app, configure a separate action or workflow.

<figure><img src="https://932524191-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mks_UuU2atghAuA9bQz%2Fuploads%2FvYz2bGAxiL3d667sQXf5%2FScreenshot%202026-10-09%20at%2012.54.46%E2%80%AFPM.png?alt=media&amp;token=9c7c9d13-cdd8-4471-903a-d4cc55868c4f" alt=""><figcaption><p>Inserting a record that tracks a change of membership</p></figcaption></figure>

## Before you begin

You'll need an app connection, a record type defined for that app, and the values or expressions that will build the record. The record type must include its fields and primary ID.

The step uses an existing record type. It does not create a new record type or add fields to its definition.

## Add the step

1. Open your workflow in the editor.
2. Click the **+** on the branch where you want to save the record.
3. Open the **Advanced** menu and select **Create or Update Record**.
4. Configure the following fields.

| Field              | Description                                                                                                                                                                |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **App connection** | The connection under which Middle will store the record.                                                                                                                   |
| **Resource**       | The record type to create or update. Available resources belong to the selected connection's app.                                                                          |
| **Record payload** | An object containing the record's field names and values. Build it using workflow parameters, including values from the triggering record, earlier steps, or calculations. |

Include the primary ID and every field defined by the selected resource. Use the field keys from the record type's definition.

**Supply the complete record, including when updating an existing record.** Middle validates and stores the submitted payload; it does not merge a partial set of fields into the existing record.

## How creates and updates work

Middle identifies a record using the combination of app connection, resource, and primary ID.

| Submitted record                                            | Result                                                       |
| ----------------------------------------------------------- | ------------------------------------------------------------ |
| A primary ID with no stored payload                         | Creates the record and records a creation activity.          |
| An existing primary ID with changed data                    | Updates the record and records an update activity.           |
| An existing primary ID with identical data after validation | Leaves the stored data unchanged and reports **No changes**. |

Use a consistent primary ID when maintaining a current value, such as a member summary. Use a distinct primary ID for each event when you want to preserve separate observations. For event records, a repeatable ID based on the source event also helps prevent a rerun from creating another copy of the same event.

## Example

Suppose you have a **Standard member** resource with these fields:

| Field             | Type                           |
| ----------------- | ------------------------------ |
| `member_id`       | Primary ID                     |
| `name`            | String                         |
| `organization_id` | Foreign key to an organization |

Configure the record payload to produce an object like this:

```json
{
  "member_id": "member-1",
  "name": "Ada",
  "organization_id": "organization-1"
}
```

In a working integration, map these values from workflow variables or expressions.

The first run creates `member-1`. If a later run produces the same ID with the name `Ada Lovelace`, Middle updates that record. Running it again with the same values results in **No changes**.

For foreign-key fields, supply the related record's primary ID. That establishes the relationship; it does not populate the related record's data.

### Use the saved record in other workflows

Created and updated records pass through Middle's normal activity-trigger processing. Configure an activity-based trigger on the destination connection and resource to run another workflow when the record is created or changed.

This lets you separate preparation from delivery. For example, one workflow can transform source data and save standardized records. A scheduled workflow can then use a [File Export Step](/middle-docs/product/accounts/workflow-steps/file-export.md) to export those records and an [Action Step](/middle-docs/product/accounts/workflow-steps/action.md) to deliver the file.

An unchanged record does not generate a new creation or update activity.

If a workflow writes to the same resource that triggers it, make sure its trigger conditions and update logic allow the process to stop.

## Inspect and troubleshoot a run

Open the workflow execution and select the **Create or Update Record** step.

The execution details show:

* **Settings:** the selected record type and app connection.
* **Record input:** the evaluated payload used by the step.
* **Stored record:** a link to the record and the associated activity ID, when a change occurred.

For an unchanged record, there is no new activity. Creation and update activities are linked to the workflow execution that produced them.

If the step fails, check that the app connection and resource are selected, the payload evaluates to an object, every defined field is present, the primary ID is not null, and field values match the resource's expected types.

Records, record history, and execution history remain subject to your [data retention settings](https://docs.middle.app/middle-docs/data-deletion).

## Limitations

The step saves one record per execution and does not expose the saved record as a step-output variable.

**Create or Update Record** is not supported in workflows executed through the [Real-time Workflow API](https://docs.middle.app/middle-docs/real-time-workflow-api).

### Related documentation

{% content-ref url="/pages/VwpSQ6iUzDSY7aFIbigv" %}
[Workflow parameters](/middle-docs/product/accounts/workflow-parameters.md)
{% endcontent-ref %}

{% content-ref url="/pages/-MlClKo-Xl6F31yC\_oE4" %}
[Triggers](/middle-docs/product/accounts/workflow-triggers.md)
{% endcontent-ref %}

{% content-ref url="/pages/N5QGzx3Un5oqiY87HwLi" %}
[File export](/middle-docs/product/accounts/workflow-steps/file-export.md)
{% endcontent-ref %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.middle.app/middle-docs/product/accounts/workflow-steps/create-or-update.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.