Integration Templates & Revisions

Integration templates are org-level reusable integration definitions. Each template can have multiple immutable revisions, allowing you to version configuration changes over time while maintaining a full audit trail.

Architecture

Integration Template (org-level, reusable)
  └── Revision v1 (immutable config snapshot)
  └── Revision v2 (immutable config snapshot)
  └── Revision v3 (immutable config snapshot)

Pipeline A → uses Template at Revision v3
Pipeline B → uses Template at Revision v2

Templates can be created manually or installed from the Integration Catalog. Once created, templates are assigned to pipelines via Pipeline Integrations.

Integration Template Object

{
  "id": "tmpl_abc123",
  "org_id": "org_xyz",
  "name": "Meta CAPI Production",
  "vendor": "meta_capi",
  "description": "Meta CAPI for our e-commerce properties",
  "catalog_vendor_key": "meta_capi",
  "catalog_variant_key": "retail",
  "created_at": "2026-02-20T10:00:00Z",
  "updated_at": "2026-02-25T14:30:00Z"
}

Integration Revision Object

{
  "id": "rev_xyz789",
  "integration_id": "tmpl_abc123",
  "org_id": "org_xyz",
  "revision_number": 3,
  "config": {
    "pixel_id": "1234567890",
    "access_token": "EAABsb...",
    "batch_size": 100,
    "hash_pii": true
  },
  "delivery_mode": "server_side",
  "change_summary": "Updated access token for Q1 2026",
  "created_by": "user_123",
  "created_at": "2026-02-25T14:30:00Z"
}

Using Pipeline Parameters in Revision Config

Revision config values can reference pipeline parameters using the {{pipeline_param.KEY}} syntax. This allows a single integration revision to be shared across multiple pipelines, with each pipeline providing its own values for credentials and IDs.

For example, a GA4 revision config with parameter references:

{
  "config": {
    "measurement_id": "{{pipeline_param.ga4_measurement_id}}",
    "api_secret": "{{pipeline_param.ga4_api_secret}}",
    "debug_mode": false
  },
  "delivery_mode": "server_side",
  "change_summary": "GA4 config with pipeline parameter references"
}

When this revision is assigned to a pipeline, the event processor substitutes {{pipeline_param.ga4_measurement_id}} and {{pipeline_param.ga4_api_secret}} with the values defined in that pipeline’s parameters object. Static values like debug_mode are used as-is.

Reading Connection Values from the Blueprint

A blueprint mapping can read one of the integration’s own connection values with a config.<key> source, where <key> is a field of the integration’s connection config (after pipeline parameters have been substituted). The same form works as a filter or expression path and as a template placeholder:

{
  "global": {
    "mappings": [
      { "source": "config.mbox_name", "target": "notifications[].mbox.name", "required": true },
      { "target": "conversion", "mode": "template",
        "template": "urn:lla:llaPartnerConversion:{{config.conversion_rule_id}}" }
    ]
  }
}

The value reaches the vendor payload only where a mapping writes it; the connection config itself is never forwarded. A required mapping whose config key is not set drops the event for that integration with a required_missing record, and default_value applies when the key is missing or blank, exactly as for an event field. An event the blueprint does not map at all (no event section, defaults.action drop) is filtered before any global mapping runs, so a required global mapping never turns an event nobody meant to deliver into a required_missing record.

A mapping can carry a condition, a filter expression over the event such as "context.device.os IN ('iOS', 'iPadOS')": it runs only for events the condition holds for, in any section and any mode, and when it does not hold it reads, writes and requires nothing. Two mappings with opposite conditions send one source to different targets, for example the mobile advertising ID as userData.idfa[] on iOS and userData.gpsaid[] on Android.

Connection fields the catalogue types as secret (API keys, access tokens, signing secrets) cannot be read this way: a config.<key> source naming one resolves as missing. Credentials belong in the request’s auth header, endpoint URL or static fields, which the delivery driver resolves. A vendor whose API requires a credential inside the event body can opt a specific key in through its delivery spec.

Static Values and JSON Types

A static mapping’s value is read as JSON when it is a JSON literal, so it reaches the vendor with that type: "true" and "false" are booleans, "42" and "12.5" are numbers, and "null" is an explicit JSON null. Anything else is sent as text.

Use "null" when a vendor requires a field to be present but empty. AppLovin, for example, requires data on every event and data: null on a page view:

