---
title: "Search brands to add to the watchlist"
method: GET
path: "/v1/email/competitive/brands/search"
tags: ["email-competitive"]
---

# Search brands to add to the watchlist

`GET /v1/email/competitive/brands/search`

## Request

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

Searches for brands by name and returns the ones that can be watched, each
with the domain its figures would describe and the identifier to add it with.
Paste a domain instead of a name to find the brand that sends from it.

Brands the panel has never seen send are left out, since no figure could be
reported for them. Results are capped at eight and can omit matches whose
sending domain could not be resolved. An empty result means no watchable match
was returned for this query; try a more specific name or known sending domain.

## Query parameters

- `q` string, required

## Headers

- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `200`

Brands matching the search.

- EmailCompetitiveBrandSearchResults: Brands matching the search. Ranked by how well they match, best first, and capped at 8 results because this backs a type-ahead. The panel's own answer is often shorter than the cap, in which case the cap was never the reason the list is short.
  - `data` EmailCompetitiveBrandMatch[], required: Watchable matches returned for this query. A capped search or an unresolved sending domain can omit a brand; an empty result does not establish that the panel has never observed it.
    - `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.
    - `sending_domains` string[], required: The domains this brand's figures would 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
- `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)