How Data Flows Through Oneprofile

This article explains what happens behind the scenes when Oneprofile syncs data between a source and a destination from the moment a sync run starts to when it completes.

The Big Picture

At a high level, every sync run follows the same three-phase process:

1. Import: Oneprofile reads records from the source.

2. Match and Map: Oneprofile matches source records to destination records using primary keys, then applies your field mappings.

3. Export: Oneprofile writes the mapped data to the destination, creating, updating, or removing records based on the sync behavior you configured.

Let's walk through each phase.

Phase 1: Import from Source

When a sync run starts, Oneprofile connects to your source integration and reads records of the configured record type.

For example, if your sync pulls "contacts" from Intercom, Oneprofile will fetch all contact records along with their properties (both builtin and custom fields).

The number of records read is reported as Profiles Imported in the sync run stats.

Phase 2: Match and Map

Once Oneprofile has the source records, it needs to figure out what to do with each one in the destination. This happens in two steps:

Record Matching via Primary Keys

Oneprofile uses primary keys to match source records to destination records. When you configure a sync, you select a primary key on each side, for example, email on the source and email on the destination.

For each source record, Oneprofile checks whether a record with the same primary key value already exists in the destination. The result of this check determines what happens next, based on your sync behavior:

Sync Behavior	Record exists in destination	Record does NOT exist in destination
Update or Create	Update the existing record	Create a new record
Update Only	Update the existing record	Skip, do nothing
Create Only	Skip, do nothing	Create a new record
Mirror	Update to match source	Create a new record (and remove destination records not in source)

Field Mapping

For each record that will be created or updated, Oneprofile applies your field mappings to translate source fields into destination fields.

For example, if you've mapped:

Source Field	Destination Field
`first_name`	`name`
`signup_date`	`created_at`
`plan`	`pricing_tier`

Then a source record like:

first_name: "Jane"
signup_date: "2025-03-15"
plan: "team"

Would be written to the destination as:

name: "Jane"
created_at: "2025-03-15"
pricing_tier: "team"

Only mapped fields are synced. Any source field that isn't included in your field mappings is ignored. It won't overwrite or clear data in the destination.

Phase 3: Export to Destination

After matching and mapping, Oneprofile writes the results to the destination. Depending on the destination integration, this might happen as individual API calls or in bulk batches for performance.

During the export phase, Oneprofile tracks:

Profiles Exported: the total number of records written to the destination.
New: how many of those were newly created records.
Updated: how many were updates to existing records.
Errors: how many records failed. Errors can happen for various reasons such as rate limiting from the destination's API, invalid field values, permission issues, or network problems.

If a record fails, Oneprofile logs the error but continues processing the remaining records. One failed record does not stop the entire sync run.

Sync Run Lifecycle

Every sync run goes through a series of states:

1. Pending: The run has been created and is waiting to start. This happens when a schedule triggers a run or when you click "Run" manually.

2. Running: Oneprofile is actively importing from the source and exporting to the destination.

3. Completed: The run finished successfully. Check the stats to see how many records were imported, exported, created, updated, and how many (if any) had errors.

4. Failed: The run could not complete. This typically means a critical issue occurred, such as the source or destination credentials being invalid, or a connection failure that couldn't be recovered.

A "completed" run may still have individual record errors. "Completed" means the run itself finished, not that every single record succeeded. Always check the error count in the run stats.

A Real-World Example

Here's a concrete example of a full data flow:

Scenario: You want to keep your Mailchimp audience in sync with your Stripe customers.

1. Source: Stripe (record type: customers)

2. Destination: Mailchimp (record type: contacts)

3. Sync behavior: Update or Create

4. Primary key: email on both sides

5. Field mappings:

Stripe Field	Mailchimp Field
`email`	`email_address`
`name`	`full_name`
`created`	`signup_date`

6. Schedule: Every 6 hours

Every 6 hours, Oneprofile will:

Read all customers from Stripe.
For each customer, check if a contact with the same email exists in Mailchimp.
If it exists, update the contact's full_name and signup_date fields.
If it doesn't exist, create a new Mailchimp contact with those fields.
Report the results in a sync run: how many were imported, exported, created, updated, and if any failed.

What Oneprofile Does NOT Do

To set the right expectations, here are a few things to keep in mind:

Oneprofile does not store a copy of your data. It reads from the source and writes to the destination in real time during a sync run. There is no intermediate data warehouse or persistent data store.
Oneprofile does not transform data. Field mapping renames and routes fields, but it does not modify values (e.g., it won't connect first and last name into a full name, or convert currencies).
Syncs are one-directional. A sync moves data from one source to one destination. If you need bidirectional sync, you would create two separate syncs going in opposite directions.
Unmapped fields are ignored, not deleted. If a destination record has fields that aren't part of your field mapping, those fields are left untouched. Oneprofile only writes to the fields you've explicitly mapped.