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.
Request
Section titled “Request”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. |
Example
Section titled “Example”Resolve a ticket and change its assignee:
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 } ] }'Response
Section titled “Response”204 No Content. Read the result back with List property changes or
List layer features.
Error responses
Section titled “Error responses”| 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." } ]}Fields and values
Section titled “Fields and values”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
valuein List layer features, or itsdefaultValuewhenvalueis missing ornull. Sendingnullfor a field the ticket holds without avalueis 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_atin List property changes is the time Sitemark received the request. Acreated_atyou 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
REQUIREDissue; itspathpoints at the change of that field, or at the ticket’s first change that is applied. - Rights: changing
ASSIGNEEneeds the “Can assign users to tickets” right, and notifies the new assignee (or the group’s members). Moving toCLOSED, or changing a closed ticket, needs the “Can close tickets” right. - Description:
DESCRIPTIONupdates the ticket’sdescription. 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.
Retries
Section titled “Retries”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.