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.
1. Set up your API key
Section titled “1. Set up your API key”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 |
2. Map your data once
Section titled “2. Map your data once”| 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). |
Mapping your fields
Section titled “Mapping your fields”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_atis the time it was created in Sitemark. If you need your own creation date, use a custom date field.
3. Create tickets
Section titled “3. Create tickets”Find a ticket by your own reference
Section titled “Find a ticket by your own reference”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.
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
Section titled “Create the ticket”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 forRetry-Afterand send it again. - Other refusals: see the table under Push your changes.
4. Push your changes
Section titled “4. 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
STATUStoRESOLVEDonly while the ticket is still open: skip it whenSTATUSis alreadyRESOLVED,CLOSEDorWONT_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. |
5. Fetch changes made in Sitemark
Section titled “5. Fetch changes made in Sitemark”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.
Polling for changed tickets
Section titled “Polling for changed tickets”Each poll walks the changed tickets of one form, oldest change first:
- First request of a poll: send
dataset_id,updated_at[gte]set to the highestupdated_atyou stored from the previous poll minus a few minutes,_sortBy=%2Bupdated_at&_sortBy=%2Bid, and a_pageSizeof at most 10,000 (larger values are reduced to 10,000). A ticket’supdated_atcan 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, leaveupdated_at[gte]out. Write the sort as%2B: a literal+arrives as a space and returns400. - Skip what you already have: skip tickets you already received in this poll with the same
updated_at(match byid). A ticket that comes back with a newerupdated_atchanged again, so process it. - End of the poll: a response with fewer rows than its
pagination.pageSizeends the poll. Count every row returned, including those you skipped in step 2. Store the highestupdated_at. Never wait for an empty page:gteincludes the last time, so that ticket always comes back. - Next request: otherwise, send the next request with
updated_at[gte]set to the exact lastupdated_atyou received (no overlap) and_page=1. Only when a full page has a singleupdated_at(a bulk edit stamps every ticket with the same time), take the next_pagewith the same filter.
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]needcurl -g, or URL-encode them as%5Band%5D. Use UTC with aZ: 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.
Copy the changes back
Section titled “Copy the changes back”- 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, ordefaultValuewhenvalueis missing ornull. A missing field is empty, and a ticket withoutSTATUScounts asTO_DO. The description is not inproperties: read it from the ticket’s top-leveldescription. - Status. Sitemark statuses are
TO_DO,PLANNED,IN_PROGRESS,RESOLVED,WONT_DOandCLOSED. - Assignee.
ASSIGNEEhas 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 withGET /principals?_pageSize=10000(all pages). For v2, find the item whoseidis equal toprincipal_id. For v1, find theUSERitem whoseuser.idis equal to the value, or theGROUPitem whosegroup.legacy_user_idis equal to it. See ResolveASSIGNEEandUSERvalues. Compare the resolved principals, not the raw values. Whendeleted_atof 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.
Read the history
Section titled “Read the history”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_idwhen it is set, and resolve it withGET /principals. Otherwise readuser_id(deprecated) and find theUSERprincipal whoseuser.idis equal to it. Both can benull. A change made with your API key has the key as its principal. DESCRIPTIONchanges are not in the history: to catch description edits, comparedescriptionyourself.
If your system is a monitoring system
Section titled “If your system is a monitoring system”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, aPRIORITY, andgeometryat the device. - Alarm changes: update the priority, the description or the status. When the alarm clears, set
STATUStoRESOLVED, only while the ticket is still open (see Push your changes).
Example
Section titled “Example”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:
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:
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.
Things to know
Section titled “Things to know”- 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 theidfilter, for exampleGET /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.