Forms API Migration Guide (2026 April Release)

The ACC Forms API Migration Guide was created for developers who are migrating from Forms API v1 to v2. It outlines the changes developers need to make to their code.

General Changes

1. Changes to URIs (v1 to v2).
2. Some query parameters have been added, removed, or replaced.
3. Response structure has been significantly reorganized with the introduction of the nativeForm object.
4. The formTemplate object has been replaced with formTemplateId reference.
5. Weather data is no longer included in the response (only weatherId is provided). Use the new GET weather endpoint to retrieve weather details.
6. Values (customValues and tabularValues) are now nested within the nativeForm object.
7. Custom tables now require columnId (UUID) to identify columns—columnName is only supported for built-in tables.
8. Form status values have changed to align with the UI. See Status Changes for the full mapping.

New Features

New features for v2 include:

1. Custom Table Support: The v2 API supports custom tables in addition to the built-in tables (worklogEntries, materialsEntries, equipmentEntries). See Working with Custom Tables for details.
2. Enhanced Filtering and Sorting: New sort parameter replaces sortBy/sortOrder with support for multi-field sorting. New search parameter for text search.
3. Granular Data Inclusion: The include parameter allows you to selectively include additional data like nativeValues, tableMetadata, layoutInformation, sublocations, and inactiveFormTemplates.
4. Native Form Structure: The nativeForm object provides a more structured representation of form data with layout information and detailed column metadata.
5. Sublocation Support: New includeSubLocations parameter to include forms from sublocations.
6. Batch Update Options: New query parameters excludeFormResponse and includeNativeFormValues for controlling response data.
7. Batch Delete Endpoint: New POST values:batch-delete endpoint for deleting table rows from both native and custom tables.
8. Dedicated Table Values Endpoint: New GET table values endpoint for retrieving values from a specific table with pagination support.
9. Weather Data Endpoint: New v3 endpoint to retrieve weather details using the weatherId from forms. See Weather Data for details.

The following tables show the specific changes for each endpoint:

GET Forms

Status Changes

The v2 API uses updated status values that are consistent with the Forms UI. If your integration filters or displays form statuses, you will need to update your code to use the new values.

Note: The status query parameter on GET forms also uses the v2 values. For example, to filter for draft forms in v2, use status=inProgress instead of status=draft.

PUT values:batch-update

Working with Custom Tables

One of the key enhancements in v2 is support for custom tables. In v1, you could only work with the three built-in tables (worklogEntries, materialsEntries, equipmentEntries). In v2, you can work with any custom table defined in your form template.

In v1, you specified the table using the table field with one of the built-in aliases:

{
  "tabularValues": [
    {
      "id": "cb95aceb-187a-3a8f-2e5f-502a555c03d5",
      "table": "worklogEntries",
      "columns": [...]
    }
  ]
}

In v2, you use the schema field, which accepts both built-in aliases and custom table identifiers (UUIDs):

{
  "tabularValues": [
    {
      "id": "cb95aceb-187a-3a8f-2e5f-502a555c03d5",
      "schema": "worklogEntries",
      "columns": [...]
    },
    {
      "id": "2f7e534d-d084-594b-8aa6-147cb8fbc060",
      "schema": "ec7b2dea-9383-49d4-b22d-52e04659e28b",
      "columns": [...]
    }
  ]
}

Built-in tables (worklogEntries, materialsEntries, equipmentEntries) support both columnName and columnId to identify columns:

{
  "columns": [
    {
      "columnName": "trade",
      "textVal": "Electricians"
    }
  ]
}

Custom tables require columnId (UUID)—columnName is not supported:

{
  "columns": [
    {
      "columnId": "e5c8eg5d-35f9-694i-87h7-90ga7fa5j396",
      "textVal": "Excavator #12"
    }
  ]
}

To find the column UUIDs for custom tables, use GET sections to retrieve the table’s column definitions. For a complete workflow, see the Work with Form Layouts and Custom Tables tutorial.

In v1, tabular data was returned at the top level with built-in table names:

{
  "tabularValues": {
    "worklogEntries": [...],
    "materialsEntries": [...],
    "equipmentEntries": [...]
  }
}

In v2, all tabular data is returned in a unified array within nativeForm.tabularValues, with each row identified by its schema:

