KaiCalls Customers API

openapi: 3.2.0
info:
  title: KaiCalls Public Customers 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: Customers
paths:
  /v1/customers:
    get:
      summary: Resolve one customer by customer_id, lead_id, phone, email or external_id, or…
      description: A customer is the durable contact record a business has talked to. `customer_id` and `lead_id` are the same value today and both are accepted, so a consumer holding either identifier resolves the same record. Supplying any ONE lookup key switches the endpoint to lookup mode and returns a single customer object (404 when nothing in the calling workspace matches — a value that exists in another workspace is reported identically, so this cannot be used to probe the platform). Supplying two lookup keys is a 400 rather than a silent precedence rule. Without a lookup key the endpoint lists customers ordered by the immutable `created_at`; page with the opaque `next_cursor` and synchronize with `updated_since`. A cursor is bound to the tenant scope, filters and sort order that produced it and is rejected against any other request.
      parameters:
      - name: customer_id
        in: query
        required: false
        schema:
          type: string
      - name: lead_id
        in: query
        required: false
        schema:
          type: string
      - name: phone
        in: query
        required: false
        schema:
          type: string
      - name: email
        in: query
        required: false
        schema:
          type: string
      - name: external_id
        in: query
        required: false
        schema:
          type: string
      - name: business_id
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: string
      - name: updated_since
        in: query
        required: false
        description: Only customers changed at or after this instant. Rows whose updated_at is null fall back to created_at, so nothing is silently excluded from a sync sweep.
        schema:
          type: string
          format: date-time
      - name: cursor
        in: query
        required: false
        description: Opaque cursor from a previous response’s next_cursor.
        schema:
          type: string
      - name: order
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      responses:
        '200':
          description: A customer object (lookup mode) or a cursor-paginated list.
        '400':
          description: More than one lookup key, an invalid cursor, or a bad updated_since.
        '403':
          description: Missing leads:read scope, or business_id outside the key.
        '404':
          description: No customer in the calling workspace matches the lookup.
      x-required-scopes: leads:read
      tags:
      - Customers
      operationId: getV1Customers
      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.