IXP - Consuming models via Document Understanding API

ixp

latest

false

IXP in Flow user guide

Overview
Model building
Model evaluation
Model deployment
Consuming models
- Consuming models via Flow
- Consuming models via automations
- Consuming models via Document Understanding API
Developer
- CLI
- API audit events
Frequently asked questions
- Frequently asked questions

Consuming models via Document Understanding API

Access IXP models built in Flow Extract nodes through the Document Understanding framework API using tag-based or extractorId-based extraction endpoints.

IXP Extract nodes are accessible through the same Document Understanding framework API. Extract nodes appear as ProjectType: "IXP" in Discovery and support both tag-based endpoints and extractorId-based endpoints for extraction.

Prerequisites

Before you call any Document Understanding or IXP API, you need an external application registered in Automation Cloud. This provides the AppID and AppSecret used for OAuth authentication.

Creating an external application

Navigate to Orchestrator at tenant level.
Select Manage Access, then Manage Accounts and Groups.
From the UiPath Administration header, select External Applications.
Select Add Application.
Fill in Application Name, for example, DU API Client.
Select Confidential application, which is required to get an app secret.
Under Resources, select Add Scopes:
- Select Document Understanding from the Resource dropdown.
- Switch to the Application Scope(s) tab.
- Check the scopes you need:
  - Du.Digitization.Api - digitize documents
  - Du.Classification.Api - classify documents
  - Du.Extraction.Api - extract data
  - Du.Validation.Api - create validation tasks
  - Du.DataDeletion.Api - delete document data
- Select Save.
Select Add to create the registration.

Note:
The Copy the App Secret immediately pop-up is displayed only once and cannot be recovered. You can generate a new one later from the edit screen.

The Application ID is visible on the External Applications page at any time.

Getting an access token

Use the App ID and App Secret to request an OAuth token through the client credentials flow:

curl -X POST 'https://cloud.uipath.com/identity_/connect/token' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<APP_ID>' \
  -d 'client_secret=<your-client-secret>' \
  -d 'scope=Du.Digitization.Api Du.Extraction.Api'
curl -X POST 'https://cloud.uipath.com/identity_/connect/token' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<APP_ID>' \
  -d 'client_secret=<your-client-secret>' \
  -d 'scope=Du.Digitization.Api Du.Extraction.Api'

Response:

{
  "access_token": "<your-access-token>",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "Du.Digitization.Api Du.Extraction.Api"
}
{
  "access_token": "<your-access-token>",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "Du.Digitization.Api Du.Extraction.Api"
}

The token expires after 1 hour. Use it as Authorization: Bearer <your-access-token> on all subsequent API calls.

Note:

If you lose the App Secret, go to Admin, then External Applications, edit the app, and select Generate New under App Secret. Update all integrations with the new secret.

Key differences

The following table shows the key differences between Document Understanding and IXP projects:

	Document Understanding (Classic or Modern)	IXP
ProjectType	`Classic` or `Modern`	`IXP`
Classification	Yes	No (extraction only)
Extraction routing	By `tag` + `documentTypeId` (recommended) or `extractorId`	By `tag` + `documentTypeId` or by `extractorId` (`gpt_ixp_[version]`)
Extraction model	Specialized or Generative	Generative only (GPT-4o, Gemini)
Schema definition	In-project or via prompts	Defined in IXP UI (taxonomy)

The IXP workflow

Discover project and tags.
Digitize the document, and poll until digitization is done.
Extract, and poll until extraction is done.
Validate (optional).

Note:

There is no classification step, as IXP only handles extractions.

Step 1: Discover the IXP project

# List all projects - filter for type "IXP"
curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'
# List all projects - filter for type "IXP"
curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

From the response, note the id of the IXP project.

Get tags (published versions)

Tags correspond to published model versions marked as Staging or Production in the IXP user interface. Each tag includes its associated extractors and document types. To get tags, run the following:

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/tags?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'
curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/tags?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

Get document types

To get document types, run the following:

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/document-types?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'
curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/document-types?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

Note:

After you know the project ID, the tag, and the document type ID, you do not need to run the discovery calls at runtime every time. Reuse these values in your automation instead.

Step 2: Digitize the document

Note:

