> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/setup-and-monitor/migrate/migrate-from-another-cdp.md).

# Migrate from another CDP

Sequence the platform's own capabilities to move from an existing CDP without losing history.

## Your goal

Move from an existing customer data platform to mediarithmics, keeping the history that matters and without a gap in collection.

## Expected outcome

A datamart holding your migrated history, live collection running in parallel with your current system, and a decision point where you can switch over with evidence.

{% hint style="info" %}
Migrations differ enough that this page does not prescribe a project plan. What it does is put the platform's capabilities in the order a migration needs them, with the constraint that matters at each step. Your account manager can help shape the plan itself.
{% endhint %}

## The constraints that shape the order

Four platform behaviours decide the sequence, and all four are hard to undo:

| Constraint                                                                | Consequence for a migration                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cleaning rules are computed at write time and are not retroactive**     | Decide retention **before** loading history, or your imported data carries the wrong expiry. See [Data retention](/setup-and-monitor/plan-and-integrate/set-up-the-environment/manage-data-retention.md).                                                             |
| **Adding an indexed property only covers data arriving afterwards**       | Publish the schema **before** importing, or your imported history is stored but not queryable. See [Schema definition](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/schema-definition.md#what-happens-when-you-change-a-schema). |
| **Identifiers route and join data; unknown registries are dropped**       | Create compartments and registries **before** the first import. See [User identity](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity.md).                                                                              |
| **A privacy wall enforced before choices exist drops data irrecoverably** | Load consent **before** enforcing. See [Import user consent](/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch/import-user-consent.md).                                                                                                            |

## The sequence

{% stepper %}
{% step %}

### Frame the target, not a copy of the source

A migration is the one moment when you can drop what you no longer use. Work through the decisions in [Frame your CDP project](/setup-and-monitor/plan-and-integrate/frame-your-cdp-project.md) against your **use cases**, not against your current system's field list.

Inventory, from the source system: which identifiers exist, which events and profile fields feed a live use case, how much history each one needs, and which consent records you hold.
{% endstep %}

{% step %}

### Prepare the environment

Organisation and datamart, then one channel per property, one compartment per registration system, and a registry per device or network identifier you will send.

[Set up the environment](/setup-and-monitor/plan-and-integrate/set-up-the-environment.md)

{% hint style="warning" %}
Map your source system's identifier namespaces onto compartments deliberately. Two source systems merged into one compartment can no longer be told apart afterwards.
{% endhint %}
{% endstep %}

{% step %}

### Design and publish the schema

Declare the objects and properties your use cases need, and index the ones you will filter on - **before** any import.

[Design your data model & schema](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema.md)
{% endstep %}

{% step %}

### Decide retention, and create the cleaning rules

Both to satisfy your policy and because the expiry of imported data is stamped as it is written.

[Cleaning rules](/setup-and-monitor/collect-and-manage-your-data/clean-and-delete-data/cleaning-rules.md)
{% endstep %}

{% step %}

### Start live collection early, in parallel

Tag your sites and apps and connect your server-side sources while the old system still runs. Collecting in parallel gives you two things: a period you can compare across both systems, and no gap when you switch.

[Collect data in real time](/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time.md)

{% hint style="danger" %}
Activities imported in bulk **do not** pass through the processing pipeline by default - no event rules, no activity analyzers, no conversion detection, no automation triggers. Either format imported history exactly as you want it stored, or set `use_processing_pipeline` on the document import. See [Import activities](/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch/import-activities.md).
{% endhint %}
{% endstep %}

{% step %}

### Load the history

In an order that makes each load resolvable:

1. **Profiles**, so accounts and compartments exist. See [Import profiles](/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch/import-profiles.md).
2. **Identifier associations**, so the users you are about to attach activities to are already consolidated. See [Enrich users with identifiers](/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch/enrich-users-with-identifiers.md).
3. **Activities**, the volume load. See [Import activities](/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch/import-activities.md).
4. **Segment memberships**, where a list has to be preserved rather than recomputed. See [Import segments](/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch/import-segments.md).

Set a deliberate **unique key** convention on imported activities so a re-run corrects rather than duplicates. See [the activity unique key](/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time.md#the-activity-unique-key).

If your source data lives in a cloud warehouse, a [warehouse sync](/setup-and-monitor/collect-and-manage-your-data/sync-with-your-data-warehouse.md) may be a better route than files - it also handles updates and deletes once a working schema exists.
{% endstep %}

{% step %}

### Load consent, then enforce

Migrate the choices you already hold, verify them, and only then attach processing activities to channels, compartments, and segments.

[Import user consent](/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch/import-user-consent.md) and [Manage consent & Processing activities](/setup-and-monitor/ensure-privacy-and-compliance/manage-consent-and-processing-activities.md)
{% endstep %}

{% step %}

### Rebuild the use cases

Segments, feeds, and dashboards. This is where the parallel period pays: rebuild a segment and compare its population with the equivalent in your current system before you activate it.
{% endstep %}

{% step %}

### Reconcile, then switch

Compare the two systems on the parallel period, using the checks below. Switch when the numbers agree, or when you understand why they do not.
{% endstep %}
{% endstepper %}

## Reconciling the two systems

| Check                            | How                                                                                                                                                                                                                                                                              |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Did everything arrive?**       | Import execution results: `total_success`, `total_failure`, and the error file. See [reading the result](/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch.md#reading-the-result).                                                                            |
| **Is it indexed?**               | [Monitor collection volume](/setup-and-monitor/operate-and-monitor/monitor-collection-volume.md) - a collection with no volume is missing from the schema.                                                                                                                       |
| **Is live collection healthy?**  | [Monitor data ingestion](/setup-and-monitor/operate-and-monitor/monitor-data-ingestion.md), step by step.                                                                                                                                                                        |
| **Is the user count plausible?** | UserPoint volume against your known customer base. A much higher number means identifiers are being minted rather than matched. See [Resolve identities](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/resolve-identities.md). |
| **Does one user look right?**    | [Explore a user profile](/setup-and-monitor/operate-and-monitor/explore-a-user-profile.md) - read the raw activities of a customer you know.                                                                                                                                     |
| **Do the segments agree?**       | Rebuild a segment and compare its population with the source system's, at **full precision**. See [Query Tool](/setup-and-monitor/operate-and-monitor/query-your-datamart/query-tool.md).                                                                                        |

## Mistakes worth avoiding

{% hint style="warning" %}

* **Importing before publishing the schema** - the data is stored, and not queryable. Reindexing has to be requested.
* **Reproducing the old model field for field** - you inherit years of unused fields, each costing index size and adding noise to the segment builder.
* **Enforcing privacy walls at the same time as loading history** - you cannot tell rejected data from absent data.
* **Loading activities before consolidating identities** - history lands on UserPoints that later merge, which works, but makes reconciliation much harder to read.
* **No unique key on imported activities** - a re-run duplicates instead of correcting.
* **Switching without a parallel period** - you lose the only reference you had for verifying the new system.
  {% endhint %}

## If you are consolidating several entities rather than replacing one system

That is a different shape: several organisations feeding a parent. See [Cross-CDP](/setup-and-monitor/plan-and-integrate/set-up-advanced-features/cross-cdp.md).

## Related pages

<table data-view="cards" data-search="false"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Frame your CDP project</strong></td><td>The decisions a migration has to take too.</td><td><a href="/setup-and-monitor/plan-and-integrate/frame-your-cdp-project.md">Frame your CDP project</a></td></tr><tr><td><strong>Import data in batch</strong></td><td>The mechanism for loading history.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch.md">Import data in batch</a></td></tr><tr><td><strong>Data planning and quality</strong></td><td>The silent failures to watch for.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/data-planning-and-quality.md">Data planning and quality</a></td></tr></tbody></table>


---

# 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.mediarithmics.io/setup-and-monitor/migrate/migrate-from-another-cdp.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.