# Run Doc AI Workflow

Start a published Document AI Workflow on one or more documents, from Apex.

> Kind: Apex method · Updated: 2026-11-17

Use this method to start a published Document AI Workflow from your own Apex code. Each payload names the workflow, binds the documents it should read to the slots the workflow declares, and passes in any field values it needs. CloudFiles accepts the run, returns a run Id, and executes the workflow's steps on its side. This is the Apex counterpart of the Run Doc AI Workflow Flow action.

## Signature

```apex
global static List<RunDocAIWorkflowResult> runWorkflow(
  List<Types.RunWorkflowPayload> payloads,
  String runAs
)
```

### Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| payloads | List&lt;<a href="#/apex-type-run-workflow-payload">Types.RunWorkflowPayload</a>&gt; | required | One entry per workflow run. Each Types.RunWorkflowPayload names the workflow, the documents bound to its slots, the field values, and the record the run is associated with. |
| runAs | String | optional | Email Id of the user on whose behalf the function should run. To run the action as the automation user, supply integrationUser. |

## Return Type

List<RunDocAIWorkflowResult&gt;. One result per payload, in the same order as the payloads. success reports whether CloudFiles accepted the run, not whether the workflow finished: the workflow runs on CloudFiles after the method returns, and its outputs are not returned to Apex. A payload that is not accepted comes back with success set to false and the reason in error; it does not throw. A request that CloudFiles rejects as a whole, for example because of an authentication failure, throws an exception.

## Example

```apex
cldfs.Resource invoice = new cldfs.Resource();
invoice.id = '069dL00000AbCdEQAV'; // ContentDocumentId of the Salesforce File
invoice.library = 'salesforce';

List<cldfs.DocumentSlotBinding> documents = new List<cldfs.DocumentSlotBinding>{
  new cldfs.DocumentSlotBinding('invoice', invoice) // slot name declared by the workflow
};

List<cldfs.FieldValue> fields = new List<cldfs.FieldValue>{
  new cldfs.FieldValue('source_record_id', '500dL00000XyZaBQAV')
};

List<cldfs.Types.RunWorkflowPayload> payloads = new List<cldfs.Types.RunWorkflowPayload>{
  new cldfs.Types.RunWorkflowPayload(
    'demo-invoice-review', // Workflow Id
    documents,
    fields,
    '500dL00000XyZaBQAV' // record the run is associated with
  )
};

List<cldfs.RunDocAIWorkflowResult> results = cldfs.Client.runWorkflow(payloads, 'integrationUser');

for (cldfs.RunDocAIWorkflowResult result : results) {
  if (result.success) {
    System.debug('Run accepted: ' + result.runId);
  } else {
    System.debug('Run not accepted: ' + result.error);
  }
}
```

> **This method makes a callout** — Salesforce does not allow a callout after uncommitted DML in the same transaction, or directly from a trigger. Call this method before any DML, or from a Queueable that implements Database.AllowsCallouts or an @future(callout=true) method.

> **Supported file types** — Workflows read pdf, xlsx, xlsm, xls, csv, tsv, html, htm, docx, docm, odt, pptx, pptm, ppsx and ppsm files. Images are not supported, so a run on a JPG or PNG fails before any step runs. Convert scans to PDF first.

> **How this differs from the Run Doc AI Workflow Flow action** — The Run Doc AI Workflow Flow action creates a CloudFiles Doc AI Run record for every run, and CloudFiles updates that record's status as the run progresses. This method sends the request straight to CloudFiles and creates no run record, so its runs do not appear on the CloudFiles Doc AI Run object and runRecordId is always empty in the result. If you need the run status in Salesforce, start the run from the Flow action.
