KaiCalls Funnel API

openapi: 3.2.0
info:
  title: KaiCalls Public Funnel 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: Funnel
paths:
  /v1/funnel:
    get:
      summary: 'Read the business''s funnel config (leads:read): ordered stages, each owned by…'
      parameters:
      - name: business_id
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Funnel config (or null) and templates
      x-required-scopes: leads:read
      tags:
      - Funnel
      operationId: getV1Funnel
      x-operation-id-source: derived
    put:
      summary: Create or replace the business's funnel (leads:write).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                business_id:
                  type: string
                template_key:
                  type: string
                name:
                  type: string
                  maxLength: 80
                stages:
                  type: array
                  minItems: 2
                  maxItems: 20
                  items:
                    type: object
                    required:
                    - key
                    - label
                    properties:
                      key:
                        type: string
                        pattern: ^[a-z][a-z0-9_]{0,63}$
                      label:
                        type: string
                        maxLength: 80
                      kind:
                        type: string
                        enum:
                        - open
                        - won
                        - lost
                      source:
                        type: string
                        enum:
                        - native
                        - external
                      native_event:
                        type: string
                        enum:
                        - lead.created
                        - call.completed
                        - appointment.booked
                      sla_hours:
                        type: number
                      suggested_action:
                        type: string
      responses:
        '200':
          description: Saved funnel config
        '400':
          description: Invalid template or stages
      x-required-scopes: leads:write
      tags:
      - Funnel
      operationId: putV1Funnel
      x-operation-id-source: derived
  /v1/funnel/events:
    get:
      summary: List recent funnel stage events for the business, or for one job with ?job_id=…
      parameters:
      - name: business_id
        in: query
        required: false
        schema:
          type: string
      - name: job_id
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Stage events, newest first
      x-required-scopes: leads:read
      tags:
      - Funnel
      operationId: getV1FunnelEvents
      x-operation-id-source: derived
    post:
      summary: Record a funnel stage move from an outside system (leads:write).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - idempotency_key
              - stage_key
              properties:
                business_id:
                  type: string
                idempotency_key:
                  type: string
                  maxLength: 200
                stage_key:
                  type: string
                occurred_at:
                  type: string
                  format: date-time
                amount_cents:
                  type: integer
                  minimum: 0
                job_external_ref:
                  type: string
                job_id:
                  type: string
                lead_id:
                  type: string
                phone:
                  type: string
                title:
                  type: string
                lost_reason:
                  type: string
                fields:
                  type: object
                imported:
                  type: boolean
      responses:
        '200':
          description: 'Duplicate idempotency_key: the original event and job'
        '201':
          description: 'Recorded: event, job, stage_changed'
        '202':
          description: 'Unmatched: parked for the owner to pick the customer'
        '404':
          description: job_id or lead_id not found for this business
        '409':
          description: The business has no funnel
        '422':
          description: Unknown stage_key, or a stage KaiCalls sets itself
      x-required-scopes: leads:write
      tags:
      - Funnel
      operationId: postV1FunnelEvents
      x-operation-id-source: derived
  /v1/funnel/jobs:
    get:
      summary: List funnel jobs (filter by stage, status, lead_id), or one job with its stage…
      parameters:
      - name: business_id
        in: query
        required: false
        schema:
          type: string
      - name: job_id
        in: query
        required: false
        schema:
          type: string
      - name: stage
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - open
          - won
          - lost
      - name: lead_id
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Jobs, or one job with events
        '404':
          description: Job not found
      x-required-scopes: leads:read
      tags:
      - Funnel
      operationId: getV1FunnelJobs
      x-operation-id-source: derived
  /v1/funnel/report:
    get:
      summary: 'Funnel report (leads:read): jobs per stage, step conversion and median days…'
      parameters:
      - name: business_id
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Funnel report
      x-required-scopes: leads:read
      tags:
      - Funnel
      operationId: getV1FunnelReport
      x-operation-id-source: derived
  /v1/funnel/unmatched:
    get:
      summary: List funnel events that could not be tied to exactly one customer (leads:read).
      parameters:
      - name: business_id
        in: query
        required: false
        schema:
          type: string
      - name: include_resolved
        in: query
        required: false
        schema:
          type: boolean
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Unmatched events
      x-required-scopes: leads:read
      tags:
      - Funnel
      operationId: getV1FunnelUnmatched
      x-operation-id-source: derived
    post:
      summary: Resolve an unmatched funnel event by naming the job or lead it belongs to…
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - unmatched_id
              properties:
                business_id:
                  type: string
                unmatched_id:
                  type: string
                job_id:
                  type: string
                lead_id:
                  type: string
      responses:
        '200':
          description: 'Replayed: event, job, stage_changed'
        '404':
          description: Unmatched event not found
        '409':
          description: Already resolved
      x-required-scopes: leads:write
      tags:
      - Funnel
      operationId: postV1FunnelUnmatched
      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.