---
updatedAt: 2026-06-03T14:46:37.000Z
agentTools:
  projectIndex: https://developers.fieldwire.com/llms.txt
---

# Create a new markup

Creates a markup on a Sheet of a Floorplan. 

Markups are user generated overlay elements that is displayed on top of a sheet of a Floorplan. Markups can be private to you
, set it by passing `is_private: true`. 

The `data` field of a Markup follows the [GeoJson](https://docs.fileformat.com/gis/geojson/) format.

Schema looks like:
```json
{
  "type": "Feature",
  "properties": {
    "style": "See below: property.style",
    "color": "#FF0000",
    "opacity": 1,
    "width": 16
  },
  "geometry": {
    "type": "See below: geometry.type",
    "coordinates": [
      [
        136,
        95
      ],
      [
        277,
        17
      ]
    ]
  }
}
```

**Properties.style can be one of these: `"arrow", "cloud", "drawing", "ellipse", "highlighter", "measurement", "measurement_line", "polygon", "rectangle" ,"text"`**

**Geometry.type is one of these: `"Polygon","LineString"`**

Here is an example of an `Arrow`:

```json
{
  "type": "Feature",
  "properties": {
    "style": "arrow",
    "color": "#FF0000",
    "opacity": 1,
    "width": 16
  },
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [
        136,
        95
      ],
      [
        277,
        17
      ]
    ]
  }
}
```

Here is an example of a `Drawing`:
```json
{
    "type": "Feature",
    "properties": {
        "style": "drawing",
        "color": "#0000FF",
        "opacity": 1,
        "width": 16
    },
    "geometry": {
        "type": "LineString",
        "coordinates": [
            [
                639,
                406
            ],
            [
                639,
                392
            ]
        ]
    }
}
```

Here is an example of a `Ellipse`:
```json
{
    "properties": {
        "style": "ellipse",
        "color": "#FF7F00",
        "opacity": 1,
        "width": 2
    },
    "geometry": {
        "coordinates": [
            [
                1775,
                298
            ]
        ],
        "radii": [
            136.03858998144713,
            56.115918367346936
        ]
    }
}
```

Here is an example of a `Measurement`:
```json
{
    "type": "Feature",
    "properties": {
        "style": "measurement",
        "color": "#FF7F00",
        "opacity": 1,
        "width": 16,
        "description": "1 centimeter",
        "fontSize": 48
    },
    "geometry": {
        "type": "LineString",
        "coordinates": [
            [
                217,
                620
            ],
            [
                359,
                622
            ]
        ]
    }
}
```

Here is an example of a `Text`:
```json
{
    "type": "Feature",
    "properties": {
      "style": "text",
      "color": "#FF0000",
      "description": "Sample",
      "fontSize": 48
    },
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          760,
          144
        ],
        [
          936,
          144
        ],
        [
          936,
          239
        ],
        [
          760,
          239
        ]
      ]
    }
}
```
Here is an example of a `Polygon`:
```json
{
        "type": "Feature",
        "properties": {
            "style": "polygon",
            "color": "#FF0000",
            "opacity": 1,
            "width": 2
        },
        "geometry": {
            "type": "Polygon",
            "coordinates": [
                [
                    286,
                    612
                ],
                [
                    408,
                    609
                ],
                [
                    408,
                    697
                ],
                [
                    337,
                    554
                ]
            ]
        }
    }
```

Here is an example of a `Measurement Line`, used to calibrate for scale:
```json
{
    "type": "Feature",
    "properties": {
        "style": "measurementline",
        "color": "#FF0000",
        "width": 2,
        "fontSize": 16
    },
    "geometry": {
        "type": "LineString",
        "coordinates": [
            [
                660,
                976
            ],
            [
                830,
                973
            ]
        ]
    }
}
```

Here is a `Rectangle`:
```json
{
    "type": "Feature",
    "properties": {
        "style": "rectangle",
        "color": "#FF00FF",
        "opacity": 1,
        "width": 2
    },
    "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                136,
                816
            ],
            [
                275,
                816
            ],
            [
                275,
                898
            ],
            [
                136,
                898
            ]
        ]
    }
}
```

Here is a `Highlighter`:
```json
{
    "type": "Feature",
    "properties": {
      "style": "highlighter",
      "color": "#FF00FF",
      "opacity": 0.25,
      "width": 40
    },
    "geometry": {
      "type": "LineString",
      "coordinates": [
        [
            881,
            415
        ],
        [
            881,
            418
        ]
      ]
    }
}
```
Here is an example of a `Cloud` shape that is private, the entire `POST` body:
```json
{
    "id": "4d109283-acc3-4a20-9e9c-21c71fdd8b51",
    "creator_user_id": 39048,
    "last_editor_user_id": 39048,
    "project_id": "c8fe9ca2-1a8a-4c03-a317-90d9a3d516fa",
    "resolved_conflict": false,
    "created_at": "2020-12-24T03:19:58.234Z",
    "updated_at": "2020-12-24T03:19:58.234Z",
    "device_created_at": "2020-12-24T03:19:57.488Z",
    "device_updated_at": "2020-12-24T03:19:57.488Z",
    "deleted_at": null,
    "sheet_id": "7e21cfaa-5a6b-4796-b369-036c906805e4",
    "is_private": true,
    "data": {
        "type": "Feature",
        "properties": {
            "style": "cloud",
            "color": "#7700B9",
            "opacity": 1,
            "arcRadius": 8
        },
        "geometry": {
            "type": "Polygon",
            "coordinates": [
                [
                    405,
                    1068
                ],
                [
                    709,
                    1068
                ],
                [
                    709,
                    1260
                ],
                [
                    405,
                    1260
                ]
            ]
        }
    }
}
```

One way to see how Fieldwire is constructing these Markup `data` is to examine the XHR tab of a browser developer console
and when you use the Floorplan markup tools, see what the body it is being POSTed to Fieldwire. 


# OpenAPI definition

````json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Fieldwire Regional API",
    "version": "v3"
  },
  "servers": [
    {
      "url": "https://client-api.{region}.fieldwire.com",
      "variables": {
        "region": {
          "default": "us",
          "enum": [
            "ca",
            "eu",
            "us"
          ]
        }
      }
    }
  ],
  "components": {
    "headers": {
      "current_user_id": {
        "description": "Current user's id",
        "schema": {
          "type": "integer"
        }
      }
    },
    "parameters": {
      "api_version": {
        "name": "Fieldwire-Version",
        "in": "header",
        "description": "Specifies the version of the API to talk to",
        "required": true,
        "schema": {
          "type": "string",
          "format": "date"
        }
      },
      "project_id": {
        "name": "project_id",
        "in": "path",
        "description": "ID of the project this entity belongs to",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "schemas": {
      "markup": {
        "type": "object",
        "description": "Markup that lives on plans",
        "required": [
          "id",
          "creator_user_id",
          "last_editor_user_id",
          "project_id",
          "sheet_id",
          "is_private",
          "data",
          "created_at",
          "device_created_at",
          "device_updated_at",
          "resolved_conflict",
          "updated_at"
        ],
        "nullable": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "nullable": false,
            "description": "ID of the entity"
          },
          "creator_user_id": {
            "type": "integer",
            "format": "int32",
            "nullable": false,
            "description": "ID of the user who created this entity"
          },
          "last_editor_user_id": {
            "type": "integer",
            "format": "int32",
            "nullable": false,
            "description": "ID of the user who most recently edited this entity"
          },
          "project_id": {
            "type": "string",
            "format": "uuid",
            "nullable": false,
            "description": "ID of the project this entity belongs to"
          },
          "sheet_id": {
            "type": "string",
            "format": "uuid",
            "nullable": false,
            "description": "ID of the sheet this markup belongs to"
          },
          "is_private": {
            "type": "boolean",
            "nullable": false,
            "description": "Whether this is a private markup"
          },
          "data": {
            "type": "object",
            "nullable": false,
            "description": "GeoJSON representation of a Markup. https://geojson.org/"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": false,
            "description": "Time when the server created the entity"
          },
          "deleted_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Time the server deleted the entity"
          },
          "device_created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": false,
            "description": "Time when the device created the entity"
          },
          "device_updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": false,
            "description": "Time when the device last updated the entity"
          },
          "resolved_conflict": {
            "type": "boolean",
            "nullable": false,
            "description": "Specifies if PUT/PATCH request was rejected - do not store this field!"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": false,
            "description": "Time when the server last updated the entity"
          }
        },
        "additionalProperties": false
      },
      "markup_create_input": {
        "type": "object",
        "required": [
          "creator_user_id",
          "last_editor_user_id",
          "data"
        ],
        "nullable": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "nullable": false,
            "description": "ID of the entity"
          },
          "creator_user_id": {
            "type": "integer",
            "format": "int32",
            "nullable": false,
            "description": "ID of the user who created this entity"
          },
          "last_editor_user_id": {
            "type": "integer",
            "format": "int32",
            "nullable": false,
            "description": "ID of the user who most recently edited this entity"
          },
          "is_private": {
            "type": "boolean",
            "nullable": false,
            "description": "Whether this is a private markup"
          },
          "device_created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": false,
            "description": "Time when the device created the entity"
          },
          "device_updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": false,
            "description": "Time when the device last updated the entity"
          },
          "data": {
            "type": "object",
            "nullable": false,
            "description": "JSON Data for the Markup"
          }
        },
        "description": "Schema for creating markup",
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "jwt": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Access token (JWT) generated using the acquired refresh token (API token). Our [authentication](https://developers.fieldwire.com/docs/authentication) guide covers the steps to generate a valid token"
      }
    }
  },
  "paths": {
    "/api/v3/projects/{project_id}/sheets/{sheet_id}/markups": {
      "post": {
        "summary": "Create a new markup",
        "operationId": "add_markup_in_sheet",
        "tags": [
          "markups"
        ],
        "description": "Creates a markup on a Sheet of a Floorplan. \n\nMarkups are user generated overlay elements that is displayed on top of a sheet of a Floorplan. Markups can be private to you\n, set it by passing `is_private: true`. \n\nThe `data` field of a Markup follows the [GeoJson](https://docs.fileformat.com/gis/geojson/) format.\n\nSchema looks like:\n```json\n{\n  \"type\": \"Feature\",\n  \"properties\": {\n    \"style\": \"See below: property.style\",\n    \"color\": \"#FF0000\",\n    \"opacity\": 1,\n    \"width\": 16\n  },\n  \"geometry\": {\n    \"type\": \"See below: geometry.type\",\n    \"coordinates\": [\n      [\n        136,\n        95\n      ],\n      [\n        277,\n        17\n      ]\n    ]\n  }\n}\n```\n\n**Properties.style can be one of these: `\"arrow\", \"cloud\", \"drawing\", \"ellipse\", \"highlighter\", \"measurement\", \"measurement_line\", \"polygon\", \"rectangle\" ,\"text\"`**\n\n**Geometry.type is one of these: `\"Polygon\",\"LineString\"`**\n\nHere is an example of an `Arrow`:\n\n```json\n{\n  \"type\": \"Feature\",\n  \"properties\": {\n    \"style\": \"arrow\",\n    \"color\": \"#FF0000\",\n    \"opacity\": 1,\n    \"width\": 16\n  },\n  \"geometry\": {\n    \"type\": \"LineString\",\n    \"coordinates\": [\n      [\n        136,\n        95\n      ],\n      [\n        277,\n        17\n      ]\n    ]\n  }\n}\n```\n\nHere is an example of a `Drawing`:\n```json\n{\n    \"type\": \"Feature\",\n    \"properties\": {\n        \"style\": \"drawing\",\n        \"color\": \"#0000FF\",\n        \"opacity\": 1,\n        \"width\": 16\n    },\n    \"geometry\": {\n        \"type\": \"LineString\",\n        \"coordinates\": [\n            [\n                639,\n                406\n            ],\n            [\n                639,\n                392\n            ]\n        ]\n    }\n}\n```\n\nHere is an example of a `Ellipse`:\n```json\n{\n    \"properties\": {\n        \"style\": \"ellipse\",\n        \"color\": \"#FF7F00\",\n        \"opacity\": 1,\n        \"width\": 2\n    },\n    \"geometry\": {\n        \"coordinates\": [\n            [\n                1775,\n                298\n            ]\n        ],\n        \"radii\": [\n            136.03858998144713,\n            56.115918367346936\n        ]\n    }\n}\n```\n\nHere is an example of a `Measurement`:\n```json\n{\n    \"type\": \"Feature\",\n    \"properties\": {\n        \"style\": \"measurement\",\n        \"color\": \"#FF7F00\",\n        \"opacity\": 1,\n        \"width\": 16,\n        \"description\": \"1 centimeter\",\n        \"fontSize\": 48\n    },\n    \"geometry\": {\n        \"type\": \"LineString\",\n        \"coordinates\": [\n            [\n                217,\n                620\n            ],\n            [\n                359,\n                622\n            ]\n        ]\n    }\n}\n```\n\nHere is an example of a `Text`:\n```json\n{\n    \"type\": \"Feature\",\n    \"properties\": {\n      \"style\": \"text\",\n      \"color\": \"#FF0000\",\n      \"description\": \"Sample\",\n      \"fontSize\": 48\n    },\n    \"geometry\": {\n      \"type\": \"Polygon\",\n      \"coordinates\": [\n        [\n          760,\n          144\n        ],\n        [\n          936,\n          144\n        ],\n        [\n          936,\n          239\n        ],\n        [\n          760,\n          239\n        ]\n      ]\n    }\n}\n```\nHere is an example of a `Polygon`:\n```json\n{\n        \"type\": \"Feature\",\n        \"properties\": {\n            \"style\": \"polygon\",\n            \"color\": \"#FF0000\",\n            \"opacity\": 1,\n            \"width\": 2\n        },\n        \"geometry\": {\n            \"type\": \"Polygon\",\n            \"coordinates\": [\n                [\n                    286,\n                    612\n                ],\n                [\n                    408,\n                    609\n                ],\n                [\n                    408,\n                    697\n                ],\n                [\n                    337,\n                    554\n                ]\n            ]\n        }\n    }\n```\n\nHere is an example of a `Measurement Line`, used to calibrate for scale:\n```json\n{\n    \"type\": \"Feature\",\n    \"properties\": {\n        \"style\": \"measurementline\",\n        \"color\": \"#FF0000\",\n        \"width\": 2,\n        \"fontSize\": 16\n    },\n    \"geometry\": {\n        \"type\": \"LineString\",\n        \"coordinates\": [\n            [\n                660,\n                976\n            ],\n            [\n                830,\n                973\n            ]\n        ]\n    }\n}\n```\n\nHere is a `Rectangle`:\n```json\n{\n    \"type\": \"Feature\",\n    \"properties\": {\n        \"style\": \"rectangle\",\n        \"color\": \"#FF00FF\",\n        \"opacity\": 1,\n        \"width\": 2\n    },\n    \"geometry\": {\n        \"type\": \"Polygon\",\n        \"coordinates\": [\n            [\n                136,\n                816\n            ],\n            [\n                275,\n                816\n            ],\n            [\n                275,\n                898\n            ],\n            [\n                136,\n                898\n            ]\n        ]\n    }\n}\n```\n\nHere is a `Highlighter`:\n```json\n{\n    \"type\": \"Feature\",\n    \"properties\": {\n      \"style\": \"highlighter\",\n      \"color\": \"#FF00FF\",\n      \"opacity\": 0.25,\n      \"width\": 40\n    },\n    \"geometry\": {\n      \"type\": \"LineString\",\n      \"coordinates\": [\n        [\n            881,\n            415\n        ],\n        [\n            881,\n            418\n        ]\n      ]\n    }\n}\n```\nHere is an example of a `Cloud` shape that is private, the entire `POST` body:\n```json\n{\n    \"id\": \"4d109283-acc3-4a20-9e9c-21c71fdd8b51\",\n    \"creator_user_id\": 39048,\n    \"last_editor_user_id\": 39048,\n    \"project_id\": \"c8fe9ca2-1a8a-4c03-a317-90d9a3d516fa\",\n    \"resolved_conflict\": false,\n    \"created_at\": \"2020-12-24T03:19:58.234Z\",\n    \"updated_at\": \"2020-12-24T03:19:58.234Z\",\n    \"device_created_at\": \"2020-12-24T03:19:57.488Z\",\n    \"device_updated_at\": \"2020-12-24T03:19:57.488Z\",\n    \"deleted_at\": null,\n    \"sheet_id\": \"7e21cfaa-5a6b-4796-b369-036c906805e4\",\n    \"is_private\": true,\n    \"data\": {\n        \"type\": \"Feature\",\n        \"properties\": {\n            \"style\": \"cloud\",\n            \"color\": \"#7700B9\",\n            \"opacity\": 1,\n            \"arcRadius\": 8\n        },\n        \"geometry\": {\n            \"type\": \"Polygon\",\n            \"coordinates\": [\n                [\n                    405,\n                    1068\n                ],\n                [\n                    709,\n                    1068\n                ],\n                [\n                    709,\n                    1260\n                ],\n                [\n                    405,\n                    1260\n                ]\n            ]\n        }\n    }\n}\n```\n\nOne way to see how Fieldwire is constructing these Markup `data` is to examine the XHR tab of a browser developer console\nand when you use the Floorplan markup tools, see what the body it is being POSTed to Fieldwire. \n",
        "security": [
          {
            "jwt": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/project_id"
          },
          {
            "$ref": "#/components/parameters/api_version"
          },
          {
            "name": "sheet_id",
            "description": "ID of the sheet to create markup in",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Successful response",
            "headers": {
              "X-Current-User-Id": {
                "$ref": "#/components/headers/current_user_id"
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "id": "1f80cdb7-fcb4-444c-8a42-5ff839e8693c",
                  "creator_user_id": 1228,
                  "last_editor_user_id": 1228,
                  "project_id": "ac14890d-b7ae-4cfd-9684-78a4df859c48",
                  "resolved_conflict": false,
                  "created_at": "2026-10-02T14:50:47.050Z",
                  "updated_at": "2026-10-02T14:50:47.050Z",
                  "device_created_at": "2026-10-02T14:50:46.718Z",
                  "device_updated_at": "2026-10-02T14:50:46.718Z",
                  "deleted_at": null,
                  "sheet_id": "ddc1cc62-d888-4905-84ac-dc887277e5c2",
                  "is_private": false,
                  "data": {
                    "a": "a"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/markup"
                }
              }
            }
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/markup_create_input"
              }
            }
          },
          "required": true
        }
      }
    }
  }
}
````