# Set up a brand from your assistant

Everything on the Brand tab, plus adding a brand and first-time setup, from Claude Code, any assistant that uses MCP, or the API.

You can do everything the Brand tab does without opening RecruitAffiliates.ai. This page lists each setting, the API operation that changes it, and the MCP tool that does the same job. **MCP** is the standard an assistant such as Claude Code uses to call our tools. The API and the tools run the same code the app runs. A change from your assistant looks exactly like one made on screen.

<Callout>
A key needs the `finder:write` scope to change anything, and `finder:read` to read. Make a key in Settings, API keys. Nothing on this page sends an email.
</Callout>

## How a change works

Every tool that changes something answers twice. The first call comes back as a **card**: one plain sentence saying what will change, what it costs, and a `preview_token`. Nothing has changed yet.

Your assistant shows you the card. When you agree, it calls again with `confirm: true` and the token, and the change applies. Change one thing and the token fails.

### On the API

The API has no card. Send the change and it applies at once, which is why a key with `finder:write` should only go to code you trust. Each answer carries an `effect`, the same sentence the app shows after a save, such as "Saved. Your next weekly search uses these."

### What an answer looks like

Every answer from a tool opens with one sentence your assistant can read out. A short list of next steps ends it.

An agent names the brand on every call, so there is no "switch brand" step. Leave it out and the call uses your oldest brand. List your brands with `GET /v1/finder/brands` or `recruit_brands`.

## Read the settings

| What | API | MCP tool |
|---|---|---|
| Every setting in one read | `GET /v1/finder/brands/{id}/settings` | `recruit_brand` |
| Competitors, with how many matches name each | `GET /v1/finder/brands/{id}/competitors` | `recruit_competitors` |
| Program page and its grade | `GET /v1/finder/brands/{id}/program-page` | `recruit_program_page` |
| Goal and progress | `GET /v1/finder/brands/{id}/goal` | `recruit_goal` |
| What rivals publish, and what the next lookup would cost | `GET /v1/finder/brands/{id}/rival-terms` | `recruit_rival_terms` |
| Changes your Not a fit answers made | `GET /v1/finder/brands/{id}/changes` | `recruit_brand_changes` |

## Change a setting

Each row is one job. All of these are free: they use no credits.

| Setting | API (POST) | MCP tool | When it takes effect |
|---|---|---|---|
| Summary, competitors, topics, who you want | `/v1/finder/brands/{id}` | `recruit_update_brand` | Targeting re-sorts your matches before the call answers. The rest reaches the next weekly search. |
| Voice: who you sell to, proof, what to avoid, tone | `/v1/finder/brands/{id}/voice` | `recruit_set_voice` | The next email we write. |
| Sending: daily limit, signature, postal address | `/v1/finder/brands/{id}/sending` | `recruit_set_sending` | Every email from now on. |
| Revenue: what a customer is worth, conversion | `/v1/finder/brands/{id}/revenue` | `recruit_set_revenue` | The estimates on your pages. |
| The offer: rate, length, bonus, discount code | `/v1/finder/brands/{id}/offer` | `recruit_set_offer` | Every new offer. Unsent drafts are rewritten. People who already said yes keep their terms. |
| Price and payout schedule | `/v1/finder/brands/{id}/price-payout` | `recruit_set_price_payout` | The next emails. |
| Signup link | `/v1/finder/brands/{id}/signup-link` | `recruit_set_signup_link` | Invites to interested affiliates. Send an empty link to remove it. |
| Brand name | `/v1/finder/brands/{id}/name` | `recruit_rename_brand` | New emails, and the name in the app. |
| Do you run an affiliate program | `/v1/finder/brands/{id}/programme` | `recruit_set_programme` | Whether sites that link to you count as your affiliates. |
| What you sell | `/v1/finder/brands/{id}/business-type` | `recruit_set_business_type` | The next search. |
| Time zone | `/v1/finder/brands/{id}/timezone` | `recruit_set_timezone` | Send windows and the morning email. It applies to every brand on the account. |
| Use my own website, on a store's sample brand | `/v1/finder/brands/{id}/own-website` | `recruit_use_own_website` | Removes the sample and its matches. A real brand is never removed. |

Put an offer in with structured terms. For 30% for life:

```json
{ "terms": { "rate": { "rate_type": "percent", "rate_bps": 3000 }, "duration": { "kind": "lifetime" } } }
```

A rate is in basis points: 100 basis points is 1%, so 3000 is 30%.

