Skip to main content

​
Embedded Integrations

Embedded Integrations let you create and provision data integrations for your customers directly inside your product. You can host the integration setup experience within your own UI and use the Matia API to create, configure, and manage integrations programmatically.
Terminology
In the Matia API, integrations are referred to as Connections. In this documentation, we use Integration to describe the customer-facing concept.
Matia Embedded

​
How Embedded Integrations Work

  1. Your backend creates an integration draft using the Matia API.
  2. Matia returns a secure, one-time URL for the embedded setup flow.
  3. You embed or redirect users to this URL inside your application.
  4. Users authenticate and configure the source.
  5. After completion, users are redirected back to your application and the integration is ready to run on Matia.

​
Creating an Embedded Integration

​
Authentication

All requests to the Matia API must be authenticated using an API key.
API keys are generated and managed in the Matia dashboard and should be securely stored on your backend. Never expose API keys in client-side code.

​
Endpoint

Create an embedded integration by calling the POST /v1/connections endpoint. This creates an integration draft and returns a URL that launches the embedded setup experience. 
POST https://api.matia.io/v1/connections

​
Required Request Fields

​
Destination Configuration

The destination must already exist in Matia before creating an embedded integration.
FieldTypeDescription
destinationIdstringID of an existing destination in Matia. The destination must be created in advance.
destinationSchemastringName of the destination schema. Must be unique (scope to be clarified).

​
Source Configuration (sourceConfig)

FieldTypeRequiredDescription
typestringYesIdentifier of the source type (for example, shopify).
namestringYesHuman-readable name for the integration.
ownersarray<string>NoList of user IDs associated with the integration. Can currently be empty.
descriptionstringNoOptional description of the integration.

​
Embedded UI Configuration (connectCardConfig)

FieldTypeRequiredDescription
redirectUristringYesURL the user is redirected to after completing the embedded setup flow.
hideSetupGuidebooleanNoIf true, hides the setup guide in the embedded UI. Defaults to false.

​
Minimal Example Request

{
  "destinationId": "12345",
  "destinationSchema": "some_schema",
  "sourceConfig": {
    "type": "shopify",
    "name": "Shopify Embedded",
    "owners": ["frontegg-id"]
  },
  "connectCardConfig": {
    "redirectUri": "https://app.matia.io/",
    "hideSetupGuide": false
  }
}
Default Behavior When creating a new embedded integration, all available streams are enabled by default. You can see the integration schema on Matia or by using the Get integration source schema API Endpoint

​
Optional Configuration

The following fields are optional when creating an embedded integration. Use them to control replication behavior and schema change handling.

​
Replication Frequency (replicationFrequency)

Controls how often data is replicated from the source to the destination. Type: string Default: manual Supported values:
  • manual
  • 5, 10, 15, 30, 60, 120, 180, 360, 480, 720
  • 1440, 4320, 10080, 43200
  • DBT
  • cron

​
Base Time (baseTime)

Specifies the starting timestamp for initial data replication. Type: string (ISO 8601 timestamp) Example: 
"baseTime": "2025-11-26T09:46:01.246Z"
If omitted, Matia determines the default replication start point based on the source type.

​
Schema Change Handling (onSchemaUpdate)

Controls how Matia responds when schema changes are detected in the source. Schema changes can include new streams, new or removed columns, or namespace-level changes, depending on the source. Type: string Supported Values
ValueDescription
enableAllAutomatically enable all newly discovered streams and schema changes.
enableColumnChangesAutomatically enable column-level schema changes, but not new streams or namespaces.
enableNamespaceChangesAutomatically enable namespace-level changes (for example, new schemas or datasets).
ignoreAllIgnore all detected schema changes and take no action.
pauseConnectionPause the integration when a schema change is detected, requiring manual intervention.

​
Next Steps

  • Embed the returned setup URL in your application
  • Handle the redirect to confirm that setup completed successfully
  • Use the Connections API to monitor status and trigger syncs