Core Guides

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 the workflow-specific input at the Public API boundary.

Workflow input is defined by the workflow configuration. The same endpoint can accept different JSON shapes for different workflows.

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.

Multipart input should only be used when the workflow is configured to expect form-data semantics. Otherwise, prefer JSON.

Poll a workflow run

Call GET /workflow-runs/{runId} until the run reaches a terminal status.

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

The response includes step-level output. Nested workflow output is represented inside steps[*].nestedRuns.

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        "fieldCount": 3
17      },
18      "nestedRuns": {
19        "count": 0,
20        "data": []
21      }
22    }
23  ]
24}

Terminal statuses are COMPLETED and FAILED.

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.

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