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

# Start Campaign (Number Pool)

> Initiates a new campaign using a managed number pool for outbound calls. Numbers are resolved automatically from the pool (rotation, spam skipping, auto-purchase).

Start a campaign using a managed number pool. Numbers are resolved automatically from the pool — handling rotation, spam skipping, and auto-purchase — so you don't need to specify individual `from_numbers`.

<Warning>
  Before starting a campaign, ensure you have:

  * Uploaded a contact list using [Upload campaign contact list](/api-reference/endpoint/campaign/upload-campaign-contact-list)
  * Configured your agent with the appropriate prompts and settings
  * Created a number pool and added numbers to it
</Warning>

## Request parameters

| Parameter                   | Type   | Required | Description                                             |
| --------------------------- | ------ | -------- | ------------------------------------------------------- |
| `agent_id`                  | string | Yes      | ID of the agent that will handle all campaign calls     |
| `list_id`                   | string | Yes      | ID of the uploaded campaign contact list                |
| `number_pool_id`            | string | Yes      | ID of the managed number pool to use for outbound calls |
| `callback_url`              | string | No       | URL to receive a webhook when the campaign completes    |
| `email_completion_user_ids` | array  | No       | User IDs to notify by email on campaign completion      |

## Standard flow

1. Upload contacts with [Upload campaign contact list](/api-reference/endpoint/campaign/upload-campaign-contact-list).
2. Save the returned `list_id`.
3. Start calls with this endpoint using a `number_pool_id`.
4. Monitor progress with [Get all campaigns](/api-reference/endpoint/campaign/get-all-campaigns).

## Error responses

* **400**: Invalid agent\_id, list\_id, or number\_pool\_id; campaign already started
* **401**: Invalid or missing API key
* **500**: Unexpected server error


## OpenAPI

````yaml post /campaign/v2/start
openapi: 3.0.0
info:
  title: Ringg AI API Documentation
  description: >-
    This is the documentation for the Ringg AI APIs. The Ringg AI API follows
    RESTful principles, making it intuitive and easy to integrate with your
    applications. All API requests should be made to the base URL. The API
    accepts and returns data in JSON format. Ensure your requests include the
    appropriate Content-Type header for POST and PATCH requests.
  version: 2.0.0
servers:
  - url: https://prod-api.ringg.ai/ca/api/v0
security: []
tags:
  - name: workspace
    description: Endpoints for managing your workspace.
  - name: agent
    description: Endpoints for managing assistants (agents).
  - name: calling
    description: Endpoints for making and managing calls.
  - name: campaign
    description: Endpoints for managing campaigns.
  - name: analytics
    description: Endpoints for accessing call analytics and performance metrics.
  - name: termination
    description: Endpoints for terminating active calls using different methods.
  - name: knowledgebase
    description: Endpoints for managing knowledge bases.
paths:
  /campaign/v2/start:
    post:
      tags:
        - campaign
      summary: Start Campaign (Number Pool)
      description: >-
        Initiates a new campaign using a managed number pool for outbound calls.
        Numbers are resolved automatically from the pool (rotation, spam
        skipping, auto-purchase).
      operationId: startCampaignV2
      parameters:
        - name: X-API-KEY
          in: header
          description: (Required) Your Ringg AI API key.
          required: true
          schema:
            type: string
            example: 7251cb4b-3373-43a4-844c-b27a1d45e0c9
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agent_id
                - list_id
                - number_pool_id
              properties:
                agent_id:
                  type: string
                  description: (Required) ID of the agent that will handle the calls.
                  example: 830f767a-397e-4b39-82ff-235cd344e2f9
                list_id:
                  type: string
                  description: (Required) ID of the uploaded campaign contact list.
                  example: 123e4567-e89b-12d3-a456-426614174000
                number_pool_id:
                  type: string
                  description: >-
                    (Required) ID of the managed number pool to use for outbound
                    calls.
                  example: pool-uuid-here
                callback_url:
                  type: string
                  nullable: true
                  description: URL to receive campaign completion webhook.
                  example: https://api.example.com/ringg/campaign-callback
                email_completion_user_ids:
                  type: array
                  items:
                    type: string
                  nullable: true
                  description: User IDs to notify by email when the campaign completes.
              example:
                agent_id: 830f767a-397e-4b39-82ff-235cd344e2f9
                list_id: 123e4567-e89b-12d3-a456-426614174000
                number_pool_id: pool-uuid-here
      responses:
        '200':
          description: Campaign started successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Success message indicating campaign registration.
                    example: campaign registered successfully!
                  has_ongoing_calls:
                    type: boolean
                    description: Whether the workspace has other ongoing calls.
                    example: false
                example:
                  status: campaign registered successfully!
                  has_ongoing_calls: false
        '400':
          description: Bad Request - Invalid input.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: Number pool not found.
        '401':
          description: Unauthorized - Invalid or missing authentication.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: Invalid credentials
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: An unexpected error occurred.

````