Using Flows

A Flow is a named automation that Diligent runs for you — for example KYC enrichment or adverse-media review. You start a run with an API call; the work happens in the background. This guide covers the public run API: how to trigger a run, how to read the result, and how the async lifecycle works.

You need a published Flow and its flowId. Find both in the Diligent dashboard, or ask your Diligent contact.

How a run works

Starting a run is asynchronous. POST /flows/{flowId}/runs validates the input, queues the run, and returns immediately with a run id. It does not wait for the Flow to finish. Poll GET /flow-runs/{runId} until status is terminal, or register a webhook for flow_run_completed and flow_run_failed. A webhook carries the terminal run object, including an inline report or output_ref when present; structured output is read separately with GET /flow-runs/{runId}/output. There is no result in the trigger response. Typical statuses:

Status	Meaning
`QUEUED`	Accepted, waiting for a worker
`RUNNING`	The Flow is executing
`COMPLETED`	Finished successfully — a Markdown `report`, structured output, or both may be available
`FAILED`	Execution failed — see `error`
`CANCELLED`	Stopped before finishing
`SKIPPED`	Not executed (for example a trigger guard skipped it)

COMPLETED, FAILED, CANCELLED, and SKIPPED are terminal. Once a run reaches one of these, status does not change again.

Quick start

1. Trigger a run

input must match the Flow’s active version input schema. The fields below are an example — use the schema for your Flow.

curl -X POST https://api.godiligent.ai/flows/flow-abc123/runs \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "fullName": "Sossio Sorrentino",
      "email": "sossio.sorrentino@example.com",
      "phone": "+393510000000",
      "country": "Italy",
      "city": "Napoli"
    }
  }'

Response (202 Accepted):

{
  "id": "8f14e45f-ceea-4c6b-a1b2-3c4d5e6f7890"
}

Save id. That is the only handle you have for polling. If input does not match the schema, the call fails immediately with 400 and does not queue a run:

{
  "code": "VALIDATION_ERROR",
  "message": "Input does not match the flow's input schema",
  "details": [
    { "field": "/fullName", "message": "must have required property 'fullName'" }
  ]
}

A 404 with FLOW_NOT_FOUND means the flowId does not exist or belongs to another customer. A 409 with NO_ACTIVE_VERSION means the Flow has no published active version.

2. Poll the run

Call Get Run with the id from step 1. Repeat until status is terminal.

curl -X GET https://api.godiligent.ai/flow-runs/8f14e45f-ceea-4c6b-a1b2-3c4d5e6f7890 \
  -H "X-API-KEY: your-api-key"

While the run is in progress:

{
  "id": "8f14e45f-ceea-4c6b-a1b2-3c4d5e6f7890",
  "customer_id": "customer-abc123",
  "flow_id": "flow-abc123",
  "flow_version_id": "version-abc123",
  "status": "RUNNING",
  "triggered_at": "2026-09-08T10:00:00.000Z",
  "trigger_type": "api",
  "triggered_by": "service_account",
  "started_at": "2026-09-08T10:00:01.000Z",
  "input": {
    "fullName": "Sossio Sorrentino",
    "email": "sossio.sorrentino@example.com",
    "phone": "+393510000000",
    "country": "Italy",
    "city": "Napoli"
  },
  "created_at": "2026-09-08T10:00:00.000Z",
  "updated_at": "2026-09-08T10:00:01.000Z"
}

When the run completes:

{
  "id": "8f14e45f-ceea-4c6b-a1b2-3c4d5e6f7890",
  "customer_id": "customer-abc123",
  "flow_id": "flow-abc123",
  "flow_version_id": "version-abc123",
  "status": "COMPLETED",
  "triggered_at": "2026-09-08T10:00:00.000Z",
  "trigger_type": "api",
  "triggered_by": "service_account",
  "started_at": "2026-09-08T10:00:01.000Z",
  "completed_at": "2026-09-08T10:02:14.000Z",
  "input": {
    "fullName": "Sossio Sorrentino",
    "email": "sossio.sorrentino@example.com",
    "phone": "+393510000000",
    "country": "Italy",
    "city": "Napoli"
  },
  "report": "# Screening report\n\n**Subject:** Sossio Sorrentino\n\nNo confirmed adverse media.\n",
  "output_ref": "runs/8f14e45f/output.json",
  "created_at": "2026-09-08T10:00:00.000Z",
  "updated_at": "2026-09-08T10:02:14.000Z"
}

What to read from the completed run:

Field	When it is set	What it is
`report`	The Flow returned a non-empty Markdown string, or an object with a non-empty `report` field	Full analyst-facing result as Markdown
`output_ref`	Structured output was captured	Presence (not the value) means you can call Get Run Output
`error`	`status` is `FAILED`	`{ code, message }` describing the failure
`degraded`	One or more tool calls failed	`true` means the Flow finished with partial data; `failed_sources` groups the failures by tool namespace

Fields that are not yet available are omitted rather than returned as null. A completed structured-only Flow may have output_ref without report, so use status to determine whether the run is finished.

3. Read structured output (optional)

Some Flows also produce structured output (JSON). If Get Run shows output_ref set, read it with Get Run Output:

