Skip to content

Sync tickets with your work system

This guide is for integrations that keep Sitemark tickets in sync with another system: a CMMS whose work orders become tickets, or a monitoring system, for example VCOM or a SCADA, whose alarms become tickets. A monitoring system also follows If your system is a monitoring system.

Create an API key from a person who has these rights. The key copies only rights given directly to that person; see What a key can do.

Right (as shown in the web app) Needed for
Can create tickets Creating tickets
Can view all tickets Creating, reading and updating any ticket. Without it, the lookup below finds nothing.
Can edit all tickets Updating tickets
Can assign users to tickets Setting or changing the assignee
Can close tickets Closing a ticket, or editing a closed one
You need Where to get it
Your plant → Sitemark site List sites. It also returns the site’s location: coordinates (the site centre) and the address lines.
The site’s ticket form List datasets with site_id=<site-id>&semantic_type=PUNCH_LIST_ITEMS. Its id is the dataset_id you create tickets in. If a site has more than one ticket form, pick it by name.
Custom fields and options List property definitions with dataset_id=<dataset-id>&_pageSize=1000. This includes the fields the form inherits from the company-level form that the key can read (see Inherited datasets). Built-in fields (STATUS, PRIORITY, ASSIGNEE, …) are not listed there; see the table on Create ticket.
People and teams List principals; the current members have deleted_at: null. Assign to a user, or to a group, for example one group per team or contractor. Write ASSIGNEE as { "version": "2", "principal_id": <id> } with the id of the item (see User values). Read both value shapes (see Resolve ASSIGNEE and USER values).

Map each field of your system to a built-in ticket field where one exists (the description, PRIORITY, ASSIGNEE, STATUS, TICKET_DUE_DATE, TICKET_PLANNED_DATE). The description is description when you create a ticket and DESCRIPTION when you update one. For anything else, ask your Sitemark admin to add a custom field to the ticket form, for example a text field for your work order id or a date field. Custom fields are listed by List property definitions and are set by their UUID.

Two things to keep in mind:

  • Your own reference: store your work order id or alarm id in a custom text field. It links the two systems and lets you find the ticket again (see below). Sitemark’s own ticket number can’t be set.
  • Dates: a ticket’s created_at is the time it was created in Sitemark. If you need your own creation date, use a custom date field.

Before you create a ticket, look it up by the value of your reference field, within one ticket form. This lookup is the only duplicate check. In this example, 1234 is the ticket form and a7c3e5d1-9b2f-4c6e-8d14-2f6b0c9e7a35 is the UUID of your reference field. If the ticket is there, keep its id; otherwise create it.

Terminal window
curl -X GET "https://api.sitemark.com/layerFeatures?dataset_id=1234&properties.a7c3e5d1-9b2f-4c6e-8d14-2f6b0c9e7a35=WO-2026-004512" \
-H "Authorization: ApiKey <your-api-key>"
  • URL-encode your reference. An unencoded +, & or # changes the value, so the lookup finds nothing and a second ticket is created.
  • Handle one reference at a time. Two lookups that run at the same time both find nothing.

Create the ticket only when none is found, with Create ticket (POST /layerFeatures), and keep the returned id next to your reference. Send geometry (a Point) at the asset; when it is left out, the ticket is placed at the site centre. A site without a boundary needs geometry.

  • When the create times out or returns a 5xx, wait a minute (the first create may still finish), look up your reference again, and create the ticket only if it is still not found. A create has no id, so resending it can make a second ticket.
  • After a 429, wait for Retry-After and send it again.
  • Other refusals: see the table under Push your changes.

Use Update ticket fields (POST /propertyChanges). Send only the fields that changed.

  • Use a new change id for each new change.
  • One refused change rejects the whole request, so send changes for different tickets in separate requests.
  • When your item is done, set STATUS to RESOLVED only while the ticket is still open: skip it when STATUS is already RESOLVED, CLOSED or WONT_DO. Otherwise a ticket closed in Sitemark is moved back.

