Skip to content

Layer features

Retrieves a paginated list of layer features based on specified filters. Layer features represent structured geographical data (e.g. anomalies, tickets, detections, etc.).

Endpoint: GET /layerFeatures

Authentication: Required (API Key)

At least one filter (id, site_id, operation_id, dataset_id, or semantic_type) must be provided.

Parameter Type Required Description
id integer[] No Filter layer features by one or more layer feature IDs, at most 200. IDs that do not exist or that you cannot read are left out of the result.
site_id (integer|null)[] No Filter layer features by one or more site IDs. Supports null to filter for layer features without an associated operation.
operation_id (integer|null)[] No Filter layer features by one or more operation IDs. Supports null to filter for layer features without an associated operation.
dataset_id integer[] No Filter layer features by one or more dataset IDs.
semantic_type (string|null)[] (enum) No Filter layer features by one or more semantic types. See Semantic Types for valid values. Supports null to filter for layer features without an associated operation.
updated_at[gte] timestamp No Return only layer features updated at or after this ISO 8601 time. Requires dataset_id. See Changed since a time.
properties.<uuid> string No Return only layer features whose custom property <uuid> (a property definition UUID) has exactly this value. Requires exactly one dataset_id. See Filtering by a custom property.
_page integer No Page number (positive integer, defaults to 1)
_pageSize integer No Number of items per page (positive integer, defaults to 10). Values above 10,000 are capped at 10,000.
_sortBy string No Sort order. Format: +field (ascending) or -field (descending); repeat the parameter for tie-breaks (_sortBy=-updated_at&_sortBy=-id). Sortable fields: id, visible_id, description, created_at, updated_at, site, and properties.<key> where <key> is a built-in property key or a custom property definition UUID. Custom-UUID property sorts only resolve when the request is scoped to a single dataset_id; otherwise they fall back to a raw text sort of the stored value (built-in property keys sort correctly regardless). Default: -updated_at then -id

Unknown query parameters are ignored, so check the spelling of every filter: a misspelled filter returns more layer features than you asked for. Two kinds of parameters return 400 instead of being ignored:

  • a properties.* key that is not properties.<uuid>;
  • a parameter with a key in brackets that this endpoint does not support, for example updated_at[lte]=… or properties[<uuid>]=…. Empty brackets for a list, such as operation_id[]=123, are fine.

updated_at[gte] returns the layer features of the given datasets that changed at or after that time, for example to poll for changes since your last check:

  • Send the time in UTC (2026-10-01T00:00:00Z), or encode the + of an offset as %2B. An unencoded + arrives as a space and returns 400.
  • To poll for changes, follow the polling recipe in Sync tickets with your work system. It sets the time to start from, the sort order and the paging.
  • Comments and relationships between layer features do not change updated_at. Adding or removing a file in an attachment property does, because it changes that property’s value. Deleted layer features are not returned.
  • Use site-level datasets, not the company-level dataset they implement (see Dataset relationships). A company-level ticket dataset that site-level datasets implement holds no tickets, so updated_at[gte] on it returns 400 with that dataset in template_dataset_ids.

properties.<uuid>=<value> returns the layer features of one dataset whose custom property has exactly that value, for example to check whether a ticket already exists for a work order before creating one:

  • <uuid> is the property definition UUID of a custom property of the dataset, its own or inherited from the company-level dataset it implements. Any other UUID returns 400 with the unknown UUIDs in unknown_property_ids. If the dataset does not exist or your API key cannot read it, every UUID is reported in unknown_property_ids. Built-in properties such as STATUS cannot be filtered this way.
  • Send each property once, with a non-empty, URL-encoded value. A repeated or empty properties.<uuid> returns 400. An unencoded +, & or # in the value changes it, so the filter can match nothing or a different layer feature.
  • The value is compared as text with the stored value, or with defaultValue when there is no value. This works for text, yes/no (YES or NO; a yes/no property that was never set matches neither), user (the user or group ID) and option properties (the option’s value, not its label). Numbers and dates match only their exact stored form (5 does not match 5.0), and properties with several values never match.
  • Use the site-level dataset, not the company-level dataset it implements. A custom property filter on a company-level ticket dataset returns 400 with that dataset in template_dataset_ids.