{
  "events": {
    "page": {
      "vendor_event_name": "page_view",
      "mappings": [
        { "target": "data", "mode": "static", "value": "null" }
      ]
    }
  }
}

The null is written even when the target is an object the vendor’s payload groups other fields under: the page view is sent with "data": null, and an event that maps fields into data is sent with the object. This applies only to a static value. A template or expression that evaluates to null writes nothing, as a missing source does.

List Integration Templates

GET /v1/admin/integration-templates

Returns a paginated list of integration templates for the current organisation.

Query parameters:

Request:

curl -X GET "http://localhost:8084/v1/admin/integration-templates?limit=20" \
  -H "Authorization: Bearer {access_token}"

Response:

{
  "integrations": [
    {
      "id": "tmpl_abc123",
      "name": "Meta CAPI Production",
      "vendor": "meta_capi",
      "description": "Meta CAPI for our e-commerce properties",
      "catalog_vendor_key": "meta_capi",
      "catalog_variant_key": "retail",
      "created_at": "2026-02-20T10:00:00Z",
      "updated_at": "2026-02-25T14:30:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Required role: viewer or above.

Create Integration Template

POST /v1/admin/integration-templates

Create a new integration template manually (without using the catalog).

Request:

{
  "name": "Custom GA4 Setup",
  "vendor": "ga4",
  "description": "GA4 for internal analytics"
}

Response (201 Created): Full template object.

Required role: editor or above.

Get Integration Template

GET /v1/admin/integration-templates/{id}

Retrieve a single integration template by ID.

Request:

curl -X GET http://localhost:8084/v1/admin/integration-templates/tmpl_abc123 \
  -H "Authorization: Bearer {access_token}"

Response: Full template object.

Required role: viewer or above.

Update Integration Template

PUT /v1/admin/integration-templates/{id}

Update metadata on an integration template. Only name and description can be updated.

Request:

{
  "name": "Meta CAPI - E-commerce",
  "description": "Updated description"
}

Response: Updated template object.

Required role: editor or above.

Delete Integration Template

DELETE /v1/admin/integration-templates/{id}

Soft-delete an integration template.

Request:

curl -X DELETE http://localhost:8084/v1/admin/integration-templates/tmpl_abc123 \
  -H "Authorization: Bearer {access_token}"

Response:

{
  "status": "deleted"
}

Required role: admin or above.

Revisions

List Revisions

GET /v1/admin/integration-templates/{id}/revisions

Returns all revisions for an integration template, ordered by revision number descending (newest first).

Request:

curl -X GET http://localhost:8084/v1/admin/integration-templates/tmpl_abc123/revisions \
  -H "Authorization: Bearer {access_token}"

Response:

{
  "revisions": [
    {
      "id": "rev_xyz789",
      "integration_id": "tmpl_abc123",
      "revision_number": 3,
      "config": { "pixel_id": "1234567890", "batch_size": 100 },
      "delivery_mode": "server_side",
      "change_summary": "Updated access token",
      "created_by": "user_123",
      "created_at": "2026-02-25T14:30:00Z"
    },
    {
      "id": "rev_abc456",
      "integration_id": "tmpl_abc123",
      "revision_number": 2,
      "config": { "pixel_id": "1234567890", "batch_size": 50 },
      "delivery_mode": "server_side",
      "change_summary": "Increased batch size",
      "created_by": "user_123",
      "created_at": "2026-02-22T09:00:00Z"
    }
  ]
}

Required role: viewer or above.

Create Revision

POST /v1/admin/integration-templates/{id}/revisions

Create a new immutable revision with updated configuration.

Request:

{
  "config": {
    "pixel_id": "1234567890",
    "access_token": "EAABsb_new_token...",
    "batch_size": 100,
    "hash_pii": true
  },
  "delivery_mode": "server_side",
  "change_summary": "Rotated access token for Q1 2026"
}

Response (201 Created): Full revision object with auto-assigned revision_number.

Required role: editor or above.

Get Revision

GET /v1/admin/integration-templates/{id}/revisions/{rev}

Retrieve a specific revision by revision number.

Request:

curl -X GET http://localhost:8084/v1/admin/integration-templates/tmpl_abc123/revisions/3 \
  -H "Authorization: Bearer {access_token}"

Response: Full revision object.

Required role: viewer or above.