Create project | Autodesk API Documentation POC

Creates a new project in the specified hub. You can create the project directly, or clone it from a project template.

When you create a project directly (not from a template), this endpoint automatically adds all of the products that are associated with the current hub to the project and activates them.
To clone the project from a template, provide the template object in the request to specify the project template ID. The products and settings in the template are copied to the new project, and the products associated with the current hub are ignored.

Note that currently, a project that is cloned from a template does not have any project members assigned initially. You can assign all of the template project members to the project in bulk by calling POST projects/:projectId/users to assign a project administrator to the project. This administrator can be any user who is currently in the same hub as the project. This triggers the automatic process of assigning the template project members to the cloned project and activating them.

You can also create a project template. Include the classification field in the request with a value of template, and set the value of the type field to Template Project. You must provide both of these values, otherwise the request returns a 400 error. Use the Forma Build UI to edit the template details and permissions, add project members to the template, and configure the template’s notification settings.

Note that you cannot create a project template from another project template, but you can base it on a production project. Set the value of the template.projectId field to the id of the production project. The new project template is not completely configured for use, but it will get you started.

For more information about creating projects, see the Create and Configure Projects tutorial.

Note that the Authorization header token can be obtained either via a three-legged OAuth flow, or via a two-legged Oauth flow with user impersonation, for which the User-Id header is required.

Note that the products array is ignored in the request. However, the products in the project do appear in the response for this and other endpoints.

Note: This operation is not backward compatible with BIM 360 projects. It only works with Autodesk Construction Cloud projects.

Authentication

AuthorizationBearer

OAuth 2.0 (2-legged with impersonation) — application context with user impersonation required. Send a User-Id header identifying the member to act on behalf of; the token authorizes the application, while the operation is evaluated against that member’s project permissions.

Client Credentials Flow

Token URL: https://developer.api.autodesk.com/authentication/v2/token

Scopes:

account:read — read account and project data
account:write — modify account and project data

AuthorizationBearer

OAuth 2.0 (3-legged) — user context required. Also accepts a Secure Service Account (SSA) token, which is headless like a two-legged flow but classified as three-legged because it preserves user context.

Authorization Code Flow

Authorization URL: https://developer.api.autodesk.com/authentication/v2/authorize

Token URL: https://developer.api.autodesk.com/authentication/v2/token

Refresh URL: https://developer.api.autodesk.com/authentication/v2/token

Scopes:

data:read — read your data
account:read — read account and project data
account:write — modify account and project data

Path parameters

accountIdstringRequiredformat: "uuid"

The ID of the hub that contains the projects. This corresponds to the hub ID used in the Data Management API, with the “b.” prefix removed. For example, b.c8b0c73d-3ae9 becomes c8b0c73d-3ae9.

Headers

User-IdstringOptionalformat: "uuidOrAutodeskId"

The ID of a user on whose behalf your request is acting.

Your app has access to all users specified by the administrator in the SaaS integrations UI. Provide this header value to identify the user to be affected by the request.

You can use either the user’s Forma ID (id), or their Autodesk ID (autodeskId).

Note that this header is required for hub Admin POST, PATCH, and DELETE endpoints if you want to use a 2-legged authentication context. This header is optional for hub Admin GET endpoints.

Request

The name and type fields are required. All other fields are optional.

If you include the project.template object in the request, the new project’s products and settings will match those of the template project. If you exclude project.template, the endpoint automatically activates all of the products associated with the Forma platform for the new project.

Note that the products array is ignored in the request. However, it does appear in the response for endpoints that return it (including this endpoint).

namestringRequired<=255 characters

The name of the project.

typestringRequired<=255 characters

The type of the project. Any value is accepted, but the following are recommended:

Possible values: Convention Center, Data Center, Hotel / Motel, Office, Parking Structure / Garage, Performing Arts, Restaurant, Retail, Stadium / Arena, Theme Park, Warehouse (non-manufacturing), Assisted Living / Nursing Home, Hospital, Medical Laboratory, Medical Office, OutPatient Surgery Center, Court House, Dormitory, Education Facility, Government Building, Library, Military Facility, Museum, Prison / Correctional Facility, Recreation Building, Religious Building, Research Facility / Laboratory, Multi-Family Housing, Single-Family Housing, Airport, Bridge, Canal / Waterway, Dams / Flood Control / Reservoirs, Harbor / River Development, Rail, Seaport, Streets / Roads / Highways, Transportation Building, Tunnel, Waste Water / Sewers, Water Supply, Manufacturing / Factory, Mining Facility, Oil & Gas, Plant, Power Plant, Solar Farm, Utilities, Wind Farm, Demonstration Project, Template Project and Training Project.

