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

# Create Campaign

> Crea una nueva Campaña para tu organización. Usa `integration_type` para seleccionar entre llamada telefónica o WhatsApp; los campos exclusivos del canal contrario son rechazados.

<Info>
  **Rate Limit:** 12 requests per second
</Info>

<Tip>
  Pass an `Idempotency-Key` header (UUID recommended) so retries don't create
  duplicate campaigns.
</Tip>

## Channel-specific Fields

| Field           | Channel      |
| :-------------- | :----------- |
| `first_message` | `phone_call` |
| `template`      | `whatsapp`   |
| `template_alt`  | `whatsapp`   |

Sending a channel-only field for the wrong `integration_type` returns a `400 INVALID_REQUEST`.

## Cycles

`cycles` is optional. When `cycles.enabled` is `false` (or omitted), the rest of the cycles block is ignored. When `cycles.mode` is `cooldown`, `schedule*` fields are rejected. Cycles can be enabled only at creation time; `cycles.enabled` and `cycles.mode` are immutable thereafter.

## Examples

### Phone-call campaign with cooldown cycles

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.altur.io/api/v1.0/campaigns" \
    -H "Authorization: api-key YOUR_API_SECRET_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: 6f0b2c8c-2a7e-4f5e-9b6a-3a2e8b9c4d10" \
    -d '{
      "name": "Q2 Reactivation",
      "agent_id": "6cy951e6-9877-4d7c-88d7-56b4948d3cce",
      "integration_id": "iph_8YqL3mZxR1tV0nKfH9bA",
      "integration_type": "phone_call",
      "timezone": "America/Mexico_City",
      "first_message": "Hi, am I speaking with {name}?",
      "cycles": {
        "enabled": true,
        "mode": "cooldown",
        "max_iterations": 3,
        "cooldown_minutes": 30,
        "filter_statuses": ["converted"]
      }
    }'
  ```

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

  payload = {
      "name": "Q2 Reactivation",
      "agent_id": "6cy951e6-9877-4d7c-88d7-56b4948d3cce",
      "integration_id": "iph_8YqL3mZxR1tV0nKfH9bA",
      "integration_type": "phone_call",
      "timezone": "America/Mexico_City",
      "first_message": "Hi, am I speaking with {name}?",
      "cycles": {
          "enabled": True,
          "mode": "cooldown",
          "max_iterations": 3,
          "cooldown_minutes": 30,
          "filter_statuses": ["converted"],
      },
  }

  response = requests.post(
      "https://api.altur.io/api/v1.0/campaigns",
      headers={
          "Authorization": "api-key YOUR_API_SECRET_KEY",
          "Idempotency-Key": str(uuid.uuid4()),
      },
      json=payload,
  )
  response.raise_for_status()
  campaign = response.json()["campaign"]
  print(campaign["id"])
  ```

  ```javascript JavaScript theme={null}
  const payload = {
    name: "Q2 Reactivation",
    agent_id: "6cy951e6-9877-4d7c-88d7-56b4948d3cce",
    integration_id: "iph_8YqL3mZxR1tV0nKfH9bA",
    integration_type: "phone_call",
    timezone: "America/Mexico_City",
    first_message: "Hi, am I speaking with {name}?",
    cycles: {
      enabled: true,
      mode: "cooldown",
      max_iterations: 3,
      cooldown_minutes: 30,
      filter_statuses: ["converted"],
    },
  };

  const res = await fetch("https://api.altur.io/api/v1.0/campaigns", {
    method: "POST",
    headers: {
      Authorization: "api-key YOUR_API_SECRET_KEY",
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify(payload),
  });
  const { campaign } = await res.json();
  ```
</CodeGroup>

