Skip to navigation
How-to GuideSubmittals

Setting Up a New Project in Submittals

View as Markdown

This tutorial explains how to configure a newly created Autodesk Forma project for use with Submittals. The steps include verifying user permissions, assigning a Submittal Manager, and configuring the custom identifier sequence type.

For more information about working with submittals, see the Help documentation.

Before You Begin

Step 1: Verify User Permissions

Call GET users/me using the project ID (d4be9275-1e59-4ba9-a68b-2dcec49e25c0) to retrieve the relevant permissions for the user.

Look for the following in the response:

  • The roles array – check if "4" (Admin) is present.
  • The permittedActions array – check if an entry with "id": "AdminMapping::create" is present.

Request

curl -v 'https://developer.api.autodesk.com/construction/submittals/v2/projects/d4be9275-1e59-4ba9-a68b-2dcec49e25c0/users/me' \
  -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a'

Response

  • From the roles array, verify that "4" (Admin) is present. The possible role values are "1" (Manager), "2" (User), and "4" (Admin). Only a user with the Admin role can create a Submittal Manager mapping (Step 2) or change the sequence type (Step 3).
  • From the permittedActions array, verify that an entry with "id": "AdminMapping::create" is present. This confirms the user is permitted to create an admin mapping. For a full description of the permittedActions structure, see the GET users/me endpoint reference.

Step 2: Create the Submittal Manager Mapping

Use POST mappings to create an admin mapping, using the following values:

  • autodeskId: the Autodesk ID of the user, role, or company to assign as Submittal Manager (WBGQM228YWFQ in this example).
  • userType: "1" (User), "2" (Company), or "3" (Role). In this example, "1" (User).
  • submittalsRole: "1" (Manager) – currently the only supported value.

Request

curl -X POST 'https://developer.api.autodesk.com/construction/submittals/v2/projects/d4be9275-1e59-4ba9-a68b-2dcec49e25c0/settings/mappings' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' \
-H 'Content-Type: application/json' \
-d '{
    "autodeskId": "WBGQM228YWFQ",
    "userType": "1",
    "submittalsRole": "1"
    }'

Response

{
"id": "eeb77e82-931a-4434-a423-b1bdef156632",
"createdBy": "MFEGJ9W5GGQL",
"createdAt": "2026-01-18T10:16:00.412194Z",
"updatedBy": "MFEGJ9W5GGQL",
"updatedAt": "2026-01-18T10:16:00.412208Z",
"oxygenId": "WBGQM228YWFQ",
"autodeskId": "WBGQM228YWFQ",
"userType": "1",
"submittalsRole": "1"
}

Note the admin mapping ID (id): eeb77e82-931a-4434-a423-b1bdef156632. This confirms the Submittal Manager has been assigned to the project.

Step 3: Set the Custom Identifier Sequence Type

Use POST custom-identifier:change-sequence-type to set the sequence type for the project. As verified in Step 1, only a user with the Admin role can perform this action:

  • sequenceType: "2" (Spec) in this example.

The two available sequence types are:

  • 1 – Global: assigns a single sequential number across all submittal items.
  • 2 – Spec: numbers items sequentially within their spec section.

Note that the sequence type can only be changed from Global to Spec — once set to Spec, it cannot be changed back.

For more details about custom numbering, see the Help documentation.

Request

curl -X POST 'https://developer.api.autodesk.com/construction/submittals/v2/projects/d4be9275-1e59-4ba9-a68b-2dcec49e25c0/settings/custom-identifier:change-sequence-type' \
  -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' \
  -H 'Content-Type: application/json' \
  -d '{ "sequenceType": "2" }'

Response

{
"id": "7eda559f-53c0-448e-a038-b28e543ab677",
"resultsPayload": {},
"asyncState": "1",
"createdAt": "2026-01-18T10:19:11.307162Z",
"updatedAt": "2026-01-18T10:19:11.307189Z",
"startedAt": null
}

The response includes an async job ID, indicating that the operation is being processed in the background.

In the next step, we will monitor the status of this job using the job ID (7eda559f-53c0-448e-a038-b28e543ab677).

Step 4: Poll the Async Job Status

Call GET async-jobs/{asyncJobId} using the job ID (7eda559f-53c0-448e-a038-b28e543ab677) returned in Step 3 to poll the status of the async job. Repeat this call until the job reaches a terminal state.

The possible asyncState values are:

  • 1 – Pending
  • 2 – Started
  • 3 – Success
  • 4 – Failure

Request

curl -v 'https://developer.api.autodesk.com/construction/submittals/v2/projects/d4be9275-1e59-4ba9-a68b-2dcec49e25c0/async-jobs/7eda559f-53c0-448e-a038-b28e543ab677' \
  -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a'

Response

{
"id": "7eda559f-53c0-448e-a038-b28e543ab677",
"resultsPayload": {},
"asyncState": "3",
"createdAt": "2026-01-18T10:19:11.307162Z",
"updatedAt": "2026-01-18T10:19:11.431956Z",
"startedAt": "2026-01-18T10:19:11.350000Z"
}

Note the asyncState value of 3, indicating that the operation has completed successfully. If the job completes with asyncState = 4, the response will include error information in resultsPayload.

By completing this tutorial, you have:

  • Verified user permissions using the roles and permittedActions arrays from a single call
  • Assigned a Submittal Manager using admin mappings
  • Configured the submittals numbering method
  • Used async jobs to apply configuration changes safely

The project is now ready for creating and managing Submittal items.

Imported from the Autodesk Platform Services documentation: https://aps.autodesk.com/en/docs/acc/v1/tutorials/submittals/submittals-settings-up-new-project.