> ## Documentation Index
> Fetch the complete documentation index at: https://docs.closient.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claim Brand

> Walk a brand owner through claiming an existing unclaimed Brand on Closient or creating + claiming a new one, then linking it to their Organization.

Closient indexes brands from many sources (Open Food Facts, Open Beauty
Facts, USDA, manual entry, etc.). A brand with `organization=null` is
**unclaimed** — crowd-sourced metadata waiting for the legitimate brand
owner to claim it and start managing the record. This skill walks an
authenticated brand-owner through the claim flow end-to-end.

## When to use

* A brand owner wants to manage their products on Closient.
* The agent needs to attach an `Organization` to an existing `Brand`
  record (so analytics, product edits, and resolver routing work).
* A retailer's onboarding flow turned up an unclaimed brand the retailer
  also owns.

For pure brand *creation* (no pre-existing record on Closient), the same
endpoint creates the brand already linked to the caller's organization —
see Step 2 below.

## Auth

OAuth token (or API key) with `brands:write` scope. The caller must hold
`OWNER` or `MANAGER` role on the `Organization` that will own the
claimed brand. A `VIEWER` cannot claim.

## Flow

### Step 1 — Discover candidate unclaimed brands

```
GET /brands/api/v1/brands?name=<query>
```

Returns paginated brands. Unclaimed brands have `organization=null` in
the source data but are NOT filtered by the API today (see **Known
gaps** below). The agent should:

1. Issue the search.
2. Pull the full brand record for each candidate via
   `GET /brands/api/v1/brands/{id}` to see `organization_id`.
3. Present the user with the matches that are unclaimed.

### Step 2 — Create-and-claim (the supported path today)

```
POST /brands/api/v1/brands
Content-Type: application/json

{
  "organization_id": "<caller's org short id>",
  "name": "Acme Snacks",
  "website": "https://acmesnacks.com",
  "description": "Premium trail mix and snack foods."
}
```

If no existing unclaimed record matches, this creates the brand already
linked to the caller's organization (which is the destination state of a
claim anyway). The endpoint rejects duplicates within the same
organization (`409`).

### Step 3 — Enrich the claimed brand

Once the brand exists and is linked, the agent should immediately:

```
PATCH /brands/api/v1/brands/{id}
{
  "instagram": "...",
  "facebook": "...",
  "website": "...",
  "description": "..."
}
```

Social links + description materially improve brand-analytics signal
and the brand's surface on the Closient resolver pages.

### Step 4 — Upload a logo (optional but recommended)

```
POST /brands/api/v1/brands/{id}/logo
Content-Type: multipart/form-data

logo: <image file>
```

PNG or SVG, max 2 MB. The logo shows on resolver hosted pages and in
search results.

### Step 5 — Verify the link

```
GET /brands/api/v1/brands/{id}
```

The `organization` field should reflect the caller's organization. Once
set, organization cannot be cleared (`Brand.organization` is a one-way
claim per `apps/brands/models.py`).

## Required inputs

* `organization_id` — the caller's organization (claim destination).
* `name` — brand display name.

## Optional inputs

* `website`, `description`
* Social links (`instagram`, `facebook`, `twitter`, `linkedin`,
  `youtube`, `tiktok`, `pinterest`, `threads`) — via `PATCH`.
* `logo` — via `POST /brands/{id}/logo`.

## Output

* `verification_status` — currently always `linked` once `POST` returns
  `201` (no manual review gate today; see Known gaps).
* `brand_id` — the short ID of the linked brand.
* `next_steps` — recommend the user upload a logo, fill social links,
  and start adding products to their brand.

## Guidance for agents

* **Search first, create second.** Always run the discovery query
  (Step 1) before creating, even if the brand is well-known — the user
  may have a Closient-side record they don't know about. Duplicate
  brands per organization are blocked (`409`) but cross-org duplicates
  are not, so this is the only protection against accidentally creating
  a second crowd-sourced copy.
* **Confirm the organization** before posting. The caller may belong to
  multiple orgs; ask which one owns the brand. The `account/whoami`
  endpoint lists the caller's organizations.
* **One-way claim.** Once `organization` is set, it cannot be cleared
  via the API (the model raises on attempts to null it). Surface this
  to the user before the `POST`.
* **Don't loop on duplicate errors.** A `409` means the brand already
  exists for that organization — fetch and patch instead of retrying.

## Known gaps (planned)

* **No "claim existing unclaimed brand" endpoint.** Today the
  `BrandUpdateIn` schema does not accept `organization`, so the only
  way to *attach an organization* to an existing unclaimed record is
  via the `POST` (which creates a new linked record). A dedicated
  `POST /brands/{id}/claim` is planned so an existing crowd-sourced
  Brand can be claimed without duplicating it. Until then, the agent
  should flag candidate unclaimed records to the human owner for
  reconciliation.
* **No `?unclaimed=true` filter.** The list endpoint accepts `name`
  and `organization_id` filters but not a "show me only unclaimed"
  query. Agents must fetch detail records to determine claim state.
* **No ownership verification step.** There is no domain-verification
  / email-loop / DNS-TXT check today — claims are accepted on the
  strength of the OAuth scope alone. A verification step (TXT record
  on the brand's website domain) is planned.
* **No brand-merge.** If a duplicate linked brand was accidentally
  created, there is no API to merge it into the canonical record.

## Related skills

* `onboard-retailer` — the parallel flow for retailer Organizations
  connecting their POS.
* `brand-scan-summary` — once claimed, see engagement on your products.
* `brand-retail-footprint` — once claimed, see distribution coverage.
* `brand-search-demand` — once claimed, see geographic demand.