Returns a paginated response with the following structure:

{
"data": [
{
"id": "integer",
"visible_id": "integer|null",
"properties": { "<key>": { "value": "any", "defaultValue": "any" } },
"geometry": "GeoJSON Feature",
"dataset_id": "integer",
"site_id": "integer",
"operation_id": "integer",
"company_id": "integer",
"semantic_type": "string",
"description": "string",
"created_at": "timestamp",
"updated_at": "timestamp",
"parent_layer_feature_id": "integer|null",
"related_layer_feature_ids": {}
}
],
"pagination": {
"page": "integer",
"pageSize": "integer",
"rowCount": "integer",
"pageCount": "integer"
}
}
  • id: Integer ID of the layer feature. This is the join key used by the GET /propertyChanges endpoint’s layer_feature_id filter — unlike visible_id, it is always present.

  • visible_id: Integer identifier shown in the app, or null. It is null for tickets: a ticket’s number is in properties.VISIBLE_ID.defaultValue.

  • properties: Object containing the layer feature properties, keyed by built-in property key or property-definition UUID. Each property is an object: read its value, or its defaultValue when value is missing or null. The ticket number is in properties.VISIBLE_ID.defaultValue. Since a dataset can inherit property definitions from a parent dataset, a UUID is not guaranteed to belong to the layer feature’s own dataset_id — call List Property Definitions with the layer feature’s dataset_id, which also returns the definitions it inherits.

  • geometry: A GeoJSON Feature whose geometry is a Point, LineString or Polygon

  • dataset_id: Integer ID of the associated dataset

  • site_id: Integer ID of the associated site

  • operation_id: Integer ID of the associated operation

  • company_id: Integer ID of the associated company

  • semantic_type: Type classification of the layer feature

  • description: Text description of the layer feature

  • created_at: ISO 8601 timestamp of when the layer feature was created

  • updated_at: ISO 8601 timestamp of when the layer feature was last updated

  • parent_layer_feature_id: Integer ID of the layer feature this one belongs to, or null. It is not a relationship type and is not returned by List Layer Feature Relationships. It points at:

    • for a ticket (including subform tickets): the component it was created on
    • for a detection or anomaly: the site component it was matched to (for an anomaly, its panel)
    • for a deviation: the misplaced component

    It is null when there is no parent, or when your API key cannot read it.

  • related_layer_feature_ids: The layer feature’s direct relationships, keyed by relationship type, each with one layer feature ID. They read from this layer feature: { "IS_COMPONENT_OF_MODEL": 42 } means “this layer feature is a component of model 42”. Possible keys: IS_SUBFORM_OF, IS_MECHANICAL_SUBCOMPONENT_OF, IS_ELECTRICAL_SUBCOMPONENT_OF, IS_COMPONENT_OF_MODEL and IS_TRIGGERED_BY. It is an empty object when there are none. Related layer features your API key cannot read are left out. For other relationship types, use List Layer Feature Relationships.

Incremental syncs: adding or removing a relationship does not change a layer feature’s updated_at, and removed relationships are deleted outright. A sync that only fetches layer features updated since its last run can therefore miss relationship changes in related_layer_feature_ids; re-read the layer features you need, or use List Layer Feature Relationships, to pick them up.

Filter by single operation ID:

Terminal window
curl -X GET "https://api.sitemark.com/layerFeatures?operation_id=123&_page=1&_pageSize=50&_sortBy=-updated_at" \
-H "Authorization: ApiKey your-api-key-here"

Filter by multiple operation IDs (without brackets):

Terminal window
curl -X GET "https://api.sitemark.com/layerFeatures?operation_id=123&operation_id=456&_page=1&_pageSize=50" \
-H "Authorization: ApiKey your-api-key-here"