{
  "nativeForm": {
    "tabularValues": [
      {
        "id": "cb95aceb-187a-3a8f-2e5f-502a555c03d5",
        "table": "worklogEntries",
        "schema": "worklogEntries",
        "rank": 0,
        "deleted": false,
        "columns": [...],
        "updatedAt": "2020-11-20T16:14:27.615127+00:00",
        "updatedBy": "USER123A"
      },
      {
        "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "schema": "ec7b2dea-9383-49d4-b22d-52e04659e28b",
        "rank": 0,
        "deleted": false,
        "columns": [...],
        "updatedAt": "2020-11-20T16:14:27.615127+00:00",
        "updatedBy": "USER123A"
      }
    ]
  }
}

Note that for custom tables, the table field is null (or omitted), and you should use the schema field to identify the table type. Custom table rows are included in nativeForm.tabularValues alongside built-in table rows - no additional API calls are needed to fetch custom table values. Built-in tables have both table and schema fields populated with the same alias value (worklogEntries, materialsEntries, or equipmentEntries), while custom tables only have the schema field containing a UUID.

For tables with many rows or when you need pagination, use the dedicated GET table values endpoint:

GET /construction/forms/v1/projects/{projectId}/forms/{formId}/table/{fieldId}/values?limit=10&offset=0

The fieldId path parameter is the table’s schema identifier (UUID). For built-in tables, use these UUIDs:

• Work Log: 6c8055d5-1301-46f6-9d18-8a2a208a277e
• Materials: 2adf5ad9-d9d3-ee42-6fd8-015c34ce474d
• Equipment: 8af6c450-dd2a-32ae-0090-5493a9cc884e

For custom tables, use the schema UUID from the form’s layout definition.

The response includes both schema (for backwards compatibility) and fieldId fields with the same UUID value.

Understanding nativeForm

The v2 API introduces the nativeForm object, which provides a more structured representation of form data:

The nativeForm.layoutInfo object provides metadata about the form’s layout:

{
  "nativeForm": {
    "layoutInfo": {
      "uid": "7e8f9a0b-1c2d-3e4f-5a6b-7c8d9e0f1a2b",
      "type": "form",
      "description": "Daily Report Template",
      "hasSectionAssignees": false
    }
  }
}

In v2, tabular values include additional metadata:

• updatedAt: Timestamp when the row was last updated
• updatedBy: User ID who last updated the row
• rank: Sort order of the row in the table
• columns: Array of column values with detailed metadata including formValueId, columnId, and columnName

Custom values (non-tabular form fields) are now nested within nativeForm.customValues and retain the same structure as v1, but with the added context of being part of the native form structure.

Using the include Parameter

The v2 GET Forms endpoint supports an include parameter that allows you to selectively include additional data in the response:

• nativeValues: Include the nativeForm object with form values
• tableMetadata: Include metadata about tables in the form
• layoutInfo: Include detailed layout information
• sublocations: Include sublocation data
• inactiveFormTemplates: Include forms created from inactive templates

Example:

GET /construction/forms/v2/projects/{projectId}/forms?include=nativeValues&include=layoutInfo

By default, if the include parameter is not specified, the response will not include the nativeForm object. This allows you to optimize response size when you only need form metadata.

Deleting Table Values

Use the POST values:batch-delete endpoint to delete rows from both native and custom tables:

POST /construction/forms/v2/projects/{projectId}/forms/{formId}/values:batch-delete

Request body:

{
  "tabularValues": [
    {
      "id": "row-uuid-to-delete",
      "schema": "worklogEntries"
    },
    {
      "id": "custom-row-uuid",
      "schema": "ec7b2dea-9383-49d4-b22d-52e04659e28b"
    }
  ]
}

Optional query parameters:

• excludeFormResponse=true: Returns HTTP 204 with no body (faster for bulk operations)
• includeNativeFormValues=true: Includes the full native form values in the response

Weather Data

To retrieve full weather details using the weatherId from forms, use the GET weather endpoint:

GET /construction/forms/v3/projects/{projectId}/weather/{weatherId}

The response includes:

• Daily summary (summaryKey, precipitationType, precipitationAccumulation)
• Hourly observations (typically at 07:00, 12:00, and 16:00 local time) with temperature, wind speed, wind direction, and humidity

Note: Weather values are returned in metric units (Celsius, km/h, mm).

Imported from the Autodesk Platform Services documentation: https://aps.autodesk.com/en/docs/acc/v1/overview/migration-guides/forms-v1-to-v2.