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

[Documentation](https://oppalerts.com/docs/) / [API](https://oppalerts.com/docs/api/) / campaigns_create

# campaigns_create

`POST https://api.oppalerts.com/v1/campaigns/create`

Creates a new campaign in your account, with its label, industry, and description.

## What it does

The tool creates a new campaign in your account. Send the label, the industry, and, if you have it, the description. The response contains the new campaign and its id. Send this id as `campaign` to the other campaign tools.

After the call, the new campaign has:

- The label, the industry, and the description that you sent.
- 5 saved opportunities, all brand searches: Brand Mentions, Brand Unlinked Mentions, Brand Link Gap, Competitor Mentions, and Competitor Links.
- No research, no daily counts, and no daily opportunities email. The campaign does not start until it is finalized: see [campaigns_finalize](https://oppalerts.com/docs/api/campaigns_finalize).
- The daily opportunities email is off until [campaigns_set_daily_opportunities_email](https://oppalerts.com/docs/api/campaigns_set_daily_opportunities_email) is called.

The next steps are [campaigns_organization_add](https://oppalerts.com/docs/api/campaigns_organization_add) for your own brand and the competitors, [campaigns_saved_opportunity_add](https://oppalerts.com/docs/api/campaigns_saved_opportunity_add) for more saved opportunities, and [campaigns_finalize](https://oppalerts.com/docs/api/campaigns_finalize). In the web app, the New Campaign page does the same job.

## Who May Call It

- The account owner or an account editor. Any other team member gets the error `no_access`.
- The token needs the scope `api:write`, and `api:read` as every API route does. Without `api:write`, the call gets the error `forbidden`. [Authentication](https://oppalerts.com/docs/getting-started/authentication#scopes) says which tokens have it.

## Authentication

Send your token in the `Authorization: Bearer` header. [The API overview](https://oppalerts.com/docs/api/) explains how to get a token. The API also accepts the same call at `POST /v1/campaigns_create`.

## Parameters

**`label`string, required, at most 255 characters**

Required. The campaign name as shown on the pages, at most 255 characters.

**`industry`string, required, at most 255 characters**

Required. The industry of the campaign, for example Boutique hotels: 2 to 10 words and at most 255 characters. Words are separated by spaces. Fewer or more words are refused with industry_words. It must be different from the industries of the other campaigns of the account.

**`description`string, optional**

Optional. The market description: 100 to 1,000 characters about the market, its buyers, and its sellers, counted after the spaces at the start and the end are removed. A text outside that range is refused with description_length. The research uses it. It can change until the campaign is finalized. Leave it out for no description: [campaigns_finalize](https://oppalerts.com/docs/api/campaigns_finalize) then refuses until [campaigns_update](https://oppalerts.com/docs/api/campaigns_update) sets one. Empty text and text containing only spaces are refused with description_empty.

## Rules

- `label` and `industry` are required, at most 255 characters each. An empty one is refused with `missing_field`.
- `industry` takes 2 to 10 words, separated by spaces. Fewer or more words are refused with `industry_words`.
- `description` is optional: 100 to 1,000 characters, counted after the spaces at the start and the end are removed. A text outside that range is refused with `description_length`. Leave it out for no description: [campaigns_finalize](https://oppalerts.com/docs/api/campaigns_finalize) then refuses until [campaigns_update](https://oppalerts.com/docs/api/campaigns_update) sets one. An empty text, or a text of only spaces, is refused with `description_empty`.
- One industry can be in only one campaign of the account. An industry that another campaign uses is refused with `industry_taken`.
- The plan sets how many campaigns can be active at one time, and the same number of campaigns can be started in any 24 hours.
- No field has a default value.

## Strict Rules

- A field that is not in the list above is refused. The answer is HTTP 400 with the error code `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 new campaign, in the same format that [campaigns_settings](https://oppalerts.com/docs/api/campaigns_settings) returns.

**`campaign.id`int**

The campaign id.

**`campaign.label`string**

The name of the campaign.

**`campaign.industry`string**

The industry of the campaign.

**`campaign.description`string**

The description of the campaign. It is an empty string when the campaign has none.

**`campaign.state`string**

The state of the campaign. The example shows `active`.

**`campaign.finalized`bool**

`true` when the campaign is finalized.

**`campaign.finalized_at`string**

The time when the campaign was finalized, as ISO 8601 text in UTC. Empty when `finalized` is `false`.

**`campaign.research`string**

The progress of the campaign’s research, with the values of `research` in [campaigns_list](https://oppalerts.com/docs/api/campaigns_list). The example shows `not_started`.

**`campaign.started_at`string**

The time when the campaign last counted as a start in the plan limit of campaigns started in 24 hours, as ISO 8601 text in UTC: its create, or [campaigns_activate](https://oppalerts.com/docs/api/campaigns_activate) of a campaign that was never finalized. Empty when the campaign has no such time.

**`campaign.taxonomy_presets`list**

The taxonomy presets of the campaign. Each item is one taxonomy category.

**`campaign.taxonomy_presets[].taxonomy`string**

The taxonomy of the category, as [taxonomy_taxonomies](https://oppalerts.com/docs/api/taxonomy_taxonomies) names it.

**`campaign.taxonomy_presets[].category_id`int**

The id of the category.

**`campaign.taxonomy_presets[].category_label`string**

The label of the category, for example `Travel > Travel Type > Hotels and Motels`.

**`campaign.daily_opportunities_email`object**

The daily opportunities email settings of the campaign.

**`campaign.daily_opportunities_email.enabled`bool**

`true` when the daily opportunities email is on.

**`campaign.daily_opportunities_email.email`string**

The address that gets the daily opportunities email.

**`campaign.daily_opportunities_email.first_name`string**

The first name used in the daily opportunities email.

**`campaign.daily_opportunities_email.send_hour`int**

The hour of the day when the daily opportunities email is sent, in `campaign.daily_opportunities_email.timezone`.

**`campaign.daily_opportunities_email.timezone`string**

The time zone of `send_hour`, for example `America/Los_Angeles`.

**`campaign.daily_opportunities_email.unsubscribed`bool**

`true` when the address unsubscribed from the daily opportunities email.

**`campaign.daily_opportunities_email.unsubscribed_at`string**

The time when the address unsubscribed with the link in the email, as ISO 8601 text in UTC. Empty when `unsubscribed` is `false`.

## Example

### Request

```bash
curl -X POST https://api.oppalerts.com/v1/campaigns/create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Boutique Hotels",
  "industry": "Boutique hotels",
  "description": "Boutique hotel brands competing for direct bookings in mid-size US cities, against the online travel agencies and the big hotel chains."
}'
```

### Response

The response is shown in full.

```json
{
  "campaign": {
    "id": 124,
    "label": "Boutique Hotels",
    "industry": "Boutique hotels",
    "description": "Boutique hotel brands competing for direct bookings in mid-size US cities, against the online travel agencies and the big hotel chains.",
    "state": "active",
    "finalized": false,
    "finalized_at": "",
    "research": "not_started",
    "started_at": "2026-11-01T15:04:05Z",
    "taxonomy_presets": [
      {
        "taxonomy": "iab-content-taxonomy",
        "category_id": 2358064203319202,
        "category_label": "Travel > Travel Type > Hotels and Motels"
      }
    ],
    "daily_opportunities_email": {
      "enabled": false,
      "email": "",
      "first_name": "",
      "send_hour": 0,
      "timezone": "",
      "unsubscribed": false,
      "unsubscribed_at": ""
    }
  }
}
```

## Errors

An error has an HTTP status and a JSON body with `error`, the error code, and `error_description`, the message. An example: a call with a token that does not have the scope `api:write`. This answer also has a `WWW-Authenticate` header with `error="insufficient_scope"` and the scopes that the call needs.

```http
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="api:read api:write", resource_metadata="https://api.oppalerts.com/.well-known/oauth-protected-resource/v1", 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): A parameter is missing or has a wrong value. The sentence names it.
- `forbidden` (HTTP 403): 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): Only the account owner or an account editor can do this.
- `db_error` (HTTP 500): The change could not be saved. Nothing was changed.
- `missing_field` (HTTP 400): label or industry is empty. The sentence names the field.
- `description_empty` (HTTP 400): description is empty or holds only spaces. Send the description of the campaign, or leave the field out for no description.
- `industry_words` (HTTP 400): industry takes 2 to 10 words.
- `description_length` (HTTP 400): description has fewer than 100 or more than 1,000 characters after the spaces at its start and end are removed. The sentence gives the count. Send 100 to 1,000 characters.
- `campaign_limit` (HTTP 409): Not created: this account already has the most active campaigns its plan allows. Archive one first.
- `activation_limit` (HTTP 409): Not created: the plan limit of campaigns started in the last 24 hours is reached. Try again in 24 hours.
- `industry_taken` (HTTP 409): Not created: another campaign in your account uses this industry. Choose a different industry.

## 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). [account_calls_left](https://oppalerts.com/docs/api/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) and uses no daily call. Send it again after a few seconds.
- The plan sets how many campaigns can be active at one time (`campaign_limit`), and the same number of campaigns can be started in any 24 hours (`activation_limit`).

## Same tool in MCP

The MCP tool is `campaigns_create`. See [campaigns_create in MCP](https://oppalerts.com/docs/mcp/campaigns_create).

## Related pages

- [New Campaign in the web app](https://oppalerts.com/docs/app/campaign/new)
- [campaigns_create in MCP](https://oppalerts.com/docs/mcp/campaigns_create)
- [campaigns_finalize](https://oppalerts.com/docs/api/campaigns_finalize): start the campaign
- [campaigns_update](https://oppalerts.com/docs/api/campaigns_update): change the label, the industry, or the description
- [campaigns_organization_add](https://oppalerts.com/docs/api/campaigns_organization_add): add your brand and the competitors
- [campaigns_saved_opportunity_add](https://oppalerts.com/docs/api/campaigns_saved_opportunity_add): add a saved opportunity
- [campaigns_list](https://oppalerts.com/docs/api/campaigns_list): the campaigns of the account and their ids
- [Set Up Your First Campaign](https://oppalerts.com/docs/getting-started/set-up-your-first-campaign)
