Management APIIntegrations (Legacy)

Integrations

Integrations connect sources to vendor destinations. Each integration defines which vendor API to deliver events to, the credentials needed, and which consent categories are required.

Integration Object

{
  "id": "int_xyz789",
  "source_id": "src_abc123",
  "type": "ga4",
  "name": "GA4 Production",
  "enabled": true,
  "config": {
    "measurement_id": "G-XXXXXXXXXX",
    "api_secret": "***"
  },
  "consent_categories": ["analytics"],
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-02-20T09:15:00Z"
}
FieldTypeDescription
idstringUnique integration identifier
source_idstringSource this integration belongs to
typestringVendor type (see supported types below)
namestringDisplay name
enabledbooleanWhether events are actively delivered
configobjectVendor-specific configuration (API keys, IDs, etc.)
consent_categoriesstring[]Consent categories required before delivery
created_atstringISO 8601 creation timestamp
updated_atstringISO 8601 last-updated timestamp

Sensitive fields such as API secrets and access tokens are masked in API responses (shown as "***"). The full value is stored encrypted in the database and used by Delivery Workers at delivery time.

Supported Integration Types

TypeVendorAPI
ga4Google Analytics 4Measurement Protocol
meta_capiMeta / FacebookConversions API
google_adsGoogle AdsEnhanced Conversions
tiktokTikTokEvents API
pinterestPinterestConversions API
snapchatSnapchatConversions API
linkedinLinkedInConversions API
the_trade_deskThe Trade DeskReal-Time Conversions
webhookCustom WebhookConfigurable HTTP endpoint
bigqueryGoogle BigQueryStreaming Insert
snowflakeSnowflakeSnowpipe
s3Amazon S3PUT Object
redshiftAmazon RedshiftCOPY

Type-Specific Configuration

Each integration type requires different configuration fields:

ga4 — Google Analytics 4

{
  "measurement_id": "G-XXXXXXXXXX",
  "api_secret": "your_mp_api_secret"
}

meta_capi — Meta Conversions API

{
  "pixel_id": "1234567890",
  "access_token": "EAAxxxxxxxxx..."
}
{
  "customer_id": "123-456-7890",
  "conversion_action_id": "987654321",
  "oauth_credentials": {
    "client_id": "...",
    "client_secret": "...",
    "refresh_token": "..."
  }
}

tiktok — TikTok Events API

{
  "pixel_id": "CXXXXXXXXXX",
  "access_token": "your_tiktok_access_token"
}

pinterest — Pinterest Conversions API

{
  "ad_account_id": "1234567890",
  "access_token": "your_pinterest_token"
}

snapchat — Snapchat Conversions API

{
  "pixel_id": "your-snap-pixel-id",
  "access_token": "your_snapchat_token"
}

linkedin — LinkedIn Conversions API

{
  "account_id": "123456789",
  "access_token": "your_linkedin_token"
}

the_trade_desk — The Trade Desk Real-Time Conversions

{
  "advertiser_id": "your_ttd_advertiser_id",
  "tracking_tag_id": "your_tracking_tag_id",
  "auth_token": "your_ttd_auth_token"
}

webhook — Custom Webhook

{
  "url": "https://api.example.com/events",
  "method": "POST",
  "headers": {
    "X-API-Key": "your_api_key"
  },
  "batch": false,
  "batch_size": 100,
  "batch_interval_ms": 5000
}

bigquery — Google BigQuery

{
  "project_id": "my-gcp-project",
  "dataset_id": "analytics",
  "table_id": "events",
  "service_account_json": "{ ... }"
}

snowflake — Snowflake

{
  "account": "xy12345.us-east-1",
  "database": "ANALYTICS",
  "schema": "PUBLIC",
  "table": "EVENTS",
  "user": "DATAFLY_LOADER",
  "private_key": "..."
}

s3 — Amazon S3

{
  "bucket": "my-analytics-bucket",
  "prefix": "events/",
  "region": "us-east-1",
  "access_key_id": "AKIA...",
  "secret_access_key": "..."
}

redshift — Amazon Redshift

{
  "host": "my-cluster.xxxx.us-east-1.redshift.amazonaws.com",
  "port": 5439,
  "database": "analytics",
  "schema": "public",
  "table": "events",
  "user": "datafly_loader",
  "password": "...",
  "s3_staging_bucket": "my-redshift-staging"
}

List Integrations

GET /v1/admin/integrations

Returns a paginated list of integrations for the current organisation.

Query parameters:

ParameterTypeDefaultDescription
source_idstring—Filter by source ID
typestring—Filter by integration type
cursorstring—Pagination cursor
limitinteger50Items per page (max 100)

Request:

curl -X GET "http://localhost:8084/v1/admin/integrations?source_id=src_abc123" \
  -H "Authorization: Bearer {access_token}"

Response:

{
  "data": [
    {
      "id": "int_xyz789",
      "source_id": "src_abc123",
      "type": "ga4",
      "name": "GA4 Production",
      "enabled": true,
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-02-20T09:15:00Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Required role: viewer or above.

Create Integration

POST /v1/admin/integrations

Create a new integration for a source.

Request:

{
  "source_id": "src_abc123",
  "type": "meta_capi",
  "name": "Meta CAPI - Production",
  "enabled": true,
  "config": {
    "pixel_id": "1234567890",
    "access_token": "EAAxxxxxxxxx..."
  },
  "consent_categories": ["advertising", "marketing"]
}

Response (201 Created):

{
  "id": "int_new456",
  "source_id": "src_abc123",
  "type": "meta_capi",
  "name": "Meta CAPI - Production",
  "enabled": true,
  "config": {
    "pixel_id": "1234567890",
    "access_token": "***"
  },
  "consent_categories": ["advertising", "marketing"],
  "created_at": "2026-02-25T10:00:00Z",
  "updated_at": "2026-02-25T10:00:00Z"
}

Required role: editor or above.

Get Integration

GET /v1/admin/integrations/{id}

Retrieve a single integration by ID.

Request:

curl -X GET http://localhost:8084/v1/admin/integrations/int_xyz789 \
  -H "Authorization: Bearer {access_token}"

Response: Full integration object.

Required role: viewer or above.

Update Integration

PUT /v1/admin/integrations/{id}

Update an existing integration.

Request:

{
  "name": "Meta CAPI - Updated",
  "enabled": false,
  "config": {
    "pixel_id": "1234567890",
    "access_token": "EAAyyyyyyyyyy..."
  },
  "consent_categories": ["advertising"]
}

Response: Updated integration object.

Required role: editor or above.

Delete Integration

DELETE /v1/admin/integrations/{id}

Delete an integration. Events will no longer be delivered to this vendor.

Request:

curl -X DELETE http://localhost:8084/v1/admin/integrations/int_xyz789 \
  -H "Authorization: Bearer {access_token}"

Response: 204 No Content

Required role: admin or above.

⚠️

Deleting an integration stops all event delivery to that vendor. Events already queued in Kafka for this integration’s delivery topic will be discarded. This action is irreversible.

Sources (Legacy)Transformations