<!-- The markdown copy of https://oppalerts.com/docs/mcp/campaigns_organization_add . All pages: https://oppalerts.com/docs/llms.txt -->

[Documentation](https://oppalerts.com/docs/) / [MCP](https://oppalerts.com/docs/mcp/) / campaigns_organization_add

# campaigns_organization_add

`POST https://mcp.oppalerts.com/mcp tool: campaigns_organization_add`

Adds one organization to a campaign: your own brand, a competitor, a partner, or a publisher.

## What it does

The tool adds one organization to a campaign, with its websites and its brand names. The brand searches look for the brand names on the pages.

Organizations can be added after the campaign is finalized. A change to an owned brand or a competitor makes the stored daily counts of the brand searches out of date. The Dashboard then offers a rebuild: [campaigns_rebuild_counts](https://oppalerts.com/docs/mcp/campaigns_rebuild_counts).

The response contains the new organization and its id. In the web app, the organization shows on the Settings tab of Edit Campaign, in the organization boxes.

## Who May Call It

- The account owner, an account editor, or a campaign editor of this campaign. An account viewer or a campaign viewer gets the error `no_access`.
- The token or the connection needs the scope `api:write`, and `mcp:use` as every MCP tool does. Without `api:write`, the call gets the error `forbidden`. [Authentication](https://oppalerts.com/docs/getting-started/authentication#scopes) says which tokens and apps have it.
- The tool tells the MCP client that it changes data, so a client such as Claude asks you before the call.

## Connect

```bash
claude mcp add --transport http oppalerts https://mcp.oppalerts.com/mcp
```

The first call opens a browser window for the OppAlerts login. Allow changes there. [Connect an AI Agent](https://oppalerts.com/docs/mcp/) has the details.

## Parameters

**`campaign`int, required, 1 to 4294967295**

The campaign id, from [campaigns_list](https://oppalerts.com/docs/mcp/campaigns_list). It must be a campaign of your account.

**`hosts`list of strings, required**

Required. The websites of the organization: host names, domains, or URLs. Only the host is kept, in lower case, with a leading www. removed. A host can belong to only one organization of the campaign. An item that gives no host is refused, and so is a host of more than 253 characters.

**`brand_names`list of strings, optional**

Optional. The brand names of the organization, one in each item. The brand searches look for these names on the pages. Leave it out for no brand names.

**`relationship`string, required**

Required. What the organization is to this campaign: org_owned_brand is your own brand, org_competitor is a competitor, and org_partner and org_publisher are the other 2. Another value is refused. Values: `org_competitor`, `org_owned_brand`, `org_partner`, and `org_publisher`.

**`color`int, optional, 0 to 11**

Optional. The color of the organization on the Dashboard charts: 0 to 11 is one of the 12 chart colors. Leave it out for no chosen color: the charts then pick one. Refused together with color_hex.

**`color_hex`string, optional, at most 20 characters**

Optional. A color as #rrggbb. Leave it out for no color. Another form is refused, and so is color_hex together with color.

## Rules

- `hosts` and `relationship` are required.
- `brand_names`, `color`, and `color_hex` are optional. A field that you leave out is none.
- `color` and `color_hex` together are refused.
- Only the host of each item of `hosts` is kept, in lower case, with a leading `www.` removed. A host can belong to only one organization of the campaign (`host_taken`). An item that gives no host is refused (`bad_host`), and so is a host of more than 253 characters. A list with no host name or domain is refused (`no_hosts`).
- An empty list is refused.
- Your own brand, a partner, and a publisher each take at most 10 brand names and 10 websites. A competitor takes at most 5 brand names and 5 websites, and a campaign takes at most 10 competitors. A call over a limit is refused with `organization_row_limit`, and nothing is cut. The sentence names the field (`brand_names`, `hosts`, or `relationship`) and the limit.
- The answer has `notes`, a list of sentences. It has one sentence for each brand name that the index cannot find: the sentence says why, and what can work. Searches for such a name find no pages. The organization is still saved: a note is not an error.

## Strict Rules

- A field that is not in the list above is refused. The result then has `isError` true, and its text starts with `bad_param`. The error names the field: "<field> is not a field of this tool."
- A bad value is refused, and the error names the field. A bad value is a value of the wrong type, a number with a fraction for a whole-number field, a value out of its range, a value that is not in its list, or an empty text, list, or object. A required field that you do not send is refused too. To send no value for an optional field, leave the field out. No field has a default value, and the tool never changes a value that you send.
- An error about the format of a call, such as a refused field, names the field. Its message ends with one sentence: "Read the documentation at https://oppalerts.com/docs for the correct format." Every other error, such as `forbidden` below, has only its own sentence.

## Response fields

The response contains the organization, in the same format that [campaigns_organizations](https://oppalerts.com/docs/mcp/campaigns_organizations) returns for each organization, plus `notes`.

**`organization.id`int**

The organization id.

**`organization.relationship`string**

The relationship to the brand: `org_owned_brand`, `org_competitor`, `org_partner`, or `org_publisher`.

**`organization.hosts`list of strings**

The hosts of the organization.

**`organization.brand_names`list of strings**

The brand names of the organization.

**`organization.color`int, optional**

The chart color of the organization, as a number. Left out when the organization has no color.

**`organization.color_hex`string, optional**

The chart color of the organization, as a hex color, for example `#1f77b4`. Left out when the organization has no color.

**`notes`list of strings**

A list of sentences. It is empty when there is nothing to say. It has one sentence for each brand name that the index cannot find: the sentence says why, and what can work. Searches for such a name find no pages. The change is still saved: a note is not an error.

## Example

### Call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "campaigns_organization_add",
    "arguments": {
      "campaign": 124,
      "hosts": [
        "example-hotels.com",
        "example-hotels.co.uk"
      ],
      "brand_names": [
        "Example Hotels",
        "Example Hotel Group"
      ],
      "relationship": "org_owned_brand"
    }
  }
}
```

### Response

The response is shown in full.

```json
{
  "organization": {
    "id": 9,
    "relationship": "org_owned_brand",
    "hosts": [
      "example-hotels.com",
      "example-hotels.co.uk"
    ],
    "brand_names": [
      "Example Hotels",
      "E&H"
    ],
    "color": 3,
    "color_hex": "#1f77b4"
  },
  "notes": [
    "Searches for \"E&H\" find no pages: the index does not hold this name. The index does not keep words of 1 character, or common words such as \"at\" and \"the\", and a symbol such as \"&\" or \"+\" splits a name into words. Add a longer name that pages use, for example the full company name."
  ]
}
```

## Errors

An error returns as a tool result with `isError` true. Its text starts with the error code. An example: a call by a team member who cannot make this change.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "no_access: You have read permissions for this campaign."
      }
    ],
    "isError": true
  }
}
```

One error is not a tool result. A call with a token that does not have the scope `api:write` gets the HTTP status 403, as the MCP standard says. The answer has a `WWW-Authenticate` header with `error="insufficient_scope"` and the scopes that the call needs. An MCP app that reads this header asks you for the permissions to change campaigns. The body has the error code `forbidden` and its sentence. The tool does not run, and the call is not counted.

```http
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="mcp:use api:write", resource_metadata="https://mcp.oppalerts.com/.well-known/oauth-protected-resource/mcp", error_description="This token cannot change data. Make a new API token with edit permissions on the API tokens page, or connect the app again and allow changes."
Content-Type: application/json

{
  "error": "forbidden",
  "error_description": "This token cannot change data. Make a new API token with edit permissions on the API tokens page, or connect the app again and allow changes."
}
```

The error codes of this tool, each with its HTTP status and its sentence:

- `bad_param` (HTTP 400 in the API): A parameter is missing or has a wrong value. The sentence names it.
- `no_campaign` (HTTP 404 in the API): That campaign is not in this account.
- `forbidden` (HTTP 403 in the API, and HTTP 403 in MCP too, see above): This token cannot change data. Make a new API token with edit permissions on the API tokens page, or connect the app again and allow changes.
- `no_access` (HTTP 403 in the API): You have read permissions for this campaign.
- `db_error` (HTTP 500 in the API): The change could not be saved. Nothing was changed.
- `no_hosts` (HTTP 400 in the API): hosts holds no host name or domain: send at least one, such as example.com.
- `host_taken` (HTTP 409 in the API): Not saved: a host of hosts already belongs to another organization of this campaign. The sentence names the host.
- `organization_row_limit` (HTTP 409 in the API): Not saved: a limit of brand names, websites, or competitors is reached. The sentence names the field (brand_names, hosts, or relationship) and the limit.
- `organization_limit` (HTTP 409 in the API): Not added: this campaign already has the most organizations it can hold.
- `bad_host` (HTTP 400 in the API): hosts holds an item that is not a website, or a host of more than 253 characters. The sentence quotes the item. Send a host name, a domain, or a URL in each item.

## Limits

- This tool has its own daily count for the account. When the count is used up, the call is refused with `daily_limit` (HTTP 429 in the API). [account_calls_left](https://oppalerts.com/docs/mcp/account_calls_left) shows the calls left today and when the count resets.
- A refused call does not use the daily count of this tool.
- This tool is not an index search. It does not use the daily count of index searches.
- Only one change runs at a time per account. A call made while another change is running for the account is refused with `one_at_a_time` (HTTP 429 in the API) and uses no daily call. Send it again after a few seconds.
- A campaign that already has the most organizations it can hold refuses a new one with `organization_limit`.

## Same change in the API

```http
POST /v1/campaigns/organization_add HTTP/1.1
Host: api.oppalerts.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{"campaign": 124, "hosts": ["example-hotels.com", "example-hotels.co.uk"], "brand_names": ["Example Hotels", "Example Hotel Group"], "relationship": "org_owned_brand"}
```

The API page is [POST /v1/campaigns/organization_add](https://oppalerts.com/docs/api/campaigns_organization_add).

## Related pages

- [Edit Campaign in the web app](https://oppalerts.com/docs/app/campaign/edit)
- [POST /v1/campaigns/organization_add in the API](https://oppalerts.com/docs/api/campaigns_organization_add)
- [campaigns_organizations](https://oppalerts.com/docs/mcp/campaigns_organizations): the organizations of one campaign
- [campaigns_organization_update](https://oppalerts.com/docs/mcp/campaigns_organization_update): change an organization
- [campaigns_organization_delete](https://oppalerts.com/docs/mcp/campaigns_organization_delete): delete an organization
- [campaigns_rebuild_counts](https://oppalerts.com/docs/mcp/campaigns_rebuild_counts): count the daily counts again