Retries. When a request times out or returns a 5xx, resend it unchanged, with the same ids (see Retries). After a 429, wait for Retry-After and resend it unchanged. Only resend to retry: a resent DESCRIPTION change, or a value that equalled the current one when it was first sent, is applied again and can overwrite a newer edit made in Sitemark.

Refusals. A refusal (a 4xx other than 429) applied nothing.

Answer Meaning What to do
400 REQUIRED on create A field required from TO_DO is empty. Send it with the ticket.
400 REQUIRED on a change The move to a status makes an empty field required, for example on RESOLVED. A field the current status already requires blocks only when the request clears it (see Required fields). Fill the field, or don’t change the status.
403 on a ticket closed in Sitemark While its STATUS is CLOSED, every change to it is refused for a key without “Can close tickets”. Stop sending changes for that ticket instead of retrying.
404 The ticket was deleted or is no longer visible to the key. Stop sending changes for it.
Any other 400 The request is wrong. Fix the request before sending it again.

A field team may set the status or the assignee in Sitemark. Check for changes on a schedule, for example every hour.

You can use these filters on List layer features:

Filter Meaning
id Only the tickets with these ids
updated_at[gte] Only tickets changed at or after this time (UTC). Requires dataset_id.
properties.<uuid> Only tickets where this custom field has exactly this value. Requires dataset_id with a single ticket form id, not a list, for example ?dataset_id=1234&properties.<uuid>=WO-2026-004512.

Plain unknown query keys are ignored, so a typo in a filter name widens the result instead of returning an error.

Each poll walks the changed tickets of one form, oldest change first:

  1. First request of a poll: send dataset_id, updated_at[gte] set to the highest updated_at you stored from the previous poll minus a few minutes, _sortBy=%2Bupdated_at&_sortBy=%2Bid, and a _pageSize of at most 10,000 (larger values are reduced to 10,000). A ticket’s updated_at can be slightly earlier than the moment its change becomes visible, so the overlap must be longer than a write takes. On the very first poll, leave updated_at[gte] out. Write the sort as %2B: a literal + arrives as a space and returns 400.
  2. Skip what you already have: skip tickets you already received in this poll with the same updated_at (match by id). A ticket that comes back with a newer updated_at changed again, so process it.
  3. End of the poll: a response with fewer rows than its pagination.pageSize ends the poll. Count every row returned, including those you skipped in step 2. Store the highest updated_at. Never wait for an empty page: gte includes the last time, so that ticket always comes back.
  4. Next request: otherwise, send the next request with updated_at[gte] set to the exact last updated_at you received (no overlap) and _page=1. Only when a full page has a single updated_at (a bulk edit stamps every ticket with the same time), take the next _page with the same filter.
Terminal window
curl -g -X GET "https://api.sitemark.com/layerFeatures?dataset_id=1234&updated_at[gte]=2026-11-02T05:55:00Z&_sortBy=%2Bupdated_at&_sortBy=%2Bid&_pageSize=10000" \
-H "Authorization: ApiKey <your-api-key>"
  • Filter by last update: the brackets of updated_at[gte] need curl -g, or URL-encode them as %5B and %5D. Use UTC with a Z: a + offset in a URL turns into a space.
  • Check one form at a time: loop over your sites’ dataset_ids.
  • What doesn’t change updated_at: comments, and relationships between tickets and other items.
  • Compare per field. A poll returns whole tickets, and your own updates come back too. Compare each field you track with the last value your system knows for it (the one you sent or last copied), and copy only the fields that differ. Don’t skip a whole ticket: it can hold your change and a field team’s change.
  • Current value. Read a field’s current value from properties.<key>.value, or defaultValue when value is missing or null. A missing field is empty, and a ticket without STATUS counts as TO_DO. The description is not in properties: read it from the ticket’s top-level description.
  • Status. Sitemark statuses are TO_DO, PLANNED, IN_PROGRESS, RESOLVED, WONT_DO and CLOSED.
  • Assignee. ASSIGNEE has two shapes: a v1 user or group id (a number, not a principal id) or a v2 value { "version": "2", "principal_id": <id> }. Read both: older values stay v1, and the value you read back can have another shape than the value you sent. List the principals with GET /principals?_pageSize=10000 (all pages). For v2, find the item whose id is equal to principal_id. For v1, find the USER item whose user.id is equal to the value, or the GROUP item whose group.legacy_user_id is equal to it. See Resolve ASSIGNEE and USER values. Compare the resolved principals, not the raw values. When deleted_at of that item is set, the user or group was removed from the company. A value with no item is a user or group removed before 17 November 2026, or one your API key cannot read.

