# 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. Related documentation: - [Document Understanding API overview](https://docs.uipath.com/document-understanding/automation-cloud/latest/api-guide/api-overview) - [Create external application for Document Understanding](https://docs.uipath.com/document-understanding/automation-cloud/latest/api-guide/create-a-new-project-and-an-external-application) - [Managing external applications](https://docs.uipath.com/automation-cloud/automation-cloud/latest/admin-guide/managing-external-applications) :::note Use API v2 to consume the models of **Extract** nodes, and use the latest version of the public Document Understanding APIs. The examples on this page use API v2 (`api-version=2`). ::: ## 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 1. Navigate to **Orchestrator** at tenant level. 2. Select **Manage Access**, then **Manage Accounts and Groups**. 3. From the **UiPath Administration** header, select **External Applications**. 4. Select **Add Application**. 5. Fill in **Application Name**, for example, `DU API Client`. 6. Select **Confidential application**, which is required to get an app secret. 7. 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**. 8. 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: ```shell curl -X POST 'https://cloud.uipath.com/identity_/connect/token' \ -d 'grant_type=client_credentials' \ -d 'client_id=' \ -d 'client_secret=' \ -d 'scope=Du.Digitization.Api Du.Extraction.Api' ``` Response: ```json { "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 ` 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 1. Discover project and tags. 2. Digitize the document, and poll until digitization is done. 3. Extract, and poll until extraction is done. 4. Validate (optional). :::note There is no classification step, as IXP only handles extractions. ::: ## Step 1: Discover the IXP project ```shell # List all projects - filter for type "IXP" curl -X GET \ 'https://cloud.uipath.com///du_/api/framework/projects?api-version=2' \ -H 'Authorization: Bearer ' ``` 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: ```shell curl -X GET \ 'https://cloud.uipath.com///du_/api/framework/projects//tags?api-version=2' \ -H 'Authorization: Bearer ' ``` ## Get document types To get document types, run the following: ```shell curl -X GET \ 'https://cloud.uipath.com///du_/api/framework/projects//document-types?api-version=2' \ -H 'Authorization: Bearer ' ``` :::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`: ```shell curl -X POST \ 'https://cloud.uipath.com///du_/api/framework/projects//digitization/start?api-version=2' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: multipart/form-data' \ -F 'file=@document.pdf;type=application/pdf' ``` Returns `{ "documentId": "..." }`. **Poll for the digitization result:** ```shell curl -X GET 'https://cloud.uipath.com///du_/api/framework/projects//digitization/result/?api-version=2' -H 'Authorization: Bearer ' ``` Poll until `status` is `Succeeded`, and then start the extraction. For the possible statuses and responses, check [Polling responses](#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) ```shell curl -X POST \ 'https://cloud.uipath.com///du_/api/framework/projects///document-types//extraction?api-version=2' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "documentId": "" }' ``` #### Asynchronous (multi-page) **Start:** ```shell curl -X POST \ 'https://cloud.uipath.com///du_/api/framework/projects///document-types//extraction/start?api-version=2' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "documentId": "" }' ``` Returns `{ "operationId": "..." }`. **Poll for result:** ```shell curl -X GET \ 'https://cloud.uipath.com///du_/api/framework/projects///document-types//extraction/result/?api-version=2' \ -H 'Authorization: Bearer ' ``` Poll until `status` is `Succeeded` or `Failed`. For the possible statuses and responses, check [Polling responses](#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):** ```shell curl -X POST \ 'https://cloud.uipath.com///du_/api/framework/projects//extractors//extraction?api-version=2' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "documentId": "" }' ``` **Asynchronous (multi-page):** ```shell curl -X POST \ 'https://cloud.uipath.com///du_/api/framework/projects//extractors//extraction/start?api-version=2' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "documentId": "" }' ``` Returns `{ "operationId": "..." }`. **Poll for result:** ```shell curl -X GET 'https://cloud.uipath.com///du_/api/framework/projects//extractors//extraction/result/?api-version=2' -H 'Authorization: Bearer ' ``` Poll until `status` is `Succeeded` or `Failed`. For the possible statuses and responses, check [Polling responses](#polling-responses). ## Step 4: Validate (optional) ```shell curl -X POST \ 'https://cloud.uipath.com///du_/api/framework/projects///document-types//validation/start?api-version=2' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "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: ```json { "status": "Running", "createdAt": "", "lastUpdatedAt": "" } ``` 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](#ixp-extraction-response-structure). ```json { "status": "Succeeded", "createdAt": "", "lastUpdatedAt": "", "result": { "extractionResult": { "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](https://docs.uipath.com/document-understanding/automation-cloud/latest/api-guide/requests-response-schema) 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. ```json { "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**: ```json { "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](faq-document-processing-limits.md). * **Metering**: For details about how IXP extraction is charged, check [IXP Flex Pricing Plan](https://docs.uipath.com/ixp/automation-cloud/latest/overview/flex-plan#metering-and-charging-logic), [Unified Pricing](https://docs.uipath.com/ixp/automation-cloud/latest/overview/unified-pricing), and [Metering and charging logic (Flex Plan)](https://docs.uipath.com/document-understanding/automation-cloud/latest/user-guide/metering-charging-logic). * **Data retention**: For details about how long digitization and extraction results are retained, check the [Document Understanding API overview](https://docs.uipath.com/document-understanding/automation-cloud/latest/api-guide/api-overview).