Digitization is a mandatory step. You cannot extract data from a document before you digitize it.

Similar to Document Understanding, upload the file to get a documentId:

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/digitization/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf;type=application/pdf'
curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/digitization/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf;type=application/pdf'

Returns { "documentId": "..." }.

Poll for the digitization result:

curl -X GET   'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/digitization/result/<documentId>?api-version=2'   -H 'Authorization: Bearer <your-access-token>'
curl -X GET   'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/digitization/result/<documentId>?api-version=2'   -H 'Authorization: Bearer <your-access-token>'

Poll until status is Succeeded, and then start the extraction. For the possible statuses and responses, check Polling responses.

Step 3: Extract

IXP extraction supports the following routing approaches:

Tag-based - Route by tag and documentTypeId. This is recommended for Production or Staging workflows.
ExtractorId-based - Route by extractorId using the format: gpt_ixp_[version]. For example, gpt_ixp_67. This is the same as for Document Understanding Classic or Modern projects.

Tag-based extraction

Uses the tag-based path with the documentTypeId from Discovery.

Synchronous (up to 5 pages)

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'
curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Asynchronous (multi-page)

Start:

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'
curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Returns { "operationId": "..." }. Poll for result:

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction/result/<operationId>?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'
curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction/result/<operationId>?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>'

Poll until status is Succeeded or Failed. For the possible statuses and responses, check Polling responses.

ExtractorId-based extraction

Uses the same extractor-based endpoints as Document Understanding Classic or Modern. The ExtractorId for IXP follows the format gpt_ixp_[version], which is visible in the discovery response. Synchronous (up to 5 pages):

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'
curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Asynchronous (multi-page):

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'
curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Returns { "operationId": "..." }. Poll for result:

curl -X GET   'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction/result/<operationId>?api-version=2'   -H 'Authorization: Bearer <your-access-token>'
curl -X GET   'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction/result/<operationId>?api-version=2'   -H 'Authorization: Bearer <your-access-token>'

Poll until status is Succeeded or Failed. For the possible statuses and responses, check Polling responses.

Step 4: Validate (optional)

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/validation/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "documentId": "<documentId>",
    "actionTitle": "Review IXP extraction",
    "actionPriority": "Medium",
    "actionCatalog": "default_du_actions",
    "actionFolder": "Shared",
    "storageBucketName": "du_storage_bucket",
    "storageBucketDirectoryPath": "du_storage_bucket",
    "extractionResult": { }
  }'
curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/validation/start?api-version=2' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "documentId": "<documentId>",
    "actionTitle": "Review IXP extraction",
    "actionPriority": "Medium",
    "actionCatalog": "default_du_actions",
    "actionFolder": "Shared",
    "storageBucketName": "du_storage_bucket",
    "storageBucketDirectoryPath": "du_storage_bucket",
    "extractionResult": { }
  }'

Polling responses

The asynchronous digitization calls in Step 2 and the asynchronous extraction calls in Step 3 return their results through polling. Each poll response contains a status, which is one of the following:

NotStarted - The job was created and is waiting to be processed.
Running - The job was picked up and is being processed.
Succeeded - The job finished successfully. The response contains the result.
Failed - The job finished with an error. The response contains the error.

Keep polling while the status is NotStarted or Running.

While the job is processing, the response contains the status and the timestamps of the job:

{
  "status": "Running",
  "createdAt": "<timestamp>",
  "lastUpdatedAt": "<timestamp>"
}
{
  "status": "Running",
  "createdAt": "<timestamp>",
  "lastUpdatedAt": "<timestamp>"
}

When the job succeeds, the response also contains the result. For extraction, the result is in result.extractionResult. For its structure, check IXP extraction response structure.

{
  "status": "Succeeded",
  "createdAt": "<timestamp>",
  "lastUpdatedAt": "<timestamp>",
  "result": {
    "extractionResult": {
      "documentId": "<documentId>"
    }
  }
}
{
  "status": "Succeeded",
  "createdAt": "<timestamp>",
  "lastUpdatedAt": "<timestamp>",
  "result": {
    "extractionResult": {
      "documentId": "<documentId>"
    }
  }
}

When the job fails, the response contains an error object with the following details:

