Create artifacts for extraction validation

Create extraction validation artifacts in Document Understanding using the artifacts APIs, then let your application create an App Task for human validation.

Observação:

This feature is in preview.

Use the artifacts APIs to prepare extraction validation artifacts stored in Orchestrator Storage Buckets. The artifacts are then used by your application to create an App Task for human validation — decoupling artifact creation from task management and giving you control over when, where, and with what user interface the task is created.

Importante:

This feature is not available in Automation Cloud Public Sector, because app creation is not supported there.

Workflow overview

1. Digitize the document.
2. Extract data from the document.
3. Retrieve the project taxonomy.
4. Start the artifact creation.
5. Poll until the content validation data is ready.
6. Create an app task in Action Center using the content validation data.
7. Complete the validation in Validation Station.
8. Retrieve the validated extraction result.

Pré-requisitos

• A Document Understanding project with an extraction model configured.
• The documentId and extractionResult from a previous extraction call. To obtain these, follow the Use the Digitization APIs guide to digitize the document and get a documentId, then follow the Use the Extraction Service guide to run extraction and get the extractionResult.
• A storage bucket and directory path accessible from your tenant.
• An app to host the validation task. You can deploy the app programmatically by using the Apps API deployUnifiedPackage endpoint.

Escopos do OAuth exigidos

Your external application must include the following scopes. For instructions on setting up an external application, see Authentication and Authorization.

API call	Required scope
Retrieve the project taxonomy	Du.Digitization.Api, Du.Extraction.Api, Du.Classification.Api, or Du.Validation.Api
Validation endpoints (artifact creation, polling, result)	Du.Validation.Api

Retrieve the project taxonomy

Retrieve the taxonomy for your Document Understanding project. Pass this taxonomy when you start the creation of the extraction validation artifacts.

curl -X 'GET' \
  'https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/projects/<Project_ID>/taxonomy?api-version=2' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Resposta:

{
  "documentTaxonomy": {
    "dataContractVersion": "1.2",
    "documentTypes": [
      {
        "documentTypeId": "0b1fde93-997d-f011-b481-000d3a207936",
        "group": "",
        "category": "",
        "name": "invoices",
        "optionalUniqueIdentifier": "",
        "typeField": {
          "fieldId": "invoices.DocumentType",
          "fieldName": "Document Type"
        },
        "fields": [
          {
            "fieldId": "invoices.invoice-no",
            "fieldName": "Invoice Number",
            "isMultiValue": false,
            "type": "Text",
            "components": [],
            "setValues": [],
            "metadata": [],
            "ruleSet": null,
            "defaultValue": null,
            "dataSource": null
          }
        ]
      }
    ],
    "groups": [],
    "supportedLanguages": ["en"],
    "reportAsExceptionSettings": null
  }
}

Alternative ways to retrieve the taxonomy

You can also retrieve the taxonomy using existing discovery endpoints:

• GET /projects/{projectId}/extractors/{extractorId} — returns the taxonomy for a specific extractor.
• GET /projects/{projectId}/tags/{tag}/document-types/{documentTypeId} — returns the taxonomy for a specific document type by tag. Tag-based filtering is not supported for classic Document Understanding projects.

Observação:

If you pass a taxonomy scoped to a specific extractor or document type, the Change document type feature is not available to the operator during validation in Validation Station.

The main taxonomy endpoint also supports projectVersion and tag query parameters. Be aware of the following when using it:

• Modern projects: Without tag filtering, the same documentTypeId may appear multiple times if multiple extractors from different deployments are based on the same document type. Use the tag parameter to scope results to a specific deployment and avoid duplicates.
• Classic projects: Tag filtering is not supported. If multiple extractors exist for the same document type, use the extractor-specific endpoint (/projects/{projectId}/extractors/{extractorId}) instead to avoid ambiguity.

Start the creation of extraction validation artifacts

Send a POST request to start the creation of extraction validation artifacts. Pass the full documentTaxonomy object retrieved in the previous call.

documentTaxonomy is required. storageBucketName and folderName are optional. If you do not specify folderName, it defaults to the Shared folder.

Importante:

Storage bucket folders inside your personal workspace are not supported.

