# Migrating automations from Document Understanding API v1 to v2

> When upgrading from **Document Understanding API v1 to v2**, the following breaking changes apply. Some updates require action to ensure your automations continue to work as expected.

When upgrading from **Document Understanding API v1 to v2**, the following breaking changes apply. Some updates require action to ensure your automations continue to work as expected.

It is recommended to take the following steps to migrate your automations from **Document Understanding API v1 to v2**:

1. Update route paths.
2. Update IXP extraction result handling (from **Tables** to **FieldGroups**).
3. Rebuild and redeploy to a non-production environment.
4. Validate that the automation works as expected in all four dimensions:
   * Discovery,
   * Classification,
   * Extraction,
   * Validation.

The following sections describe the changes in detail and the required migration steps.

## Endpoint path changes

Tag-based routes have been normalized to improve consistency across the API.

All tag-based endpoints using the previous path structure return **400 Bad Request** in v2.

The change affects all operations that include `{tag}` directly after `{projectId}`.

**v1**
```
POST /projects/{projectId}/{tag}/classification
```

**v2**
```
POST /projects/{projectId}/tags/{tag}/classification
```

**Required action**

Search your codebase for: `/projects/{projectId}/{tag}/`

Replace with: `/projects/{projectId}/tags/{tag}/`

Ensure this update is applied consistently across all environments.

## Discovery response schema change: `fields` property removed

The `fields` property is no longer returned. Any deserialization logic or strongly typed models referencing **fields** will fail or return null values.

**v1**
```
{
  "fields": [
    {
      "name": "InvoiceNumber",
      "type": "string"
    }
  ]
}
```

**v2**
```
{
  "taxonomy": {
    ...
  }
}
```

**Required action**
1. Update your response models to consume the `taxonomy` object.
2. Refactor downstream logic that previously depended on `fields`.

## Discovery response schema change: `tag` renamed to `tags`

Response parsing may fail if your model expects a single `tag` property. If you are using strict schema validation, updates are required.

**v1**
```
{
  "tag": "staging"
}
```

**v2**
```
{
  "tags": ["staging"]
}
```

**Required action**:
1. Update response models to replace `tag` with `tags`.
2. Adjust logic if assuming a single tag value.

## IXP extraction result schema changes: tables removed and FieldType.Table replaced by FieldType.FieldGroup

This change affects only IXP extraction results.

In v1, the API returned an IXP extraction result as one or more Tables. This was a mapping of the IXP concept of FieldGroups to tables. All values inside those tables were represented as text (string), regardless of their original IXP data type.

In v2, the API returns IXP extraction results as **FieldGroups**. This introduces a 1-to-1 mapping with the IXP FieldGroup concept. Each field preserves its actual IXP data type (for example, **Text**, **Number**, **Date**, **MonetaryQuantity**).

**v1 (IXP extraction result returned as Tables; values represented as text)**
```
{
  "Tables": [
    {
      "FieldId": "Seller",
      "FieldName": "Seller",
      "IsMissing": false,
      "DataSource": "Automatic",
      "DataVersion": 0,
      "OperatorConfirmed": false,
      "Values": [
        {
          "OperatorConfirmed": true,
          "Confidence": 0.9999834,
          "OcrConfidence": 1.0,
          "Cells": [
            {
              "RowIndex": 0,
              "ColumnIndex": 0,
              "IsHeader": true,
              "IsMissing": false,
              "OperatorConfirmed": false,
              "DataSource": "Automatic",
              "DataVersion": 0,
              "Values": [
                {
                  "Components": [],
                  "Value": "Name",
                  "UnformattedValue": "Name",
                  "Reference": {
                    "TextStartIndex": 0,
                    "TextLength": 0,
                    "Tokens": []
                  },
                  "DerivedFields": [],
                  "Confidence": -1.0,
                  "OperatorConfirmed": false,
                  "OcrConfidence": 1.0,
                  "TextType": "Unknown"
                }
              ]
            }
          ],
          "ColumnInfo": [
            {
              "FieldId": "Name",
              "FieldName": "Name",
              "FieldType": "Text"
            }
          ],
          "NumberOfRows": 2
        }
      ]
    }
  ]
}
```

**v2 (IXP extraction result returned as FieldGroups; values preserve IXP data types)**
```
{
  "Fields": [
    {
      "FieldId": "Default.Seller",
      "FieldName": "Seller",
      "FieldType": "FieldGroup",
      "IsMissing": false,
      "DataSource": "Automatic",
      "Values": [
        {
          "Components": [
            {
              "FieldId": "Default.Seller.Name",
              "FieldName": "Name",
              "FieldType": "Text",
              "IsMissing": false,
              "DataSource": "Automatic",
              "Values": [
                {
                  "Components": [],
                  "Value": "John Doe",
                  "UnformattedValue": "John Doe",
                  "Reference": {
                    "TextStartIndex": 0,
                    "TextLength": 8,
                    "Tokens": [
                      "..."
                    ]
                  },
                  "DerivedFields": [],
                  "Confidence": 0.9999834,
                  "OperatorConfirmed": false,
                  "OcrConfidence": 0.90999997,
                  "TextType": "Text",
                  "ValidatorNotes": "",
                  "ValidatorNotesInfo": ""
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

* In **v1**, IXP “table-like” results were represented as **FieldType.Table** in the **Fields** array and mapped to a **tables** structure for convenience.
* In **v2**, IXP results are represented as **FieldType.FieldGroup** and returned as FieldGroups (1:1 with IXP FieldGroup). Any logic expecting **FieldType.Table** or **tables** will break.

**Required action**
1. Update IXP extraction result handling to use **FieldGroups** instead of **Tables**.
2. If your automation treats IXP extraction results as tables, update parsing logic to handle the new **FieldGroup** structure and typed fields.
3. Replace string-based parsing with type-aware handling. For example:
   * Date: parse as a date value
   * Number: parse as a numeric value
   * MonetaryQuantity: handle value and currency as a single data object

```
{
  "Fields": [
    {
      "FieldId": "Seller",
      "FieldName": "Seller",
      "FieldType": "Table",
      "IsMissing": false,
      "DataSource": "Automatic",
      "Values": [
        {
          "Components": [
            {
              "FieldId": "Seller.Header",
              "FieldName": "Header",
              "FieldType": "Internal",
              "IsMissing": false,
              "DataSource": "Automatic",
              "Values": [],
              "DataVersion": 0,
              "OperatorConfirmed": false,
              "ValidatorNotes": ""
            },
            {
              "FieldId": "Seller.Body",
              "FieldName": "Body",
              "FieldType": "Internal",
              "IsMissing": false,
              "DataSource": "Automatic",
              "Values": [],
              "DataVersion": 0,
              "OperatorConfirmed": false,
              "ValidatorNotes": ""
            }
          ],
          "Value": "",
          "UnformattedValue": "",
          "Reference": {
            "TextStartIndex": 0,
            "TextLength": 0,
            "Tokens": []
          },
          "DerivedFields": [],
          "Confidence": 0.9999834,
          "OperatorConfirmed": true,
          "OcrConfidence": 1.0,
          "TextType": "Unknown"
        }
      ],
      "DataVersion": 0,
      "OperatorConfirmed": false,
      "ValidatorNotes": ""
    }
  ]
}
```