Merge Docs

Authenticated Passthrough Request

Learn how to create a new authenticated request to the integration API using stored linked account credentials.
This feature is only available to customers on our Core, Professional, or Enterprise plans. View the Merge Plans to learn more.
Overview

Using Merge's authenticated passthrough request, you can make requests directly to an integration's API.

Merge makes it easy to make API requests to any of Merge's supported integrations with the account tokens that you've stored on behalf of your users. These requests are sent directly to the integration's API and follow each integration's specific API formats instead of Merge's unified format. This approach is ideal for when you're looking to fetch data that Merge may not make requests for.

How Authenticated Passthrough Requests Work

If you believe Merge already pulls this data in its standard queries, you can avoid an additional API request to the integration platform by querying for Remote Data instead.


API Endpoint

Send POST requests to the URL below with the required body parameters to create a passthrough request.

https://api.merge.dev/api/{CATEGORY}/v1/passthrough

Replace CATEGORY in the URL with hris, ats, accounting, ticketing, crm, mktg, or filestorage depending on the relevant category you're making an API request to.


Body Parameters

Reference the integration's API documentation to accurately fill out the body parameters for the specific passthrough request you're looking to make.


methodString
Required
The method for the third-party request, such as GET or POST.

pathString
Required
The path for the third-party request, such as /levels.

dataString
Optional
The data for the request body.

headersObject
Optional
The headers to use for the request (Merge will handle the account's authorization headers). "Content-Type" header is required for passthrough. Choose content type corresponding to expected format of receiving server. Example for request_format JSON:
"Content-Type":"application/json"

multipart_form_dataMultipartFormField[]
Optional
Pass an array of MultipartFormField objects in here instead of using the data param if request_format is set to MULTIPART.
The MultipartFormField object
The MultipartFormField object is used to represent fields in an HTTP request using multipart/form-data.
JSON
{
"name": "resume",
"data": "SW50ZWdyYXRlIGZhc3QKSW50ZWdyYXRlIG9uY2U=",
"encoding": "BASE64",
"file_name": "resume.pdf",
"content_type": "application/pdf"
}
Properties

nameString
Required
The name of the form field

dataString
Required
The data for the form field.

encodingEnum
Optional
The encoding of the value of data. Defaults to RAW if not defined. Possible values include: RAW, BASE64.

file_nameString
Optional
The file name of the form field, if the field is for a file.

content_typeString
Optional
The MIME type of the file, if the field is for a file.

request_formatEnum
Optional
Use one of the following choices: JSON, XML, MULTIPART.

Accessing Linked Account Credentials

Some third-party APIs require you to include credentials directly in the path or request body (data) when making passthrough requests to the third-party API on behalf of a linked account. You can securely access a linked account's stored credentials programmatically by including variables in double brackets (e.g. {{API_KEY}}).

Below is the full list of variables available for use in passthrough requests:

VariableDescription
API_URL_SUBDOMAINThird-party API URL subdomain.
API_KEYThird-party API Key.
USERNAMEBasic auth username for third-party API.
PASSWORD

Basic auth password for third-party API.

LINKED_ACCOUNT_ATTR.field_name

If an account-specific credential is needed to make a request to a third-party API, and is not otherwise covered in the other variables, you can access it using this format.

field_name represents the name of the field in the third-party API and should be replaced with that field name when using this in practice.

Example - JazzHR

An example of how these variables are used in practice is with JazzHR's API. The relevant account's API key must be included as a query parameter in the request URL. A passthrough request to JazzHR's API with the relevant linked account's API_KEY included in the path would look like this.

Example request body
JSON
{
"method": "GET",
"path": "/applicants?apikey={{API_KEY}}"
}

Example - Paylocity

This is an example request body that demonstrates how the API_URL_SUBDOMAIN variable can be used for passthrough requests to Paylocity's API.

Example request body
JSON
{
"method": "GET",
"path": "/v2/companies/{{API_URL_SUBDOMAIN}}/employees/"
}

Some third-party APIs require you to encode credentials using Base64 encoding. You can specify what needs to be encoded into Base64 format in your third-party request by wrapping that content between {BASE-64} tags in the passthrough request body.

Example - Workday

This is an example request body that demonstrates how the BASE-64 method can be used for passthrough requests to Workday's API.

Example request body
JSON
{
"method": "GET",
"path": "/service/customreport2/{{API_URL_SUBDOMAIN}}/100814/Demographic_Report?format=json",
"headers": {
"Authorization": "Basic {BASE-64}{{USERNAME}}:{{PASSWORD}}{BASE-64}"
}
}

Fetching with the Merge SDK

See below for an example of how to create an authenticated passthrough request with Merge's SDK:

Passthrough Request via SDK
1from __future__ import print_function
2import json
3import MergeATSClient
4from MergeATSClient.api import passthrough_api
5from MergeATSClient.model.data_passthrough import DataPassthroughRequest
6
7configuration = MergeATSClient.Configuration()
8api_client = MergeATSClient.ApiClient(configuration)
9api_instance = passthrough_api.PassthroughApi(api_client)
10passthrough_object = DataPassthroughRequest(method="POST", path="/unique-data", data={"id": 123, "value": "ABC"}, headers={"EXTRA-HEADER": "header_value"})
11
12try:
13 api_response = api_instance.passthrough_create(x_account_token, passthrough_object)
14 print(api_response)
15except MergeATSClient.ApiException as e:
16 print("Exception when calling passthrough_create: %s" % e)

Response

The response to your query will look like the following:

Sample Response to Passthrough Request
JSON
{
"method": "GET",
"path": "/unique-data",
"status": 200,
"response": {
"id": 23454,
"value": "ABC"
},
"headers": {
...
"Authorization": "<redacted>"
}
}