Embedded RETL (Reverse ETL)

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

What is Embedded RETL?

Embedded RETL is the destination-side variant of Matia Embedded: your customer connects their own destination (HubSpot, Salesforce, Facebook Ads, etc.) directly inside your product, while the source (typically your warehouse) is one you already manage in Matia.

Creating an Embedded RETL Integration

Endpoint

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

This creates an integration draft and returns the URL that launches the embedded setup experience.

Required Fields

Source configuration - the source must already exist in Matia before you create an embedded integration.

Field	Type	Description
`sourceId`	string	ID of an existing source in Matia

Destination configuration (destinationConfig)

Field	Type	Description
`type`	string	Destination type identifier, no suffix, e.g. `hubspot`, `salesforce`, `facebook_ads`
`name`	string	Human-readable name for the integration
`owners` (optional)	`array<string>`	User IDs associated with the integration
`description` (optional)	string	Optional description

Integration configuration

Field	Type	Description
`sql`	string	The model query used in the RETL integration
`destinationObject`	string	The object records will be stored in at the destination (case sensitive)
`syncMode`	string	`Mirror` or `Upsert`

Embedded UI configuration (connectCardConfig)

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

Optional Fields

Field	Type	Description
`replicationFrequency`	string	`manual` (default), a minute interval (`5`,`10`,`15`,`30`,`60`,`120`,`180`,`360`,`480`,`720`,`1440`,`4320`,`10080`,`43200`), `cron`, or `dbt`
`baseTime`	string (ISO 8601)	Starting timestamp for initial replication
`primaryKey`	string	Primary key of the source table (case sensitive). Optional in the API, but mandatory for destinations that require one (e.g. HubSpot, some Salesforce objects)
`enabled`	boolean	Enabled (`true`) or disabled (`false`) on creation
`tags`	`array<string>`	Tag IDs to associate with the integration and asset. Must be Mongo IDs.

What's Specific to RETL

No validation on sql. A malformed query can still return a valid API response - the problem only surfaces when the integration is opened in Matia.
There's no schema tab. Unlike ETL integrations, Reverse ETL integrations don't have enabled tables/columns to review - instead, review the field mappings and primary key assignment after setup.
Matia auto-maps fields by naming similarity, and auto-mapping can return zero results for a field, which can silently cause sync failures. Don't assume auto-mapping is complete.
destinationObject and primaryKey are case sensitive.
Facebook Ads needs an extra step: set type to facebook_ads and destinationObject to custom_audience. The customer will also pick an ad account and (once selected) a custom audience during the embedded setup flow.

Examples

Minimal example (HubSpot)

{
  "sourceId": "12345",
  "sql": "select * from schema",
  "destinationObject": "Contact",
  "syncMode": "Upsert",
  "destinationConfig": {
    "type": "hubspot",
    "name": "hubspot RETL Embedded",
    "owners": ["owner-id"]
  },
  "connectCardConfig": {
    "redirectUri": "https://app.yourproduct.com/integrations/callback",
    "hideSetupGuide": false
  }
}

With a primary key

{
  "sourceId": "12345",
  "sql": "select * from table",
  "destinationObject": "Contact",
  "syncMode": "Upsert",
  "primaryKey": "EMAIL",
  "destinationConfig": {
    "type": "hubspot",
    "name": "hubspot RETL Embedded",
    "owners": ["owner-id"]
  },
  "connectCardConfig": {
    "redirectUri": "https://app.yourproduct.com/integrations/callback",
    "hideSetupGuide": false
  }
}