startDatedateOptional

The estimated start date for the project, in ISO 8601 format.

endDatedateOptional

The estimated end date for the project, in ISO 8601 format.

classificationenumOptionalDefaults to production

The classification of the project. Possible values:

production – Standard project.
template – A project that serves as a template for creating new projects.
component – A placeholder project containing reusable components (e.g., forms). Only one component project is allowed per hub. Known as a library in the Forma UI.
sample – A single sample project automatically created for Forma trials (limited to one per hub).

Allowed values:

projectValueobjectOptional

Contains details about the estimated cost of the project, including the amount (value) and the currency (currency).

statusenumOptionalDefaults to active

The status of the project.

Possible values: active, pending, archived and suspended.

Allowed values:

jobNumberstringOptional<=100 characters

A user-defined identifier for the project. This value is assigned when the project is created and can be used to filter projects. It supports partial matches when used with filterTextMatch.

addressLine1stringOptional<=255 characters

The first line of the project’s address.

addressLine2stringOptional<=255 characters

Additional address details for the project location.

citystringOptional<=255 characters

The city wher the project is located.

stateOrProvincestringOptional<=255 characters

The state or province where the project is located. It must be a valid name or an ISO 3166-2 code. The provided state or province must exist in the country of the project.

postalCodestringOptional<=255 characters

The postal or ZIP code of the project location.

countrystringOptional<=255 characters

The country where the project is located, using an ISO 3166-1 alpha-2 code.

latitudestringOptional<=25 characters

The latitude coordinate of the project location.

longitudestringOptional<=25 characters

The longitude coordinate of the project location.

timezoneenumOptional

The time zone where the project is located. It must be a valid IANA time zone name from the IANA Time Zone Database (e.g., America/New_York). If no time zone is set, this field may be null.

constructionTypestringOptional

The type of construction for the project. Recommended values: New Construction, Renovation. Any value is accepted.

deliveryMethodstringOptional

The method used to deliver the project. Recommended values include Design-Bid-Build, Construction Management (CM) at Risk, and Integrated Project Delivery (IPD). Any value is accepted.

contractTypestringOptional

The type of contract for the project. For example, Lump Sum, Cost Plus, Guaranteed Maximum Price, Unit Price. Any value is accepted.

currentPhasestringOptional

The current phase of the project. Recommended values include, Concept, Design, Bidding, Planning, Preconstruction, Construction, Commissioning, Warranty, Complete, Facility Management, Operation, Strategic Definition, Preparation and Brief, Concept Design, Developed Design, Technical Design, Construction, Handover and Close Out and In Use.

Any value is accepted.

businessUnitIdstringOptionalformat: "uuid"

The ID of the business unit that the project is associated with.

sheetCountintegerOptional

The total number of sheets associated with the project.

Note that this field is relevant only in responses. It is ignored in requests.

productsanyOptional

platformenumOptionalDefaults to acc

The APS platform where the project is stored. Possible values: acc, bim360.

Note that this field is relevant only in responses. It is ignored in requests.

Allowed values:

companyCountintegerOptional

The total number of companies associated with the project.

Note that this field is relevant only in responses. It is ignored in requests.

memberCountintegerOptional

The total number of members on the project.

Note that this field is relevant only in responses. It is ignored in requests.

templateobjectOptional

Information about a project in the current user’s hub that is configured as a template from which to copy products and settings when creating a new project:

If you include this object in a POST accounts/:accountId/projects request, the cloned project’s products and settings will match those of the template project.
If you omit this object from a POST accounts/:accountId/projects request, all of the current Forma hub’s products are added to the cloned project and activated.

Response headers

RateLimit-Remaininginteger

The number of requests remaining in the current rate-limit window.

RateLimit-Valueinteger

The maximum number of requests that the server is willing to accept during the current full minute

Request-IdstringOptional

The unique ID for this request which can be provided when reporting issues to assist in facilitating improved research.

Response-TimestringOptional

The time taken to generate the response.

Response

