---
title: "Add a competitor brand to the watchlist"
method: POST
path: "/v1/email/competitive/watchlist/brands"
tags: ["email-competitive"]
---

# Add a competitor brand to the watchlist

`POST /v1/email/competitive/watchlist/brands`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/email/competitive/watchlist/brands`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Adds a brand to the workspace's watchlist so its figures appear next to your
own. Pass a `brand_id` from a brand search.

Adding a brand records the one domain the panel sees the most of its mail
from, and every figure reported for the brand describes that domain. A brand
that mails from several domains therefore reports less than its full volume.
A brand the panel has never seen send cannot be measured at all and is
refused.

How many brands can be watched is capped per organization, counted across
every workspace it owns, so the same competitor watched from two workspaces
uses two of the allowance.

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Request body

- EmailCompetitiveWatchlistBrandCreate: The brand to add to the watchlist. Obtained from a brand search, which only returns brands that can be watched.
  - `brand_id` string, required: Identifier of the brand in the panel's catalog, used to add it to the watchlist. It is a string for the same reason a campaign id is: the values are wide enough that a client storing every number as a floating point value would round them, and a rounded identifier matches no brand at all.

## Response `201`

The brand was added to the watchlist.

- EmailCompetitiveWatchlistBrand: A brand on the workspace's watchlist. This is the watchlist entry itself, with no figures on it; read the watchlist to get those.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `id` string, required
  - `brand_id` string, required: Identifier of the brand in the panel's catalog, used to add it to the watchlist. It is a string for the same reason a campaign id is: the values are wide enough that a client storing every number as a floating point value would round them, and a rounded identifier matches no brand at all.
  - `name` string, required: The brand's name when it was added. It is kept as it was so the row still reads correctly if the brand is later renamed or stops being tracked.
  - `industry` string, nullable, required: The brand's industry when it was added, or null when the brand is not classified.
  - `sending_domains` string[], required: The domains this brand's figures describe. Always one domain today, chosen as the one the panel sees the most of its mail from.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `409`: Resource conflict
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)