---
title: "Manage agency enrollments using a strict reviewed command."
method: POST
path: "/v1/agency-enrollments"
---

# Manage agency enrollments using a strict reviewed command.

`POST /v1/agency-enrollments`

## Request

- Base URL: `https://www.kaicalls.com/api`
- URL: `https://www.kaicalls.com/api/v1/agency-enrollments`
- Auth: HTTP bearer

IDs are in the body. Runtime refinements, current role, assignment and exact approval/hash/lease guards apply. Enrollment creation and commit require a stable Idempotency-Key. Installation run_scenarios also requires evals:write. Care requires sms:write and exact owner approval; preparation creates a draft, launch explicitly queues it. Provider-unknown outcomes require reconciliation. Configuration, testing, activation, billing and measured outcomes are distinct.

## Headers

- `Idempotency-Key` string

## Request body

- union
  - object
    - `action` 'start_self_service', required
    - `offerVersionId` string, uuid, required
    - `name` string, required
    - `facts` object, required
      - `schemaVersion` 1, required
      - `profile` object, required
        - `timezone` string, required
        - `services` string[], required
        - `serviceArea` string, required
        - `hours` string, required
        - `instructions` string, required
        - `website` union, required
          - ''
          - string, uri
        - `reviewUrl` union, required
          - ''
          - string, uri
      - `discovery` object
        - `observations` object[], required
          - `field` string, required
          - `value` union, required
            - string
            - number
            - boolean
            - string[]
          - `sourceRef` string, required
          - `observedAt` string, date-time, nullable, required
          - `state` 'unknown' | 'suggestion' | 'conflict' | 'owner_confirmed', required
          - `revision` string, required
          - `ownerRole` 'client_owner' | 'agency_operator' | 'provider', required
        - `locations` object[], required
          - `id` string, required
          - `label` string, required
          - `serviceArea` string, required
          - `languages` string[], required
          - `timezone` string, required
          - `reviewUrl` union, required
            - string, uri
            - ''
        - `primaryLocationId` string, nullable, required
        - `tools` object[], required
          - `name` string, required
          - `purpose` 'voice' | 'recovery' | 'reviews' | 'email' | 'crm' | 'booking' | 'reporting', required
          - `decision` 'unknown' | 'retain' | 'integrate' | 'coexist' | 'replace', required
          - `executor` 'unknown' | 'kai' | 'existing' | 'human', required
          - `connectionRef` string, nullable, required
      - `intakeCoverage` object
        - `timezone` string, required
        - `schedule` object[], required
          - `day` integer, required
          - `start` string, required
          - `end` string, required
        - `afterHours` string, required
      - `qualification` object[]
        - `question` string, required
        - `instruction` string, required
      - `routing` object
        - `kind` 'owner_notification' | 'crm', required
        - `destination` string, required
        - `destinationPhone` string
        - `connectionRef` string
        - `instruction` string, required
      - `fallback` object
        - `mode` 'callback' | 'transfer', required
        - `instruction` string, required
        - `phone` string
      - `booking` object
        - `enabled` boolean, required
        - `instruction` string, required
      - `faqs` object[]
        - `question` string, required
        - `answer` string, required
      - `reporting` object
        - `timezone` string, required
        - `recipientUserIds` string[], required
  - object
    - `action` 'finish_self_service', required
    - `partnerId` string, uuid, required
    - `sessionId` string, uuid, required
  - object
    - `action` 'owner_save', required
    - `partnerId` string, uuid, required
    - `sessionId` string, uuid, required
    - `expectedRevision` string, uuid, required
    - `facts` object, required
      - `schemaVersion` 1, required
      - `profile` object, required
        - `timezone` string, required
        - `services` string[], required
        - `serviceArea` string, required
        - `hours` string, required
        - `instructions` string, required
        - `website` union, required
          - ''
          - string, uri
        - `reviewUrl` union, required
          - ''
          - string, uri
      - `discovery` object
        - `observations` object[], required
          - `field` string, required
          - `value` union, required
            - string
            - number
            - boolean
            - string[]
          - `sourceRef` string, required
          - `observedAt` string, date-time, nullable, required
          - `state` 'unknown' | 'suggestion' | 'conflict' | 'owner_confirmed', required
          - `revision` string, required
          - `ownerRole` 'client_owner' | 'agency_operator' | 'provider', required
        - `locations` object[], required
          - `id` string, required
          - `label` string, required
          - `serviceArea` string, required
          - `languages` string[], required
          - `timezone` string, required
          - `reviewUrl` union, required
            - string, uri
            - ''
        - `primaryLocationId` string, nullable, required
        - `tools` object[], required
          - `name` string, required
          - `purpose` 'voice' | 'recovery' | 'reviews' | 'email' | 'crm' | 'booking' | 'reporting', required
          - `decision` 'unknown' | 'retain' | 'integrate' | 'coexist' | 'replace', required
          - `executor` 'unknown' | 'kai' | 'existing' | 'human', required
          - `connectionRef` string, nullable, required
      - `intakeCoverage` object
        - `timezone` string, required
        - `schedule` object[], required
          - `day` integer, required
          - `start` string, required
          - `end` string, required
        - `afterHours` string, required
      - `qualification` object[]
        - `question` string, required
        - `instruction` string, required
      - `routing` object
        - `kind` 'owner_notification' | 'crm', required
        - `destination` string, required
        - `destinationPhone` string
        - `connectionRef` string
        - `instruction` string, required
      - `fallback` object
        - `mode` 'callback' | 'transfer', required
        - `instruction` string, required
        - `phone` string
      - `booking` object
        - `enabled` boolean, required
        - `instruction` string, required
      - `faqs` object[]
        - `question` string, required
        - `answer` string, required
      - `reporting` object
        - `timezone` string, required
        - `recipientUserIds` string[], required
  - object
    - `action` 'create', required
    - `partnerId` string, uuid, required
    - `offerVersionId` string, uuid, required
    - `entries` object[], required
      - `businessId` string, uuid
      - `newClient` object
        - `name` string, required
        - `externalRef` string, required
        - `ownerEmail` string, email, required
      - `expectedRevision` string, nullable, required
      - `facts` object, required
        - `schemaVersion` 1, required
        - `profile` object, required
          - `timezone` string, required
          - `services` string[], required
          - `serviceArea` string, required
          - `hours` string, required
          - `instructions` string, required
          - `website` union, required
            - ''
            - string, uri
          - `reviewUrl` union, required
            - ''
            - string, uri
        - `discovery` object
          - `observations` object[], required
            - `field` string, required
            - `value` union, required
              - …
            - `sourceRef` string, required
            - `observedAt` string, date-time, nullable, required
            - `state` 'unknown' | 'suggestion' | 'conflict' | 'owner_confirmed', required
            - `revision` string, required
            - `ownerRole` 'client_owner' | 'agency_operator' | 'provider', required
          - `locations` object[], required
            - `id` string, required
            - `label` string, required
            - `serviceArea` string, required
            - `languages` string[], required
            - `timezone` string, required
            - `reviewUrl` union, required
              - …
          - `primaryLocationId` string, nullable, required
          - `tools` object[], required
            - `name` string, required
            - `purpose` 'voice' | 'recovery' | 'reviews' | 'email' | 'crm' | 'booking' | 'reporting', required
            - `decision` 'unknown' | 'retain' | 'integrate' | 'coexist' | 'replace', required
            - `executor` 'unknown' | 'kai' | 'existing' | 'human', required
            - `connectionRef` string, nullable, required
        - `intakeCoverage` object
          - `timezone` string, required
          - `schedule` object[], required
            - `day` integer, required
            - `start` string, required
            - `end` string, required
          - `afterHours` string, required
        - `qualification` object[]
          - `question` string, required
          - `instruction` string, required
        - `routing` object
          - `kind` 'owner_notification' | 'crm', required
          - `destination` string, required
          - `destinationPhone` string
          - `connectionRef` string
          - `instruction` string, required
        - `fallback` object
          - `mode` 'callback' | 'transfer', required
          - `instruction` string, required
          - `phone` string
        - `booking` object
          - `enabled` boolean, required
          - `instruction` string, required
        - `faqs` object[]
          - `question` string, required
          - `answer` string, required
        - `reporting` object
          - `timezone` string, required
          - `recipientUserIds` string[], required
    - `ownerEmail` string, email
  - object
    - `action` 'save', required
    - `partnerId` string, uuid, required
    - `sessionId` string, uuid, required
    - `expectedRevision` string, uuid, required
    - `entries` object[], required
      - `businessId` string, uuid
      - `newClient` object
        - `name` string, required
        - `externalRef` string, required
        - `ownerEmail` string, email, required
      - `expectedRevision` string, nullable, required
      - `facts` object, required
        - `schemaVersion` 1, required
        - `profile` object, required
          - `timezone` string, required
          - `services` string[], required
          - `serviceArea` string, required
          - `hours` string, required
          - `instructions` string, required
          - `website` union, required
            - ''
            - string, uri
          - `reviewUrl` union, required
            - ''
            - string, uri
        - `discovery` object
          - `observations` object[], required
            - `field` string, required
            - `value` union, required
              - …
            - `sourceRef` string, required
            - `observedAt` string, date-time, nullable, required
            - `state` 'unknown' | 'suggestion' | 'conflict' | 'owner_confirmed', required
            - `revision` string, required
            - `ownerRole` 'client_owner' | 'agency_operator' | 'provider', required
          - `locations` object[], required
            - `id` string, required
            - `label` string, required
            - `serviceArea` string, required
            - `languages` string[], required
            - `timezone` string, required
            - `reviewUrl` union, required
              - …
          - `primaryLocationId` string, nullable, required
          - `tools` object[], required
            - `name` string, required
            - `purpose` 'voice' | 'recovery' | 'reviews' | 'email' | 'crm' | 'booking' | 'reporting', required
            - `decision` 'unknown' | 'retain' | 'integrate' | 'coexist' | 'replace', required
            - `executor` 'unknown' | 'kai' | 'existing' | 'human', required
            - `connectionRef` string, nullable, required
        - `intakeCoverage` object
          - `timezone` string, required
          - `schedule` object[], required
            - `day` integer, required
            - `start` string, required
            - `end` string, required
          - `afterHours` string, required
        - `qualification` object[]
          - `question` string, required
          - `instruction` string, required
        - `routing` object
          - `kind` 'owner_notification' | 'crm', required
          - `destination` string, required
          - `destinationPhone` string
          - `connectionRef` string
          - `instruction` string, required
        - `fallback` object
          - `mode` 'callback' | 'transfer', required
          - `instruction` string, required
          - `phone` string
        - `booking` object
          - `enabled` boolean, required
          - `instruction` string, required
        - `faqs` object[]
          - `question` string, required
          - `answer` string, required
        - `reporting` object
          - `timezone` string, required
          - `recipientUserIds` string[], required
  - object
    - `action` 'preview', required
    - `partnerId` string, uuid, required
    - `sessionId` string, uuid, required
  - object
    - `action` 'enroll', required
    - `partnerId` string, uuid, required
    - `sessionId` string, uuid, required
    - `expectedRevision` string, uuid, required
    - `fingerprint` string, required
    - `approvalIds` string[], required
  - object
    - `action` 'claim_owner', required
    - `partnerId` string, uuid, required
    - `sessionId` string, uuid, required
    - `token` string, required
  - object
    - `action` 'approve_owner', required
    - `partnerId` string, uuid, required
    - `sessionId` string, uuid, required
    - `expectedRevision` string, uuid, required
    - `fingerprint` string, required
  - object
    - `action` 'rotate_owner_link', required
    - `partnerId` string, uuid, required
    - `sessionId` string, uuid, required
    - `expectedRevision` string, uuid, required
  - object
    - `action` 'revoke', required
    - `partnerId` string, uuid, required
    - `sessionId` string, uuid, required

## Response `200`

Recorded command receipt; read back current evidence.

## Other responses

- `202`: Enrollment per-client receipt; inspect waiting and conflict states.
- `400`: Invalid command.
- `403`: Authority or approved owner revision required.
- `409`: State changed or provider reconciliation required.
- `503`: Dependency unavailable; durable operation retained.

---

[API](https://skmtc.dev/kaicalls/apis/kaicalls-public-api.md) · [All operations](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/revisions/e607fc6cf36e?raw)