---
title: "Finalize HITL config"
method: POST
path: "/api/v1/hitl/{id}/finalize"
tags: ["HITL"]
---

# Finalize HITL config

`POST /api/v1/hitl/{id}/finalize`

## Request

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

Transition a pending HITL configuration to active. Requires an uploaded encryption keypair. Creates authorizations for configured channels and dispatches consent messages.

## Path parameters

- `id` string, required: MongoDB ObjectId

## Response `200`

HITL config finalized (pending → active)

- HitlFinalizeResponse: Finalized HITL configuration (pending → active) with optional authorization dispatch results
  - `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
  - `authorizations` object[]: Authorization consent dispatch results (present when consent messages were sent)
    - `channel` string, required
    - `recipient` string, required: Channel recipient (chat_id, phone number, or BSUID)
    - `authorization_id` string, required: MongoDB ObjectId
    - `status` string, required

## Other responses

- `400`: Encryption keypair must be configured before finalizing (keypair_required)
- `404`: Pending HITL config not found

---

[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/6b8d61ee354f?raw)