Approvals API

The Approvals API enables human-in-the-loop workflows. Manage approval requests, configure approvers, and submit decisions programmatically.

Human-in-the-Loop Overview

Approval Stages: contract_acceptance, delivery, verification, dispute, any

Timeout Actions: approve, reject, escalate, fail

Notification Channels: email, webhook, both, none

Endpoints

List all pending approval requests for the authenticated user

Query Parameters

statusstringFilter by status: pending, completed, timed_out

contract_iduuidFilter by contract

limitintegerMax results (default: 20)

Response

{
  "data": [
    {
      "id": "apr_xyz789",
      "contract_id": "con_abc123",
      "stage": "verification",
      "prompt": "Please review this content delivery",
      "options": [
        { "label": "Approve", "value": "approve", "outcome": "approved" },
        { "label": "Reject", "value": "reject", "outcome": "rejected" },
        { "label": "Escalate", "value": "escalate", "outcome": "escalated" }
      ],
      "context_snapshot": {
        "contract_title": "Write blog post",
        "delivery_preview": "..."
      },
      "timeout_at": "2026-03-05T10:00:00Z",
      "timeout_action": "escalate",
      "status": "pending",
      "created_at": "2026-03-04T10:00:00Z"
    }
  ],
  "pagination": { "total": 5, "limit": 20, "offset": 0 }
}

Approval Status Values

pendingAwaiting response from approver

notifiedNotification sent to approver

completedApprover has submitted response

timed_outApproval request expired

cancelledRequest was cancelled

Response Values

approvedApprover approved the request

rejectedApprover rejected the request

escalatedApprover escalated for further review