HomeGuidesSamplesAPI
API

Actions

The SafetyCulture API gives you direct access to your Actions data. There are methods to search and retrieve actions.

Action format

This section describes the complete action response format.

Action top level

{
  "action": {
    "task": {
      "task_id": "d6658a5a-6154-4802-b1f3-953a67e492c6",
      "creator": {
        "user_id": "c3aa4fae-bbad-4abf-8550-29c683012796",
        "firstname": "SafetyCulture",
        "lastname": "User"
      },
      "title": "Test Action",
      "description": "This is a test action generated by the SafetyCulture API.",
      "created_at": "2022-02-21T23:59:00.226559Z",
      "due_at": null,
      "priority_id": "58941717-817f-4c7c-a6f6-5cd05e2bbfde",
      "status_id": "17e793a1-26a3-4ecd-99ca-f38ecc6eaa2e",
      "collaborators": [],
      "template_id": "",
      "inspection": {
        "inspection_id": "",
        "inspection_name": ""
      },
      "inspection_item": {
        "inspection_item_id": "",
        "inspection_item_name": "",
        "inspection_item_type": "",
        "inspection_item_response_values": []
      },
      "site": {
        "id": "",
        "name": "",
        "region": "",
        "area": ""
      },
      "modified_at": "2022-02-21T23:59:00.226559Z",
      "references": [],
      "completed_at": null,
      "template_name": "",
      "status": {
        "status_id": "17e793a1-26a3-4ecd-99ca-f38ecc6eaa2e",
        "key": "TO_DO",
        "label": "To Do",
        "display_order": 1
      }
    }
  }
}
KeyTypeDescription
task_idString (UUID)The action ID.
template_idString (UUID)The template ID of the inspection which the action belongs to.
template_nameStringThe template name of the inspection which the action belongs to.
inspectionObjectThe inspection which the action belongs to inspection.
inspection_itemObjectThe inspection item which the action belongs to inspection_item.
creatorObjectInformation about the action creator.
titleStringThe title of the action.
descriptionStringThe description of the action.
created_atString (ISO8601)Date and time when the action was created.
modified_atString (ISO8601)Date and time when the action was last modified.
completed_atString (ISO8601)Date and time when the action was completed.
due_atString (ISO8601)Date and time when the action is due.
priority_idString (UUID)ID of the action priority.
statusObjectStatus information of the action status.
siteObjectGeneral information of the site where the action was created.
collaboratorsArrayList of Collaborators of the action.
referenceObjectInformation about from where the action was created. Only available when the action was created from an Inspection or a Sensor Alert.

Inspection

.inspection contains the information about the inspection which action belongs to.

{
  "inspection": {
    "inspection_id": "40a57fda-bb93-4891-9db3-d34466adeedd",
    "inspection_name": "25 Nov 2021 / Safetyculture user"
  }
}
KeyTypeDescription
inspection_idString (UUID)ID of the inspection.
inspection_nameStringname of the inspection.

Inspection item

.inspection_item contains the information about the inspection item which action belongs to.

{
  "inspection_item": {
    "inspection_item_id": "09ce922d-a3c4-426b-8860-27adfcb5e89f",
    "inspection_item_name": "question name",
    "inspection_item_type": "question"
  }
}
KeyTypeDescription
inspection_item_idString (UUID)ID of the inspection item.
inspection_item_nameStringname of the inspection item.
inspection_item_typeStringtype of the inspection item.

Creator

.creator contains the information about the creator of the action.

{
  "creator": {
    "user_id": "c3aa4fae-bbad-4abf-8550-29c683012796",
    "firstname": "SafetyCulture",
    "lastname": "User"
  }
}
KeyTypeDescription
idString (UUID)ID of the creator of the action.
firstnameStringFirst name of the creator of the action.
lastnameStringLast name of the creator of the action.

Action site

.site contains the information about the site which the action belongs to.

{
  "site": {
    "id": "704d6061-0383-4e2c-a8dc-a1804712677a",
    "name": "Bilpin",
    "region": "NSW",
    "area": "Australia"
  }
}
KeyTypeDescription
idString (UUID)ID of the site.
nameStringName of the site.
regionStringThe region of the site.
areaStringThe area of the site.

Priority

.priority_id contains the id of the priority of an action.

The current accepted priorities are:

IDValue
58941717-817f-4c7c-a6f6-5cd05e2bbfdeNone
16ba4717-adc9-4d48-bf7c-044cfe0d2727Low
ce87c58a-eeb2-4fde-9dc4-c6e85f1f4055Medium
02eb40c1-4f46-40c5-be16-d32941c96ec9High

Status

.status contains the information about the status of an action.

{
  "status": {
    "status_id": "17e793a1-26a3-4ecd-99ca-f38ecc6eaa2e",
    "key": "TO_DO",
    "label": "To Do",
    "display_order": 1
  }
}
KeyTypeDescription
status_idString (UUID)ID of the status.
labelStringName of the status.

Action status labels can be customized for an organization. If an action status's label is not customized, it should be using one of the following default labels:

IDLabelAction is completed?
17e793a1-26a3-4ecd-99ca-f38ecc6eaa2eTo doNo
20ce0cb1-387a-47d4-8c34-bc6fd3be0e27In progressNo
7223d809-553e-4714-a038-62dc98f3fbf3CompleteYes
06308884-41c2-4ee0-9da7-5676647d3d75Can't doYes

Collaborators

.collaborators contains the information about the collaborators of the action. It can contain multiple users, groups or external users.

{
  "collaborators": [
    {
      "collaborator_id": "c3aa4fae-bbad-4abf-8550-29c683012796",
      "collaborator_type": "USER",
      "assigned_role": "ASSIGNEE",
      "user": {
        "user_id": "c3aa4fae-bbad-4abf-8550-29c683012796",
        "firstname": "SafetyCulture",
        "lastname": "User"
      }
    },
    {
      "collaborator_id": "f877808b-9b86-4147-9269-274e0169e021",
      "collaborator_type": "GROUP",
      "assigned_role": "ASSIGNEE",
      "group": {
        "group_id": "f877808b-9b86-4147-9269-274e0169e021",
        "name": "Test Group"
      }
    },
    {
      "collaborator_id": "4251c7c8-9af6-4233-8d4e-967b28a48c93",
      "collaborator_type": "EXTERNAL_USER",
      "assigned_role": "ASSIGNEE",
      "external_user": {
        "id": "4251c7c8-9af6-4233-8d4e-967b28a48c93",
        "email": "[email protected]"
      }
    }
  ]
}

Collaborator data

KeyTypeDescription
collaborator_idString (UUID)ID of the collaborator of the action.
collaborator_typeStringThe type of collaborator of the action.
assigned_roleStringThe role of collaborator of the action.
userObjectInformation about the user. Only available when the collaborator_type is COLLABORATOR_TYPE_USER.
groupObjectInformation about the group. Only available when the collaborator_type is COLLABORATOR_TYPE_GROUP.
external_userObjectInformation about the external user. Only available when the collaborator_type is COLLABORATOR_TYPE_EXTERNAL_USER.

Collaborator type

The type of the collaborator.

KeyDescription
USERThe collaborator is a specific user.
GROUPThe collaborator is a group. This means that every user that belongs to that group is also a collaborator.
EXTERNAL_USERThe collaborator is not a SafetyCulture user.

Collaborator role

The current role of an action collaborator.

KeyDescription
ASSIGNEEThe collaborator is an assignee of the action.

User

.collaborators[].user contains the information about a specific user.

{
  "user": {
    "user_id": "c3aa4fae-bbad-4abf-8550-29c683012796",
    "firstname": "SafetyCulture",
    "lastname": "User"
  }
}
KeyTypeDescription
user_idString (UUID)ID of the user.
firstnameStringFirst name of the user.
lastnameStringLast name of the user.

Group

.collaborators[].group contains the information about a group.

{
  "group": {
    "group_id": "f877808b-9b86-4147-9269-274e0169e021",
    "name": "Test Group"
  }
}
KeyTypeDescription
group_idString (UUID)ID of the group.
nameStringName of the group.

External user

.collaborators[].external_user contains the information about an external user (an user who do not belong to the organisation).

{
  "external_user": {
    "id": "4251c7c8-9af6-4233-8d4e-967b28a48c93",
    "email": "[email protected]"
  }
}
KeyTypeDescription
idString (UUID)ID of the external user.
emailStringEmail of the external user.

Reference

.reference contains information about the entity that originated the action. Not available for standalone actions.