Filter by multiple operation IDs (with brackets):

Terminal window
curl -g -X GET "https://api.sitemark.com/layerFeatures?operation_id[]=123&operation_id[]=456&_page=1&_pageSize=50" \
-H "Authorization: ApiKey your-api-key-here"

Filter by layer features without an operation:

Terminal window
curl -g -X GET "https://api.sitemark.com/layerFeatures?operation_id[]&_page=1&_pageSize=50" \
-H "Authorization: ApiKey your-api-key-here"

Filter by a specific operation OR layer features without an operation:

Terminal window
curl -g -X GET "https://api.sitemark.com/layerFeatures?operation_id[]=123&operation_id[]&_page=1&_pageSize=50" \
-H "Authorization: ApiKey your-api-key-here"

Filter by single semantic type:

Terminal window
curl -X GET "https://api.sitemark.com/layerFeatures?semantic_type=SOLAR_PANELS&_page=1&_pageSize=50" \
-H "Authorization: ApiKey your-api-key-here"

Filter by multiple semantic types (without brackets):

Terminal window
curl -X GET "https://api.sitemark.com/layerFeatures?semantic_type=SOLAR_PANELS&semantic_type=SOLAR_ANOMALIES&_page=1&_pageSize=50" \
-H "Authorization: ApiKey your-api-key-here"

Filter by multiple semantic types (with brackets):

Terminal window
curl -g -X GET "https://api.sitemark.com/layerFeatures?semantic_type[]=SOLAR_PANELS&semantic_type[]=SOLAR_ANOMALIES&_page=1&_pageSize=50" \
-H "Authorization: ApiKey your-api-key-here"

Combine multiple filters:

Terminal window
curl -X GET "https://api.sitemark.com/layerFeatures?operation_id=123&semantic_type=ANNOTATIONS&_page=1&_pageSize=50" \
-H "Authorization: ApiKey your-api-key-here"

Filter by single site ID:

Terminal window
curl -X GET "https://api.sitemark.com/layerFeatures?site_id=5678&_page=1&_pageSize=50" \
-H "Authorization: ApiKey your-api-key-here"

Filter by single dataset ID:

Terminal window
curl -X GET "https://api.sitemark.com/layerFeatures?dataset_id=1234&_page=1&_pageSize=50" \
-H "Authorization: ApiKey your-api-key-here"

Filter by layer feature IDs:

Terminal window
curl -X GET "https://api.sitemark.com/layerFeatures?id=101&id=102&_page=1&_pageSize=50" \
-H "Authorization: ApiKey your-api-key-here"

Layer features of a dataset changed since a time:

Terminal window
curl -g -X GET "https://api.sitemark.com/layerFeatures?dataset_id=1234&updated_at[gte]=2026-10-01T00:00:00Z&_page=1&_pageSize=50" \
-H "Authorization: ApiKey your-api-key-here"

Find the ticket of a work order by a custom property:

Terminal window
curl -X GET "https://api.sitemark.com/layerFeatures?dataset_id=1234&properties.0190d7a4-1b2c-7d3e-8f40-123456789abc=WO-123&_page=1&_pageSize=50" \
-H "Authorization: ApiKey your-api-key-here"
{
"data": [
{
"id": 482107,
"visible_id": null,
"properties": {
"VISIBLE_ID": { "defaultValue": 143 },
"STATUS": { "value": "IN_PROGRESS" },
"PRIORITY": { "value": "HIGH" },
"a7c3e5d1-9b2f-4c6e-8d14-2f6b0c9e7a35": { "value": "WO-2026-004512" }
},
"geometry": {
"type": "Feature",
"properties": {},
"geometry": { "type": "Point", "coordinates": [4.4699, 51.0259, 0] }
},
"dataset_id": 1234,
"site_id": 5678,
"operation_id": null,
"company_id": 9012,
"semantic_type": "PUNCH_LIST_ITEMS",
"description": "Inverter 4 offline since 06:10",
"created_at": "2026-11-02T06:14:03.000Z",
"updated_at": "2026-11-02T09:41:27.000Z",
"parent_layer_feature_id": null,
"related_layer_feature_ids": {}
}
],
"pagination": {
"page": 1,
"pageSize": 50,
"rowCount": 1,
"pageCount": 1
}
}

