Authenticated Passthrough Request
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.

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.
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.
Reference the integration's API documentation to accurately fill out the body parameters for the specific passthrough request you're looking to make.
method
Stringpath
Stringdata
Stringheaders
Object"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_data
MultipartFormField[]MultipartFormField
objects in here instead of using the data
param if request_format
is set to MULTIPART
.MultipartFormField
object is used to represent fields in an HTTP request using multipart/form-data
.{"name": "resume","data": "SW50ZWdyYXRlIGZhc3QKSW50ZWdyYXRlIG9uY2U=","encoding": "BASE64","file_name": "resume.pdf","content_type": "application/pdf"}
name
Stringdata
Stringencoding
Enumdata
. Defaults to RAW
if not defined. Possible values include: RAW
, BASE64
.file_name
Stringcontent_type
Stringrequest_format
EnumJSON
, XML
, MULTIPART
.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:
Variable | Description |
API_URL_SUBDOMAIN | Third-party API URL subdomain. |
API_KEY | Third-party API Key. |
USERNAME | Basic 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.
|
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.
{"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.
{"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.
{"method": "GET","path": "/service/customreport2/{{API_URL_SUBDOMAIN}}/100814/Demographic_Report?format=json","headers": {"Authorization": "Basic {BASE-64}{{USERNAME}}:{{PASSWORD}}{BASE-64}"}}
See below for an example of how to create an authenticated passthrough request with Merge's SDK:
1from __future__ import print_function2import json3import MergeATSClient4from MergeATSClient.api import passthrough_api5from MergeATSClient.model.data_passthrough import DataPassthroughRequest67configuration = 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"})1112try: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)
The response to your query will look like the following:
{"method": "GET","path": "/unique-data","status": 200,"response": {"id": 23454,"value": "ABC"},"headers": {..."Authorization": "<redacted>"}}