To preview what strict targeting would hide before you turn it on, use `GET /v1/finder/brands/{id}/strict-mode-preview?target_countries=GB,US` or `recruit_preview_strict_mode`. To put back a setting a Not a fit answer changed, use `POST /v1/finder/brands/{id}/changes/{change_id}/restore` or `recruit_restore_change`.

## Competitors

Add one with a domain and a tier. **Direct** sells what you sell. **Adjacent** sells to your buyers. **Platform** is the affiliate software a rival runs on. You can hold 20 in all: 8 direct, 8 adjacent, 4 platforms.

| Job | API | MCP tool |
|---|---|---|
| Add | `POST /v1/finder/brands/{id}/competitors` | `recruit_add_competitor` |
| Remove, by domain or name | `POST /v1/finder/brands/{id}/competitors/remove` | `recruit_remove_competitor` |

A change reaches the next weekly search. Nothing is searched or charged on the spot.

## People you already work with

These are your **exclusions**. A person on the list is never offered to you again, and never emailed.

| Job | API | MCP tool |
|---|---|---|
| List | `GET /v1/finder/exclusions` | `recruit_exclusions` |
| Add typed entries | `POST /v1/finder/exclusions` | `recruit_add_exclusions` |
| Paste a list: emails, sites, channel links, handles | `POST /v1/finder/exclusions/import` | `recruit_add_exclusions` |
| Upload a CSV | `POST /v1/finder/exclusions/upload` | `recruit_add_exclusions` |
| Remove one | `DELETE /v1/finder/exclusions/{id}` | `recruit_remove_exclusion` |
| Remove everything you uploaded | `POST /v1/finder/exclusions/remove-uploaded` | `recruit_clear_uploaded_exclusions` |
| Add your AffiliateRail partners | `POST /v1/finder/exclusions/sync-partners` | `recruit_sync_partners` |

Adding the same person twice is safe. Name the platform for a bare `@name`; we never guess it. A YouTube `@handle` counts as unresolved, since looking one up costs money. A Do not contact mark can't be removed this way, on purpose.

## Program page, goal and brand

| Job | API | MCP tool |
|---|---|---|
| Save the public program page | `POST /v1/finder/brands/{id}/program-page` | `recruit_set_program_page` |
| Set a goal, such as 5 new partners this month | `POST /v1/finder/brands/{id}/goal` | `recruit_set_goal` |
| Clear the goal | `DELETE /v1/finder/brands/{id}/goal` | `recruit_clear_goal` |
| Add another brand | `POST /v1/finder/brands` | `recruit_add_brand` |

Adding a brand copies the offer, targeting and voice of the brand you copy from, and starts its first search. Your plan sets how many brands you can have. At the limit the call is refused with `brand_limit` and nothing is written.

## First-time setup

One call takes a blank account to a brand with its first search running. Give the domain and country, what it does, its competitors or topics, and the offer.

| Job | API | MCP tool |
|---|---|---|
| See which setup steps are done | `GET /v1/finder/setup` | `recruit_setup_guide` |
| Set up, or fill in what is missing | `POST /v1/finder/setup` | `recruit_setup_brand` |
| Read the site and suggest competitors | `POST /v1/finder/brands/{id}/research` | `recruit_research_brand` |

Send `"dry_run": true` to the API to see what a setup call would change without changing anything. Setup starts the first search once there is a competitor or topic to look for. The first search uses no credits.

## Paid lookups

Two calls spend our money, not your credits. Neither touches your credit balance. Each says the cost first.

- **Rival search terms** (`POST /v1/finder/brands/{id}/rival-terms`, `recruit_find_rival_terms`). Reads each rival's affiliate program page so you can compare terms. With the lookup switched on, it also runs one Google search per rival, which costs up to a fraction of a cent each. The card, or the `quote` on the API's read, shows the most it can cost. The API refuses to run unless you send `confirm_cost_cents` at or above that quote.
- **Read the site** (`POST /v1/finder/brands/{id}/research`, `recruit_research_brand`). Uses part of your trial's site-reading allowance, and a brand gets three runs.

## Errors

| Code | Meaning | What to do |
|---|---|---|
| `resource_missing` (404) | The brand, exclusion or change isn't on your account. | List them and use an id from the list. |
| `brand_limit` (402) | Your plan runs this many brands. | Remove one, or change plan in the app. |
| `quote_changed` (409) | The lookup's cost moved since you read it. | Read the quote again and confirm the new number. |
| `exclusion_protected` (403) | A Do not contact mark can't be removed this way. | Leave it. It protects someone who asked not to be written to. |
| `research_unavailable` (409) | Site reading isn't set up on this deployment. | Fill the card in with `POST /v1/finder/setup`. |
| `sandbox_real_row` (403) | A test key only changes sample data. | Use a live key. |