---
title: "Match advertisers"
method: GET
path: "/api/v1/advertisers"
tags: ["Advertisers"]
---

# Match advertisers

`GET /api/v1/advertisers`

## Request

- Base URL: `https://llmse.ai`
- URL: `https://llmse.ai/api/v1/advertisers`
- Auth: one of:
  - none
  - HTTP bearer

Matches advertising networks to website content based on classification demographics. Provide either a URL (classification will be fetched automatically) or demographics directly (category, age, gender, sentiment). At least one of url, category, age, gender, or sentiment must be provided. Scoring weights: category match (+10), age match (+5), gender match (+3), sentiment match (+2), with CPM as tiebreaker.

## Query parameters

- `url` string, uri
- `category` string
- `subcategory` string
- `age` string
- `gender` 'male' | 'female' | 'all'
- `sentiment` 'Good' | 'Neutral' | 'Bad'
- `limit` integer
- `min_cpm` number
- `max_cpm` number

## Response `200`

Advertiser matches. Response shape varies: includes 'classification' when URL is provided, or 'demographics' and 'cpm_filter' when demographics are provided directly.

- union
  - AdvertiserResultUrl: Advertiser match result when URL is provided
    - `url` string, required
    - `classification` DemographicsInfo, required: Demographics used for advertiser matching
      - `category` string, nullable
      - `subcategory` string, nullable
      - `age` string, nullable
      - `gender` string, nullable
      - `sentiment` string, nullable
    - `matches` AdvertiserMatch[], required
      - `advertiser` Advertiser, required: An advertiser with targeting preferences
        - `id` string, required: Unique advertiser identifier
        - `name` string, required: Advertiser display name
        - `categories` string[], required: Target categories
        - `age_groups` string[], required: Target age groups
        - `genders` string[], required: Target genders
        - `sentiments` string[], required: Acceptable sentiment values
        - `bid_cpm` number, required: CPM bid amount in dollars
        - `creative_url` string, required: URL to ad creative
        - `landing_url` string, required: Click destination URL
        - `active` boolean, required: Whether advertiser is currently active
      - `score` number, required: Total match score (category +10, age +5, gender +3, sentiment +2, CPM tiebreaker)
      - `category_match` boolean, required
      - `age_match` boolean, required
      - `gender_match` boolean, required
      - `sentiment_match` boolean, required
    - `match_count` integer, required
  - AdvertiserResultDemographics: Advertiser match result when demographics are provided directly
    - `demographics` DemographicsInfo, required: Demographics used for advertiser matching
      - `category` string, nullable
      - `subcategory` string, nullable
      - `age` string, nullable
      - `gender` string, nullable
      - `sentiment` string, nullable
    - `cpm_filter` object, required
      - `min_cpm` number, nullable
      - `max_cpm` number, nullable
    - `matches` AdvertiserMatch[], required
      - `advertiser` Advertiser, required: An advertiser with targeting preferences
        - `id` string, required: Unique advertiser identifier
        - `name` string, required: Advertiser display name
        - `categories` string[], required: Target categories
        - `age_groups` string[], required: Target age groups
        - `genders` string[], required: Target genders
        - `sentiments` string[], required: Acceptable sentiment values
        - `bid_cpm` number, required: CPM bid amount in dollars
        - `creative_url` string, required: URL to ad creative
        - `landing_url` string, required: Click destination URL
        - `active` boolean, required: Whether advertiser is currently active
      - `score` number, required: Total match score (category +10, age +5, gender +3, sentiment +2, CPM tiebreaker)
      - `category_match` boolean, required
      - `age_match` boolean, required
      - `gender_match` boolean, required
      - `sentiment_match` boolean, required
    - `match_count` integer, required

## Other responses

- `400`: No filters provided or invalid CPM values
- `429`: Rate limited

---

[API](https://skmtc.dev/llmse/apis/llmse-api.md) · [All operations](https://skmtc.dev/llmse/apis/llmse-api/llms.txt) · [OpenAPI document](https://skmtc.dev/llmse/apis/llmse-api/revisions/8aedf67208e4?raw)