GET /layerFeatures has its own limits, on top of the company limits. They are counted separately from the limits of GET /propertyChanges:

  • 10 requests per 10 seconds
  • 50 requests per minute
  • 5 concurrent requests
Status Code Description
401 Unauthorized - Invalid or missing API key
400 Bad Request - Invalid query parameters, missing required filter, or updated_at[gte] / properties.<uuid> on a company-level ticket dataset. See Errors.
429 Too Many Requests - A rate limit was exceeded
500 Internal Server Error

Note: If you don’t provide at least one filter parameter (id, site_id, operation_id, dataset_id, or semantic_type), you will receive a 400 error.

Creates a ticket in a site’s ticket form, the same way a user creates one in the Sitemark web app.

Names used in this section:

  • Ticket id: the id of the ticket. Use it as the key in your system. Other endpoints call it layer_feature_id, because in the API a ticket is a layer feature.
  • Ticket number: the number shown in the Sitemark app, stored in properties.VISIBLE_ID. Ticket numbers start again in each ticket form, so don’t use them as a key.

Endpoint: POST /layerFeatures

Authentication: Required (API key). The key needs “Can create tickets” (or “Can view and edit operation results”, the same as creating in the web app) and “Can view all tickets”.

Headers: only Authorization and Content-Type.

Field Type Required Description
dataset_id integer Yes The ticket form on the site. Find it with List datasets: GET /datasets?site_id=<site-id>&semantic_type=PUNCH_LIST_ITEMS. A site can have more than one ticket form; pick the right one by name.
geometry object No A GeoJSON Point: { "type": "Point", "coordinates": [longitude, latitude] }, optionally with a height as a third number (it defaults to 0). When left out, the ticket is placed at the centre of the site.
description string No The ticket’s description text, at most 2000 characters.
properties object Yes The ticket’s fields, at most 100. Each field is an object with only a value. Other keys inside a field, such as defaultValue, return 400. Built-in fields use their own name, custom fields use their property definition UUID. Send {} to set no fields.

Built-in ticket fields (not listed by List property definitions):

Field Type Values
STATUS option TO_DO, PLANNED, IN_PROGRESS, RESOLVED, WONT_DO, CLOSED. Optional, defaults to TO_DO.
PRIORITY option LOW, MEDIUM, HIGH
ASSIGNEE user A user or group of the ticket’s company, as { "version": "2", "principal_id": <id> } with the id from List principals. See User values.
TICKET_DUE_DATE date A plain date YYYY-MM-DD, for example "2026-11-05"
TICKET_PLANNED_DATE date range One ISO 8601 interval string "<start>/<end>" of two timestamps with an offset or Z, start before end, for example "2026-11-03T08:00:00+01:00/2026-11-03T12:00:00+01:00"
MODULE_SERIAL_NUMBER text A string of at most 2000 characters
TAGS list A list of 1 to 100 distinct, non-empty strings of at most 2000 characters, for example ["inverter", "urgent"]. [] is refused; leave the field out or send null for no tags. A list containing internal returns 400 for keys whose company uses internal tickets and that can’t see them.

Set by Sitemark (read-only): don’t send these. They appear in the response.

Field Meaning
id The ticket id
properties.VISIBLE_ID The ticket number, set as a defaultValue
visible_id Not used for tickets. Ignore it.
created_at, updated_at When the ticket was created and last changed in Sitemark
site_id, company_id, semantic_type Taken from the ticket form
operation_id Always null for tickets
parent_layer_feature_id, related_layer_feature_ids Always null and {}: a ticket created through the API is not linked to other layer features
Other keys in properties Added by Sitemark. Some have no value. Ignore keys you don’t know.

