Managing Migration IDs and Data During Profile Migration
Managing Migration IDs and Migration Data for Client Profiles
This document explains how to use Migration ID (or external ID) to link client profiles to records in legacy systems, how to populate this field via UI and API, and how to view associated unstructured migration data and search by Migration ID.
Step 1: Open or Create a Client Profile
Open the application and navigate to the client profiles area. You can either open an existing profile or create a new prospect to work with the Migration ID field.
Once the profile screen is open, confirm you are viewing the correct profile record.
If needed, switch to creating a new prospect so you can see where the Migration ID is captured.
Before proceeding further on the existing profile, choose the option to create a new prospect record.
In the new prospect form, scroll to the “Additional Information” section to locate the Migration ID field, which will be used to store the external or legacy system ID.
Step 2: Enter Migration ID Manually in the UI
In the “Additional Information” section, enter the appropriate Migration ID for this prospect or client. This value should correspond to the identifier used in your legacy or external system.
Use this field whenever a record is created manually so that it can be linked back to its external source.
Step 3: Populate Migration ID During Data Migration
During bulk migration, configure your migration process to map and insert the Migration ID into this same field. This ensures that all migrated records are consistently linked to their legacy counterparts.
Step 4: Use the API to Set or Update Migration ID
When creating clients via API, use the Create Client API and pass the Migration ID in the appropriate request field so it is stored against the prospect or client profile.
The Migration ID sent through the API will be recorded against that specific prospect profile.
This guarantees that every programmatic client creation is associated with its external identifier.
You can also update the Migration ID later using the client record PATCH endpoint.
Through this PATCH endpoint, the Migration ID on an existing client record can be replaced or modified as needed, giving flexibility to correct or realign IDs after initial migration.
Although the example shown may not have a Migration ID value, the PATCH capability remains available, allowing you to overwrite or update the Migration ID field via API.
From an API perspective, both POST (create) and PATCH (update) operations support handling the Migration ID, while from the front end you can set it when creating or editing records.
Step 5: Display Unstructured Migration Data for Migrated Records
Once a Migration ID is mapped to a profile, you can also attach unstructured migration information that cannot be stored in structured fields of the current system.
Such unstructured details can be surfaced in the UI as an additional tab for the profile
For records that have both a Migration ID and associated migration comments, an extra “Migration Data” tab will be visible on the profile.
This dedicated tab appears only for migrated records that include migration comments.
When both conditions are met (Migration ID present and migration comments populated), users will see the “Migration Data” tab on the profile screen.
Open the “Migration Data” tab to view any migration-related text or data that has been stored for that profile.
The content in this tab supports Markdown formatting, enabling you to structure and format migration notes, lists, or contextual information that could not be migrated as discrete fields. Typical use cases include capturing legacy notes, partial data that could not be exported, or additional context that simplifies the migration process. This Markdown-supported field allows flexible formatting so information is clearly presented to end users.
Any content stored here will always be shown in the “Migration Data” tab for that profile.
Step 6: Review and Edit Migration Comments on a Profile
Within the selected profile, review the migration comments currently stored. For example, it might show a comment such as “This is migrated data,” but you can store any text that is meaningful for your migration context.
The comment text is entirely configurable and can be tailored to your organization’s needs.
If you need to change either the Migration ID or the migration comments, edit the profile from the UI.
While in edit mode, scroll down to the Migration ID field and copy or adjust the value as required for your records or for testing search behavior.
Step 7: Search Profiles by Migration ID
After copying or confirming the Migration ID, use the application’s omni search feature to locate the profile by pasting or typing the Migration ID into the search bar.
Initiate the search from the omni search interface, ensuring that the query exactly matches the stored Migration ID.
The system will return the profile associated with that Migration ID, and opening the result will bring you back to the same profile, demonstrating that Migration ID is fully searchable.
Updated on: 16/02/2026
Thank you!