Invoice Approval Agent API

Base URL

Production: https://api.sigmodx.com. Use your local FastAPI backend URL during development (for example http://localhost:8000).

Authentication

Agent endpoints require Authorization: Bearer <api_key>. The API key must belong to the same agent_id in the path. Agents must be organization-scoped (created under an org pilot).

Submit a decision

POST /agents/{agent_id}/decisions/invoice — creates an append-only decision event. Returns 201 with decision_event_id.

curl -sS -X POST "https://api.sigmodx.com/agents/YOUR_AGENT_ID/decisions/invoice" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision_type": "approve",
    "input_hash": "sha256:abc123...",
    "input_hash_algo": "sha256",
    "rationale": "Invoice matches PO #4821. Vendor in good standing. Amount within delegated authority.",
    "confidence": 0.94,
    "invoice_amount": 142500.00,
    "invoice_currency": "USD",
    "vendor_name": "Acme Consulting LLC",
    "vendor_id": "VENDOR-4821",
    "po_reference": "PO-4821",
    "invoice_reference": "INV-2026-0042",
    "delegated_authority_limit": 500000.00
  }'

decision_type: approve, reject, or escalate. input_hash and rationale are required (min 10 characters).

// 201 Created
{
  "decision_event_id": "550e8400-e29b-41d4-a716-446655440000",
  "requires_human_approval": false,
  "agent_state": "ALLOW",
  "created_at": "2026-05-17T12:00:00Z"
}

If approve and invoice_amount exceeds delegated_authority_limit, the response sets requires_human_approval: true.

Input hash

Hash the structural payload your agent used to decide (amounts, vendor id, PO reference— not full PDFs). Use the Python or TypeScript SDK hash_inputs() for a stable SHA-256 digest. See invoice approval methodology for security guidance.

# Python (pip install sigmodx)
from sigmodx import hash_inputs

payload = {
    "invoice_amount": 142500.00,
    "vendor_id": "VENDOR-4821",
    "po_reference": "PO-4821",
}
input_hash = hash_inputs(payload)

Check reliability state

GET /agents/{agent_id}/current-state?scenario=invoice_approval — read-only; no auth required. Use before executing a decision in your orchestration layer.

curl -sS "https://api.sigmodx.com/agents/YOUR_AGENT_ID/current-state?scenario=invoice_approval"

When state is BLOCK, decision submission returns 403.

Record outcome (org users)

POST /decisions/{decision_event_id}/outcome — records what happened after the decision (processed, rejected, reversed, disputed). Requires a Supabase session JWT for an org admin or member—not the agent API key. Outcomes are immutable once set (409 on second write).

curl -sS -X POST "https://api.sigmodx.com/decisions/DECISION_EVENT_ID/outcome" \
  -H "Authorization: Bearer SUPABASE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "processed", "outcome_note": "Paid via AP batch 2026-05-17"}'

Related endpoints

• POST /decisions/{id}/review — human reviewer assessment (org JWT, auditor/admin)
• GET /orgs/{org_id}/decisions/invoice — paginated decision log for your dashboard
• GET /attestations/verify?verification_string=... — public attestation lookup (no auth)

SDKs

Official clients on PyPI and npm. Source and issues on GitHub: sdk-python, sdk-typescript.

pip install sigmodx

from sigmodx import SigmodxClient, InvoiceDecision, hash_inputs

client = SigmodxClient(api_key="...", agent_id="...")
result = client.submit_invoice_decision(InvoiceDecision(
    decision_type="approve",
    input_hash=hash_inputs({...}),
    rationale="...",
))

npm install @sigmodx/sdk

import { SigmodxClient, hashInputs } from '@sigmodx/sdk';

const client = new SigmodxClient(process.env.SIGMODX_API_KEY!, process.env.AGENT_ID!);
await client.submitInvoiceDecision({
  decisionType: 'approve',
  inputHash: hashInputs({ invoice_amount: 142500, vendor_id: 'VENDOR-4821' }),
  rationale: 'Within delegated authority.',
});

HTTP errors

• 401 — missing or invalid API key
• 403 — agent state is BLOCK
• 404 — agent not found or wrong org
• 422 — validation error (body fields)