Update a location event definition

Request#

PATCH /api/v1/location-events/{event}

Requires location-events:update and an active token creator who remains an administrator of the token’s organization. Location event setup and permissions.

Send Authorization: Bearer YOUR_API_TOKEN and Accept: application/json.

Path parameters#

event integer Required

Definition ID from list definitions.

Query parameters#

This endpoint does not use query parameters.

Request body#

Send JSON with Content-Type: application/json.

name string Optional

Display name, 3–255 characters.

icon string Optional

Available icon name, up to 100 lowercase letters, numbers, or hyphens. Use setup options; defaults to map-pin when creating.

color string Optional

Color from setup options; defaults to gray when creating.

visible boolean Optional

Whether this definition is offered when logging location events; defaults to true when creating.

sets_status string or null Optional

active or inactive to set the location’s status whenever this event is logged, or null (the default) to leave status alone.

limit_to_categories integer array Optional

Accepted only as an empty list. Category restrictions apply to asset events only.

cost_category_id null Optional

Accepted only as null. Cost categories apply to asset lifecycle events only.

fields object array Optional

Complete replacement field list. See field definitions below. Omit to preserve fields.

Field definitions#

A supplied fields array replaces the complete list, with at most 100 entries. Each entry accepts only the following properties. Preserve every existing field you want to keep and strip read-only response properties before sending it.

id integer or null Required

Existing field ID from this definition, or null for a new field. Existing IDs must be distinct.

slug string or null Required

Existing immutable slug, a built-in slug (date, time, and notes), or null for a new custom field. Built-in slugs must be unique within the list.

name string Required

Display label, 2–255 characters.

datatype string Required

text, number, date, boolean, yesno, phone, or editor. Built-ins use their server-defined datatype. Fields with saved values cannot change datatype.

size string Required

Display width: full or half.

is_required boolean Required

Whether a value is required when the event is logged. Always normalized to false for boolean fields.

visible boolean Required

Whether the field is shown and accepted. Set false to hide a field while retaining its history.

The built-in date and time fields map to the logged event’s event_date, and notes maps to its description; marking them required makes those inputs required when logging an event. Custom fields take values through field_values. is_system, has_values, and position are read-only; omit them from field payloads. The array order determines field position. Adding required fields does not backfill historical values.

Retry protection#

Requires Idempotency-Key: 8–128 letters, numbers, dots, underscores, colons, or hyphens. Reuse the same method, path, body, and key for retries. Successful responses are remembered for 24 hours per token. Conflicting key reuse returns 409. Idempotency and retries.

Example#

Replace the example ID with an ID from your organization. Set ASSETCENTER_API_TOKEN as described in the quick start.

curl --request PATCH "https://my.assetcenter.app/api/v1/location-events/42" \
  --header "Authorization: Bearer $ASSETCENTER_API_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --header "Content-Type: application/json" \
  --data '{"color":"green","sets_status":null}'

For retries, reuse the original key instead of generating another UUID.

Response#

200 OK. Illustrative values; IDs and positions will differ.

{
  "data": {
    "id": 42,
    "group": "location",
    "name": "Fire inspection",
    "icon": "map-pin",
    "color": "green",
    "visible": true,
    "is_system": false,
    "is_global": false,
    "parent_id": null,
    "position": 0,
    "limit_to_categories": [],
    "cost_category_id": null,
    "sets_status": null,
    "can_delete": true,
    "fields": [
      {
        "id": 101,
        "slug": "date",
        "name": "Date",
        "datatype": "date",
        "size": "half",
        "position": 0,
        "is_system": true,
        "is_required": false,
        "visible": true,
        "has_values": false
      },
      {
        "id": 102,
        "slug": "time",
        "name": "Time",
        "datatype": "text",
        "size": "half",
        "position": 1,
        "is_system": true,
        "is_required": false,
        "visible": true,
        "has_values": false
      },
      {
        "id": 103,
        "slug": "notes",
        "name": "Notes",
        "datatype": "text",
        "size": "full",
        "position": 2,
        "is_system": true,
        "is_required": false,
        "visible": true,
        "has_values": false
      },
      {
        "id": 104,
        "slug": null,
        "name": "Inspector",
        "datatype": "text",
        "size": "full",
        "position": 3,
        "is_system": false,
        "is_required": true,
        "visible": true,
        "has_values": false
      }
    ]
  }
}

Behavior and constraints#

PATCH changes only supplied fields and requires at least one writable property. Omitting fields preserves all existing fields and their IDs. A supplied array replaces the complete list and sets its order; fields with saved values cannot be omitted or change datatype. Send visible: false to hide a definition or field. Group, slug, tenant, parent, system identity, and direct position changes are rejected. Changing sets_status affects only events logged afterward; it does not change any location’s current status.

Errors#

401 means the customer token is missing, invalid, expired, or revoked, or its creator is inactive. 403 means the required permission or administrator membership is missing. 404 means the definition is unavailable in the token’s organization. 422 means invalid or unsupported input. 429 means the rate limit was reached. Errors and limits. 409 means conflicting idempotency-key reuse or a protected deletion.