curl -X GET https://api.godiligent.ai/flow-runs/8f14e45f-ceea-4c6b-a1b2-3c4d5e6f7890/output \
  -H "X-API-KEY: your-api-key"

Response: the output itself. Its fields depend on the Flow, and every object key is snake_case:

{
  "status": "PARTIALLY_RESOLVED",
  "alert_id": "2b7c1f4e-9d3a-4e8b-a6c5-1f0e9d8c7b6a",
  "hits_processed": 2,
  "per_hit": [
    {
      "hit_reference": "HIT-0002",
      "verdict": "UNRESOLVED",
      "reason": "left-for-analyst",
      "comment": "Potential match. No significant mismatch is present."
    }
  ],
  "needs_human_review": 1,
  "synced": true
}

If the run has no structured output, this endpoint returns 404 with OUTPUT_NOT_AVAILABLE.

Examples

Poll until the run finishes (bash)

Poll every 3 seconds and stop when the status is terminal. Then print the report.

API="https://api.godiligent.ai"
KEY="your-api-key"
FLOW_ID="flow-abc123"

RUN_ID=$(curl -s -X POST "$API/flows/$FLOW_ID/runs" \
  -H "X-API-KEY: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"fullName":"Sossio Sorrentino","country":"Italy"}}' \
  | jq -r '.id')

echo "Queued run $RUN_ID"

while true; do
  BODY=$(curl -s "$API/flow-runs/$RUN_ID" -H "X-API-KEY: $KEY")
  STATUS=$(echo "$BODY" | jq -r '.status')
  echo "status=$STATUS"

  case "$STATUS" in
    COMPLETED|FAILED|CANCELLED|SKIPPED) break ;;
  esac

  sleep 3
done

if [ "$STATUS" = "COMPLETED" ]; then
  if echo "$BODY" | jq -e '.report' >/dev/null; then
    echo "$BODY" | jq -r '.report'
  else
    echo "Run completed without a Markdown report"
  fi
else
  echo "$BODY" | jq '.error'
  exit 1
fi

Poll until the run finishes (Python)

import time
import requests

API = "https://api.godiligent.ai"
HEADERS = {"X-API-KEY": "your-api-key"}
TERMINAL = {"COMPLETED", "FAILED", "CANCELLED", "SKIPPED"}

created = requests.post(
    f"{API}/flows/flow-abc123/runs",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={"input": {"fullName": "Sossio Sorrentino", "country": "Italy"}},
)
created.raise_for_status()
run_id = created.json()["id"]

while True:
    run = requests.get(f"{API}/flow-runs/{run_id}", headers=HEADERS)
    run.raise_for_status()
    body = run.json()
    status = body["status"]

    if status in TERMINAL:
        break
    time.sleep(3)

if body["status"] != "COMPLETED":
    raise RuntimeError(body.get("error") or body)

if body.get("report"):
    print(body["report"])

if body.get("output_ref"):
    output = requests.get(f"{API}/flow-runs/{run_id}/output", headers=HEADERS)
    output.raise_for_status()
    print(output.json())

Failed run

When execution fails, polling still ends on a terminal status. Read error instead of report.

{
  "id": "8f14e45f-ceea-4c6b-a1b2-3c4d5e6f7890",
  "customer_id": "customer-abc123",
  "flow_id": "flow-abc123",
  "flow_version_id": "version-abc123",
  "status": "FAILED",
  "triggered_at": "2026-09-08T10:00:00.000Z",
  "trigger_type": "api",
  "triggered_by": "service_account",
  "started_at": "2026-09-08T10:00:01.000Z",
  "completed_at": "2026-09-08T10:00:12.000Z",
  "input": { "fullName": "Sossio Sorrentino" },
  "error": {
    "code": "EXECUTION_ERROR",
    "message": "entityName is required"
  },
  "created_at": "2026-09-08T10:00:00.000Z",
  "updated_at": "2026-09-08T10:00:12.000Z"
}

Polling guidance

Poll GET /flow-runs/{runId} for the simplest integration, or use flow_run_completed and flow_run_failed webhooks to receive the terminal run object.
Start with a 2–5 second interval. Runs can take seconds to minutes depending on the Flow.
Stop when status is COMPLETED, FAILED, CANCELLED, or SKIPPED.
Persist the run id in your system so you can resume polling after a restart.
Read report when present; a completed Flow may produce structured output without Markdown.
Call the output endpoint only after output_ref is set.

Getting Started

How a run works

Quick start

1. Trigger a run

2. Poll the run

3. Read structured output (optional)

Examples

Poll until the run finishes (bash)

Poll until the run finishes (Python)

Failed run

Polling guidance

Next steps

​How a run works

​Quick start

​1. Trigger a run

​2. Poll the run

​3. Read structured output (optional)

​Examples

​Poll until the run finishes (bash)

​Poll until the run finishes (Python)

​Failed run

​Polling guidance

​Next steps

How a run works

Quick start

1. Trigger a run

2. Poll the run

3. Read structured output (optional)

Examples

Poll until the run finishes (bash)

Poll until the run finishes (Python)

Failed run

Polling guidance

Next steps