Merge Visitor or Account IDs

Changing the format or values of your Visitor or Account IDs creates new records in Pendo, disconnecting historical data associated with previous IDs. Unless the old IDs and new IDs are merged, it can be difficult or impossible to track a single visitor or account over time. Pendo offers a service to merge old IDs into new ones so all events are mapped to a single ID. The merge process is irreversible and consists of two parts.

• “On-the-fly” mapping: all future events sent to Pendo using an old ID are rewritten to the new ID.
• Historical rewrite: past events (such as clicks and page views) are rewritten so that they’re associated with the new ID instead of the old ID. 

Once this process is complete, only the new ID will appear in Pendo. The old ID will not appear in Pendo because there will be no events associated with it. The merge process requires working with Pendo Support, and can take up to 2 weeks to complete, depending on the number of IDs and events involved.

Important: If the merge request involves over 100,000 IDs or the Pendo subscription has more than 100 billion events, contact your Pendo account representative or the Professional Services Team (services@pendo.io) for custom pricing. 

Other considerations

• Case sensitivity
  • Visitor and Account IDs are case-sensitive. The casing in your mapping CSV must match the actual IDs in Pendo.
  • In the CSV file, the value for kind is also case sensitive and must be exactly visitor or account.
• Only one-to-one or many-to-one merges are supported: You can merge one old ID into one new ID or many old IDs into one new ID.
  • One ID can’t be split into multiple new IDs.
  • IDs can’t be merged to a blank or null value. A blank or null value cannot be merged to an ID.
  • Chained merges ( A -> B and B -> C) aren’t supported.
• Metadata: Web SDK metadata and Segment.io metadata are carried over to the new ID. Salesforce, Hubspot, and custom metadata are not carried over.
• Other record-specific settings (e.g. Exclude List, Hide guides from this visitor) would not be carried over and would have to be manually enabled for the new ID.
• Legacy Feedback is not impacted by ID merging:
  • After the merge, legacy Feedback will show both old and new IDs.
  • If a GDPR request is submitted for either the old or new ID, Pendo will also delete the corresponding ID from Feedback.
• NPS Themes -  Previously detected NPS Themes will not be re-associated with the new IDs after the merge.

Next steps

Follow these steps if you're working with Pendo Support. The Professional Services team may provide alternate instructions.

Step 1. (Optional) Disable automatic guides

Note: This step is only recommended if you’re merging Visitor IDs. If you’re merging Account IDs, skip to the next step.

When you update your Pendo installation with the new Visitor ID format, Pendo treats those users as new visitors. Automatic guides might display again for users who have already seen them. To prevent this, disable automatic guides until the merge is complete. After the merge, the guide history will be associated with the new IDs, and the  automatic guides can safely be re-enabled

Step 2. Update your installation

Update your Pendo installation to pass in the new Visitor or Account ID format before Pendo starts the merge process. This will ensure that any new visitors or accounts created using the old ID format are included in the merge. If you were to update the Pendo installation after the merge process has already begun, some new users could be excluded from the merge and will remain in Pendo with the old ID.

Step 3. Create a CSV file

Create and provide a CSV file with three columns for each ID to be merged. 

• oldId: The original Visitor or Account ID
• newId: The new ID you want to use
• kind: Specify visitor or account

Example:

In this example, two visitors (userAAA and userBBB) are merged into user123, and another visitor userCCC is merged into user456.

If requesting a merge for both Visitor IDs and Account IDs, please put them in separate CSV files.

Step 4. Contact Support and grant temporary subscription access

Submit a Support ticket and enable temporary subscription access.

Step 5. Pendo Support starts the merge process

Pendo Support will validate the CSV file(s) and start the ID merge process. During this process, analytics may be in flux as historical data is rewritten to the new IDs. Expect to see both old and new IDs until the merge process is complete.

Step 6. Post-merge action items

After Pendo Support confirms that the merge is complete, you will need to re-enable any automatic guides that were disabled in Step 1. No other actions are needed.