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

# Create Campaign (v1)

> Create a campaign with a required agent ID that will be used for all calls

<Note>
  Create a campaign to organize multiple calls under a single ID. Requires an `agent_id` that will be used for all calls in this campaign.
</Note>

## Quick Example

```bash theme={null}
curl -X POST https://api.callkaro.ai/call/campaign \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "name": "Sales Campaign Q1",
    "agent_id": "6803fa770b666a64ab1694c1e"
  }'
```

## Workflow

<Steps>
  <Step title="Create the campaign">
    ```bash theme={null}
    curl -X POST https://api.callkaro.ai/call/campaign \
      -H "X-API-KEY: your_api_key_here" \
      -d '{
        "name": "Inspection Campaign",
        "agent_id": "6803fa770b666a64ab1694c1e"
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "batch_id": "68433b7b0dee98e59245ebab",
      "message": "Campaign created successfully",
      "status": "success"
    }
    ```
  </Step>

  <Step title="Add calls to the campaign">
    Use the `batch_id` from step 1 with the outbound call API:

    ```bash theme={null}
    curl -X POST https://api.callkaro.ai/call/outbound \
      -H "X-API-KEY: your_api_key_here" \
      -d '{
        "to_number": "+919876543210",
        "batch_id": "68433b7b0dee98e59245ebab",
        "agent_id": "6803fa770b666a64ab1694c1e",
        "metadata": {
          "name": "Abhinav",
          "city": "Bangalore"
        },
        "schedule_at": "2025-12-31T09:30:00",
        "min_trigger_time": "09:00",
        "max_trigger_time": "18:00",
        "number_of_retries": 3,
        "gap_between_retries": 30
      }'
    ```
  </Step>

  <Step title="Monitor in dashboard">
    Track campaign performance at `/dashboard/batch-calls/{batch_id}`
  </Step>
</Steps>

## When to Use v1

Use Campaign v1 when:

* ✅ All calls will use the **same agent**
* ✅ You have the agent ID ready
* ✅ You want simpler campaign management

<Info>
  **Need flexibility?** Use [Campaign v2](/api-reference/campaign-v2) if you want to use different agents for different calls in the same campaign.
</Info>

## Response

### Success (200 OK)

```json theme={null}
{
  "batch_id": "68433b7b0dee98e59245ebab",
  "message": "Campaign created successfully",
  "status": "success"
}
```

Save the `batch_id` - you'll need it to add calls to this campaign!

## Tips

<Tip>
  **Organize your campaigns**: Use descriptive names like "Q1 Sales Outreach" or "December Follow-ups" to easily identify them in the dashboard.
</Tip>

<Tip>
  **Same agent requirement**: All calls added to a v1 campaign must use the same `agent_id` that was specified when creating the campaign.
</Tip>


## OpenAPI

````yaml POST /call/campaign
openapi: 3.1.0
info:
  title: CallKaro AI API
  description: Campaign and outbound call management API for CallKaro AI voice agents
  version: 1.0.0
  contact:
    name: CallKaro AI Support
    email: support@callkaro.ai
    url: https://callkaro.ai
servers:
  - url: https://api.callkaro.ai
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /call/campaign:
    post:
      tags:
        - Endpoints
      summary: Create Campaign (v1)
      description: >-
        Create a campaign with a required agent ID that will be used for all
        calls
      operationId: createCampaignV1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignV1Request'
            example:
              name: Sales Campaign Q1
              agent_id: 6803fa770b666a64ab1694c1e
      responses:
        '200':
          description: Campaign created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignResponse'
              example:
                batch_id: 68433b7b0dee98e59245ebab
                message: Campaign created successfully
                status: success
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: error
                message: Missing agent_id
        '403':
          description: Forbidden - Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CampaignV1Request:
      type: object
      required:
        - name
        - agent_id
      properties:
        name:
          type: string
          description: Campaign name for identification and organization
          example: Sales Campaign Q1
          minLength: 1
          maxLength: 200
        agent_id:
          type: string
          description: ID of the agent that will be used for all calls in this campaign
          example: 6803fa770b666a64ab1694c1e
    CampaignResponse:
      type: object
      properties:
        batch_id:
          type: string
          description: Unique identifier for the created campaign
          example: 68433b7b0dee98e59245ebab
        message:
          type: string
          example: Campaign created successfully
        status:
          type: string
          example: success
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: error
        message:
          type: string
          description: Error description
          example: 'Missing required field: to_number'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key from https://callkaro.ai/dashboard/api-key

````