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 to read and write, triggers to decide when a sync runs, and workflows 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.

How sync works

A sync is a workflow that runs on a trigger, 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.
• The destination is where the records land, written with a connector action.

A sync built once on the Platform runs across all three Refold products. This page does not re-document workflow building. See Workflows overview.

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: 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 if the app pushes change notifications, or a schedule trigger if it does not. The workflow reads the changed records and writes them into your app, often through an API proxy 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.

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.

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	Your backend fires an event	Your app is the source and you control when records change
Webhook	The connected app sends a change notification	The app supports webhooks and you want near-real-time updates
Schedule	A recurring time arrives	The app has no webhooks, or batching on a cadence is enough

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.

For the full list of trigger types and their configuration, see Triggers overview.

Best practices

1. 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.

2. Sync incrementally

   Read only records changed since the last run, using a timestamp or cursor, instead of re-reading the whole dataset every time.

3. Guard against loops in two-way sync

   Mark records you write so an inbound change notification for your own write is ignored.

4. 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.

See also

Two-way sync recipe

Build a bidirectional sync end to end.

Data import recipe

Bring a customer’s existing records in on first connect.

Triggers overview

Every trigger type and how to configure it.

Read and write data

The actions a sync uses to read and write records.