a7c3e5d1-9b2f-4c6e-8d14-2f6b0c9e7a35 is the UUID of a custom text field that holds the external work order id. Custom fields are set by their UUID, which you get from List property definitions. Filtering List property definitions by dataset_id also returns the fields the ticket form inherits.

Terminal window
curl -X POST "https://api.sitemark.com/layerFeatures" \
-H "Authorization: ApiKey <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"dataset_id": 1234,
"description": "Inverter 4 offline since 06:10",
"properties": {
"PRIORITY": { "value": "HIGH" },
"ASSIGNEE": { "value": { "version": "2", "principal_id": 501 } },
"a7c3e5d1-9b2f-4c6e-8d14-2f6b0c9e7a35": { "value": "WO-2026-004512" }
}
}'

No geometry is sent, so the ticket is placed at the site centre. Principal 501 is the user with user.id 42, so the response can hold the v1 value 42 (see User values).

201 Created with the new ticket, in the same shape as one item of List layer features. The geometry comes back as a GeoJSON Feature with three coordinates:

{
"id": 482107,
"visible_id": null,
"properties": {
"VISIBLE_ID": { "defaultValue": 143 },
"STATUS": { "value": "TO_DO" },
"PRIORITY": { "value": "HIGH" },
"ASSIGNEE": { "value": 42 },
"a7c3e5d1-9b2f-4c6e-8d14-2f6b0c9e7a35": { "value": "WO-2026-004512" }
},
"geometry": {
"type": "Feature",
"properties": {},
"geometry": { "type": "Point", "coordinates": [4.4699, 51.0259, 0] }
},
"dataset_id": 1234,
"site_id": 5678,
"operation_id": null,
"company_id": 9012,
"semantic_type": "PUNCH_LIST_ITEMS",
"description": "Inverter 4 offline since 06:10",
"created_at": "2026-11-02T06:14:03.000Z",
"updated_at": "2026-11-02T06:14:03.000Z",
"parent_layer_feature_id": null,
"related_layer_feature_ids": {}
}

This response doesn’t include the ticket’s regions (properties.REGIONS): they are added just after the ticket is saved. Use List layer features to see them.

Status Code Description
400 The body doesn’t have the shape above (issues, see Errors), a field can’t be written (issues), a required field is missing (issues), the form isn’t a site’s ticket form, the site has no location and no geometry was sent, or an unsupported case (see Rules).
401 Missing, invalid, revoked or expired API key
403 Your API key isn’t allowed to create this ticket: for example it can’t view all tickets, or it may not create tickets in this form, with an ASSIGNEE (even null), or as CLOSED
404 The form (dataset_id) does not exist, or your key has no access to it: the form belongs to another company (for a partner API key: neither the partner company nor a company it manages), or to a site your key has no access to
429 Too Many Requests - A rate limit was exceeded

Errors return a JSON body with a message. When fields are the problem, issues lists each one with its place in the request (path), a code and a message:

{
"message": "Some fields cannot be written.",
"issues": [
{
"path": ["properties", "PRIORITY", "value"],
"code": "INVALID_VALUE",
"message": "PRIORITY must be one of LOW, MEDIUM, HIGH."
}
],
"public": true
}

The codes are listed in Errors. A request body that doesn’t have the shape above (an unknown key, a field without value, more than 100 fields, a description longer than 2000 characters, an invalid point) returns issues with the code INVALID_REQUEST. A field value that is too long returns an INVALID_VALUE issue; only description returns INVALID_REQUEST.

