Merge — Link

Get Started

Introduction

Get acquainted

Unified API

Pull test data

Linked Account

Create a connection

Link

Add to your frontend

Magic Link

Want to start using Link without writing any code?

View our Magic Link guide to send end users a URL to authorize their integrations!

Add Link to Your Product

Link utilizes a series of token exchanges to securely authenticate your users' integrations.

In this guide, you'll set up the following in your application:

Get a link_token to initialize a Link session for your end user.
Make Link appear in your frontend.
Swap for an account_token, which authenticates future requests to the Unified API.

Step 1

Backend – Get Link Token

In your backend, set up a POST request to initialize a Link session and get alink_token from this URL:

https://api.merge.dev/api/integrations/create-link-token

Pass in your Production Access API key as a header.

POST Request Body

Configure your Link with the following parameters:

Parameter	Type	Description
`end_user_origin_id`	String	Unique ID for your end user.
`end_user_organization_name`	String	Your end user's organization.
`end_user_email_address`	String	Your end user's email address.
`categories`	Array	The integration categories to show in Merge Link. `["hris", "ats", "accounting", "ticketing", "crm", "mktg", "filestorage"]`
`integration`Optional	String	Identifier of third-party platform to skip Link menu for. See Single Integration guide.

API Response

The response will include the following fields:

Parameter	Type	Description
`link_token`	String	Temporary token to initialize your end user's Link.
`integration_name`	String	The name of any previously connected third-party platform (otherwise `null`).

Pass the link_token to your frontend to display Link in step 2.

Backend - Generate Link Token


1import requests
2
3# Replace api_key with your Merge production API Key
4def create_link_token(user, api_key):
5    body = {
6        "end_user_origin_id": user.organization.id, # unique entity ID
7        "end_user_organization_name": user.organization.name,  # your user's organization name
8        "end_user_email_address": user.email_address, # your user's email address
9        "categories": ["hris", "ats", "accounting", "ticketing", "crm"], # choose your category
10    }
11
12    headers = {"Authorization": f"Bearer {api_key}"}
13
14    link_token_url = "https://api.merge.dev/api/integrations/create-link-token"
15    link_token_result = requests.post(link_token_url, data=body, headers=headers)
16    link_token = link_token_result.json().get("link_token")
17
18    return link_token

End User Origin ID

Each end_user_origin_id can have a maximum of one Linked Account per category.

For example, each ID can have up to one HR, Payroll, and Directory, one ATS, one Accounting, one Ticketing, one CRM, one Marketing Automation, and one File Storage integration simultaneously.

If you want to link multiple accounts for the same user, learn more in our help center.

Step 2

Frontend – Make Link Appear

In your frontend, use the link_token from step 1 to open Link.

Display Link

Pass in these parameters:

Parameter	Type	Description
`linkToken`	String	Initializing token from step 1.
`onSuccess`	Function	Callback to handle `public_token`, which is returned when your end user finishes their Link session.
`tenantConfig?`	Object	Optional parameter to specify a tenant. For example, to point to our EU multi-tenant, `apiBaseURL` should be set to `https://api-eu.merge.dev`.

Pass the public_token to your backend to securely swap it for an account_token in step 3.

Frontend - Initiate Link


1import React, { useCallback } from "react";
2// In your React project folder, run:
3// npm install --save @mergeapi/react-merge-link
4import { useMergeLink } from "@mergeapi/react-merge-link";
5
6const App = () => {
7  const onSuccess = useCallback((public_token) => {
8    // Send public_token to server (Step 3)
9  }, []);
10
11  const { open, isReady } = useMergeLink({
12    linkToken: "ADD_GENERATED_LINK_TOKEN", // Replace ADD_GENERATED_LINK_TOKEN with the token retrieved from your backend (Step 1)
13    onSuccess,
14    // tenantConfig: {
15    // apiBaseURL: "https://api-eu.merge.dev" /* OR your specified single tenant API base URL */
16    // },
17  });
18
19  return (
20    <button disabled={!isReady} onClick={open}>
21      Preview linking experience
22    </button>
23  );
24};
25
26export default App;

Step 3

Backend – Swap public token for account token

In your backend, create a request to exchange the short-lived public_token for a permanent account_token.

Important: Securely store this account_token in your database for authenticating future API requests to the Unified API regarding the end user's data.

Backend - Swap for Account Token


1import requests
2
3def retrieve_account_token(public_token, api_key):
4    headers = {"Authorization": f"Bearer {api_key}"}
5
6    account_token_url = "https://api.merge.dev/api/integrations/account-token/{}".format(public_token)
7    account_token_result = requests.get(account_token_url, headers=headers)
8
9    account_token = account_token_result.json().get("account_token")
10    return account_token  # Save this in your database