v1/projects/{projectId}/forms/{formId}/values:batch-update
Updates a form’s main form fields, both tabular and non-tabular. Note that we do not currently support updating PDF forms.
To edit form values, the form needs to be in draft status and the user must have permissions to edit the form. See the Forms help documentation for information about template configuration.
To update non-tabular fields you need to use the relevant value type. For example, to update a number field you need to use numberVal
. To find the value type for the field, call GET forms and check the valueName
.
See the Manage Forms tutorial for more details about how to update forms.
To update the form’s details, use PATCH forms/:formId API.
Note that we do not currently support adding issues or photos.
Resource Information
Method and URI | PUT https://developer.api.autodesk.com/construction/forms/v1/projects/:projectId/forms/:formId/values:batch-update |
Authentication Context | user context required |
Required OAuth Scopes | data:write |
Data Format | JSON |
Request
Headers
Authorization* string | Must be Bearer <token> , where <token> is obtained via a three-legged OAuth flow. |
Content-Type* string | Must be application/json |
Request
URI Parameters
projectId string | The ID of the project.
Use the Data Management API to retrieve the project ID. For more information, see the Retrieve a Project ID tutorial. You need to convert the project ID into a project ID for the ACC API by removing the “b." prefix. For example, a project ID of b.a4be0c34a-4ab7 translates to a project ID of a4be0c34a-4ab7. |
formId string | The unique identifier of the form.
Use GET forms to retrieve the form ID. |
Request
Body Structure
customValues array: object | The list of non-tabular fields. |
fieldId* string: UUID | The unique identifier of the field. |
notes string | Text for the field’s notes section. This is relevant for all fields.
Max length: 8000 |
textVal string | The attribute used for updating text value fields, For example, textVal: This is my response! .
Each non-tabular field is assigned a specific value type, which you need to specify when updating the field. Max length: 8000 |
choiceVal string | The attribute used for updating single-select and dropdown fields. For example, choiceVal: Answer 3 .
Each non-tabular field is assigned a specific value type, which you need to specify when updating the field. |
arrayVal array: string | The attribute used for updating multi-select fields. For example, arrayVal: ["Answer 1", "Answer 2"] .
Each non-tabular field is assigned a specific value type, which you need to specify when updating the field. |
dateVal string | The attribute used for updating date fields, in the following format (YYYY-MM-DD) . For example, "dateVal": "1999-12-31" .
Each non-tabular field is assigned a specific value type, which you need to specify when updating the field. |
numberVal number | The attribute used for updating number fields. For example, "numberVal": "42" .
Each non-tabular field is assigned a specific value type, which you need to specify when updating the field. |
toggleVal enum:string | The attribute used for updating preconfigured fields. For example, “toggleVal”: “Yes”.
Each non-tabular field is assigned a specific value type, which you need to specify when updating the field. |
svgVal string | The attribute used for updating signature fields.
Each non-tabular field is assigned a specific value type, which you need to specify when updating the field. The signature needs to be in SVG format and it needs to be base64 encoded. |
name string | The name of the person who signed the form. By default, it is the name of the logged in user. It is only relevant for signature fields. To update the name you need to use the signature field ID. |
tabularValues array: object | The list of tabular fields. |
id* string: UUID | The ID of the table row. You need to generarte the ID (UUID) for the row. |
table* enum:string | The table to update.
Possible values: worklogEntries , materialsEntries , equipmentEntries |
columns array: object | The set of values for the columns in the row. |
columnName enum:string | The name of the column to update. Possible values:
For the Work Log table:
For the Equipment table:
For the Materials table:
|
numberVal number | The attribute used for updating number columns. For example, "numberVal": "42" .
Each tabular field is assigned a specific value type, which you need to specify when updating the field. |
textVal string | The attribute used for updating text value columns.
Each tabular field is assigned a specific value type, which you need to specify when updating the field. Max length: 8000 |
timespanVal number | The attribute used for updating time-related columns.
Each tabular field is assigned a specific value type, which you need to specify when updating the field. |
Response
HTTP Status Code Summary
200 OK | The updated Form |
400 Bad Request | The request could not be understood by the server due to malformed syntax or missing request header |
401 Unauthorized | The request was not accepted because it lacked valid authentication credentials |
403 Forbidden | The request was not accepted because the client is authenticated, but is not authorized to access the target resource |
404 Not Found | The resource cannot be found |
409 Conflict | The request could not be completed due to a conflict with the current state of the target resource |
429 Too Many Requests | The request could not be completed due to a conflict with the current state of the target resource |
500 Internal Server Error | The request could not be completed due to a conflict with the current state of the target resource |
Response
Body Structure (200)
status enum:string | The current status of the form. Note that forms are created in draft status. Possible values:
|
id string | The unique identifier of the form. |
projectId string | The unique identifier of the project the form belongs to. |
formNum int | A chronological user-fiendly identifier of the form within the project e.g. form #5. |
formDate string | Date the form pertains to. |
assigneeId string | The unique identifier of the user, role, or company the form is assigned to. |
assigneeType enum:string | Type of entity the form is assigned to.
Possible values: company , role , user |
locationId string | Location identifier associated with the form. For more information about the location, see GET nodes. |
updatedAt datetime: ISO 8601 | When form was last updated, UTC date and time in ISO-8601 format. |
createdBy string | The unique identifier of the user who created the form. |
notes string | Text for the form’s notes section. |
description string | Text for the form’s description section. |
name string | The name of the form instance.
Max length: 100 |
formTemplate object | Information about the form’s template. |
status enum:string | Possible values: active , inactive , deleted |
id string | The unique identifier of the template. |
projectId string | Unique indentifier of the project the template belongs to. |
name string | Name of the form template. |
templateType string | User defined type of the form template. |
pdfValues array: object | For PDF forms, values extracted from fields in the PDF. |
name string | The name of the PDF field. |
value string | The value of the PDF field. |
pdfUrl string | For PDF forms, the URL to download the form’s PDF. |
weather object | Weather forecast captured on the form. |
summaryKey string | A code describing the the weather (e.g. Clear, PartlyCloudy). |
precipitationAccumulation number | Amount of precipitation accumulated throughout the day. |
precipitationAccumulationUnit string | Indicates the measurement unit of the precipitationAccumulation . |
temperatureMin number | Minimum temperature during the day. |
temperatureMax number | Maximum temperature during the day. |
temperatureUnit string | Indicates the measurement unit of the temperature values e.g. temperatureMin , temperatureMax , temp . |
humidity number | A percentage value indicating the humidity over the course of the day. |
windSpeed number | Average wind speed observed throughout the day. |
windGust number | Maximum wind speed observed throughout the day. |
speedUnit string | Indicates the measurement unit of the windSpeed and windGust . |
windBearing number | Direction of the wind, in degrees. |
hourlyWeather array: object | Weather information for specific hours (07:00:00, 12:00:00, 16:00:00). |
id int | Unique identifier. |
hour string | Hour of the day for this forecast. |
temp number | Temperature during specified hour. |
windSpeed number | Average wind speed. |
windBearing int | Direction of the wind, in degrees. |
humidity number | A percentage value indicating the humidity. |
fetchedAt datetime: ISO 8601 | Date when weather was fetched from weather API. |
createdAt datetime: ISO 8601 | Date when weather was first fetched. |
updatedAt datetime: ISO 8601 | When the weather was last updated. |
provider enum:string | Indicates the source of the weather data.
Possible values: darksky , weatherkit |
tabularValues object | For non-PDF forms, data stored in the tables on the form. |
worklogEntries array: object | Entries associated with work log table in a Form. |
id string | Unique identifier for the work log row. |
deleted boolean | Indicates if the work log row has been deleted. |
trade string | A text field indicating the worker’s trade. |
timespan int | Total duration of work performed (in milliseconds). |
headcount int | Number of workers. |
description string | A text description of the work performed. |
materialsEntries array: object | Entries associated with materials table in a Form. |
id string | Unique identifier for the material log row. |
deleted boolean | Indicates if the material log row has been deleted. |
item string | Text indicating the material used. |
quantity number | The quantity of material that was used. |
unit string | The unit of measure for the quantity specified. |
description string | Additional description of the materials. |
equipmentEntries array: object | Entries associated with equipment table in a Form. |
id string | Unique identifier for the equipment log row. |
deleted boolean | Indicates if the equipment log row has been deleted. |
item string | Text indicating the equipment utilized. |
timespan int | The total time all equipment was utilized (in milliseconds). |
quantity number | The amount of equipment utilized. |
description string | Text describing the equipment utilized. |
customValues array: object | For non-PDF forms, data stored in the form fields. |
fieldId string | The unique identifier of the field. |
sectionLabel string | Name of the section containing this field. |
itemLabel string | The field’s label or question text. |
valueName enum:string | Indicates the type of value used for this item.
Possible values: textVal , toggleVal , arrayVal , numberVal , choiceVal , dateVal , svgVal |
toggleVal enum:string | A boolean like enum value.
Possible values: Yes , No , False , True , Minus , Plus , Fail , Pass , NA |
textVal string | A text value. |
arrayVal string | Multi select values. |
numberVal number | A numeric value. |
choiceVal string | A single select value. |
dateVal string | A date value. |
svgVal string | A signature value (base64 encoded SVG). |
notes string | Text for the field’s notes section.
Max length: 8000 |
lastReopenedBy string | Unique identifier for the user that last re-opened the Form (if applicable). |
lastSubmitterSignature string | Signature of the reviewer who last submitted the Form (if applicable). Signature value (base64 encoded SVG). |
userCreatedAt datetime: ISO 8601 | When form was created on the client, UTC date and time in ISO-8601 format. |
createdAt datetime: ISO 8601 | When form was created on the server, UTC date and time in ISO-8601 format. |