---
title: "Create HITL config"
method: POST
path: "/api/v1/hitl"
tags: ["HITL"]
---

# Create HITL config

`POST /api/v1/hitl`

## Request

- Base URL: `https://api.proof.holdings`
- URL: `https://api.proof.holdings/api/v1/hitl`
- Auth: HTTP bearer

Create a new HITL configuration with messaging channels and timeout settings.

## Request body

- CreateHitlBody: Request body for creating a HITL configuration
  - `name` string, required: Name for this HITL configuration
  - `channels` HitlChannel[]: At least one messaging channel for approvals. Optional when circle_id is provided (a circle-backed Approval routes through its Circle members).
    - union: A messaging channel configured for HITL approvals
      - object
        - `type` 'telegram', required
        - `config` object, required: Telegram channel configuration
          - `chat_id` string, required: Telegram chat ID for receiving approval requests
      - object
        - `type` 'whatsapp', required
        - `config` object, required: WhatsApp channel configuration — at least one of phone_number or bsuid is required
          - `phone_number` string: Phone number in E.164 format
          - `bsuid` string: WhatsApp Business-Scoped User ID (e.g. US.abc123...)
  - `circle_id` string: Optional Circle to route this Approval through (h-approvals-circle-reshape). When set, recipients come from the circle's members; the caller must own the circle (403 otherwise). Either channels or circle_id is required.
  - `timeout_seconds` number: Default timeout in seconds for confirmations (60–86400)
  - `profile_id` string: Optional public profile to associate with this HITL config for branded messages. When omitted, the user's primary profile is used. The caller must own the profile (403 otherwise).

## Response `201`

HITL config created

- Hitl: HITL configuration with messaging channels and timeout
  - `id` string, required: MongoDB ObjectId
  - `user_id` string, required: MongoDB ObjectId
  - `name` string, nullable
  - `profile_id` string: MongoDB ObjectId
  - `circle_id` string: MongoDB ObjectId
  - `channels` HitlChannel[], required
    - union: A messaging channel configured for HITL approvals
      - object
        - `type` 'telegram', required
        - `config` object, required: Telegram channel configuration
          - `chat_id` string, required: Telegram chat ID for receiving approval requests
      - object
        - `type` 'whatsapp', required
        - `config` object, required: WhatsApp channel configuration — at least one of phone_number or bsuid is required
          - `phone_number` string: Phone number in E.164 format
          - `bsuid` string: WhatsApp Business-Scoped User ID (e.g. US.abc123...)
  - `timeout_seconds` integer, required
  - `status` 'pending' | 'active' | 'archived', required: Status of a HITL configuration
  - `keypair` object, nullable, required: Encryption keypair metadata (null if not configured)
    - `kid` string, required: Key identifier (SHA-256 of public key DER)
    - `has_encrypted_private_key` boolean, required: Whether encrypted private key is stored
    - `has_wrapped_dek` boolean, required: Whether the keypair carries a master-key-wrapped DEK (v2 envelope)
    - `has_backup_wrapper` boolean, required: Whether the DEK carries a recovery (backup-code) wrapper
  - `environment` 'production' | 'test', required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: Validation error
- `403`: profile_mismatch — a project-bound API key named another project (it acts for its own project only); profile_not_owned — the named project does not belong to the account (h-subaccount-branding-per-project)

---

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