For who changed a field and when, read List property changes, for example GET /propertyChanges?layer_feature_id=…&property_key=STATUS&_pageSize=10000 (up to 200 ids per request; the default page size is 10). If a response has more than one page (pagination.pageCount above 1), send fewer ids per request, so that each read fits in one page. Changes come oldest first, so the latest change to a field, by created_at, is the last row for that ticket. This endpoint has its own rate limit, on top of the company limits.

  • There is no “old value”; compare with the previous change of the same field.
  • Who made a change: read principal_id when it is set, and resolve it with GET /principals. Otherwise read user_id (deprecated) and find the USER principal whose user.id is equal to it. Both can be null. A change made with your API key has the key as its principal.
  • DESCRIPTION changes are not in the history: to catch description edits, compare description yourself.

A monitoring system creates a ticket from an alarm, keeps it up to date while the alarm changes, and reads back what happens to it in Sitemark. Follow the steps above, with your alarm id as your own reference, and these rules:

  • One id per alarm occurrence. If your system reuses ids when an alarm fires again, add the alarm’s start time to the id, or the lookup finds the old resolved ticket. Write the start time in UTC with Z.
  • New alarm: create the ticket with the alarm as description, a PRIORITY, and geometry at the device.
  • Alarm changes: update the priority, the description or the status. When the alarm clears, set STATUS to RESOLVED, only while the ticket is still open (see Push your changes).

An alarm fires on inverter 4. 1234 is the ticket form and a7c3e5d1-9b2f-4c6e-8d14-2f6b0c9e7a35 is the alarm id field.

The lookup for ALM-88123 finds nothing, so the ticket is created:

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",
"geometry": { "type": "Point", "coordinates": [4.4699, 51.0259] },
"properties": {
"PRIORITY": { "value": "MEDIUM" },
"a7c3e5d1-9b2f-4c6e-8d14-2f6b0c9e7a35": { "value": "ALM-88123" }
}
}'

The response holds the ticket’s id, here 482107. The alarm gets worse, so the priority is raised:

Terminal window
curl -X POST "https://api.sitemark.com/propertyChanges" \
-H "Authorization: ApiKey <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"changes": [
{
"id": "0193f1a2-8d24-7b62-8c4f-2a3b4c5d6e70",
"layer_feature_id": 482107,
"property_key": "PRIORITY",
"new_value": "HIGH"
}
]
}'

The answer is 204 No Content. A field team then fixes the inverter and resolves the ticket in Sitemark. The next poll returns the ticket with properties.STATUS { "value": "RESOLVED" } and properties.PRIORITY { "value": "HIGH" }. PRIORITY equals what was sent, so only STATUS is copied to your system.

  • Required fields, rights and error answers: see Create ticket, Update ticket fields and their rules (create, update).
  • Limits today: Sitemark doesn’t call your system when a ticket changes (no webhooks), so poll for changes. Comments and files can’t be read yet. Deleted tickets are not returned by updated_at[gte], so re-check the tickets you hold with the id filter, for example GET /layerFeatures?id=482107&id=482108&_pageSize=200: up to 200 ids per request with _pageSize=200 (the default page size is 10). A missing id was deleted or is no longer readable.
  • Keys expire after one year; see Authentication.