---
title: "Generic approval-channel intake for an external agent control plane (approvals:write; issued only to trusted control planes, not self-serve mintable via POST /v1/keys). Dispatches a voice approval interaction via the existing outbound-call machinery, tagged with source metadata (approval_source, source_request_id, source_intent_id, source_message_id, source_intent_hash, source_callback_url, approval_expires_at, required_factors) and treated as transactional/user-requested, not marketing outreach, for TCPA/DNC purposes. Zehrava Gate is the first documented source; the contract itself is source-neutral."
method: POST
path: "/v1/approval-requests"
---

# Generic approval-channel intake for an external agent control plane (approvals:write; issued only to trusted control planes, not self-serve mintable via POST /v1/keys). Dispatches a voice approval interaction via the existing outbound-call machinery, tagged with source metadata (approval_source, source_request_id, source_intent_id, source_message_id, source_intent_hash, source_callback_url, approval_expires_at, required_factors) and treated as transactional/user-requested, not marketing outreach, for TCPA/DNC purposes. Zehrava Gate is the first documented source; the contract itself is source-neutral.

`POST /v1/approval-requests`

## Request

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

## Request body

- ApprovalRequestCreate: Generic, provider-neutral approval-channel intake — lets an external agent control plane (first consumer: Zehrava Gate) reach a human by voice and get the interaction tracked through the normal call lifecycle.
  - `source` string, required: Lowercase control-plane slug, e.g. "zehrava-gate".
  - `source_request_id` string, required
  - `source_intent_id` string
  - `message_id` string
  - `responds_to_hash` string
  - `principal_id` string, required
  - `channel` object, required
    - `type` 'voice' | 'voice_then_sms' | 'sms_then_voice' | 'sms', required: Only voice-prefixed types dispatch a live call today; "sms" returns 501.
    - `address` string, required: E.164 phone number.
  - `summary` string, required
  - `risk_level` 'low' | 'medium' | 'high' | 'critical', required
  - `required_factors` string[]
  - `expires_at` string, date-time, required
  - `callback_url` string, uri, required: Must be https and host-allowlisted.
  - `callback_secret_id` string

## Response `202`

Approval interaction dispatched.

## Other responses

- `400`: Malformed request (missing/invalid field).
- `403`: Missing approvals:write scope, or callback_url not allowlisted.
- `410`: Request already expired.
- `422`: Unsupported required_factors entry for this deployment.
- `501`: channel.type "sms" (SMS-only delivery not yet implemented).
- `502`: Provider dispatch failure.
- `503`: No approval-channel agent configured.

---

[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)