Magellan AI

Datafly Signal delivers conversion events to Magellan AI server-to-server, allowing Magellan to credit conversions back to the podcast ad that drove them. Server delivery gives you reliable attribution coverage that does not depend on third-party cookies or client-side pixels.

Prerequisites

Before configuring Magellan AI in Signal, you need a Magellan advertiser account and an API key.

Step 1: Identify your advertiser ID

Log in to the Magellan AI dashboard and open Settings > Advertiser. Your numeric Advertiser ID is shown at the top of the page — this is what Signal sends with every conversion event.

Step 2: Generate an API key

In the Magellan dashboard, go to Settings > API.
Click Generate API Key.
Name the key (e.g. Datafly Signal) and copy the value immediately — Magellan only shows it once.

⚠️

Treat the API key as a secret. Store it in your secrets manager and rotate it if you suspect it has leaked. Magellan API keys do not expire automatically.

Configure in Signal

Configuration fields

Field	Required	Description
`api_key`	Yes	Bearer token used to authenticate every request.
`advertiser_id`	Yes	Numeric Magellan advertiser ID from the Magellan dashboard.

Management UI setup

Go to Integrations > Add Integration > Magellan AI.
Select the Retail preset.
Enter your api_key and advertiser_id.
Set consent categories — defaults to marketing.
Click Save.

Management API setup

curl -X POST http://localhost:8084/v1/admin/integrations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "src_abc123",
    "vendor": "magellan_ai",
    "name": "Magellan AI — Podcast Attribution",
    "enabled": true,
    "config": {
      "api_key": "ak_magellan_abc123...",
      "advertiser_id": "12345"
    },
    "consent_categories": ["marketing"]
  }'

API endpoint

POST https://api.magellan.ai/v2/integrations/conversions
Authorization: Bearer {api_key}
Content-Type: application/json

Each conversion is delivered as a single JSON object.

Identity signals

Magellan matches conversions to podcast impressions using a combination of identifiers. The more identifiers you provide, the higher the match rate.

Signal	Field	Notes
`external_id`	Datafly `anonymous_id`	Stable cross-session identifier set by Signal as a first-party value. The strongest match key.
`ip`	Visitor IP address	Forwarded from the original browser request. Used as a fallback match key.
`user_agent`	Visitor User-Agent	Forwarded from the original browser request. Used alongside IP for probabilistic matching when no external_id is present.
`url`	Page URL at conversion	Optional context.
`referrer`	Referring URL	Optional context.
`utm_source` / `utm_medium` / `utm_campaign`	UTM parameters	Optional. Useful when conversions also need to be attributed inside Magellan’s UTM-based reports.

Magellan’s primary attribution path is the external_id (Datafly’s anonymous_id). For deterministic credit, ensure Signal’s first-party identification is enabled on every page that participates in the funnel.

Event mapping

Retail preset

Signal event	Magellan event
`Order Completed`	`conversion`

Magellan’s API is conversion-only — page views and intermediate funnel events are not ingested. If you want to send other conversion types (sign-ups, leads, app installs) to Magellan, duplicate the integration and remap the source event to Order Completed’s slot, or add additional events to the blueprint’s event map.

Example: Order Completed

Datafly.js call:

datafly.track("Order Completed", {
  order_id: "ORD-001",
  revenue: 129.99,
  currency: "GBP",
  coupon: "PODCAST10"
});

Magellan payload sent by Signal:

{
  "advertiser_id": "12345",
  "transaction_id": "ORD-001",
  "value": 129.99,
  "currency": "GBP",
  "coupon": "PODCAST10",
  "external_id": "anon_a1b2c3d4e5f6",
  "ip": "203.0.113.50",
  "user_agent": "Mozilla/5.0 ...",
  "url": "https://example.com/checkout/confirmation",
  "referrer": "https://example.com/cart",
  "utm_source": "podcast",
  "utm_medium": "audio",
  "utm_campaign": "spring_2026"
}

Testing

In the Magellan dashboard, open Reports > Conversions and filter to the last 15 minutes.
Trigger a test Order Completed event from your site or via the Management API preview tool.
The conversion should appear in the Magellan dashboard within a minute, with the external_id and UTM fields populated.
To trace a specific event end-to-end, copy the event_id from the Signal event log and search for the matching transaction_id in Magellan.

Troubleshooting

Problem	Solution
`401 Unauthorized`	API key is invalid or revoked. Generate a new key in Settings > API and update the integration config.
`403 Forbidden`	The API key is valid but not authorised for the supplied `advertiser_id`. Confirm both belong to the same Magellan account.
Conversions arrive but are unattributed	The `external_id` is missing or doesn’t match any Magellan impression. Confirm Signal’s first-party identification is active on landing pages and that the listener clicked through a Magellan-tracked promo link.
Duplicate conversions	Ensure `transaction_id` is populated and unique per order. Magellan deduplicates on `transaction_id` within a 24-hour window.
Low match rate	Add user-level identifiers via `datafly.identify()` early in the funnel so the `anonymous_id` is bound to a known user before checkout.

Kargo Merkle