curl -X 'POST' \
  'https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/extraction-validation/artifacts/start?api-version=2' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "documentId": "25a03e48-cfe8-ed11-9f75-000d3a4964af",
  "extractionResult": {
    "documentId": "25a03e48-cfe8-ed11-9f75-000d3a4964af",
    "resultsVersion": 0,
    "resultsDocument": {
      "documentTypeId": "0b1fde93-997d-f011-b481-000d3a207936",
      "documentTypeName": "invoices",
      "fields": [
        {
          "fieldId": "invoices.invoice-no",
          "fieldName": "Invoice Number",
          "type": "Text",
          "isMissing": false,
          "dataSource": "Automatic",
          "values": [
            {
              "value": "181038",
              "confidence": 0.98,
              "operatorConfirmed": false
            }
          ]
        }
      ]
    }
  },
  "documentTaxonomy": {
    "dataContractVersion": "1.2",
    "documentTypes": [
      {
        "documentTypeId": "0b1fde93-997d-f011-b481-000d3a207936",
        "name": "invoices",
        "fields": [
          {
            "fieldId": "invoices.invoice-no",
            "fieldName": "Invoice Number",
            "type": "Text"
          }
        ]
      }
    ],
    "groups": [],
    "supportedLanguages": ["en"],
    "reportAsExceptionSettings": null
  },
  "storageBucketName": "du_storage_bucket",
  "storageBucketDirectoryPath": "du_storage_bucket"
}'

Response — provides the operationId and URLs for the next two calls:

{
  "operationId": "7c320dfc-a1b2-4c3d-8e9f-000d3a4964af",
  "artifactsUrl": "https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/extraction-validation/artifacts/content-validation-data/7c320dfc-a1b2-4c3d-8e9f-000d3a4964af?api-version=2",
  "resultUrl": "https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/extraction-validation/artifacts/validation-result/7c320dfc-a1b2-4c3d-8e9f-000d3a4964af?api-version=2"
}

Poll for artifact readiness

Send GET requests to the artifactsUrl returned when you started the artifact creation, until the status is Succeeded or Failed.

curl -X 'GET' \
  'https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/extraction-validation/artifacts/content-validation-data/<operationId>?api-version=2' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

The response returns one of four statuses:

Status	Significado
NotStarted	The job is queued but not yet processing.
Running	Artifact preparation is in progress.
Succeeded	Artifacts are ready. Continue with creating the app task (stage 6).
Failed	Artifact preparation failed. Check error.code for details.

Response when artifacts are ready:

{
  "contentValidationData": {
    "bucketName": "du_storage_bucket",
    "bucketId": 261151,
    "folderId": 810789,
    "folderKey": "4c6ff0e2-0a05-4ce1-9508-7102b977bd58",
    "documentId": "25a03e48-cfe8-ed11-9f75-000d3a4964af",
    "encodedDocumentPath": "du_storage_bucket/7c320dfc-.../encoded.zip",
    "textPath": "du_storage_bucket/7c320dfc-.../text.zip",
    "documentObjectModelPath": "du_storage_bucket/7c320dfc-.../dom.zip",
    "taxonomyPath": "du_storage_bucket/7c320dfc-.../taxonomy.zip",
    "automaticExtractionResultsPath": "du_storage_bucket/7c320dfc-.../input_results.zip",
    "validatedExtractionResultsPath": "du_storage_bucket/7c320dfc-.../output_results.zip",
    "customizationInfoPath": "du_storage_bucket/7c320dfc-.../customization_info.zip"
  },
  "status": "Succeeded",
  "createdAt": "2026-04-28T10:00:00Z",
  "lastUpdatedAt": "2026-04-28T10:00:05Z"
}

Observação:

The contentValidationData object contains the Orchestrator Storage Bucket paths needed to open the document in Validation Station. Validation Station uses compact mode for App Tasks flows; classic mode is not available for this flow.

Response when still processing:

{
  "status": "Running",
  "createdAt": "2026-04-28T10:00:00Z",
  "lastUpdatedAt": "2026-04-28T10:00:02Z"
}

Retrieve the validated extraction result

Call this endpoint after the human operator has completed validation in Validation Station (stages 6–7). Send a GET request to the resultUrl returned when you started the artifact creation.

curl -X 'GET' \
  'https://{AutomationCloudURL}/<Organization_Name>/<Tenant_Name>/du_/api/framework/extraction-validation/artifacts/validation-result/<operationId>?api-version=2' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Observação:

If the Action Center task has not been completed yet (stages 6–7 not yet done), the endpoint returns 200 with an empty result:

{
  "result": {}
}

Response when validation is complete:

{
  "result": {
    "validatedExtractionResults": {
      "documentId": "25a03e48-cfe8-ed11-9f75-000d3a4964af",
      "resultsVersion": 1,
      "resultsDocument": {
        "documentTypeId": "0b1fde93-997d-f011-b481-000d3a207936",
        "documentTypeName": "invoices",
        "fields": [
          {
            "fieldId": "invoices.invoice-no",
            "fieldName": "Invoice Number",
            "type": "Text",
            "isMissing": false,
            "dataSource": "Automatic",
            "values": [
              {
                "value": "181038",
                "confidence": 1,
                "operatorConfirmed": true
              }
            ],
            "operatorConfirmed": true
          }
        ]
      }
    }
  }
}

Resultado

A 200 response containing validatedExtractionResults confirms the extraction validation is complete. The operatorConfirmed: true flag on each field indicates the result has been validated.