> ## Documentation Index
> Fetch the complete documentation index at: https://cobalt-55-abhishek.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync data

> Keep records aligned between your app and your customers' connected apps, with one-way and two-way sync patterns.

A **sync** keeps records in agreement between your app and a customer's connected app, so a change on one side shows up on the other. Build a sync from the same pieces you already use to move data: [actions](/v3/native/move-data/read-write) to read and write, [triggers](/v3/platform/concepts/workflows/triggers/overview) to decide when a sync runs, and [workflows](/v3/platform/concepts/workflows/overview) to orchestrate the steps.

This page covers the sync patterns and when to use each, plus how to choose what starts a sync. It is conceptual. The end-to-end build lives in the [Two-way sync recipe](/v3/native/recipes/two-way-sync).

## How sync works

A sync is a workflow that runs on a [trigger](/v3/platform/concepts/workflows/triggers/overview), reads records from a source, optionally maps them, and writes them to a destination.

* **The source** is where the change originates, either your app or the connected app.
* **The trigger** decides when the sync runs: an event from your app, a webhook from the connected app, or a schedule.
* **The mapping** reshapes records so they fit the destination's fields. See [Data mapping](/v3/native/move-data/data-mapping).
* **The destination** is where the records land, written with a connector [action](/v3/native/move-data/read-write).

<Note>
  A sync built once on the Platform runs across all three Refold products. This page does not re-document workflow building. See [Workflows overview](/v3/platform/concepts/workflows/overview).
</Note>

## Sync patterns

Choose the pattern that matches where changes originate.

| Pattern         | Direction                     | Use when                                                       |
| --------------- | ----------------------------- | -------------------------------------------------------------- |
| **One-way out** | Your app to the connected app | Your app owns the record and the third-party system mirrors it |
| **One-way in**  | The connected app to your app | The third-party system owns the record and your app mirrors it |
| **Two-way**     | Both directions               | Either side can change a record and both must stay current     |

### One-way out

Your app is the source of truth. When a record changes in your app, push it to the customer's connected app.

Start the sync with an [event trigger](/v3/platform/concepts/workflows/triggers/events): your backend fires an event when the record changes, and the workflow writes the change to the connected app with a write action.

### One-way in

The connected app is the source of truth. When a record changes there, pull it into your app.

Start the sync with a [webhook trigger](/v3/platform/concepts/workflows/triggers/webhook) if the app pushes change notifications, or a [schedule trigger](/v3/platform/concepts/workflows/triggers/schedule) if it does not. The workflow reads the changed records and writes them into your app, often through an [API proxy](/v3/native/configure/developer/api-proxies) so the data lands on your own endpoint.

### Two-way

Both sides can change a record. Run both directions: one workflow pushes your changes out, another pulls the connected app's changes in.

<Warning>
  Two-way sync can loop, where a write you make triggers a change notification that writes back to you. Track the last-modified source or a sync marker on each record so a change you just wrote does not bounce back as a new change.
</Warning>

## Choose what starts a sync

The trigger you pick determines how fresh the synced data is and how much load you place on the connected app.

| Trigger                                                           | Starts the sync when                          | Reach for it when                                             |
| ----------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------- |
| **[Event](/v3/platform/concepts/workflows/triggers/events)**      | Your backend fires an event                   | Your app is the source and you control when records change    |
| **[Webhook](/v3/platform/concepts/workflows/triggers/webhook)**   | The connected app sends a change notification | The app supports webhooks and you want near-real-time updates |
| **[Schedule](/v3/platform/concepts/workflows/triggers/schedule)** | A recurring time arrives                      | The app has no webhooks, or batching on a cadence is enough   |

<Tip>
  Prefer a webhook over a schedule when the app supports it. Webhooks sync only what changed, when it changed, instead of re-reading everything on a timer.
</Tip>

For the full list of trigger types and their configuration, see [Triggers overview](/v3/platform/concepts/workflows/triggers/overview).

## Best practices

<Steps>
  <Step title="Pick one source of truth per field">
    Decide which side owns each field before you build. Conflicting owners are the root of most sync bugs.
  </Step>

  <Step title="Sync incrementally">
    Read only records changed since the last run, using a timestamp or cursor, instead of re-reading the whole dataset every time.
  </Step>

  <Step title="Guard against loops in two-way sync">
    Mark records you write so an inbound change notification for your own write is ignored.
  </Step>

  <Step title="Map and validate before you write">
    Reshape and check records on the way to the destination so a bad record does not reach the connected app. See [Data mapping](/v3/native/move-data/data-mapping).
  </Step>
</Steps>

## See also

<CardGroup cols={2}>
  <Card title="Two-way sync recipe" icon="arrows-rotate" href="/v3/native/recipes/two-way-sync">
    Build a bidirectional sync end to end.
  </Card>

  <Card title="Data import recipe" icon="file-import" href="/v3/native/recipes/data-import">
    Bring a customer's existing records in on first connect.
  </Card>

  <Card title="Triggers overview" icon="bolt" href="/v3/platform/concepts/workflows/triggers/overview">
    Every trigger type and how to configure it.
  </Card>

  <Card title="Read and write data" icon="arrow-right-arrow-left" href="/v3/native/move-data/read-write">
    The actions a sync uses to read and write records.
  </Card>
</CardGroup>