Required fields. A custom field can be required from a status onwards. In List property definitions such a field has config.validation: "REQUIRED" and config.validation_enforcement.STATUS set to the first status where it is required: "TO_DO", "PLANNED", "RESOLVED" or "CLOSED". It is then required for that status and every later status, in the order TO_DO → PLANNED → IN_PROGRESS → RESOLVED → CLOSED. WONT_DO never requires anything. A missing required field returns 400 with a REQUIRED issue whose path holds the field’s UUID, also for a field the form inherits that List property definitions doesn’t show to your key. A field with validation: "REQUIRED" but no validation_enforcement is not enforced. Hidden fields, and fields that don’t apply to the ticket, are never required. A form whose required field can’t be written through the API (see below) can’t be used to create tickets.

Fields shown only under conditions are accepted whether or not the conditions hold, and the value is kept.

Supported fields. You can set the built-in fields above and custom fields of the types below (type in List property definitions). Fields of other types are refused with 400.

Custom field type Value to send
STRING A string of at most 2000 characters, for example "WO-2026-004512"
URL A string of at most 2000 characters, for example "https://example.com/work-orders/4512"
BOOLEAN A yes/no field: "YES" or "NO" (strings, not true or false)
FLOAT A number, for example 12.5. If the field’s config.measure is TEMPERATURE or LENGTH, send °C or metres.
DATE A plain date "YYYY-MM-DD". If the field’s config.includeTime is true, an ISO 8601 date and time with offset, for example "2026-11-05T08:00:00+01:00".
OPTION The value of one of the field’s config.options, not its label
MULTI_OPTION An array of distinct option values, for example ["<uuid>", "<uuid>"]
USER One user or group of the ticket’s company, as { "version": "2", "principal_id": <id> }. See User values.

Values.

  • A built-in field value outside the table above, or a date in the wrong format, returns 400.
  • Send custom field values in the shapes listed in the table above. A custom value outside its type or options returns 400 with INVALID_VALUE.

ASSIGNEE and USER fields accept two shapes:

Shape Example Send
v2 { "version": "2", "principal_id": 501 } The id of a USER or GROUP item of List principals.
v1 42 Deprecated. The user.id of a USER item or the group.legacy_user_id of a GROUP item. Not a principal id.
  • Send v2. v1 is deprecated for writes and can be removed in the future.
  • The user or group must be of the ticket’s company, and your key must see it in List principals with deleted_at set to null. Else the field returns 400 with UNREADABLE_USER.
  • A v2 value that names a group whose group.legacy_user_id is null returns 400 with UNREADABLE_USER: such a group cannot be assigned yet.
  • A v2 value that names another principal type, such as API_KEY, returns 400 with UNREADABLE_USER until Sitemark supports that type. Sitemark plans to accept other types.
  • A value in neither shape returns 400 with INVALID_VALUE.
  • Sitemark can store a value in a shape other than the shape you sent. The stored shape depends on the progress of the migration on the side of Sitemark, and can change without notice. So the value that you read back can differ from the value that you sent, but it always identifies the same user or group. To compare two values, resolve both to a principal, as described in Resolve ASSIGNEE and USER values.

Location. Without geometry the ticket is placed at the centre of the site, so all such tickets get the same automatic regions. If the site boundary has an unusual shape or several parts, the centre can be outside the boundary, and the ticket may then get no automatic region. A site without a boundary has no centre: send geometry there, or the request returns 400.

Emails. Creating a ticket with an assignee does not send an email, the same as in the web app, unless your company has set up an automation for new tickets.

Retries. Each request creates a new ticket. If a request times out or returns a 5xx error, the ticket may still have been created, so a retry can create a second one. Before you retry, wait a minute (the first create may still finish), then look up your own reference, such as the work order number you store in a custom field (see the example), with Filtering by a custom property: dataset_id=<dataset-id>&properties.<uuid>=<your-reference>. Create the ticket only if it is not found.

Not supported. These requests are refused with 400:

  • forms linked to Procore;
  • forms with sub-tickets;
  • linking the new ticket to another item, such as a finding, a component or another ticket (as its parent or as a relationship);
  • creating many tickets in one request. Send one request per ticket.

Requests to Procore-linked forms and forms with sub-tickets fail with 400 before the fields are checked.