This article will help you understand what the end user origin id is and what to use as your end user origin id!
What is an End User Origin Id?
The end user origin id is a value passed into the generation of a link token during the creation of a linked account. In technical terms, it’s a string that can have any value, as you (a Merge customer) will be the party determining it.
Why does the End User Origin Id matter?
The value is extremely important in a successful integration with Merge as it is the predominant factor in the determination of a unique linked account. The combination of end user origin id and the resultant category selected from the end user’s interaction with Merge Link will determine a unique linked account.
What value should I use as the End User Origin Id for my integration with Merge?
There isn’t a single correct answer, as every Merge customer's use case varies. In general, there are 3 different use cases or best practices that can be utilized. To explain each option, let's say your backend is set up with the below data model, where users within your application are grouped into organizations.
This guide assumes that organization/admin-based authentication is used. Per-user authentication can be used for certain Merge categories like File Storage and Ticketing, but it is not suggested for HRIS, ATS, or Accounting integrations.
Option One: One Linked Account per Category
The first and simplest option is to generate a unique end user origin id per organization, in which the organization and category are the unique identifiers for a linked account. This allows each of your end users to have access to the same linked accounts, sharing data across the account!
This will not work for all use cases, however, as it means an organization can only have a single platform within a category linked at a time. If multiple platforms need to be linked within a single category, say a SCIM integration like Okta and a Directory integration like BambooHR, a different option must be used.
Option Two: One Linked Account per Integration
The second option is to generate a unique end user origin id for every integration within an organization, in which the combination of organization, category, and integration is the unique identifier for a linked account. This builds on top of the first option, allowing your end users to share data across their organization, but also allowing them to link multiple platforms within a single category.
While this will work for the majority of use cases, there are certain instances where you may want to allow your customer to link multiple accounts for a specific integration. Say your customer has two business entities, a US entity, and an EU entity. It is not uncommon that they would split their systems by entity, having separate instances of the same HR or Accounting platform. For these cases, you may need a different option.
Option Three: Multiple Linked Accounts per Integration
The final option is to use a sequence number or name in addition to all other metadata to generate a unique identifier. This will allow your users to link multiple instances of a given platform, handling cases where your customers split their platforms into different instances. Check out this article for additional detail on this approach!
This option is often utilized in tandem with a "segmented" integrations UI within your application. A possible implementation of a "segmented" integrations UI is to separate existing linked accounts into a "Connected Accounts" section, incomplete linked accounts into an "Incomplete Connections" section, and the ability to add a new linked account into a "Connect a New Account" section.
Common Missteps to Avoid
1. Generating a unique end user origin id for every linking session.
This is a common approach to use when testing Merge, but if this is not revisited prior to launch it will result in many duplicate linked accounts! As you are billed by linked accounts, this will not only clutter your Merge Dashboard, but will affect billing too. Choose one of the three options above before going into production to avoid this!
2. Not saving incomplete linked accounts.
When an end user begins to link an account but does not successfully complete the link attempt, an Incomplete account is created. A common pitfall Merge customers run into results from not saving these incomplete attempts. Since the attempt was not saved, a new end user origin id is generated for the next attempt, and your Merge Dashboard starts looking like the above. Save the end user origin id at the start of the Merge linking flow to avoid this!