Skip to main content

​
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

RuleDetails
Max length256 characters
Allowed charactersa-z, A-Z, 0-9, -, _, ., :
Case sensitivityYes - 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

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