{
  "reference": {
    "type": "INSPECTION",
    "id": "51d4482f-f78b-5a30-9618-2217025f55cc",
    "inspection_context": {},
    "sensor_alert_context": {}
  }
}
KeyTypeDescription
typeStringType of the reference.
idString (UUID)ID of the referenced entity.
inspection_contextObjectInformation about the Inspection that originated the action. Only available when the action was created from an Inspection.
sensor_alert_contextObjectInformation about the Sensor Alert that originated the action. Only available when the action was created from a Sensor Alert.

Reference type

.reference.type contains the type of the entity that originated the action.

TypeDescription
INSPECTIONIndicates that the action was created from an inspection or inspection item. When the reference is from this type, the reference.id will be the ID of the Inspection.
SENSOR_ALERTIndicates that the action was created from a sensor alert. When the reference is from this type, the reference.id will be the ID of the Sensor Alert.

Inspection context

.reference.inspection_context contains the information of the inspection and inspection item that originated the action.

{
  "inspection_context": {
    "inspection_id": "effa93bb-8cfb-4783-af5d-c507340dc6e0",
    "inspection_name": "11 Aug 2021 / Checklist",
    "inspection_item_id": "67034555-c11e-4411-bf75-140866c555be",
    "inspection_item_name": "Question Name",
    "inspection_item_type": "",
    "inspection_item_path": []
  }
}
KeyTypeDescription
inspection_idString (UUID)ID of the inspection (UUID).
inspection_nameStringName of the inspection.
inspection_item_idString (UUID)ID of the inspection item (UUID).
inspection_item_nameStringName of the inspection item.
inspection_item_typeStringName of the inspection item type.
inspection_item_pathStringThe ancestor Names of the inspection item.

Sensor alert context

.reference.sensor_alert_context contains the information of the sensor alert that originated the action.

{
  "sensor_alert_context": {
    "sensor_alert_id": "79ce7380-0809-5a0a-9d58-a7ead30d078e",
    "level": "OK",
    "created_at": "2021-12-01T12:39:09.313635Z",
    "detected_at": "2021-11-30T22:55:00Z",
    "sensor_id": "a5ea5ae1-304c-46ef-9dfd-ce845208290f",
    "site_name": "2 Lacey St - L1",
    "metric_type": "WIND_GUST",
    "sensor_name": "Weather"
  }
}
KeyTypeDescription
sensor_alert_idString (UUID)ID of the sensor alert.
levelStringLevel of importance of the sensor alert.
created_atString (ISO8601)Date and time when the alert was created.
detected_atString (ISO8601)Date and time when the alert was detected.
sensor_idString (UUID)ID of the sensor where the alert was created.
site_nameStringName of the site where the alert was created.
metric_typeStringType of the alert metric.
sensor_nameStringName of the sensor where the alert was created.

Sensor alert event level

.reference.sensor_alert_context.level represents the level of importance of the sensor alert.

LevelDescription
ALERT_EVENT_LEVEL_OKIndicates that the device metric becomes healthy.
ALERT_EVENT_LEVEL_INFOIndicates that the first alert was sent.
ALERT_EVENT_LEVEL_WARNIndicates that the second alert was sent.
ALERT_EVENT_LEVEL_CRITICALIndicates that the third alert was sent.

Sensor alert metric type

.reference.sensor_alert_context.metric_type represents the type of received metric.

TypeDescription
METRIC_TYPE_TEMPERATURETemperature metric.
METRIC_TYPE_HUMIDITYHumidity metric.
METRIC_TYPE_BATTERYBattery level. Percentage based i.e. 0 - 100.
METRIC_TYPE_SIGNALSignal strength metric.
METRIC_TYPE_AIR_QUALITY_PM25Air quality for particulate matter less than 2.5 microns.
METRIC_TYPE_AIR_QUALITY_PM10Air quality for particulate matter less than 10 microns.
METRIC_TYPE_TEMPERATURE_2Alternative temperature for hardware that sends 2 temperatures.
METRIC_TYPE_DIFFERENTIAL_AIR_PRESSUREDifferential air pressure.
METRIC_TYPE_COCarbon monoxide.
METRIC_TYPE_DOOR_OPEN_CLOSEDDoor open/closed (boolean metric).
METRIC_TYPE_BATTERY_VOLTAGEBattery voltage metric.