InfiVoice Campaigns API

openapi: 3.2.0
info:
  title: InfiVoice REST Campaigns API
  description: Welcome to the InfiVoice REST API documentation. This API enables you to programmatically automate AI-powered voice communications at scale.
  version: 1.0.0
servers:
- url: /api/v1
  description: API v1
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Campaigns
  description: 'Campaigns enable you to call multiple contacts automatically using a single AI agent. Perfect for outreach, reminders, and surveys.


    **Campaign Lifecycle:**

    1. Create a campaign (status: `draft`)

    2. Add contacts to the campaign

    3. Start the campaign (status: `running`)

    4. Monitor progress or pause if needed

    5. Campaign completes when all contacts are called


    **Features:**

    - Schedule campaigns for specific times

    - Set calling windows (e.g., 9 AM - 6 PM)

    - Configure retry attempts for unanswered calls

    - Limit concurrent calls'
paths:
  /campaigns:
    get:
      summary: List Campaigns
      description: 'Retrieve all campaigns with their current status and progress metrics.


        **Campaign Statuses:**

        - `draft` — Created but not started

        - `scheduled` — Waiting for scheduled start time

        - `running` — Actively making calls

        - `paused` — Temporarily stopped

        - `completed` — All contacts processed

        - `cancelled` — Permanently stopped


        **Required Scope:** `campaigns:read`'
      operationId: listCampaigns
      tags:
      - Campaigns
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PageSizeParam'
      responses:
        '200':
          description: List of campaigns with progress metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Create Campaign
      description: 'Create a new bulk calling campaign with optional contacts CSV upload. The campaign starts in `draft` status and won''t execute until you start it.


        **Simplified Workflow:**

        1. Create campaign with contacts CSV → 2. Start campaign


        **Request Format:**

        This endpoint accepts `multipart/form-data` to allow simultaneous campaign creation and contact import.


        **Campaign Data Options:**

        - Send as JSON string in `data` field, OR

        - Send as individual form fields (name, agentId, etc.)


        **CSV Upload (Optional):**

        Include a `contacts` field with your CSV file. Recognized columns:

        - `phone` or `phone_number` — Required

        - `firstName`, `lastName`, `name`, `email`

        - Any other columns become custom fields


        **Configuration Options:**

        - **Calling Windows:** Restrict calls to business hours

        - **Concurrent Calls:** Control call volume (1-100)

        - **Retry Logic:** Automatically retry unanswered calls

        - **Scheduling:** Start immediately or at a future time


        **Required Scope:** `campaigns:write`'
      operationId: createCampaign
      tags:
      - Campaigns
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - name
              - agentId
              properties:
                data:
                  type: string
                  description: Campaign data as JSON string (alternative to individual fields)
                  example: '{"name": "Q1 Outreach", "agentId": "550e8400-e29b-41d4-a716-446655440000"}'
                name:
                  type: string
                  description: Campaign name (use either this or data field)
                  example: Q1 Lead Outreach
                agentId:
                  type: string
                  format: uuid
                  description: Agent to use for calls
                phoneNumberId:
                  type: string
                  format: uuid
                  description: Phone number to call from
                engine:
                  type: string
                  enum:
                  - elevenlabs
                  - plivo
                  - twilio-openai
                  description: Telephony engine
                scheduledStartTime:
                  type: string
                  format: date-time
                  description: When to start the campaign
                timezone:
                  type: string
                  example: America/New_York
                callWindowStart:
                  type: string
                  pattern: ^\d{2}:\d{2}$
                  example: 09:00
                callWindowEnd:
                  type: string
                  pattern: ^\d{2}:\d{2}$
                  example: '18:00'
                maxConcurrentCalls:
                  type: integer
                  minimum: 1
                  maximum: 100
                  example: 10
                contacts:
                  type: string
                  format: binary
                  description: Optional CSV file with contacts
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCampaignRequest'
            examples:
              basic:
                summary: Basic campaign (JSON)
                value:
                  name: Q1 Lead Outreach
                  agentId: 550e8400-e29b-41d4-a716-446655440000
              scheduled:
                summary: Scheduled campaign
                value:
                  name: Appointment Reminders
                  agentId: 550e8400-e29b-41d4-a716-446655440000
                  scheduledStartTime: '2024-01-15T09:00:00Z'
                  timezone: America/New_York
                  callWindowStart: 09:00
                  callWindowEnd: '18:00'
                  maxConcurrentCalls: 10
      responses:
        '201':
          description: Campaign created with optional contact import results
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CampaignResponse'
                - type: object
                  properties:
                    data:
                      type: object
                      properties:
                        contacts:
                          type: object
                          description: Present only if CSV was uploaded
                          properties:
                            fileName:
                              type: string
                            totalRows:
                              type: integer
                            contactsAdded:
                              type: integer
                            contactsSkipped:
                              type: integer
                            invalidRows:
                              type: integer
              example:
                success: true
                data:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  name: Q1 Lead Outreach
                  status: draft
                  agentId: 550e8400-e29b-41d4-a716-446655440001
                  contacts:
                    fileName: leads.csv
                    totalRows: 150
                    contactsAdded: 145
                    contactsSkipped: 3
                    invalidRows: 2
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /campaigns/{id}:
    get:
      summary: Get Campaign Details
      description: 'Retrieve detailed information about a campaign including:

        - Current status and progress

        - Contact counts (total, called, remaining)

        - Schedule and timing information

        - Configuration settings


        **Required Scope:** `campaigns:read`'
      operationId: getCampaign
      tags:
      - Campaigns
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Campaign details with progress metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /campaigns/{id}/contacts:
    post:
      summary: Add Campaign Contacts
      description: 'Add contacts to a campaign''s call list. You can add up to 10,000 contacts per request.


        **Important:** Contacts can only be added when the campaign status is `draft` or `paused`. Running campaigns will reject new contacts.


        **Contact Fields:**

        - `phoneNumber` (required) — Phone number in E.164 format

        - `firstName`, `lastName`, `email` — Optional contact info

        - `customFields` — Key-value pairs for personalization in agent scripts


        **Tip:** Use `customFields` to pass data like appointment times or account numbers that your agent can reference during the call.


        **Required Scope:** `campaigns:write`'
      operationId: addCampaignContacts
      tags:
      - Campaigns
      parameters:
      - $ref: '#/components/parameters/IdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddCampaignContactsRequest'
            examples:
              simple:
                summary: Basic contacts
                value:
                  contacts:
                  - phoneNumber: '+14155551234'
                    firstName: John
                    lastName: Doe
                  - phoneNumber: '+14155555678'
                    firstName: Jane
                    lastName: Smith
              withCustomFields:
                summary: Contacts with custom fields
                value:
                  contacts:
                  - phoneNumber: '+14155551234'
                    firstName: John
                    customFields:
                      appointmentTime: 2:00 PM
                      doctorName: Dr. Smith
      responses:
        '201':
          description: Contacts added with success/skip counts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddContactsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
  /campaigns/{id}/contacts-upload:
    post:
      summary: Upload CSV Contacts
      description: 'Upload a CSV file to add contacts to a campaign. This is the recommended method for bulk contact imports.


        **CSV Format:**

        The CSV must include a header row. Recognized columns:

        - `phone` or `phone_number` — Required, contact phone number

        - `firstName` or `first_name` — First name

        - `lastName` or `last_name` — Last name

        - `name` — Full name (splits into first/last automatically)

        - `email` — Email address

        - Any other columns become custom fields


        **ElevenLabs Format Support:**

        Columns prefixed with `dynamic_data.` are automatically converted to custom fields.


        **Example CSV:**

        ```

        phone,firstName,lastName,appointmentTime

        +14155551234,John,Doe,2:00 PM

        +14155555678,Jane,Smith,3:30 PM

        ```


        **Limits:**

        - Maximum file size: 10MB

        - Maximum contacts: 10,000 per upload


        **Required Scope:** `campaigns:write`'
      operationId: uploadCampaignContacts
      tags:
      - Campaigns
      parameters:
      - $ref: '#/components/parameters/IdParam'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: CSV file containing contacts
      responses:
        '201':
          description: CSV processed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      campaignId:
                        type: string
                        format: uuid
                      fileName:
                        type: string
                        example: contacts.csv
                      totalRows:
                        type: integer
                        description: Total rows parsed from CSV
                        example: 150
                      contactsAdded:
                        type: integer
                        description: New contacts added
                        example: 145
                      contactsSkipped:
                        type: integer
                        description: Duplicate contacts skipped
                        example: 3
                      invalidRows:
                        type: integer
                        description: Rows with invalid phone numbers
                        example: 2
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
  /campaigns/{id}/start:
    post:
      summary: Start Campaign
      description: 'Begin executing a campaign. The system will start placing calls to contacts according to your configuration.


        **Prerequisites:**

        - Campaign must have at least one contact

        - Sufficient credits for estimated calls

        - Associated agent must be active


        **Behavior:**

        - Calls are placed respecting `maxConcurrentCalls` limit

        - Calling windows are honored (no calls outside configured hours)

        - Failed calls are retried based on `retryAttempts` setting


        **Required Scope:** `campaigns:write`'
      operationId: startCampaign
      tags:
      - Campaigns
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Campaign started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignActionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
  /campaigns/{id}/pause:
    post:
      summary: Pause Campaign
      description: 'Temporarily pause a running campaign. Active calls will complete, but no new calls will be initiated.


        **Resume:** Use the Start Campaign endpoint to resume a paused campaign.


        **Use Cases:**

        - Credit running low

        - Need to add more contacts

        - Business hours ended


        **Required Scope:** `campaigns:write`'
      operationId: pauseCampaign
      tags:
      - Campaigns
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Campaign paused. Active calls will complete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignActionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
components:
  schemas:
    Campaign:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        status:
          type: string
          enum:
          - draft
          - scheduled
          - running
          - paused
          - completed
          - cancelled
        agentId:
          type: string
          format: uuid
        phoneNumberId:
          type: string
          format: uuid
        totalContacts:
          type: integer
        calledContacts:
          type: integer
        scheduledStartTime:
          type: string
          format: date-time
        startedAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
    CampaignActionResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            campaignId:
              type: string
            status:
              type: string
            message:
              type: string
        meta:
          $ref: '#/components/schemas/Meta'
    Meta:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        timestamp:
          type: string
          format: date-time
    AddCampaignContactsRequest:
      type: object
      required:
      - contacts
      properties:
        contacts:
          type: array
          minItems: 1
          maxItems: 10000
          items:
            type: object
            required:
            - phoneNumber
            properties:
              phoneNumber:
                type: string
              firstName:
                type: string
              lastName:
                type: string
              email:
                type: string
                format: email
              customFields:
                type: object
                additionalProperties:
                  type: string
    CreateCampaignRequest:
      type: object
      required:
      - name
      - agentId
      properties:
        name:
          type: string
          maxLength: 255
        agentId:
          type: string
          format: uuid
        phoneNumberId:
          type: string
          format: uuid
        engine:
          type: string
          enum:
          - elevenlabs
          - plivo
          - twilio-openai
        scheduledStartTime:
          type: string
          format: date-time
        timezone:
          type: string
          example: America/New_York
        callWindowStart:
          type: string
          pattern: ^\d{2}:\d{2}$
          example: 09:00
        callWindowEnd:
          type: string
          pattern: ^\d{2}:\d{2}$
          example: '18:00'
        maxConcurrentCalls:
          type: integer
          minimum: 1
          maximum: 100
          default: 5
        retryAttempts:
          type: integer
          minimum: 0
          maximum: 5
          default: 2
        retryDelayMinutes:
          type: integer
          minimum: 1
          maximum: 1440
          default: 30
    CampaignListResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/Campaign'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    PaginationMeta:
      allOf:
      - $ref: '#/components/schemas/Meta'
      - type: object
        properties:
          pagination:
            type: object
            properties:
              page:
                type: integer
              pageSize:
                type: integer
              totalItems:
                type: integer
              totalPages:
                type: integer
              hasNext:
                type: boolean
              hasPrev:
                type: boolean
    CampaignResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/Campaign'
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: Invalid request parameters
            details:
              type: object
        meta:
          $ref: '#/components/schemas/Meta'
    AddContactsResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            campaignId:
              type: string
            contactsAdded:
              type: integer
            contactsSkipped:
              type: integer
        meta:
          $ref: '#/components/schemas/Meta'
  responses:
    Conflict:
      description: Resource conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication required or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InsufficientCredits:
      description: Insufficient credits
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    PageSizeParam:
      name: pageSize
      in: query
      description: Items per page (max 100)
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
    PageParam:
      name: page
      in: query
      description: Page number (1-indexed)
      schema:
        type: integer
        default: 1
        minimum: 1
    IdParam:
      name: id
      in: path
      required: true
      description: Resource UUID
      schema:
        type: string
        format: uuid
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token (API key)