Colony Segmentation

Audience Segmentation API

Overview

The Audience Segmentation API analyses listener behaviour and automatically groups listeners into meaningful engagement segments. It combines RFM scoring, semantic vector search, AI inference, predictive intelligence and an AI agent layer to build a complete audience intelligence platform for radio stations.

Authentication

All /api/v1/* endpoints require an API key in the request header:

X-Segmentation-Key: <your-api-key>

Public routes — no authentication required: - GET / — landing page - GET /health — service health check - GET /docs — Swagger UI - GET /docs/api-guide — this guide - GET /redoc — ReDoc

Requests without a valid key return:

{"detail": "Invalid or missing API key"}

HTTP Status Codes

Error response format

{
  "detail": "No profile found for 27821234567 at company 184"
}

Common error scenarios

How Segmentation Works

RFM Scoring

Seven Primary Segments

How Demographics Are Populated

1. Survey answers — structured profile questions.

2. USSD/bot conversations — Q&A extraction, SA ID → gender + age auto-derived.

3. ORE signals — extracted from every interaction by live-core: - language — AWS Comprehend detection - location — AWS Comprehend location - gender — ore mining (stored as male / female) - display_name — WhatsApp/Telegram display name - profile_image — profile image URL

4. Free text extraction — SA ID number (13 digits) detected via regex. Gender and age group derived automatically.

5. AI inference — on demand when a producer views a listener. Cached 30 days.

Endpoints

Base URL: https://segmentation.live.colonyhq.com

GET /health — Public

{
  "status": "ok",
  "mongodb": "ok",
  "qdrant": "ok",
  "openai": "ok — model: gpt-4o-mini"
}

GET /api/v1/segments/{company_id}/summary

{
  "company_id": 184,
  "total_listeners": 136348,
  "high_engagement_count": 513,
  "segment_counts": {
    "new_listener": 11135,
    "super_fan": 38,
    "dormant": 120529
  }
}

GET /api/v1/segments/{company_id}/insights

Segment distribution with percentages and plain English explanations.

GET /api/v1/segments/{company_id}/tags

Tag distribution per segment with counts, percentages and descriptions.

GET /api/v1/segments/{company_id}/filter

Retargeting filter. Gender matching is case-insensitive (male/Male/female/Female).

/filter?segment=dormant&inferred_gender=male&inferred_interests=automotive
/filter?gender=female&language=English&opt_in=true

GET /api/v1/segments/{company_id}/aggregate

Aggregated breakdown counts for the full filtered dataset — not just a page. Accepts the same filters as /filter. Use this to power dashboard charts so totals reflect the true audience size regardless of pagination.

/aggregate
/aggregate?segment=dormant
/aggregate?segment=super_fan&gender=Female

{
  "company_id": 184,
  "total": 107286,
  "channel_counts": {"12": 33010, "9": 13664, "0": 14212},
  "gender_counts": {"other": 107280, "male": 5, "female": 1},
  "age_group_counts": {"Other": 107281, "35-49": 2},
  "language_counts": {"other": 107278, "english": 8},
  "location_counts": {"Other": 106621, "Johannesburg": 5},
  "segment_counts": {"dormant": 107279, "new_listener": 6},
  "momentum_counts": {"0": 107279, "1": 7},
  "campaign_type_counts": {"message_board": 95945, "competition": 11193}
}

Gender and language keys are normalised to lowercase (Male/male merge into male). Location is capped at the top 20 by count.

GET /api/v1/segments/{company_id}/export

Returns all matching listener records for a filter set — no pagination. Intended for bulk CSV export and campaign targeting.

/export?segment=dormant
/export?segment=super_fan&opt_in=true
/export?channel_pair=9,0

{
  "company_id": 184,
  "total": 1,
  "listeners": [
    {
      "originator": "27724430967",
      "originator_type": "mobile_number",
      "current_segment": "super_fan",
      "gender": "Male",
      "age_group": "18-24",
      "location": "Johannesburg",
      "language": "English",
      "primary_channel_type": 9,
      "opt_in": true,
      "permission": true,
      "tags": ["drive_time_listener", "campaign_loyal"],
      "recency_days": 0,
      "interactions_total": 5492,
      "inferred_lsm": null
    }
  ]
}

GET /api/v1/segments/{company_id}/cross-channel

Cross-channel co-engagement matrix. For every pair of channels, returns how many listeners are active on both, plus per-channel unique totals and percentages. Powers the Cross Platform Engagement grid.

/cross-channel
/cross-channel?segment=super_fan

{
  "company_id": 184,
  "total": 107286,
  "channels": [0, 9, 12],
  "uniques": {"9": 13664, "0": 14212, "12": 33010},
  "matrix": {"9": {"0": 1200, "12": 800}, "0": {"9": 1200}},
  "percentages": {"9": {"0": 1.1, "12": 0.7}, "0": {"9": 1.1}}
}

Read matrix["9"]["0"] = 1200 as: 1,200 listeners are active on both WhatsApp (9) and SMS (0). percentages["9"]["0"] is that count as a percentage of the total filtered audience — use it for tooltips like "1.1% of your audience engaged on both WhatsApp and SMS."

GET /api/v1/segments/{company_id}/search

Semantic search. Qdrant finds by meaning — MongoDB narrows by demographics.

/search?q=music lovers
/search?q=car enthusiasts&segment=dormant&min_score=0.65

GET /api/v1/listeners/{company_id}/{originator}

Full behavioural profile including ORE-enriched demographics.

{
  "demographics": {
    "name": "Ozias Munyamela",
    "display_name": "Ozias Munyamela",
    "gender": "male",
    "age_group": "35-49",
    "location": "Johannesburg",
    "language": "English",
    "profile_image": "https://..."
  }
}

DELETE /api/v1/listeners/{company_id}/{originator}

POPIA erasure. Clears all PII, keeps anonymised behavioural data. Cannot be undone.

{
  "erased": true,
  "originator_hash": "sha256:a3f9c2d1...",
  "erased_at": "2026-08-22T10:00:00Z"
}

GET /api/v1/ai/segments/{company_id}/insights

AI-powered plain English insights for all segments.

GET /api/v1/ai/listeners/{company_id}/{originator}

AI demographic inference and interest tagging. Cached 30 days — no charge on repeat calls. Response includes "cached": true/false.

PUT /api/v1/ai/listeners/{company_id}/{originator}/promote-demographics

Promotes AI-inferred to declared. Only where declared is null and confidence ≥ 0.70.

{
  "promoted": {"gender": "female", "age_group": "25-34"},
  "skipped": {"income_bracket": "confidence too low (0.60)"},
  "message": "2 field(s) promoted to declared demographics"
}

POST /api/v1/ai/segments/{company_id}/custom-segment

Find listeners using plain English. Stateless — use Audiences for persistence.

{"theme": "pet lovers", "description": "listeners who own dogs or cats", "limit": 200}

GET /api/v1/intelligence/listeners/{company_id}/{originator}/churn-risk

{
  "churn_risk": "high",
  "churn_risk_score": 75,
  "churn_signals": [
    "Engagement momentum is declining",
    "Last engaged 45 days ago"
  ]
}

Risk levels: low (0–29) / medium (30–59) / high (60–100)

GET /api/v1/intelligence/listeners/{company_id}/{originator}/similar

Behaviourally similar listeners via Qdrant cosine similarity.

/similar?limit=20&min_score=0.75&exclude_segment=dormant

GET /api/v1/intelligence/segments/{company_id}/{segment_key}/profile

Composite demographic and behavioural profile for a segment.

{
  "segment": "dormant",
  "total_in_segment": 120529,
  "channels": {"primary": "USSD"},
  "top_campaigns": [{"title": "Parmalat", "total_interactions": 336}]
}

POST /api/v1/agent/{company_id}/recommend

AI campaign recommendation from an advertiser brief. Results cached 24 hours — same brief returns cached result instantly. Response includes "cached": true/false.

{
  "brief": "Caltex fuel advertiser targeting male drivers aged 25-49 in Gauteng",
  "sample_size": 500
}

POST /api/v1/agent/{company_id}/parse-brief

Parses an advertiser brief into structured targeting criteria.

{"brief": "FMCG brand targeting female listeners aged 25-34 in Gauteng"}

POST /api/v1/audiences/{company_id}

Creates a named persistent custom audience.

{"name": "Colony Campaigns Pet Lovers", "theme": "pet lovers", "limit": 500, "expiry_days": 30}

GET /api/v1/audiences/{company_id}

Lists all custom audiences — member lists excluded for performance.

GET /api/v1/audiences/{company_id}/{audience_id}

Returns audience with full member list enriched with profile data.

PUT /api/v1/audiences/{company_id}/{audience_id}/refresh

Re-runs search strategy, updates members with latest data.

DELETE /api/v1/audiences/{company_id}/{audience_id}

Deletes a custom audience. Cannot be undone.

Channel Type Reference

Phased Roadmap

Phase 1 — Behaviour-led segmentation     ✓ Complete
Phase 2 — Semantic search                ✓ Complete
Phase 3 — AI inference layer             ✓ Complete
Phase 4 — Predictive intelligence        ✓ Complete
Phase 5 — AI agent layer                 ✓ Complete
Phase 6 — Full-dataset aggregation       ✓ Complete