message - The description of the error.
severity - The severity of the failure, most commonly Error.
code - The code that identifies the type of error.
parameters - Additional information about the error, if applicable.

For details, check Requests response schemas in the Document Understanding API guide.

IXP extraction response structure

In API v2, all fields and values reported by IXP use correct field types, including field groups and child fields, using an exact mapping of the IXP field group and child field definitions.

{
  "extractionResult": {
    "ResultsDocument": {
      "Fields": [
        {
          "FieldId": "Default.Seller",
          "FieldName": "Seller",
          "FieldType": "FieldGroup",
          "IsMissing": false,
          "DataSource": "Automatic",
          "Values": [
            {
              "Components": [
                {
                  "FieldId": "Default.Seller.Name",
                  "FieldName": "Name",
                  "FieldType": "Text",
                  "Values": [
                    {
                      "Value": "John Doe",
                      "Confidence": 0.9999834
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}
{
  "extractionResult": {
    "ResultsDocument": {
      "Fields": [
        {
          "FieldId": "Default.Seller",
          "FieldName": "Seller",
          "FieldType": "FieldGroup",
          "IsMissing": false,
          "DataSource": "Automatic",
          "Values": [
            {
              "Components": [
                {
                  "FieldId": "Default.Seller.Name",
                  "FieldName": "Name",
                  "FieldType": "Text",
                  "Values": [
                    {
                      "Value": "John Doe",
                      "Confidence": 0.9999834
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Note:

We recommend using API v2 for IXP consumption, due to the one-to-one mapping between the field groups and field types of the IXP project and the reported results.

IXP discovery response structure

IXP projects expose versioning through tags and projectVersions:

{
  "id": "044fedbc-40a6-8078-8f06-02a0d362ab44",
  "name": "Invoices",
  "type": "IXP",
  "properties": ["SupportsTags", "SupportsVersions"],
  "extractors": [
    {
      "id": "gpt_ixp_67",
      "documentTypeId": "00000000-0000-0000-0000-000000000000",
      "projectVersion": 67
    }
  ],
  "projectVersions": [
    { "version": 67, "tag": "live", "deployed": true }
  ],
  "classifiers": []
}
{
  "id": "044fedbc-40a6-8078-8f06-02a0d362ab44",
  "name": "Invoices",
  "type": "IXP",
  "properties": ["SupportsTags", "SupportsVersions"],
  "extractors": [
    {
      "id": "gpt_ixp_67",
      "documentTypeId": "00000000-0000-0000-0000-000000000000",
      "projectVersion": 67
    }
  ],
  "projectVersions": [
    { "version": 67, "tag": "live", "deployed": true }
  ],
  "classifiers": []
}

The tag name, for example, live, maps to the Production or Staging label in the IXP user interface.

Consider the following when calling the IXP extraction endpoints:

Tag = model version: Use the tag that corresponds to the Production or Staging version you want to call.
DocumentTypeId: IXP projects typically use a single default document type (00000000-0000-0000-0000-000000000000).
Page limits: For page and token limits, check Document processing limits.
Metering: For details about how IXP extraction is charged, check IXP Flex Pricing Plan, Unified Pricing, and Metering and charging logic (Flex Plan).
Data retention: For details about how long digitization and extraction results are retained, check the Document Understanding API overview.

Was this page helpful?

PREVIOUSConsuming models via automations

NEXTCLI

Prerequisites​

Creating an external application​

Getting an access token​

Key differences​

The IXP workflow​

Step 1: Discover the IXP project​

Get tags (published versions)​

Get document types​

Step 2: Digitize the document​

Step 3: Extract​

Tag-based extraction​

Synchronous (up to 5 pages)​

Asynchronous (multi-page)​

ExtractorId-based extraction​

Step 4: Validate (optional)​

Polling responses​

IXP extraction response structure​

IXP discovery response structure​

Was this page helpful?

Prerequisites

Creating an external application

Getting an access token

Key differences

The IXP workflow

Step 1: Discover the IXP project

Get tags (published versions)

Get document types

Step 2: Digitize the document

Step 3: Extract

Tag-based extraction

Synchronous (up to 5 pages)

Asynchronous (multi-page)

ExtractorId-based extraction

Step 4: Validate (optional)

Polling responses

IXP extraction response structure

IXP discovery response structure