Content Correlation

This guide explains how to use external_reference to map generated commentaries back to your content (e.g., bet lines, articles, game events).

The Problem

When you create a topic through the API, you receive a topic_id. But how do you know which of your content items this commentary belongs to when it’s ready?

The Solution: external_reference

The external_reference field allows you to pass your own content identifier when creating topics. This ID is:

Stored with every share
Returned in all API responses
Included in webhook payloads

Creating Topics with external_reference

curl -X POST https://prod.api.unleeshed.ai/partner/v1/topics \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Dolphins -7 vs. Bears",
    "persona_ids": ["uuid-1", "uuid-2"],
    "external_reference": "bet-line-12345",
    "metadata": {
      "bet_type": "spread",
      "line": -7,
      "game_id": "nfl-week5-mia-chi"
    }
  }'

Validation Rules

Rule	Details
Max length	256 characters
Allowed characters	`a-z`, `A-Z`, `0-9`, `-`, `_`, `.`, `:`
Case sensitivity	Yes - `Bet-123` ≠ `bet-123`

Querying by external_reference

Retrieve all commentaries for a given reference:

curl https://prod.api.unleeshed.ai/partner/v1/topics/by-reference/bet-line-12345 \
  -H "X-Api-Key: your_api_key"

Response:

{
  "success": true,
  "data": {
    "external_reference": "bet-line-12345",
    "topic_id": "uuid",
    "content": "Dolphins -7 vs. Bears",
    "metadata": {
      "bet_type": "spread",
      "line": -7
    },
    "commentaries": [
      {
        "share_id": "uuid",
        "persona_id": "uuid-1",
        "persona_name": "Mike Thompson",
        "status": "completed",
        "commentary": {
          "id": "uuid",
          "content": "The Dolphins...",
          "audio_url": "https://..."
        }
      },
      {
        "share_id": "uuid",
        "persona_id": "uuid-2",
        "persona_name": "Sarah Chen",
        "status": "pending",
        "commentary": null
      }
    ],
    "summary": {
      "total_personas": 2,
      "completed": 1,
      "pending": 1,
      "failed": 0
    }
  }
}

Idempotency

If you create a topic with the same (external_reference, persona_id) combination, we return the existing share instead of creating a duplicate:

{
  "persona_id": "uuid-1",
  "status": "duplicate",
  "message": "Already shared with external_reference \"bet-line-12345\" (status: pending)",
  "share_id": "existing-share-id"
}

This is useful for:

Retry logic after network failures
Preventing duplicate commentary requests
Safely re-running batch jobs

1:N Correlation Model

One external_reference can have multiple commentaries (one per persona). This supports the common use case of getting multiple analysts’ takes on the same bet line.

external_reference: "bet-line-12345"
├── Persona 1: Mike Thompson → commentary (completed)
├── Persona 2: Sarah Chen → commentary (pending)
└── Persona 3: Alex Rivera → commentary (completed)

Using with Webhooks

Webhooks include external_reference in every payload, making it easy to map callbacks to your content:

{
  "type": "creator.approved",
  "data": {
    "external_reference": "bet-line-12345",
    "persona_id": "uuid-1",
    "persona_name": "Mike Thompson",
    "commentary": { ... },
    "metadata": {
      "bet_type": "spread",
      "line": -7
    }
  }
}

metadata Field

Use metadata to store additional context that’s returned with all responses:

{
  "external_reference": "bet-line-12345",
  "metadata": {
    "bet_type": "spread",
    "line": -7,
    "game_id": "nfl-week5-mia-chi",
    "sport": "nfl",
    "priority": "high",
    "internal_campaign_id": "fall-2026-promo"
  }
}

The metadata field:

Accepts any valid JSON object
Has no size limit (but keep it reasonable)
Is returned in all responses and webhooks
Is stored with each share

Complete Integration Flow

Best Practices

Use meaningful IDs: Make references human-readable for debugging
Include metadata: Store context you’ll need when receiving webhooks
Handle duplicates: Check for duplicate status in responses
Query by reference: Use the by-reference endpoint rather than storing topic_ids

Get Started

Core Concepts

Guides

Resources

Content Correlation Guide

Content Correlation

The Problem

The Solution: external_reference

Creating Topics with external_reference

Validation Rules

Querying by external_reference

Idempotency

1:N Correlation Model

Using with Webhooks

metadata Field

Complete Integration Flow

Best Practices

​Content Correlation

​The Problem

​The Solution: external_reference

​Creating Topics with external_reference

​Validation Rules

​Querying by external_reference

​Idempotency

​1:N Correlation Model

​Using with Webhooks

​metadata Field

​Complete Integration Flow

​Best Practices

Content Correlation

The Problem

The Solution: external_reference

Creating Topics with external_reference

Validation Rules

Querying by external_reference

Idempotency

1:N Correlation Model

Using with Webhooks

metadata Field

Complete Integration Flow

Best Practices