Human-in-the-Loop

The Approver Model

Any contract can have one or more approvers. An approver is either a registered FinalTX user or an agent. They are notified when their stage is reached, given a prompt and a set of options, and their decision determines what the contract does next.

Adding Approvers

Add a human approver by passing a user_id or an agent approver by passing an agent_id — not both.

// Add a human approver to a contract
POST /api/v1/contracts/{contract_id}/approvers

{
  "user_id": "usr_01jk9x2...",       // a registered FinalTX user
  "label": "Legal Reviewer",
  "approval_stage": "verification",  // when they act in the lifecycle
  "timeout_hours": 72,               // time before auto-action
  "timeout_action": "escalate",      // approve | reject | escalate | fail
  "notification_channel": "email",   // email | webhook | both | none
  "can_approve": true,
  "can_reject": true,
  "can_escalate": true
}

// Add an agent as an approver
POST /api/v1/contracts/{contract_id}/approvers

{
  "agent_id": "agt_01jk9x2...",      // a registered FinalTX agent
  "label": "Compliance Agent",
  "approval_stage": "contract_acceptance",
  "notification_channel": "webhook",
  "webhook_url": "https://agent.example.com/hooks/approvals"
}

Approval Stages

The approval_stage controls when the approver is activated in the contract lifecycle.

Using HITL in Workflows

Add a human_approval step anywhere in a workflow definition. The workflow pauses until the assigned approver responds or the timeout expires.

{
  "name": "Manager Approval Gate",
  "steps": [
    {
      "id": "manager_approval",
      "type": "human_approval",
      "config": {
        "prompt": "Delivery has been verified. Please confirm release of funds.",
        "reviewer_role": "approver",
        "timeout_hours": 48,
        "timeout_action": "escalate",
        "notification_channel": "email",
        "required_fields": [
          {
            "name": "notes",
            "label": "Notes for the seller",
            "type": "textarea",
            "required": false
          }
        ],
        "options": [
          { "label": "Approve Release", "value": "approve", "outcome": "approved" },
          { "label": "Request Revision", "value": "revision", "outcome": "rejected" },
          { "label": "Escalate to Legal", "value": "legal", "outcome": "escalated" }
        ]
      }
    }
  ]
}

Submitting a Decision

When an approval request is pending, the assigned approver submits their decision via the respond endpoint. Their response resumes the paused workflow and is permanently recorded in the contract audit trail.

// Submit a decision on an approval request
POST /api/v1/approvals/{request_id}/respond

{
  "approver_id": "apr_01jk9x2...",
  "response": "approved",            // approved | rejected | escalated
  "selected_option": "approve",
  "statement": "Looks good. Approved for release.",
  "field_values": {
    "notes": "Great work on this deliverable."
  }
}

Timeout Behavior

Every approval request has a timeout_at deadline. When it passes without a response, the timeout_action is applied automatically.