How to Properly Set UserID from Backend for Lead Association Across Multiple Emails/VisitorIDs

Hello Matomo Community,

I am working on integrating Matomo tracking with my external lead management system and have encountered a challenge with setting the UserID through backend processes.

In our setup, users can become leads multiple times, using different browsers or devices, which results in multiple VisitorIDs and potentially multiple emails associated with the same actual user. Our goal is to merge these various identities to construct a unified user profile within Matomo, providing a comprehensive view of the user’s interactions over time.

Here is the issue: when triggering a lead event from our external system to Matomo, if I include the uid parameter, it seems to override the cid parameter. Conversely, if I omit uid, the event is associated with the cid, but it does not link the cid to the uid.

I am looking to understand the correct approach to ensure that when I send the same uid with different cids, Matomo recognizes that these VisitorIDs are the same and merges the information to build a single user profile.

Could anyone advise on the correct method to set the UserID using a backend-triggered URL that looks something like this?

plaintextCopy code

https://analytics.mysystem.app/matomo.php?idsite=76&rec=1&apiv=1&action_name=Funnel%20-%20Lead&e_c=Funnel&e_a=Lead&e_n=funnelID&cid=VISITOR_ID&_idts=TIMESTAMP&token_auth=YOUR_TOKEN_AUTH&uid=USER_EMAIL

In this structure, how should I include the uid parameter to ensure that the cid is associated with it for subsequent visits?

Any insights or guidance on this would be greatly appreciated.

Thank you in advance for your assistance!