Update action item

PATCH

/action-items/{actionItemId}

curl --request PATCH \
  --url https://safe-api.safetyradar.com/v2/action-items/123e4567-e89b-12d3-a456-426614174000 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-team: my-team-slug' \
  --data '{ "title": "example", "description": "example", "assignedToUserId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "assignedToUserExternalId": "example", "assignedToDepartmentId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "assignedToRoleSlug": "example", "dueDate": "2026-04-15T12:00:00Z", "priority": "low", "status": "open", "statusExternalId": "example", "locationExternalId": "example", "externalId": "example", "responseNotes": "example", "fields": { "crew": "A-shift", "corrective_cost": 1250 }, "metadata": { "additionalProperty": "example" } }'

• Production

Partially update an action item by UUID; omitted fields are left unchanged. Supply statusExternalId to move it to a status in the organization’s Action Item flow, or locationExternalId to set the location/equipment. Unrecognised external IDs are ignored rather than rejected — check statusName / assetName on the response to confirm what was mapped. externalId renames the item’s own correlation ID and returns 409 if another action item already holds that value. To update by correlation ID instead of UUID, POST to /action-items with an externalId that already exists.

fields is a partial patch of your organization’s custom fields: only the keys you send are written, an omitted key keeps its stored value, and null on a key clears it. A refused envelope is a 400 with a per-key list and nothing is written.

Authorizations

• Bearer

Parameters

Path Parameters

actionItemId

required

Action item UUID

string format: uuid

Example

123e4567-e89b-12d3-a456-426614174000

Action item UUID

Header Parameters

x-team

Deprecated — accepted but ignored; the v2 API is org-scoped.

string

Example

my-team-slug

Deprecated — accepted but ignored; the v2 API is org-scoped.

Request Body^required

Media typeapplication/json

object

title

string

>= 1 characters

description

string

nullable >= 1 characters

assignedToUserId

string format: uuid

nullable

assignedToUserExternalId

string

assignedToDepartmentId

string format: uuid

assignedToRoleSlug

string

nullable

dueDate

string format: date-time

nullable

priority

string

Allowed values: low medium high urgent

status

string

Allowed values: open in_progress complete

statusExternalId

string

locationExternalId

string

externalId

string

>= 1 characters

responseNotes

string

nullable

fields

The organization’s admin-defined custom fields, keyed by definition key. Validated against the organization’s own definitions: an unknown key, a bad enum value or a missing required field is a 400 carrying a per-key list. Does not merge with metadata — the two are stored separately and neither overwrites the other. Discover the contract at GET /v2/modules/action_item/fields. A PARTIAL patch: only the keys sent are written, an omitted key leaves its stored value alone, and null clears one.

object

key

additional properties

any

Example

{
  "crew": "A-shift",
  "corrective_cost": 1250
}

metadata

Verbatim, unvalidated. Use fields — typed, admin-defined, validated. See GET /v2/modules/action_item/fields. Replaces the stored bag wholesale rather than merging into it.

object

key

additional properties

nullable

Responses

200

Updated action item

Media typeapplication/json

object

data

required

object

id

required

string format: uuid

entityType

required

string

nullable

entityId

required

string format: uuid

nullable

formSubmissionId

required

string format: uuid

nullable

sourceSectionNodeId

required

string

nullable

title

required

string

description

required

string

nullable

assignedToUserId

required

string format: uuid

nullable

assignedToUserName

string

nullable

assignedToDepartmentId

required

string format: uuid

nullable

assignedToRoleSlug

required

string

nullable

dueDate

required

string

nullable

priority

required

string

Allowed values: low medium high urgent

statusId

required

string format: uuid

nullable

statusName

required

string

nullable

statusGroup

required

string

nullable

Allowed values: new in_progress complete on_hold cancelled

status

required

string

Allowed values: open in_progress complete

assetId

required

string format: uuid

nullable

assetName

required

string

nullable

externalId

required

string

nullable

responseNotes

required

string

nullable

attachments

required

Array<object>

nullable

object

key

additional properties

nullable

completedAt

required

string

nullable

completedById

required

string format: uuid

nullable

completedByName

required

string

nullable

createdById

required

string format: uuid

nullable

fields

required

The organization’s custom module fields, keyed by definition key. Always present; {} when the organization has configured none, and a defined key this item holds no value for is absent rather than null. Discover the keys, types and filter operators at GET /v2/modules/action_item/fields.

object

key

additional properties

any

metadata

required

Verbatim, unvalidated. Use fields — typed, admin-defined, validated. See GET /v2/modules/action_item/fields.

object

key

additional properties

nullable

organizationId

required

string format: uuid

teamId

required

string format: uuid

nullable

createdAt

required

string

updatedAt

required

string

Example

{
  "data": {
    "priority": "low",
    "statusGroup": "new",
    "status": "open",
    "fields": {
      "crew": "A-shift",
      "corrective_cost": 1250
    }
  }
}

400

Validation error, or a fields envelope the organization’s definitions refuse (code: invalid_fields, with the per-key list under details.fields)

Media typeapplication/json

Any of:

object

object

code

required

string

Allowed values: invalid_fields

message

required

string

details

required

object

fields

required

Array<object>

object

key

required

string

message

required

string

object

object

code

required

string

message

required

string

details

object

key

additional properties

nullable

Example

{
  "code": "invalid_fields"
}

401

Unauthorized

Media typeapplication/json

object

code

required

string

message

required

string

details

object

key

additional properties

nullable

Example^generated

{
  "code": "example",
  "message": "example",
  "details": {
    "additionalProperty": "example"
  }
}

404

Action item not found

Media typeapplication/json

object

code

required

string

message

required

string

details

object

key

additional properties

nullable

Example^generated

{
  "code": "example",
  "message": "example",
  "details": {
    "additionalProperty": "example"
  }
}

409

ExternalId is already in use by another action item

Media typeapplication/json

object

code

required

string

message

required

string

details

object

key

additional properties

nullable

Example^generated

{
  "code": "example",
  "message": "example",
  "details": {
    "additionalProperty": "example"
  }
}