### WhatsApp campaign

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.altur.io/api/v1.0/campaigns" \
    -H "Authorization: api-key YOUR_API_SECRET_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Promo June",
      "agent_id": "6cy951e6-9877-4d7c-88d7-56b4948d3cce",
      "integration_id": "iwa_8YqL3mZxR1tV0nKfH9bA",
      "integration_type": "whatsapp",
      "template": "promo_june_v1"
    }'
  ```

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

  response = requests.post(
      "https://api.altur.io/api/v1.0/campaigns",
      headers={"Authorization": "api-key YOUR_API_SECRET_KEY"},
      json={
          "name": "Promo June",
          "agent_id": "6cy951e6-9877-4d7c-88d7-56b4948d3cce",
          "integration_id": "iwa_8YqL3mZxR1tV0nKfH9bA",
          "integration_type": "whatsapp",
          "template": "promo_june_v1",
      },
  )
  response.raise_for_status()
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://api.altur.io/api/v1.0/campaigns", {
    method: "POST",
    headers: {
      Authorization: "api-key YOUR_API_SECRET_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Promo June",
      agent_id: "6cy951e6-9877-4d7c-88d7-56b4948d3cce",
      integration_id: "iwa_8YqL3mZxR1tV0nKfH9bA",
      integration_type: "whatsapp",
      template: "promo_june_v1",
    }),
  });
  ```
</CodeGroup>


## OpenAPI

````yaml POST /campaigns
openapi: 3.0.1
info:
  title: Altur API
  description: >-
    An API aimed to allow third-party developers to interact with the Altur
    platform through a RESTful interface.
  license:
    name: MIT
  version: '1.0'
servers:
  - url: https://api.altur.io/api/v1.0
security:
  - apiKeyAuth: []
paths:
  /campaigns:
    post:
      description: >-
        Creates a new Campaign for your organization. Use `integration_type` to
        select between phone-call and WhatsApp; channel-only fields are rejected
        when they don't match the chosen type.
      parameters:
        - name: Idempotency-Key
          in: header
          description: >-
            Optional client-generated key (UUID recommended) to make the request
            idempotent. Replays within the dedup window return the original
            response.
          schema:
            type: string
          required: false
      requestBody:
        description: Campaign to be created
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignCreate'
      responses:
        '201':
          description: Campaign created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignDetailResponse'
        '400':
          description: Invalid input or unsupported integration type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Billing limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignApiError'
        '404':
          description: Agent or Integration not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignApiError'
