Request

Response

    Forms
    GET

    v2/projects/{projectId}/forms

    Returns a paginated list of forms in a project.

    Forms are sorted by updatedAt in ascending order by default (oldest first).

    Note: For PDF forms, pdfFile references the PDF document; to retrieve the field values entered into the PDF, use the GET PDF values endpoint. For web forms, nativeForm includes general form data and layout information. To retrieve custom field values or table values for web forms, use the GET custom values and GET table values endpoints respectively.

    Resource Information

    Method and URI
    GET
    https://developer.api.autodesk.com/construction/forms/v2/projects/:projectId/forms
    Authentication Context
    User context required
    Required OAuth Scopes
    data:read
    Data Format
    JSON

    Request

    Headers

    Authorization*
    string
    Must be Bearer <token>, where <token> is a three-legged access token obtained via an Authorization Code flow or a Secure Service Account (SSA) flow.

    The SSA flow is designed for headless server-to-server operations. While it functions like a two-legged flow (no user interaction), it is classified as three-legged because it preserves user context.

    * Required

    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 Forma API by removing the “b." prefix. For example, a project ID of b.a4be0c34a-4ab7 translates to a project ID of a4be0c34a-4ab7.

    Request

    Query String Parameters

    offset
    int
    The number of records to skip before returning results. Default value: 0. To retrieve subsequent pages, increase the offset by the number of records returned in the previous request.
    limit
    int
    The maximum number of results per page. Possible values: 1-50. Default value: 50.
    ids
    array: string
    An array of Form IDs to retrieve.
    formDateMin
    string
    Return Forms with formDate at or after specified date.
    formDateMax
    string
    Return Forms with formDate at or before specified date.
    updatedAfter
    datetime: ISO 8601
    Return Forms updated at or after a specified time.
    updatedBefore
    datetime: ISO 8601
    Return Forms updated at or before a specified time.
    templateId
    string
    Return Forms on template with given ID.
    statuses
    array: string
    Return Forms with given statuses.
    sort
    string
    A string that specifies how to sort returned objects. The string provides a valid name (formDate, updatedAt, status, formNum, description, dueDate, templateName, createdByName, updatedByName) with an optional direction, either asc (ascending) or desc (descending). The string may contain multiple comma-separated expressions (max of 3) for secondary sorts. The default sort order is asc if not provided.

    Example: updatedAt desc,formNum asc

    search
    string
    Search for forms containing the exact match of the specified text.
    locationIds
    array: string
    A sequence of location IDs. Each returned objects must/will be associated with one of the locations specified by the IDs.
    includeSubLocations
    boolean
    Include forms associated with sublocations of the specified locationIds.
    include
    array: string
    Include the specified extra fields. You can specify multiple values by repeating the parameter (e.g., include=sublocations&include=layoutInfo). Possible values: sublocations, inactiveFormTemplates, layoutInfo.

    Response

    HTTP Status Code Summary

    200
    OK
    Forms in project at specified page.
    400
    Bad Request
    The request is invalid due to malformed syntax or a missing request header.
    401
    Unauthorized
    The request lacks valid authentication credentials.
    403
    Forbidden
    The client is authenticated but does not have permission to access the resource.
    404
    Not Found
    The resource cannot be found.
    429
    Too Many Requests
    The request exceeds the rate limit for this resource.
    500
    Internal Server Error
    The request failed due to an internal server error.

    Response

    Body Structure (200)

    Expand all
    data
    array: object
    List of forms in the project.
    formTemplateId
    string: UUID
    Unique identifier of template the form belongs to.
    id
    string: UUID
    Unique identifier of the form.
    status
    enum:string
    Current state of the form e.g. inProgress Possible values: draft, inReview, submitted, archived
    formNum
    int
    Unique identifier of form, autoincremental, unique per project.
    formDate
    string
    Date the Form is created for.
    assigneeId
    string
    ID of the entity form is assigned to.
    assigneeType
    enum:string
    Type of the entity form is assigned to. Possible values: company, role, user
    dueDate
    string
    Date the Form is due.
    locationId
    string: UUID
    The unique identifier of the Form’s location
    createdBy
    string
    User ID that created the Form.
    createdAt
    datetime: ISO 8601
    Timestamp when the form was received and stored on the server. UTC date and time in ISO-8601 format.
    userCreatedAt
    datetime: ISO 8601
    Timestamp when the form was created on the client device or external system. This may differ from createdAt if the form was created offline and synced later. UTC date and time in ISO-8601 format.
    notes
    string
    Form notes.
    description
    string
    Form description.
    name
    string
    Form name
    updatedAt
    datetime: ISO 8601
    When form was last updated, UTC date and time in ISO-8601 format.
    updatedBy
    string
    User ID that last updated the Form.
    weatherId
    int
    Unique identifier of weather associated with this form.
    lastSubmitterSignature
    string
    Signature of the reviewer who last submitted the Form (if applicable). Signature value (base64 encoded SVG).
    lastSubmittedBy
    string
    User ID that last submitted the Form.
    lastSubmittedAt
    datetime: ISO 8601
    When form was last submitted (if applicable), UTC date and time in ISO-8601 format.
    lastReopenedBy
    string
    User ID that re-opened the Form (if applicable).
    lastStatusChanges
    object
    Contains the last transition into each status. Since a form can transition between statuses multiple times (e.g., reopened from closed back to inProgress), this shows the most recent transition for each status the form has been in.
    previousStatus
    string
    The status the form was in before the current status.
    inProgress
    object
    The last time the form transitioned into inProgress status.
    by
    string
    User ID who made the status change.
    at
    string
    When the status change occurred, UTC date and time in ISO-8601 format.
    inReview
    object
    The last time the form transitioned into inReview status.
    by
    string
    User ID who made the status change.
    at
    string
    When the status change occurred, UTC date and time in ISO-8601 format.
    closed
    object
    The last time the form transitioned into closed status.
    by
    string
    User ID who made the status change.
    at
    string
    When the status change occurred, UTC date and time in ISO-8601 format.
    archived
    object
    The last time the form transitioned into archived status.
    by
    string
    User ID who made the status change.
    at
    string
    When the status change occurred, UTC date and time in ISO-8601 format.
    discarded
    object
    The last time the form transitioned into discarded status.
    by
    string
    User ID who made the status change.
    at
    string
    When the status change occurred, UTC date and time in ISO-8601 format.
    nativeForm
    object
    Native form data including layout information. To retrieve form field values, use the GET custom values endpoint.
    id
    string: UUID
    The form’s unique identifier. This is the same value as the top-level form id.
    layoutId
    string: UUID
    Unique identifier of the layout.
    version
    string
    Semantic version indicating the feature set available for this form’s template. Clients can use this to determine which features are supported. For example, version 13.0 or higher is required for custom tables support. The Forms App typically uses the highest available version.
    layoutInfo
    object
    Information about the layout of this form.
    description
    string
    The description of the layout.
    hasSectionAssignees
    boolean
    Determines if section assignment is enabled.
    pdfFile
    object
    PDF file information for the form.
    id
    string
    Unique identifier of the PDF file.
    fileName
    string
    Name of the PDF file.
    pdfUrl
    string
    URL to download the PDF file.
    lastFetchedAt
    datetime: ISO 8601
    When form was retrieved from the API, UTC date and time in ISO-8601 format.
    pagination
    object
    Pagination information.
    offset
    int
    The number of results skipped.
    limit
    int
    The maximum number of results per page.
    totalResults
    int
    The total number of results.
    nextUrl
    string
    The URL for the next page of results. The value can be null if it is the last page.

    Example

    Forms in project at specified page.

    Request

    curl -v 'https://developer.api.autodesk.com/construction/forms/v2/projects/:projectId/forms' \
      -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a'
    

    Response

    {
      "data": [
        {
          "formTemplateId": "2f634a22-779d-4930-9f08-8391a41fea05",
          "id": "932da979-e537-4530-b8aa-18607ac6db37",
          "status": "draft",
          "formNum": 1,
          "formDate": "2020-11-20",
          "assigneeId": "fc830fd8-f1ef-4cd6-9163-fb115dc698d7",
          "assigneeType": "company",
          "dueDate": "2020-11-25",
          "locationId": "d14ce3a6-e61b-4ab0-a9be-5acf7b5366df",
          "createdBy": "USER123A",
          "createdAt": "2019-01-20T12:14:28.000000+00:00",
          "userCreatedAt": "2019-01-20T12:14:27.615127+00:00",
          "notes": "Form notes",
          "description": "Form description",
          "name": "Form name",
          "updatedAt": "2020-11-20T16:14:27.615127+00:00",
          "updatedBy": "USER123A",
          "weatherId": 12345,
          "lastSubmitterSignature": "PHN2ZyBoZWlnaHQ9IjIwMCIgd2lkdGg9IjUwMCI+PHBvbHlsaW5lIHBvaW50cz0iMjAsMjAgNDAsMjUgNjAsNDAgODAsMTIwIDEyMCwxNDAgMjAwLDE4MCIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6YmxhY2s7c3Ryb2tlLXdpZHRoOjMiIC8+PC9zdmc+",
          "lastSubmittedBy": "USER123A",
          "lastSubmittedAt": "2020-11-20T18:14:27.615127+00:00",
          "lastReopenedBy": "USER123A",
          "lastStatusChanges": {
            "previousStatus": "inProgress",
            "inProgress": {
              "by": "USER123A",
              "at": "2020-11-20T16:14:27.615127+00:00"
            },
            "inReview": {
              "by": "USER123A",
              "at": "2020-11-20T16:14:27.615127+00:00"
            },
            "closed": {
              "by": "USER123A",
              "at": "2020-11-20T16:14:27.615127+00:00"
            },
            "archived": {
              "by": "USER123A",
              "at": "2020-11-20T16:14:27.615127+00:00"
            },
            "discarded": {
              "by": "USER123A",
              "at": "2020-11-20T16:14:27.615127+00:00"
            }
          },
          "nativeForm": {
            "id": "932da979-e537-4530-b8aa-18607ac6db37",
            "layoutId": "123e4567-e89b-12d3-a456-426614174001",
            "version": "13.0",
            "layoutInfo": {
              "description": "",
              "hasSectionAssignees": false
            }
          },
          "pdfFile": {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "fileName": "form_report.pdf",
            "pdfUrl": "https://example.com/form_report.pdf"
          },
          "lastFetchedAt": "2020-11-20T16:14:27.615127+00:00"
        }
      ],
      "pagination": {
        "offset": 0,
        "limit": 50,
        "totalResults": 1,
        "nextUrl": null
      }
    }
    
    Show More