Skip to main content
Async Passthrough

Details on passthrough vs. asynchronous passthrough requests

Updated over a week ago

This article will help you understand what asynchronous passthrough is as well as how and when to use it!

What is a passthrough request?

A passthrough request is a direct request to an integration's API where Merge handles the authentication using the stored account credentials for the linked account. This approach is ideal for when you're looking to fetch data that Merge may not make requests for or doesn't store in our common models.

What is async (asynchronous) passthrough?

An asynchronous passthrough request is a type of passthrough request that allows you to retrieve the response at a later time. We decided to build asynchronous passthrough because third-party response times differ and can cause delays for you when calling passthrough requests. With async passthrough you won't have to wait for a response before calling other requests or endpoints!

Each category now includes a new endpoint to call async passthrough. The request to this endpoint will be the same as passthrough, however the response will contain a passthrough receipt id (instead of the data payload of a passthrough). This passthrough receipt id can be used to get the actual data payload at a later time - either through polling or webhook.

When should you use async passthrough?

If you have experienced delays or timeouts with passthrough requests we recommend switching to use the new async passthrough functionality. Additionally our current passthrough endpoint will return a 408 status if there is a timeout in getting the response and explanation to use the new async passthrough.

In the async passthrough workflow:

  1. Make a passthrough POST request using new /<category>/v1/async-passthrough endpoint, with the exact same payload as normal passthrough.

  2. Merge will respond with status 200 and a async_passthrough_receipt_id in the response body.

  3. You can either poll using using GET request to /<category>/v1/async-passthrough/<async_passthrough_receipt_id> OR setup a webhook to listen for the request from our server.

    1. The webhook can configured in the same way as existing webhooks in the dashboard.

    2. Polling requests are rate-limited to 1 request per 10 seconds.

  4. Async passthrough will return a response using the same format as passthrough.

  5. We will store the response for 24 hours!


For more information on how to set up webhooks, please refer to our docs page!

Did this answer your question?