Workflow Runs

Use workflow runs when the full process is configured in Plextera Studio and your application only needs to start it, monitor it, and consume the result.

Workflows can include Document Insights, web automation, data transformation, file handling, and custom processing steps.

Before you start

You need:

• An API key. See Authentication.
• A published workflow identifier known to your integration.
• The input shape expected by that workflow. Plextera does not validate workflow-specific input at the Public API boundary — a wrong shape is not rejected at submission and surfaces later as a failed run.

Start a workflow with JSON

Use JSON when the workflow trigger expects structured request data.

$
curl -X POST https://api.plextera.com/api/public/v1/workflows/daily-lab-loader/runs \
>
  -H "Authorization: api-key YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "customerId": "customer-42",
>
    "document": {
>
      "fileId": "file_01JY7M4ZVX5R1P3M3Q0TA1S7ZM"
>
    }
>
  }'

The response is accepted asynchronously:

1
{
2
  "id": "69d224901610662a576cd7e6",
3
  "status": "PROCESSING",
4
  "workflow": {
5
    "id": "daily-lab-loader",
6
    "name": "Daily Lab Loader"
7
  }
8
}

Start a workflow with multipart form-data

Use multipart form-data when the workflow was designed to consume form fields and uploaded files, similar to a webhook trigger.

$
curl -X POST https://api.plextera.com/api/public/v1/workflows/incoming-claim/runs \
>
  -H "Authorization: api-key YOUR_API_KEY" \
>
  -F "claimId=claim-42" \
>
  -F "state=CT" \
>
  -F "document=@claim.pdf"

Multipart behavior:

• Text fields are forwarded under their original part names.
• JSON parts are parsed as JSON when their content type is application/json.
• File parts are uploaded to Plextera File Service.
• File parts are exposed to the workflow under the same part name as file-node arrays.

Part names are workflow-specific. Send the exact names that the target workflow expects.

Poll a workflow run

Call GET /workflow-runs/{runId} until the run reaches a terminal status. Workflow runtimes vary widely with the steps involved — poll every few seconds at first, then back off to every 15–30 seconds for long-running workflows.

$
curl https://api.plextera.com/api/public/v1/workflow-runs/69d224901610662a576cd7e6 \
>
  -H "Authorization: api-key YOUR_API_KEY"

The response includes step-level output as produced by each step. Nested workflow output is represented inside steps[*].nestedRuns. For document_insights steps, output.extractionId links the step to its extraction - fetch the full result with GET /document-insights/extractions/{extractionId}.

1
{
2
  "id": "69d224901610662a576cd7e6",
3
  "status": "COMPLETED",
4
  "workflow": {
5
    "id": "daily-lab-loader",
6
    "name": "Daily Lab Loader"
7
  },
8
  "steps": [
9
    {
10
      "id": "step_01",
11
      "name": "Extract Lab Result",
12
      "type": "document_insights",
13
      "status": "COMPLETED",
14
      "output": {
15
        "extractionId": "69654f0bc073ef404baec649",
16
        "fileName": "lab-result.pdf",
17
        "fields": [
18
          {
19
            "id": "605c644cbf48241234f62121",
20
            "name": "patientName",
21
            "type": "TEXT",
22
            "value": "John Doe"
23
          }
24
        ],
25
        "metaAttributes": {
26
          "recordId": "69654f0bc073ef404baec649"
27
        },
28
        "document": {
29
          "id": "69d224901610662a576cd800",
30
          "fileName": "lab-result.pdf",
31
          "mimeType": "APPLICATION_PDF",
32
          "source": "DOCUMENT_INSIGHTS",
33
          "size": 126
34
        }
35
      },
36
      "nestedRuns": {
37
        "count": 0,
38
        "data": []
39
      }
40
    }
41
  ]
42
}

Terminal statuses are COMPLETED, FAILED, and CLOSED.

List and filter workflow runs

Use GET /workflow-runs to list recent workflow runs.

$
curl "https://api.plextera.com/api/public/v1/workflow-runs?workflowId=daily-lab-loader&status=CLOSED" \
>
  -H "Authorization: api-key YOUR_API_KEY"

CLOSED is a terminal Studio state. Use it when you need to find runs that were closed in Plextera Studio.

Results are always newest first and paged with page/size (default 50, max 100).

Receive workflow events

Subscribe to workflow events when your application should be notified after a run completes or fails:

• workflow.run.completed
• workflow.run.failed

For completed workflow runs, the event payload includes the full run model with step-level outputs.

Runs closed in Plextera Studio (CLOSED) also trigger workflow.run.failed; the event payload carries status: "CLOSED" so your handler can distinguish a closure from a processing failure.

See Event Subscriptions for setup, headers, signatures, and retry behavior.

Related reference

• API Reference
• Event Reference