# Document Understanding coded automation APIs (preview)

> Coded automation APIs for the Document Understanding activities package, covering document classification, data extraction, and validation artifacts.

`UiPath.DocumentUnderstanding.Activities`

Coded workflow API for classifying documents, extracting structured data, and creating and retrieving document validation artifacts. These APIs are available when designing coded automations. For an introduction to coded automations and how to design them using APIs, see [Coded Automations](https://docs.uipath.com/studio/standalone/2023.10/user-guide/coded-automations-introduction).

- **Service accessor:** `du` (type `IDocumentUnderstandingService`)
- **Required package:** `"UiPath.DocumentUnderstanding.Activities": "*"` in the `project.json` dependencies.

## Auto-imported namespaces

The following namespaces are automatically available in coded workflows when the Document Understanding package is installed:

* `UiPath.DocumentUnderstanding.Activities.Api`
* `UiPath.Platform.ResourceHandling`
* `UiPath.DocumentProcessing.Contracts.Actions`
* `UiPath.IntelligentOCR.StudioWeb.Activities.DataExtraction`
* `UiPath.IntelligentOCR.StudioWeb.Activities.DocumentClassification`

## Service overview

The `du` service exposes each Document Understanding operation as a direct method call. There is no connection or scope to open. Call methods on the service accessor directly:

```csharp
var extracted = du.ExtractDocumentData(@"C:\invoices\invoice.pdf", "Invoices", "Production", "invoice");
```

The service mirrors the Studio Web **Classify Document**, **Extract Document Data**, **Create Document Validation Artifacts**, and **Retrieve Document Validation Artifacts** activities.

### Project version or tag

The `projectVersionOrTag` parameter maps to Studio's single **Version** dropdown. Pass either a version name (for example, `v3`) or a tag (for example, `Production`, `Staging`, `live`). The runtime resolves whichever kind matches the project. For the Predefined project, use `Production`.

### Common parameters

* `timeoutMs` (`Int`) - Timeout in milliseconds for classification and extraction. Defaults to `3600000` (1 hour).
* `docType` (`String`) - The document type id. Pass the document type name for projects with multiple document types, or an empty string for IXP-style projects that have a single extractor per version.

## Classification

### `DocumentData ClassifyDocument(string documentPath, string projectName, string projectVersionOrTag, int timeoutMs = 3600000)`

Classifies a document from a local file path against a Document Understanding project. Returns a [DocumentData](https://docs.uipath.com/activities/other/latest/document-understanding/document-data) object, including the predicted document type.

### `DocumentData ClassifyDocument(IResource file, string projectName, string projectVersionOrTag, int timeoutMs = 3600000)`

Classifies the supplied document resource. Accepts any `IResource`, such as the output of the **Path Exists** or **Get Local File or Folder** activity.

## Data extraction

### `IDocumentData<DictionaryData> ExtractDocumentData(string documentPath, string projectName, string projectVersionOrTag, string docType, int timeoutMs = 3600000)`

Extracts structured data from a document at a local file path. Returns the extracted fields as [`IDocumentData<DictionaryData>`](https://docs.uipath.com/activities/other/latest/document-understanding/document-data).

### `IDocumentData<DictionaryData> ExtractDocumentData(IResource file, string projectName, string projectVersionOrTag, string docType, int timeoutMs = 3600000)`

Extracts structured data from the supplied document resource.

### `IDocumentData<DictionaryData> ExtractDocumentData(DocumentData classifiedDocument, string projectName, string projectVersionOrTag, string docType = null, int timeoutMs = 3600000)`

Extracts structured data from a document already classified with `ClassifyDocument`, which avoids re-digitizing the file. When `docType` is `null`, it is derived from the classified document's document type.

## Validation artifacts

### `ContentValidationData CreateDocumentValidationArtifacts(IDocumentData<DictionaryData> automaticExtractionResults, string orchestratorFolderName, string orchestratorBucketName = null)`

Uploads extraction results to Orchestrator storage and returns a [ContentValidationData](https://docs.uipath.com/activities/other/latest/document-understanding/contentvalidationdata-class) handle. Use the handle to create a validation action, or to retrieve the results later with `RetrieveDocumentValidationArtifacts`. When `orchestratorBucketName` is `null`, the default bucket is used.

### `IDocumentData<DictionaryData> RetrieveDocumentValidationArtifacts(ContentValidationData contentValidationData, object completedAppAction = null, bool removeDataFromStorage = false, bool returnAutomaticExtractionResults = false)`

Retrieves validated extraction results from storage. When `removeDataFromStorage` is `true`, the storage artifacts are deleted after retrieval. When `returnAutomaticExtractionResults` is `true`, the original automatic extraction results are returned instead of the validated ones.

## Relationship to the activities

The coded API and the Document Understanding XAML activities run on the same runtime, so a coded workflow reaches the same classification, extraction, and validation-artifact behavior as the [Extract Document Data](https://docs.uipath.com/activities/other/latest/document-understanding/extract-document-data) and [Classify Document](https://docs.uipath.com/activities/other/latest/document-understanding/document-understanding-classify-document) activities. The difference is the call shape: the service takes plain file paths or `IResource` inputs and returns [Document Data](https://docs.uipath.com/activities/other/latest/document-understanding/document-data) objects directly, and you use ordinary `try`/`catch` instead of the activity **Continue On Error** option.

## Common patterns

### Classify, then extract

This pattern classifies a document and then reuses the classified result to extract data, which avoids digitizing the file a second time.

```csharp
[Workflow]
public void Execute()
{
    var classified = du.ClassifyDocument(@"C:\docs\file.pdf", "MyProject", "Production");
    Log($"Document type: {classified.DocumentType.DisplayName}");

    // Reuses the classified document, so the file is not digitized again.
    var extracted = du.ExtractDocumentData(classified, "MyProject", "Production");
}
```

### Extract and prepare data for app tasks containing the validation control

This pattern extracts data, uploads it to storage as validation artifacts for review in an app task, and retrieves the validated results after the action completes.

```csharp
[Workflow]
public void Execute()
{
    var extracted = du.ExtractDocumentData(@"C:\docs\invoice.pdf", "Invoices", "Production", "invoice");

    // Upload the results so they can be reviewed in Action Center.
    var artifacts = du.CreateDocumentValidationArtifacts(extracted, "Shared");

    // After the Action Center validation action completes, retrieve the validated results.
    var validated = du.RetrieveDocumentValidationArtifacts(artifacts, removeDataFromStorage: true);
}
```