> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api.docs.gooclaim.com/llms.txt.
> For full documentation content, see https://api.docs.gooclaim.com/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api.docs.gooclaim.com/_mcp/server.

# Workflows

Gooclaim ships **three workflows** in `v1.0`. Each one runs end-to-end without
human intervention for the happy path, falling back to a human only when
policy or knowledge gaps demand it.

## The three workflows

**Read-only status lookup.**
Claimant asks where their claim is; Gooclaim fetches from your CMS and
replies via a templated message.

**Stateful follow-up.**
Gooclaim asks for the documents you marked pending, waits, reminds, and
notifies you when the claimant uploads.

**KB-backed explanation.**
Claimant asks "why?" — Gooclaim finds the answer in your knowledge base,
runs it through the Policy Gate, and replies.

## How a workflow runs

Every workflow follows the same six-stage pipeline:

```
1. Channel Gateway     → receives inbound message (WhatsApp)
2. Consent Capture     → ensures DPDP consent is on file
3. Workflow Engine     → routes to the correct workflow
4. Truth Layer         → fetches data from your CMS (read-only)
5. Knowledge Layer     → looks up answers in your KB (if needed)
6. Policy Gate         → validates the output (Guardrails AI, 4-tier check)
7. Outbound Engine     → sends the templated message back
```

Every step emits an **audit event** you can query via the
[Audit Ledger API](/api-reference/audit-ledger).

## Claim Status

**Trigger:** Claimant sends "status" / "claim status" / equivalent in HI/EN/HI\_EN
on WhatsApp.

**Flow:**

1. Gooclaim recognizes intent (template match — no free-text LLM)
2. Identity gate matches phone → claim record
3. Truth Layer pulls live status from your CMS (with circuit breaker)
4. Template selected per channel + language
5. Outbound dispatches the reply

**Typical end-to-end latency:** under 3 seconds.

**Sample status query:**

```bash
curl https://api.gooclaim.com/v1/workflows/wf_abc123 \
  -H "Authorization: Bearer ${TOKEN}"
```

```json
{
  "workflow_id": "wf_abc123",
  "workflow_type": "claim-status",
  "tenant_id": "tnt_xyz",
  "claim_id_hash": "sha256:...",
  "status": "completed",
  "started_at": "2026-05-20T10:14:22Z",
  "completed_at": "2026-05-20T10:14:25Z",
  "audit_event_ids": ["evt_001", "evt_002", "evt_003"]
}
```

## Pending Documents

**Trigger:** Your CMS marks a claim as `DOCUMENTS_PENDING` (push) **or**
claimant asks "what's pending?" (pull).

**Flow:**

1. Gooclaim retrieves the pending-docs list from your CMS
2. Templated reminder dispatched ("Please upload X, Y, Z")
3. **Temporal workflow** waits up to 72 hours
4. If documents arrive → notifies you via webhook
5. If timeout → escalates to your team

This is a **durable** workflow — restarts, deploys, and incidents do not lose
state. Each pending workflow has a `pending_docs_workflow_id` you can resume
or cancel.

**Cancel a pending-docs workflow:**

```bash
curl -X DELETE https://api.gooclaim.com/v1/workflows/wf_def456 \
  -H "Authorization: Bearer ${TOKEN}"
```

## Query Reason

**Trigger:** Claimant asks "why" — rejection reason, deduction reason, delay
reason.

**Flow:**

1. Intent classified as `query-reason`
2. Knowledge Layer searches your tenant-specific KB (Airweave-backed)
3. Cache check via Template Registry — has this exact question been answered?
4. If miss → KB result passes through the **Policy Gate**:
   * Tier 1: exact-match deny list
   * Tier 2: semantic check (Guardrails AI)
   * Tier 3: PHI redaction
   * Tier 4: source attribution check
5. Templated reply with the cited reason

If the Policy Gate blocks the answer (e.g. answer would contain PHI it
shouldn't, or no trusted source can back the claim), the workflow ends with
status `policy_blocked` and the claimant is told a human will follow up.

## Operational modes

Every tenant has an **operational mode** that gates workflow execution:

| Mode          | What happens                                                      |
| ------------- | ----------------------------------------------------------------- |
| `OPERATIONAL` | All workflows run normally                                        |
| `RESTRICTED`  | Only Claim Status runs; Pending Documents and Query Reason paused |
| `SUSPENDED`   | No outbound messages — workflows queued                           |

Your current operational mode is shown in the Portal's tenant settings view.
Mode changes are also pushed as `operational_mode.changed` webhook events
(see [Webhooks](/home/get-started/webhooks)).

## Workflow events

Every state transition emits a webhook to your configured URL. See
[Webhooks](/home/get-started/webhooks) for the full event catalog.

## Next: receive workflow events

Head to [Webhooks](/home/get-started/webhooks) to subscribe to lifecycle events from your side.