The Merge.dev Connection Plugin enables users to sync data from hundreds of third-party integrations directly into Flatfile through the Merge.dev unified API platform. When a user establishes a connection to a service via Merge within the Flatfile UI, the plugin automatically creates a new Flatfile Workbook with a schema that matches the data models for that integration. The plugin performs an initial data sync and allows users to manually trigger full data refreshes at any time.

​
Installation

Install the plugin using npm: 
npm install @flatfile/plugin-connect-via-merge

​
Configuration & Parameters

This plugin is configured through Flatfile Secrets rather than code-based options.

​
Required Secret

​
MERGE_ACCESS_KEY
Secret (String)
required
Your API key from your Merge.dev account. This secret must be created in your Flatfile Space and is used to authenticate with the Merge API for token exchange, schema fetching, and data synchronization.Default Behavior: If the MERGE_ACCESS_KEY secret is not present or invalid, the plugin will fail during workbook creation or data sync, resulting in a failed Flatfile Job with an error message indicating the missing key.

​
Function Signature

The plugin exports a single function: 
mergePlugin(): (listener: FlatfileListener) => void
Parameters: None Returns: A function that registers job handlers with the Flatfile listener for:
  • space:createConnectedWorkbook: Creates workbooks based on Merge schemas
  • workbook:syncConnectedWorkbook: Syncs data from connected services

​
Usage Examples

import { FlatfileListener } from "@flatfile/listener";
import { mergePlugin } from "@flatfile/plugin-connect-via-merge";

export default function (listener) {
  // Add the Merge.dev plugin to the listener
  listener.use(mergePlugin());
}

​
Complete Setup Example

import { FlatfileListener } from "@flatfile/listener";
import { mergePlugin } from "@flatfile/plugin-connect-via-merge";

export default function (listener) {
  // Register the Merge.dev plugin handlers
  listener.use(mergePlugin());

  // Add other listeners as needed
  listener.on('**', (event) => {
    console.log(`Event received: ${event.topic}`);
  });
}

​
Configuration Setup

  1. Create the Secret: In your Flatfile Space settings, create a new Secret with the name MERGE_ACCESS_KEY and your Merge.dev API key as the value.
  2. Use the Plugin: The plugin automatically looks for the MERGE_ACCESS_KEY secret in the Space where it’s running. 
import { FlatfileListener } from "@flatfile/listener";
import { mergePlugin } from "@flatfile/plugin-connect-via-merge";

export default function (listener) {
  // The plugin automatically uses the 'MERGE_ACCESS_KEY' secret
  listener.use(mergePlugin());
}

​
Troubleshooting

​
Missing API Key Error

If you encounter errors related to missing Merge API keys, ensure that:
  1. The MERGE_ACCESS_KEY secret is properly set in your Flatfile Space
  2. The API key value is correct and active in your Merge.dev account

​
Sync Timeout Issues

If sync operations timeout, the plugin polls Merge.dev for up to 5 minutes (30 attempts at 10-second intervals). If Merge doesn’t complete its sync within this window, the job will fail with a timeout error.

​
Job Failures

Check the Flatfile Job logs in your dashboard for specific error messages. The plugin provides descriptive error messages for common issues like missing credentials or API failures.

​
Notes

​
Prerequisites

  • The connections feature flag must be enabled for your Flatfile account (contact support@flatfile.com)
  • Active Merge.dev account required
  • MERGE_ACCESS_KEY secret must be configured in your Flatfile Space

​
Alpha Release Warning

This plugin is an alpha release. Functionality and APIs may change in future versions.

​
Data Sync Behavior

  • Each sync performs a full refresh of data
  • All existing records are deleted before inserting current data
  • Manual changes made in Flatfile will be overwritten on next sync
  • This ensures data consistency with the source system

​
Automatic Secret Management

The plugin automatically creates workbook-specific secrets named <workbookId>:MERGE_X_ACCOUNT_TOKEN to store account tokens for each connection. These are managed internally by the plugin.

​
Error Handling Pattern

The plugin uses centralized error handling that:
  • Logs original errors to the console for debugging
  • Throws user-friendly error messages displayed in the Flatfile UI
  • Causes failed jobs to show descriptive error messages in the dashboard

​
Manual Sync Actions

After initial setup, the plugin automatically adds a “Sync” action to connected workbooks. Users can trigger this action from the Flatfile UI to refresh data without additional code.