components:
  schemas:
    CampaignCreate:
      type: object
      required:
        - name
        - agent_id
        - integration_id
        - integration_type
      properties:
        name:
          type: string
          maxLength: 255
        description:
          type: string
        agent_id:
          type: string
          format: uuid4
          description: '`public_id` of the agent that will own this campaign.'
        integration_id:
          type: string
          description: '`public_id` of the integration to use. Must belong to `agent_id`.'
        integration_type:
          type: string
          enum:
            - phone_call
            - whatsapp
        timezone:
          type: string
          description: IANA timezone. Defaults to `America/Mexico_City`.
        retries:
          type: integer
          minimum: 0
          maximum: 5
          default: 1
        message_limit:
          type: integer
          minimum: 1
          maximum: 10000
          default: 250
        first_message:
          type: string
          description: >-
            First message the Agent will say upon the call being answered.
            Phone-call only.
        template:
          type: string
          description: WhatsApp template name. WhatsApp only.
        template_alt:
          type: string
          description: Alternate WhatsApp template name. WhatsApp only.
        scheduling:
          $ref: '#/components/schemas/CampaignSchedule'
        cycles:
          $ref: '#/components/schemas/CampaignCyclesConfig'
    CampaignDetailResponse:
      type: object
      properties:
        success:
          type: boolean
        campaign:
          $ref: '#/components/schemas/CampaignDetail'
    CampaignApiError:
      type: object
      description: Standard error envelope returned by the v1.0 campaigns API.
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Stable, UPPER_SNAKE_CASE error key.
          enum:
            - FORBIDDEN
            - NOT_FOUND
            - RATE_LIMITED
            - SERVER_ERROR
            - INVALID_REQUEST
            - INVALID_STATUS
            - IMMUTABLE_FIELD
            - UNKNOWN_ACTION
            - AGENT_NOT_FOUND
            - INTEGRATION_NOT_FOUND
            - INVALID_INTEGRATION_TYPE
            - INVALID_FILTER_TAG
            - INVALID_PHONE_NUMBER
            - MISSING_CONTACT
            - CONTACT_NOT_FOUND
            - CONTACT_NOT_DELETABLE
            - CAMPAIGN_FINISHED
            - CYCLES_NOT_ENABLED
            - SCHEDULED_MODE_ONLY
            - INVALID_STATUS_TRANSITION
            - BILLING_LIMIT_REACHED
        message:
          type: string
        field:
          type: string
          description: >-
            Set when `error` is `IMMUTABLE_FIELD`; identifies the offending
            field path.
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
    CampaignSchedule:
      type: object
      properties:
        mon:
          $ref: '#/components/schemas/CampaignScheduleDay'
          description: Monday
          type: object
        tue:
          $ref: '#/components/schemas/CampaignScheduleDay'
          description: Tuesday
          type: object
        wed:
          $ref: '#/components/schemas/CampaignScheduleDay'
          description: Wednesday
          type: object
        thu:
          $ref: '#/components/schemas/CampaignScheduleDay'
          description: Thursday
          type: object
        fri:
          $ref: '#/components/schemas/CampaignScheduleDay'
          description: Friday
          type: object
        sat:
          $ref: '#/components/schemas/CampaignScheduleDay'
          description: Saturday
          type: object
        sun:
          $ref: '#/components/schemas/CampaignScheduleDay'
          description: Sunday
          type: object
    CampaignCyclesConfig:
      type: object
      description: Cycles configuration block. Phone-call campaigns only.
      properties:
        enabled:
          type: boolean
          description: Whether cycles are enabled. Immutable after creation.
        mode:
          type: string
          enum:
            - cooldown
            - scheduled
          description: Cycle mode. Immutable after creation.
        max_iterations:
          type: integer
          minimum: 2
          maximum: 12
        cooldown_minutes:
          type: integer
          minimum: 0
          maximum: 1440
        filter_statuses:
          type: array
          items:
            type: string
          description: Contact statuses excluded from the next iteration.
        filter_tags:
          type: array
          items:
            type: string
          description: >-
            Thread tag ids whose contacts are excluded from the next iteration.
            Input-only — not returned on the detail response.
        schedule:
          $ref: '#/components/schemas/CampaignSchedule'
          description: Per-day schedule. Only used when `mode` = `scheduled`.
        schedule_start_date:
          type: string
          format: date
          nullable: true
          description: Only used when `mode` = `scheduled`.
        schedule_end_date:
          type: string
          format: date
          nullable: true
          description: Only used when `mode` = `scheduled`.
    CampaignDetail:
      type: object
      description: >-
        Single Campaign detail with nested agent, integration and cycles config.
        The `analytics` field is included only when a snapshot is available for
        the campaign.
      properties:
        id:
          description: Unique identifier for the Campaign
          type: integer
        name:
          description: Name of the Campaign
          type: string
        status:
          description: Current status of the Campaign
          type: string
          enum:
            - pending
            - ready
            - active
            - inactive
            - cooldown
            - finished
        integration:
          description: Nested {id, type} of the integration the Campaign was created on
          type: object
          nullable: true
          properties:
            id:
              type: string
            type:
              type: string
              enum:
                - phone_call
                - whatsapp
        agent:
          type: object
          properties:
            id:
              type: string
              format: uuid4
            name:
              type: string
        created_at:
          type: string
          format: date-time
        scheduling:
          $ref: '#/components/schemas/CampaignSchedule'
        cycles:
          $ref: '#/components/schemas/CampaignCyclesConfig'
        analytics:
          description: >-
            Analytics snapshot for the Campaign. Shape depends on
            `integration.type` — see `CampaignAnalyticsPhoneCall` and
            `CampaignAnalyticsWhatsApp`.
          type: object
    CampaignScheduleDay:
      type: object
      properties:
        startTime:
          description: Start time of the Campaign on Monday
          type: string
        stopTime:
          description: End time of the Campaign on Monday
          type: string
        active:
          description: Boolean describing if the Campaign is active on Monday
          type: boolean
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Add `api-key YOUR_API_SECRET_KEY` as the value of the `Authorization`
        header.

````