KaiCalls Campaigns API

openapi: 3.2.0
info:
  title: KaiCalls Public Campaigns API
  version: '2026-06-05'
  description: Machine-readable surface for KaiCalls external developers and client agents.
servers:
- url: https://www.kaicalls.com/api
security:
- bearerAuth: []
tags:
- name: Campaigns
paths:
  /v1/campaigns:
    get:
      summary: List campaigns (filter by status) or retrieve one by id (with enrolled-lead…
      parameters:
      - name: id
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: string
      - name: business_id
        in: query
        required: false
        schema:
          type: string
      x-required-scopes: calls:read
      tags:
      - Campaigns
      operationId: getV1Campaigns
      x-operation-id-source: derived
    post:
      summary: Create a draft outbound campaign (cadence + optional lead batch).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - cadence_config
              properties:
                business_id:
                  type: string
                name:
                  type: string
                description:
                  type: string
                cadence_config:
                  type: object
                  properties:
                    template:
                      type: string
                    attempts:
                      type: integer
                lead_ids:
                  type: array
                  items:
                    type: string
      x-required-scopes: calls:write
      tags:
      - Campaigns
      operationId: postV1Campaigns
      x-operation-id-source: derived
    patch:
      summary: Launch/resume (action=launch, needs agent_id) or pause (action=pause) a…
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              - action
              properties:
                id:
                  type: string
                action:
                  type: string
                  enum:
                  - launch
                  - pause
                agent_id:
                  type: string
                business_id:
                  type: string
      x-required-scopes: calls:write
      tags:
      - Campaigns
      operationId: patchV1Campaigns
      x-operation-id-source: derived
  /v1/campaigns/audit-context:
    get:
      summary: Read unique, tenant-bound audit context for an inbound caller.
      parameters:
      - name: business_id
        in: query
        required: false
        schema:
          type: string
      - name: agent_id
        in: query
        required: true
        schema:
          type: string
      - name: phone
        in: query
        required: true
        schema:
          type: string
          pattern: ^\+[1-9]\d{7,14}$
      responses:
        '200':
          description: Held audit context, or null for an unknown, ambiguous, suppressed or expired binding
        '400':
          description: Missing agent or invalid E.164 phone
        '403':
          description: Missing leads:read scope or business access
      x-required-scopes: leads:read
      tags:
      - Campaigns
      operationId: getV1CampaignsAuditContext
      x-operation-id-source: derived
  /v1/campaigns/audit-activation:
    get:
      summary: Read audit-attributed activation and payment evidence through canonical…
      description: Requires access to both source and customer businesses. Performs provider reads only; does not provision, send notifications, reconcile activation state or release campaign dispatch. Existing payments without this audit and checkout binding do not count as campaign revenue.
      parameters:
      - name: business_id
        in: query
        required: false
        schema:
          type: string
      - name: customer_business_id
        in: query
        required: true
        schema:
          type: string
      - name: lead_id
        in: query
        required: true
        schema:
          type: string
      - name: audit_id
        in: query
        required: true
        schema:
          type: string
      - name: checkout_session_id
        in: query
        required: true
        schema:
          type: string
          pattern: ^cs_[A-Za-z0-9_]{1,200}$
      responses:
        '200':
          description: Independent checkout, activation and paid flags with bound receipt identifiers; outbound remains held
        '400':
          description: Missing audit, lead or checkout identifiers
        '403':
          description: Missing required read scopes or source/customer business access
        '404':
          description: Audit binding unavailable
        '503':
          description: Activation or Stripe evidence unavailable; no success inferred
      x-required-scopes:
        allOf:
        - leads:read
        - workspaces:read
        - billing:read
      tags:
      - Campaigns
      operationId: getV1CampaignsAuditActivation
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'KaiCalls API key. Per-operation scope requirements are published on each operation as `x-required-scopes` — a scope string, or a nested `{ allOf: [...] }` / `{ anyOf: [...] }` expression. An operation with no `x-required-scopes` requires a valid key but no particular scope.'
      x-scopes:
      - workspaces:read
      - workspaces:write
      - numbers:read
      - numbers:write
      - agents:read
      - agents:write
      - communication-runs:read
      - communication-runs:write
      - calls:read
      - calls:write
      - sms:read
      - sms:write
      - webhooks:read
      - webhooks:write
      - events:read
      - events:replay
      - lifecycle:write
      - leads:read
      - leads:write
      - emails:read
      - emails:write
      - sdr:read
      - sdr:write
      - evals:read
      - evals:write
      - appointments:read
      - appointments:write
      - knowledge:read
      - knowledge:write
      - products:read
      - products:write
      - integrations:write
      - approvals:write
      - concierge:write
      - billing:read
      - billing:write
      - call_evidence:read
      - call_evidence:write
      - support:write
    sessionAuth:
      type: apiKey
      in: cookie
      name: sb-access-token
      description: Authenticated dashboard session cookie. Used by first-party flows that mint or manage API keys.