Making a Passthrough Request

API endpoint

Send POST requests to the URL below with the required body parameters to create a Passthrough Requests.

https://api.merge.dev/api/{CATEGORY}/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.

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. {{USERNAME}}).

Below is the full list of variables available for use in Passthrough Requests:

1
{
2
  "method": "GET",
3
  "path": "/v2/companies/{{API_URL_SUBDOMAIN}}/employees/"
4
}

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.

1
{
2
  "method": "GET",
3
  "path": "/service/customreport2/{{API_URL_SUBDOMAIN}}/100814/Demographic_Report?format=json",
4
  "headers": {
5
    "Authorization": "Basic {BASE-64}{{USERNAME}}:{{PASSWORD}}{BASE-64}"
6
  }
7
}

Fetching with the Merge SDK

See below for an example of how to create an authenticated Passthrough Request with Merge’s SDK:

1
import merge
2
from merge.client import Merge
3
4
5
client = Merge(
6
    api_key="API_KEY",
7
    account_token="ACCOUNT_TOKEN",
8
)
9
10
11
passthrough_result = client.crm.passthrough.create(
12
    request=merge.resources.crm.types.DataPassthroughRequest(
13
        method="GET",
14
        path="/contacts/lists",
15
        request_format="JSON",
16
        base_url_override="https://override.baseurl.com",
17
    )
18
)

Response

The response to your query will look like the following:

1
{
2
  "method": "GET",
3
  "path": "/unique-data",
4
  "status": 200,
5
  "response": {
6
    "id": 23454,
7
    "value": "ABC"
8
  },
9
  "headers": {
10
    ...
11
    "Authorization": "<redacted>"
12
  }
13
}

The Passthrough Request endpoint will return a 408 status if there is a timeout in getting the response. If you have experienced delays or timeouts with normal Passthrough Requests we recommend switching to use Merge’s Async Passthrough requests.