Floorplan Collections API guide

This guide covers the four API endpoints that support the floorplan collections feature — a way to organize plans into named folder groups within a project or project template.

Prerequisite: Collections must be enabled on a project before you can use the relevant project endpoints below.

Endpoints

1. Enable Collections on a Project

PATCH /api/v3/projects/{project_id}/floorplans/flags/collections

Enables the floorplan collections feature flag for the given project. This also creates a default collection folder with the name you provide. This flag can only be enabled — it cannot be set back to false.

⚠️

This endpoint must be called before batch_move will work.

Path Parameters

Request Body

{
  "value": true,
  "default_collection_name": "Default Collection"
}

Responses

Example

curl -X PATCH "https://client-api.us.fieldwire.com/api/v3/projects/{project_id}/floorplans/flags/collections" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "value": true,
    "default_collection_name": "Default Collection"
  }'

201 response:

{
  "id": "f1a2b3c4-...",
  "project_id": "...",
  "name": "is_collections_enabled",
  "value": true,
  "creator_user_id": 123,
  "last_editor_user_id": 123,
  "created_at": "2026-03-03T10:00:00.000000Z",
  "updated_at": "2026-03-03T10:00:00.000000Z"
}

Authorization

Requires project admin role.

2. Batch Move Floorplans into a Collection

POST /api/v3/projects/{project_id}/floorplans/batch_move

Moves one or more floorplans into a target folder collection (or back to the root/unfiled level). The operation is asynchronous and processed via a background worker — the endpoint returns 200 OK immediately once the job is enqueued.

Requires collections to be enabled. Call the Enable Collections endpoint first.

Path Parameters

Request Body

{
  "floorplan_ids": ["uuid-1", "uuid-2"],
  "folder_id": "target-folder-uuid"
}

Responses

Example — Move to a Collection

curl -X POST "https://client-api.us.fieldwire.com/api/v3/projects/{project_id}/floorplans/batch_move" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "floorplan_ids": ["uuid-1", "uuid-2"],
    "folder_id": "target-collection-uuid"
  }'

Example — Move Back to Root (Unfiled)

curl -X POST "https://client-api.us.fieldwire.com/api/v3/projects/{project_id}/floorplans/batch_move" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "floorplan_ids": ["uuid-1"],
    "folder_id": null
  }'

Authorization

Requires the Plan Upload role on the project.

3. Duplicate a Project Folder Collection

POST /api/v3/projects/{project_id}/folders/{id}/duplicate

Duplicates a folder collection and all of its contents (floorplans, nested folders, etc.) within a project. This is an async operation — on the first call the server enqueues a background job and returns a jid. Poll the same endpoint with ?jid=<jid> until a 200 with the duplicated folder is returned.

Path Parameters

Request Body

{
  "folder": {
    "name": "Copy of Level 1 Plans"
  }
}

Responses

Example — Initial Request

curl -X POST "https://client-api.us.fieldwire.com/api/v3/projects/{project_id}/folders/{id}/duplicate" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "folder": { "name": "Copy of Level 1 Plans" } }'

202 response:

{ "jid": "abc123def456" }

Example — Polling

curl -X POST "https://client-api.us.fieldwire.com/api/v3/projects/{project_id}/folders/{id}/duplicate?jid=abc123def456" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "folder": { "name": "Copy of Level 1 Plans" } }'

200 response:

{
  "id": "e4b1f3a2-...",
  "name": "Copy of Level 1 Plans",
  "kind": "floorplan",
  "project_id": "...",
  ...
}

Authorization

Requires the Plan Upload role on the project.

4. Duplicate a Project Template Folder Collection

POST /api/v3/account/project_template_folders/{id}/duplicate

Duplicates a project template folder collection and all of its contents. Same async polling pattern as the project-level duplicate above.

Path Parameters

Request Body

{
  "project_template_folder": {
    "name": "Copy of Structural Plans"
  }
}

Responses

Authorization

Requires create permission on ProjectTemplateFolder (account admin).

Typical Workflow

1. Enable collections on the project
   PATCH /api/v3/projects/{project_id}/floorplans/flags/collections
   { "value": true, "default_collection_name": "Default Collection" }

2. Create additional collection folders (optional)
   POST /api/v3/projects/{project_id}/folders
   { "folder": { "name": "Level 1 Plans", "kind": "floorplan" } }

3. Move floorplans into a collection
   POST /api/v3/projects/{project_id}/floorplans/batch_move
   { "floorplan_ids": [...], "folder_id": "collection-uuid" }

4. Duplicate a collection when needed
   POST /api/v3/projects/{project_id}/folders/{id}/duplicate
   { "folder": { "name": "Copy of Level 1 Plans" } }
   → poll with ?jid=<jid> until 200