KaiCalls Phone Numbers API

openapi: 3.2.0
info:
  title: KaiCalls Public Phone Numbers 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: Phone Numbers
paths:
  /v1/phone-numbers/available:
    get:
      summary: List currently unassigned phone numbers from the KaiCalls registry
      parameters:
      - name: country
        in: query
        required: false
        schema:
          type: string
      - name: area_code
        in: query
        required: false
        schema:
          type: string
      - name: capability
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      responses:
        '200':
          description: Available phone number list. Additive capability_status reports configured_unverified, blocked or unknown from registry configuration, never live verification. Legacy Boolean capabilities and capability filtering remain unchanged; omit the filter to inspect unknown entries.
      x-required-scopes: numbers:read
      tags:
      - Phone Numbers
      operationId: getV1PhoneNumbersAvailable
      x-operation-id-source: derived
  /v1/phone-numbers:
    get:
      summary: List assigned phone numbers or retrieve one assigned number by phone_number
      parameters:
      - name: business_id
        in: query
        required: false
        schema:
          type: string
      - name: phone_number
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Assigned phone number list or object, including stored provider and additive capability_status (configured_unverified, blocked or unknown). capability_evidence is registry_configuration with runtime_verified=false. Legacy Boolean capabilities are identifier heuristics, not dispatch or delivery proof.
      x-required-scopes: numbers:read
      tags:
      - Phone Numbers
      operationId: getV1PhoneNumbers
      x-operation-id-source: derived
    post:
      summary: Assign an existing registry phone number to a workspace
      responses:
        '200':
          description: Assigned phone number
      x-required-scopes: numbers:write
      tags:
      - Phone Numbers
      operationId: postV1PhoneNumbers
      x-operation-id-source: derived
    delete:
      summary: Release an assigned phone number without deleting historical evidence
      responses:
        '200':
          description: Release result
      x-required-scopes: numbers:write
      tags:
      - Phone Numbers
      operationId: deleteV1PhoneNumbers
      x-operation-id-source: derived
  /v1/phone-numbers/external:
    post:
      summary: Answer one number from your own connected Twilio account with a voice agent…
      description: Reads only the named number from the connected Twilio account. dry_run defaults to true and writes nothing; it returns would_change (VoiceUrl and VoiceMethod) and the unchanged fields. On execute, the only Twilio fields changed are that number's VoiceUrl and VoiceMethod; SmsUrl, SmsMethod, SmsApplicationSid and StatusCallback are read back and must equal their prior values, otherwise they are put back and the request fails. Refuses a number a Twilio app answers, and a number another service answers unless replace_existing_voice is true. Uses one plan line.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - business_id
              - phone_number
              - agent_id
              properties:
                business_id:
                  type: string
                phone_number:
                  type: string
                  description: E.164 number on your own Twilio account.
                agent_id:
                  type: string
                dry_run:
                  type: boolean
                  default: true
                replace_existing_voice:
                  type: boolean
                  default: false
      responses:
        '200':
          description: Dry-run plan, or before/after snapshots of the number.
        '402':
          description: A paid plan is required.
        '404':
          description: Number not in the connected Twilio account.
        '409':
          description: Another service or app answers the number, or it is already attached.
        '500':
          description: Text settings changed during attach; they were put back.
      x-required-scopes: numbers:write
      tags:
      - Phone Numbers
      operationId: postV1PhoneNumbersExternal
      x-operation-id-source: derived
    delete:
      summary: Stop answering a number from your own Twilio account and put its earlier call…
      parameters:
      - name: business_id
        in: query
        required: true
        schema:
          type: string
      - name: phone_number
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Detached; restored VoiceUrl and VoiceMethod.
      x-required-scopes: numbers:write
      tags:
      - Phone Numbers
      operationId: deleteV1PhoneNumbersExternal
      x-operation-id-source: derived
  /v1/phone-numbers/forward:
    post:
      summary: Plan, apply, reconcile or roll back forwarding between two existing owned lines…
      description: Supported Telnyx public source to same-business Twilio ring ingress. Reads the source’s saved ring group and secretary. Calls directly to the target also use that source group while active. Apply requires the exact read-only plan hash; target is verified before source cutover. Reconcile reads carriers without repeating a provider write. Configuration verification does not establish a successful call. No purchase, port, primary-number change or credential grant.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - business_id
              - action
              - source_phone_number
              - target_phone_number
              properties:
                business_id:
                  type: string
                action:
                  type: string
                  enum:
                  - plan
                  - apply
                  - reconcile
                  - rollback
                source_phone_number:
                  type: string
                  description: Existing public source, E.164.
                target_phone_number:
                  type: string
                  description: Existing same-business ring ingress, E.164.
                operation_id:
                  type: string
                  description: Required except for plan. Stable identity; existing operations must be reconciled.
                expected_plan_hash:
                  type: string
                  description: 'Required for apply: exact SHA-256 hash returned by plan.'
      responses:
        '200':
          description: Plan or independently read-back configuration outcome; verified_call_flow remains false.
        '400':
          description: Invalid input or missing reviewed plan hash.
        '403':
          description: Missing numbers:write scope or business access.
        '409':
          description: Line identity, routing drift, active dependency or configuration conflict. No blind retry.
        '502':
          description: Carrier outcome requires reconciliation.
        '503':
          description: Private protection, audit or configuration receipt unavailable; repair remains held.
      x-required-scopes: numbers:write
      tags:
      - Phone Numbers
      operationId: postV1PhoneNumbersForward
      x-operation-id-source: derived
  /v1/phone-numbers/search:
    get:
      summary: Search purchasable phone numbers by area code and country
      parameters:
      - name: area_code
        in: query
        required: false
        schema:
          type: string
      - name: country
        in: query
        required: false
        schema:
          type: string
          default: US
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 20
          default: 10
      responses:
        '200':
          description: Purchasable phone number candidates
      x-required-scopes: numbers:read
      tags:
      - Phone Numbers
      operationId: getV1PhoneNumbersSearch
      x-operation-id-source: derived
  /v1/phone-numbers/purchase:
    post:
      summary: Purchase and assign a phone number (billed as an extra line when over the plan…
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - phone_number
              properties:
                phone_number:
                  type: string
                  description: E.164 number from GET /v1/phone-numbers/search
                business_id:
                  type: string
                agent_id:
                  type: string
                  nullable: true
      responses:
        '200':
          description: Purchased and assigned phone number
      x-required-scopes: numbers:write
      tags:
      - Phone Numbers
      operationId: postV1PhoneNumbersPurchase
      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.