---
title: "List a brand's competitors"
method: GET
path: "/api/admin/brand-competitors"
tags: ["Brand Competitors"]
---

# List a brand's competitors

`GET /api/admin/brand-competitors`

## Request

- Base URL: `https://api.sponsorunited.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.sponsorunited.com/api/admin/brand-competitors`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/sponsorunited/apis/sponsorunited-api/docs/api/admin/brand-competitors/get.ts> (a function with typed inputs; its response is checked against the schema)

Paginated list of a brand's visible competitors, linked and unlinked. Rows removed by an admin or no longer returned by the scrape are left out. Requires approve-company permission.

## Query parameters

- `source_brand_id` integer, required
- `q` string
- `decision_source` 'auto_linked' | 'approved' | 'admin_added' | 'unlinked'
- `order_by` 'raw_name' | 'created_at' | 'last_seen_at'
- `order_direction` 'asc' | 'desc'
- `page` integer
- `per_page` integer

## Response `200`

Paginated competitors.

- object
  - `current_page` integer
  - `data` BrandCompetitorResource[]
    - `id` integer
    - `source_brand_id` integer
    - `raw_name` string, nullable
    - `normalized_name` string, nullable
    - `raw_name_from_target_brand` boolean: True when raw_name was copied from the target brand name because the scraped name was not kept.
    - `linked` boolean: True when the competitor is linked to a SponsorUnited brand.
    - `target_brand` object, nullable
      - `id` integer
      - `name` string
      - `logo` string, nullable
    - `decision_source` 'auto_linked' | 'approved' | 'admin_added' | 'unlinked': admin_added: added by an admin. unlinked: scraped, no SponsorUnited brand. approved: scraped and linked, confirmed by an admin. auto_linked: scraped and linked by the matcher, not yet confirmed (a rejected link is listed here too).
    - `origin` 'scraped' | 'admin'
    - `decision` 'auto_linked' | 'approved' | 'rejected', nullable
    - `match_source` 'ems' | 'meilisearch' | 'brand_synonym' | 'none', nullable
    - `linked_by_parent_brand` boolean: True when the competitor is linked to a brand that owns it rather than to its own SponsorUnited brand (for example Apple for Apple Watch): either the scrape named a parent brand for a competitor with no brand of its own, or the matched brand's name is only part of the competitor's name. No synonym is written for such a link. A later scrape that matches the competitor to its own brand replaces the link, unless an admin has confirmed the link, renamed the competitor, or removed it. An admin who links or re-points the competitor clears this flag.
    - `score_at_decision` integer, nullable
    - `decided_at` string, date-time, nullable
    - `decided_by` object, nullable
      - `id` integer
      - `name` string, nullable
      - `email` string, nullable
    - `last_seen_at` string, date-time
    - `created_at` string, date-time, nullable
    - `updated_at` string, date-time, nullable
  - `first_page_url` string, nullable
  - `from` integer, nullable
  - `last_page` integer
  - `last_page_url` string, nullable
  - `links` object[]
    - `url` string, nullable
    - `label` string
    - `active` boolean
  - `next_page_url` string, nullable
  - `path` string, nullable
  - `per_page` integer
  - `prev_page_url` string, nullable
  - `to` integer, nullable
  - `total` integer

## Other responses

- `401`: Unauthenticated
- `403`: Forbidden
- `422`: Validation error

---

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