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.

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

必要なアクション

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": {
    ...
  }
}

必要なアクション

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.

必要なアクション

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": ""
    }
  ]
}