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

# Campaign Control — POST /api/v1/campaigns/{id}/control

> Start, pause, or resume a Scalysis bulk calling campaign by posting a control action to the campaign identified by its numeric ID.

Use this endpoint to change the running state of an existing campaign. After you create a campaign, it sits in a `not_started` state until you explicitly start it. You can also pause a running campaign mid-flight — for example, to adjust capacity or investigate an issue — and then resume it when you are ready. All three operations are issued through this single endpoint using the `action` field.

**Endpoint**

```text theme={null}
POST https://app.scalysis.com/api/v1/campaigns/{campaign_id}/control
```

**Authentication**

Include your API key in the request using either the `Authorization` header as a Bearer token or the `X-API-Key` header.

```text theme={null}
Authorization: Bearer <your_api_key>
```

```text theme={null}
X-API-Key: <your_api_key>
```

***

## Path Parameter

<ParamField path="campaign_id" type="number" required>
  The unique numeric ID of the campaign you want to control. This is the `campaign_id` returned when you [created the campaign](/api-reference/campaigns/create).
</ParamField>

***

## Request Body

<ParamField body="action" type="string" required>
  The control action to apply to the campaign. Accepted values:

  | Value      | Description                                                                         |
  | ---------- | ----------------------------------------------------------------------------------- |
  | `"start"`  | Begins dialling contacts. Valid from the `not_started` state.                       |
  | `"pause"`  | Halts dialling without discarding progress. Valid from the `running` state.         |
  | `"resume"` | Continues dialling from where the campaign left off. Valid from the `paused` state. |
</ParamField>

***

## Campaign States

A campaign moves through the following states during its lifecycle:

| State         | Description                                             |
| ------------- | ------------------------------------------------------- |
| `not_started` | Campaign has been created but not yet started.          |
| `running`     | Campaign is actively dialling contacts.                 |
| `paused`      | Campaign has been paused; progress is preserved.        |
| `completed`   | All contacts have been attempted; campaign is finished. |
| `stopped`     | Campaign was stopped and cannot be resumed.             |

***

## Example Requests

<CodeGroup>
  ```bash Start Campaign theme={null}
  curl --request POST \
    --url https://app.scalysis.com/api/v1/campaigns/42/control \
    --header 'Authorization: Bearer <your_api_key>' \
    --header 'Content-Type: application/json' \
    --data '{
      "action": "start"
    }'
  ```

  ```bash Pause Campaign theme={null}
  curl --request POST \
    --url https://app.scalysis.com/api/v1/campaigns/42/control \
    --header 'Authorization: Bearer <your_api_key>' \
    --header 'Content-Type: application/json' \
    --data '{
      "action": "pause"
    }'
  ```

  ```bash Resume Campaign theme={null}
  curl --request POST \
    --url https://app.scalysis.com/api/v1/campaigns/42/control \
    --header 'Authorization: Bearer <your_api_key>' \
    --header 'Content-Type: application/json' \
    --data '{
      "action": "resume"
    }'
  ```
</CodeGroup>

***

## Response Fields

<ResponseField name="success" type="boolean">
  `true` when the control action was successfully applied.
</ResponseField>

<ResponseField name="action" type="string">
  The action that was performed — one of `"start_campaign"`, `"pause_campaign"`, or `"resume_campaign"`.
</ResponseField>

<ResponseField name="campaign_id" type="number">
  The ID of the campaign that was updated, echoed back from the path parameter.
</ResponseField>

<ResponseField name="state" type="string">
  The new state of the campaign after applying the action (e.g. `"running"`, `"paused"`).
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable message confirming what happened (e.g. `"Campaign started"`).
</ResponseField>

***

## Example Success Response

```json theme={null}
{
  "success": true,
  "action": "start_campaign",
  "campaign_id": 42,
  "state": "running",
  "message": "Campaign started"
}
```

***

<Tip>
  **Pause before you stop.** If you need to halt a campaign permanently, prefer using `"pause"` first so you can review progress in the dashboard before deciding. A `stopped` campaign cannot be resumed, so only stop a campaign when you are certain you want to end it entirely.
</Tip>