# Create Campaign

`POST /api/cc/campaigns`

Create a campaign on one of your agent groups. It starts as `draft`; nothing is called until you [start](/api-docs/campaigns/actions) it.

Requires a Bearer API token (from [Authentication](/api-docs/authentication) / dashboard **API Tokens**) and the **call-center** permission.

Rate limit: 60 requests per minute per account, shared by all Campaign API endpoints.

## Request Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| request_id | string | Yes | 16–64 characters, unique per create. The same id within 15 minutes returns `409 duplicate_request`. |
| name | string | Yes | 1–100 characters. |
| group_id | integer | Yes | `id` from [List Groups](/api-docs/campaigns/groups). |
| phone_numbers | string[] | No | Up to 1,000. Invalid and repeated numbers are skipped and counted, not refused. Add more later with [Add Numbers](/api-docs/campaigns/add-numbers). |
| customer_ring_seconds | integer | No | How long the customer's phone rings, 5–120. Default 30. |
| max_customer_wait_seconds | integer | No | How long an answered customer may wait for an agent, 5–120. Default 20. |

## Request Example

```bash
curl -X POST https://api.awajdigital.com/api/cc/campaigns \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "crm-renewals-2026-10-001",
    "name": "October renewals",
    "group_id": 7,
    "phone_numbers": [
      "01712345678",
      "+8801812345678"
    ]
  }'
```

```javascript
// Browser JavaScript (Fetch API)
const response = await fetch('https://api.awajdigital.com/api/cc/campaigns', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_token_here',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "request_id": "crm-renewals-2026-10-001",
    "name": "October renewals",
    "group_id": 7,
    "phone_numbers": [
      "01712345678",
      "+8801812345678"
    ]
  })
});

const data = await response.json();
console.log(data);
```

```javascript
// Node.js with axios
const axios = require('axios');

async function createCampaign() {
  try {
    const response = await axios.post(
      'https://api.awajdigital.com/api/cc/campaigns',
      {
        "request_id": "crm-renewals-2026-10-001",
        "name": "October renewals",
        "group_id": 7,
        "phone_numbers": [
          "01712345678",
          "+8801812345678"
        ]
      },
      {
        headers: {
          'Authorization': 'Bearer your_api_token_here',
          'Accept': 'application/json',
          'Content-Type': 'application/json'
        }
      }
    );

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

createCampaign();
```

```python
# Python with requests
import requests

def create_campaign():
    url = 'https://api.awajdigital.com/api/cc/campaigns'
    headers = {
        'Authorization': 'Bearer your_api_token_here',
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    }
    payload = {
      "request_id": "crm-renewals-2026-10-001",
      "name": "October renewals",
      "group_id": 7,
      "phone_numbers": [
        "01712345678",
        "+8801812345678"
      ]
    }

    try:
        response = requests.post(url, json=payload, headers=headers)
        print(response.json())
    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')

create_campaign()
```

```php
<?php
// PHP with cURL
$url = 'https://api.awajdigital.com/api/cc/campaigns';
$token = 'your_api_token_here';
$payload = <<<JSON
{
  "request_id": "crm-renewals-2026-10-001",
  "name": "October renewals",
  "group_id": 7,
  "phone_numbers": [
    "01712345678",
    "+8801812345678"
  ]
}
JSON;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Accept: application/json',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>
```

## Success Response Example (201)

```json
{
  "data": {
    "id": 42,
    "name": "October renewals",
    "status": "draft",
    "group_id": 7,
    "group_name": "Sales",
    "contact_count": 2,
    "customer_ring_seconds": 30,
    "max_customer_wait_seconds": 20,
    "started_at": null,
    "stopped_at": null,
    "created_at": "2026-10-21T10:00:00.000+06:00"
  },
  "contacts": {
    "added": 2,
    "duplicates": 0,
    "invalid": 0
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| id | integer | Campaign id. Use it in every `/api/cc/campaigns/:id` path. |
| name | string | The name you gave it. |
| status | string | `draft`, `running`, `paused`, `stopped` or `completed` — see [Statuses](/api-docs/campaigns#statuses). |
| group_id | integer\|null | The agent group taking the calls; `null` if the group was deleted later. |
| group_name | string\|null | The group's name. |
| contact_count | integer | Numbers in the campaign. |
| customer_ring_seconds | integer | How long the customer's phone rings. |
| max_customer_wait_seconds | integer | How long an answered customer may wait for an agent. |
| started_at | string\|null | First start, ISO 8601 with `Asia/Dhaka` offset. |
| stopped_at | string\|null | When it was stopped. |
| created_at | string | When it was created. |
| contacts.added | integer | Numbers added to the campaign. |
| contacts.duplicates | integer | Valid numbers given more than once. |
| contacts.invalid | integer | Entries that are not a Bangladesh mobile number. |

A refused create saves nothing and frees its `request_id`, so you can fix the request and send it again. If the first request did create a campaign, the `409 duplicate_request` response includes its id:

```json
{
  "error": "Request already processed",
  "code": "duplicate_request",
  "campaign_id": 42
}
```

## Error Responses

| Status | Code | Description |
| --- | --- | --- |
| 401 | — | Missing or invalid access token |
| 403 | — | Account does not have the call-center permission |
| 409 | `duplicate_request` | The same `request_id` was used within 15 minutes |
| 422 | `group_not_eligible` | The group is not approved or has no number |
| 422 | `no_valid_numbers` | `phone_numbers` was given but none is valid |
| 422 | — | Validation error (`errors` array) |
| 429 | — | Rate limit exceeded (60 requests/minute) |
| 503 | `engine_unreachable` | The call engine could not be reached; nothing was saved |