APS has received the request but not yet completed it.

idstringOptionalRead-onlyformat: "uuid"

The internally generated ID for the project.

namestringOptional<=255 characters

The name of the project.

startDatedateOptional

The estimated start date for the project, in ISO 8601 format.

endDatedateOptional

The estimated end date for the project, in ISO 8601 format.

typestringOptional<=255 characters

The type of the project. Any value is accepted, but the following are recommended:

classificationenumOptionalDefaults to production

The classification of the project. Possible values:

production – Standard project.
template – A project that serves as a template for creating new projects.
component – A placeholder project containing reusable components (e.g., forms). Only one component project is allowed per hub. Known as a library in the Forma UI.
sample – A single sample project automatically created for Forma trials (limited to one per hub).

Allowed values:

projectValueobjectOptional

Contains details about the estimated cost of the project, including the amount (value) and the currency (currency).

statusenumOptionalDefaults to active

The status of the project.

Possible values: active, pending, archived and suspended.

Allowed values:

jobNumberstringOptional<=100 characters

A user-defined identifier for the project. This value is assigned when the project is created and can be used to filter projects. It supports partial matches when used with filterTextMatch.

addressLine1stringOptional<=255 characters

The first line of the project’s address.

addressLine2stringOptional<=255 characters

Additional address details for the project location.

citystringOptional<=255 characters

The city wher the project is located.

stateOrProvincestringOptional<=255 characters

The state or province where the project is located. It must be a valid name or an ISO 3166-2 code. The provided state or province must exist in the country of the project.

postalCodestringOptional<=255 characters

The postal or ZIP code of the project location.

countrystringOptional<=255 characters

The country where the project is located, using an ISO 3166-1 alpha-2 code.

latitudestringOptional<=25 characters

The latitude coordinate of the project location.

longitudestringOptional<=25 characters

The longitude coordinate of the project location.

timezoneenumOptional

The time zone where the project is located. It must be a valid IANA time zone name from the IANA Time Zone Database (e.g., America/New_York). If no time zone is set, this field may be null.

constructionTypestringOptional

The type of construction for the project. Recommended values: New Construction, Renovation. Any value is accepted.

deliveryMethodstringOptional

The method used to deliver the project. Recommended values include Design-Bid-Build, Construction Management (CM) at Risk, and Integrated Project Delivery (IPD). Any value is accepted.

contractTypestringOptional

The type of contract for the project. For example, Lump Sum, Cost Plus, Guaranteed Maximum Price, Unit Price. Any value is accepted.

currentPhasestringOptional

Any value is accepted.

businessUnitIdstringOptionalformat: "uuid"

The ID of the business unit that the project is associated with.

lastSignIndatetimeOptionalRead-only

The timestamp of the last time someone signed into the project.

imageUrlstringOptionalRead-only<=255 characters

The URL of the main image associated with the project. This field can be null.

thumbnailImageUrlstringOptionalRead-only<=255 characters

The URL of the project’s thumbnail image. This field can be null.

createdAtdatetimeOptionalRead-only

The timestamp when the project was created, in ISO 8601 format. This value is set at creation and does not change.

updatedAtdatetimeOptionalRead-only

The timestamp when the project was last updated, in ISO 8601 format. This reflects changes to project fields but not updates to resources within the project.

memberGroupIdstringOptionalRead-only<=25 characters

Not relevant

adminGroupIdstringOptionalRead-only<=25 characters

Not relevant

accountIdstringOptionalRead-onlyformat: "uuid"

The hub ID associated with the project.

sheetCountintegerOptional

The total number of sheets associated with the project.

Note that this field is relevant only in responses. It is ignored in requests.

productsanyOptional

platformenumOptionalDefaults to acc

The APS platform where the project is stored. Possible values: acc, bim360.

Note that this field is relevant only in responses. It is ignored in requests.

Allowed values:

companyCountintegerOptional

The total number of companies associated with the project.

Note that this field is relevant only in responses. It is ignored in requests.

memberCountintegerOptional

The total number of members on the project.

Note that this field is relevant only in responses. It is ignored in requests.

templateIdstringOptionalRead-onlyformat: "uuid"

The ID of the project that was used as a template to create this project.

jobIdstringOptionalformat: "uuid"

Not relevant - we don’t currently support this field.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

410

Gone Error

415

Unsupported Media Type Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error