Passthrough and Async Passthrough guide

Last updated: January 5, 2026

Overview

Passthrough requests allow you to make authenticated requests directly to third-party integration APIs using Merge's stored credentials. Merge acts as an authentication wrapper, handling the authentication layer while you provide the method, endpoint, data, and headers for your request. The response maintains the original format from the third-party API, meaning responses will be non-normalized and specific to each integration. Merge makes it easy to make API requests to any supported integration with the account tokens stored on behalf of your users.

When to use Passthrough Requests

Passthrough requests are ideal when you need to:

  • Access endpoints not covered by Merge's common models - Fetch data from endpoints that Merge doesn't make requests to

  • Interact with custom fields or platform-specific features - Access integration-specific functionality beyond the standardized common models

  • Need real-time data access - Get data without waiting for sync cycles

  • Perform specialized operations - Execute platform-specific operations unique to certain integrations

Important considerations: If you believe Merge already pulls the data you need in its standard queries, you can avoid an additional API request by querying for Remote Data instead of using passthrough.

Passthrough requests are only available to customers on Merge's Professional or Enterprise plans.

Before implementing passthrough, verify that:

  • You have familiarity with the target API's endpoints and documentation

  • You understand that response formats will be non-normalized

To make a passthrough request, send POST requests to /passthrough.

For a full instructional guide on making passthrough requests, please refer to our API developer documentation. There is a 55 second timeout for normal passthrough requests.

Rate limit considerations

Why rate limits occur

Merge applies integration-specific rate limits to all API requests sent to third-party providers. These limits include both Merge syncs and passthrough requests.

Some third-party providers limit the number of simultaneous sync tasks. Sending passthrough requests during an active sync makes hitting rate limits more likely, which can cause your syncs or passthrough requests to fail.

Best practices for rate limits

  1. Avoid passthrough requests during active sync windows to reduce the chance of exceeding rate limits

  2. Use exponential backoff in your retry logic - Start with a 1-minute delay and increase the delay with each retry

  3. Reach out to Merge Support: Please reach out to Merge Support if you continue to hit rate limits despite the measures above.

When to use Async passthrough

An asynchronous passthrough request allows you to retrieve the response at a later time rather than waiting for an immediate response. This was built because third-party response times differ and can cause delays when calling passthrough requests. If you have experienced delays or timeouts with passthrough requests, switch to the async passthrough functionality.

The current passthrough endpoint will return a 408 status if there is a timeout, with an explanation to use async passthrough. The async passthrough system uses a dedicated queue with a global timeout of 5 minutes and an outbound timeout of 10 seconds. Responses are automatically deleted after 24 hours via a job.

To make an async passthrough request, send POST requests to: /async-passthrough.

For a full instructional guide on making asynchronous passthrough requests, please refer to our API developer documentation.

Rate limits exist for the async retrieval endpoint with a threshold of 1 request per 10 seconds.

Responses are stored for 24 hours.

Async passthrough response codes

  • 202 status - Request is still being processed (no response body yet)

  • 200 status - Request completed successfully, response data available

  • 500 status - Task failed to run

  • 404 status - Response not found (deleted after 24 hours)

Note that when writing data with async passthrough, the data parameter containing the request body must be a string data type. It cannot be an object.

  • This is to support and handle three separate request body formats (JSON, XML, MULTIPART)

  • The string allows for efficient storage and retrieval of the async passthrough

Example async request body

{
    "method": "POST",
    "path": "/timetracking/add",
    "data": "{\"timeTracking\":\"value\",\"employeeNumber\":\"identification1\"}",
    "headers": {
        "Content-Type": "application/json"
    }
}

Looking for some examples to get you started? We’ve put together a list of commonly used passthrough examples. You may need to log in to the Help Center using your work email address to view it.

Related documentation: