Skip to content

Update ticket fields

Changes one or more fields on one or more tickets, the same way as an edit in the web app: notifications go out and automations run. Changes to fields are recorded in the ticket history, which you can read back with List property changes.

Endpoint: POST /propertyChanges

Authentication: Required (API key). The key needs the “Can view all tickets” and “Can edit all tickets” rights; see Rules for the assignee and closing rights.

{
"changes": [
{
"id": "uuid",
"layer_feature_id": "integer",
"property_key": "string",
"new_value": "any | null"
}
]
}
Field Type Required Description
id uuid Yes A UUID you generate for this change (UUIDv7 recommended). Use a new id for every new change.
layer_feature_id integer Yes The ticket’s id from List layer features, not the ticket number.
property_key string Yes A built-in field (see Fields and values) or a custom property definition UUID.
new_value any Yes The new value itself, not wrapped in { "value": … }. null clears the field, where the field allows it.

Resolve a ticket and change its assignee:

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-7c10-7a51-9a3e-1b2c3d4e5f60",
"layer_feature_id": 482107,
"property_key": "STATUS",
"new_value": "RESOLVED"
},
{
"id": "0193f1a2-7c10-7a51-9a3e-1b2c3d4e5f61",
"layer_feature_id": 482107,
"property_key": "ASSIGNEE",
"new_value": 3315
}
]
}'

204 No Content. Read the result back with List property changes or List layer features.

Status Code Description
400 Invalid body or value (see Fields and values and Rules), a layer feature that isn’t a ticket, or a ticket linked to Procore or on a Procore-linked form
401 Missing, invalid, revoked or expired API key
403 The key may not make this change, for example closing without the “Can close tickets” right
404 A ticket does not exist, is not visible to the key, or is outside the key’s company or sites
429 Too Many Requests - A rate limit was exceeded
500 Internal Server Error

Errors return a JSON body with a message. Other fields can be present. A body that doesn’t match the shape above (for example more than 100 changes, or the same field twice) returns only Bad Request. When field values are refused, issues lists each problem; path points at the change in your request, and code is one of FIELD_NOT_WRITABLE, UNSUPPORTED_TYPE, INVALID_VALUE, UNREADABLE_USER, NOT_YET_SUPPORTED or REQUIRED (see Create ticket):

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

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

Field Values
STATUS TO_DO, PLANNED, IN_PROGRESS, RESOLVED, WONT_DO, CLOSED
PRIORITY LOW, MEDIUM, HIGH
ASSIGNEE The id of a user or group of the ticket’s company, from List users
TICKET_DUE_DATE A plain date YYYY-MM-DD, for example "2026-11-05"
TICKET_PLANNED_DATE One ISO 8601 interval "<start>/<end>" of two timestamps with offset, start before end, for example "2026-11-03T08:00:00+01:00/2026-11-03T12:00:00+01:00"
MODULE_SERIAL_NUMBER A string
DESCRIPTION A string of at most 2000 characters; it updates the ticket’s description (see Rules)

Custom fields, by their type in List property definitions. Fields of other types, and fields Sitemark sets itself, are refused with 400.

Custom field type Value to send
STRING A string
FLOAT A number
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. This is a UUID, not the label.
MULTI_OPTION An array of distinct option values
USER One user or group id of the ticket’s company, from List users

User fields and ASSIGNEE only accept a user or group of the ticket’s company that the key can see in List users. Fields that are shown only under conditions are refused for now.

  • Size: at most 100 changes per request, and each field of a ticket at most once.
  • All or nothing: if one change is refused, none of the changes is applied. Fix the request and send it again.
  • Only changes: a value equal to the current one is ignored and creates no history, even for a field the key could not change. The current value is the field’s value in List layer features, or its defaultValue when value is missing or null. Sending null for a field the ticket holds without a value is ignored too. You can send a ticket’s full state as List layer features returns it.
  • Time of the change: for changes sent with this endpoint, created_at in List property changes is the time Sitemark received the request. A created_at you send is ignored.
  • Required fields: a custom field can be required from a status onwards (see List property definitions). Moving a ticket to a status where a required field is empty is refused, as in the web app, and so is clearing a field that is required at the ticket’s status. Each empty field is a REQUIRED issue; its path points at the change of that field, or at the ticket’s first change that is applied.
  • Rights: changing ASSIGNEE needs the “Can assign users to tickets” right, and notifies the new assignee (or the group’s members). Moving to CLOSED, or changing a closed ticket, needs the “Can close tickets” right.
  • Description: DESCRIPTION updates the ticket’s description. Description changes are not recorded in the history, and replaying an old change can overwrite a newer description.
  • Concurrent changes: if your system and a Sitemark user change the same field, the latest change wins.

See Retries. A resent request is checked again, and an old change can overwrite a value that was changed since, so only resend a request to retry one that failed or timed out.