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

# Create Campaign

## Create Campaign

Create a new campaign for the authenticated user. This endpoint accepts multipart/form-data.

## Request Body (multipart/form-data)

<ParamField body name="name" type="string" required>
  Campaign name
</ParamField>

<ParamField body name="phone_number_id" type="integer" required>
  ID of the phone number to use
</ParamField>

<ParamField body name="agent_id" type="string" required>
  ID of the agent to use for calls
</ParamField>

<ParamField body name="recipients_file" type="file" required>
  CSV file with recipient phone numbers. Format: one phone number per line.
</ParamField>

<ParamField body name="send_immediately" type="boolean" required>
  Whether to send the campaign immediately (true) or schedule it (false)
</ParamField>

<ParamField body name="schedule_date" type="string" optional>
  Date in YYYY-MM-DD format (required if send\_immediately is false)
</ParamField>

<ParamField body name="schedule_time" type="string" optional>
  Time in HH:MM:SS format (required if send\_immediately is false)
</ParamField>

## CSV File Format

The recipients file should be a CSV with phone numbers. Example:

```csv theme={null}
phone_number
+1234567890
+0987654321
+1122334455
```

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.example.com/api/v1/campaigns" \
    -H "X-API-Key: your-api-key-here" \
    -F "name=Q1 Product Launch Campaign" \
    -F "phone_number_id=1" \
    -F "agent_id=123" \
    -F "recipients_file=@recipients.csv" \
    -F "send_immediately=true"
  ```

  ```javascript JavaScript theme={null}
  const formData = new FormData();
  formData.append('name', 'Q1 Product Launch Campaign');
  formData.append('phone_number_id', '1');
  formData.append('agent_id', '123');
  formData.append('recipients_file', fileInput.files[0]);
  formData.append('send_immediately', 'true');

  const response = await fetch('https://api.example.com/api/v1/campaigns', {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key-here'
    },
    body: formData
  });

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

  ```python Python theme={null}
  import requests

  headers = {
      'X-API-Key': 'your-api-key-here'
  }

  files = {
      'recipients_file': ('recipients.csv', open('recipients.csv', 'rb'), 'text/csv')
  }

  data = {
      'name': 'Q1 Product Launch Campaign',
      'phone_number_id': 1,
      'agent_id': '123',
      'send_immediately': True
  }

  response = requests.post(
      'https://api.example.com/api/v1/campaigns',
      headers=headers,
      files=files,
      data=data
  )

  result = response.json()
  ```
</RequestExample>

## Scheduled Campaign Example

To schedule a campaign for later:

```bash theme={null}
curl -X POST "https://api.example.com/api/v1/campaigns" \
  -H "X-API-Key: your-api-key-here" \
  -F "name=Scheduled Campaign" \
  -F "phone_number_id=1" \
  -F "agent_id=123" \
  -F "recipients_file=@recipients.csv" \
  -F "send_immediately=false" \
  -F "schedule_date=2024-02-01" \
  -F "schedule_time=10:00:00"
```

## Response

<ResponseField name="status" type="object">
  Response status information

  <ResponseField name="code" type="integer">
    HTTP status code (201)
  </ResponseField>

  <ResponseField name="message" type="string">
    Status message
  </ResponseField>
</ResponseField>

<ResponseField name="data" type="object">
  Created campaign object
</ResponseField>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "status": {
      "code": 201,
      "message": "Campaign created successfully"
    },
    "data": {
      "id": 1,
      "name": "Q1 Product Launch Campaign",
      "status": "pending",
      "elevenlabs_batch_call_id": null,
      "recipients_count": 500,
      "scheduled_at": null,
      "send_immediately": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  }
  ```
</ResponseExample>

## Error Responses

<ResponseField name="401" type="object">
  Unauthorized - Invalid or missing authentication
</ResponseField>

<ResponseField name="404" type="object">
  Phone number or agent not found
</ResponseField>

<ResponseField name="422" type="object">
  Validation error - Invalid request body or file format
</ResponseField>

<ResponseField name="502" type="object">
  Bad gateway - ElevenLabs API error
</ResponseField>