Making a Passthrough Request

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.

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. In cases where there is no clear mapping, the original value passed through will be returned.

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

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. `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 - 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.

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.

Fetching with the Merge SDK

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

Response

The response to your query will look like the following:

The passthrough 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.

Overview