Embedded ETL

General concept, flow, and shared considerations live in Matia Embedded. This doc covers what's specific to embedding source connections.

What is Embedded ETL?

Embedded ETL is the source-side flavor of Matia Embedded: your customer connects their own data source (Salesforce, Postgres, Shopify, Stripe, etc.) directly inside your product, while the destination (typically your warehouse) is one you already manage in Matia.

Creating an Embedded ETL Integration

Endpoint

POST https://api.matia.io/v1/connections/etl

Required Fields

Destination configuration - the destination (typically your warehouse) must already exist in Matia.

Field	Type	Description
`destinationId`	string	ID of an existing destination in Matia

Source configuration (sourceConfig)

Field	Type	Description
`type`	string	Connector identifier for the source your customer is connecting, e.g. `salesforce`, `postgres`, `shopify`
`name`	string	Human-readable name for the integration
`description` (optional)	string	Optional description
`owners` (optional)	`array<string>`	User IDs associated with the integration

Note what's not here: unlike a standard (non-embedded) POST /v1/integrations call, you don't pass source credentials (connection details like username/password/hostname) up front. In the embedded flow, the customer supplies those themselves inside the connector card.

Embedded UI configuration (connectCardConfig)

Field	Type	Description
`redirectUri`	string	Where the user lands after finishing the embedded setup flow
`hideSetupGuide` (optional)	boolean	`true` hides the in-flow setup guide. Defaults to `false`

Optional Fields

Field	Type	Description
`destinationSchema`	string	Schema/namespace at the destination where the source's data will land
`replicationFrequency`	string	e.g. `1440` (minutes), or other supported interval/cron values - same value set as standard ETL integrations
`baseTime`	string (ISO 8601)	Starting timestamp for initial replication
`onSchemaUpdate`	string	How to handle newly detected schema/tables, e.g. `enableAll`
`enabled`	boolean	Enabled or disabled on creation
`syncImmediately`	boolean	Whether to kick off a sync as soon as setup completes
`tags`	`array<string>`	Tag IDs (Mongo IDs) to associate with the integration

What's Specific to ETL

There's a schema to review. Unlike Reverse ETL integrations (which have no Schema tab), an ETL integration has enabled tables/columns and sync modes per table. After the customer finishes setup, check what onSchemaUpdate actually enabled - don't assume every stream is one you want on by default.

Example

{
  "destinationId": "651bf61c8b46dd602fc383fd",
  "destinationSchema": "snowflake_salesforce",
  "replicationFrequency": "1440",
  "baseTime": "2025-04-09T17:40:58.783Z",
  "onSchemaUpdate": "enableAll",
  "enabled": true,
  "syncImmediately": false,

  "sourceConfig": {
    "type": "salesforce",
    "name": "snowflake_salesforce_etl_embedded",
    "description": "",
    "owners": ["owner-id"]
  },
  "connectCardConfig": {
    "redirectUri": "https://app.yourproduct.com/integrations/callback",
    "hideSetupGuide": false
  }
}

This creates the connector card and, once the customer authenticates through it, an ETL integration ready to sync - with the same observability and platform features as any other Matia pipeline.