The SafetyCulture API gives you access to your Issues data. The API includes methods to retrieve a list of issues, retrieve a specific issue, as well as endpoints to create and update an issue. Issues has some methods of access control, such as site-based access and category level restrictions. However, if the account being used for API access has the "Manage all data" permission, this permission will act as an override and give access to all data within your organisation.
Note that much of the Issues API has references to "incident", including the endpoints and the response objects. Issues used to be called Incidents, but was renamed. For all intents and purposes, "incident" is synonymous with "issue".
Issue format
This section describes the complete issue response format.
{
"incident": {
"task": {
"task_id": "eaf9b051-914e-4ca3-8571-e6e8e816ec3c",
"creator": {},
"title": "Test Issue",
"description": "This is a test issue generated by the SafetyCulture API.",
"created_at": "2022-01-25T05:42:21.832670Z",
"due_at": "2022-01-27T05:42:21.832670Z",
"priority_id": "58941717-817f-4c7c-a6f6-5cd05e2bbfde",
"status_id": "547ed646-5e34-4732-bb54-a199d304368a",
"collaborators": [],
"template_id": "",
"inspection": {},
"inspection_item": {},
"site": {},
"occurred_at": "2022-01-25T05:42:21.832670Z",
"modified_at": "2022-02-03T00:48:59.689138Z",
"references": [],
"completed_at": null,
"template_name": "",
"status": null
},
"category_id": "01cc874c-a6c8-464b-ae75-ab8688f1113c",
"category": {},
"media": [],
"location": null,
"inspections": []
}
}
Creator
.creator contains the information about the creator of the issue.
{
"creator": {
"user_id": "04b11270-14f8-4f46-81e6-6694fee2ee19",
"firstname": "SafetyCulture",
"lastname": "User"
},
}
| Key | Type | Description |
|---|---|---|
id | String (UUID) | ID of the creator of the action. |
firstname | String | First name of the creator of the action. |
lastname | String | Last name of the creator of the action. |
Collaborators
.collaborators contains the information about the assignee of the issue.
{
"collaborators": [
{
"collaborator_id": "eb6307fb-cf76-402b-b64a-8e61f8959ce8",
"collaborator_type": "USER",
"assigned_role": "ASSIGNEE",
"user": {
"user_id": "eb6307fb-cf76-402b-b64a-8e61f8959ce8",
"firstname": "SafetyCulture",
"lastname": "User"
}
}
]
}
| Key | Type | Description |
|---|---|---|
assigned_role | String | The role of the assignee of the issue. Will only be ASSIGNEE. |
collaborator_type | String | The type of assignee of the issue. Will only be USER. |
user | Object | Information about the user. |
| Key | Type | Description |
|---|---|---|
user_id | String (UUID) | The ID of the user who is assigned to the issue. |
firstname | String | The first name of the user who is assigned to the issue. |
lastname | String | The last name of the user who is assigned to the issue. |
Inspections
The fields, .inspection and .inspection_item are deprecated. Inspections that have been linked to an issue are in .inspections.
{
"inspections": [
{
"id": "c29994d6-f581-4a50-bcc7-9df75bf07918",
"created_at": "2022-01-31T06:01:54.238Z",
"status": "INSPECTION_STATUS_DELETED",
"title": "31 Jan 2022 / SafetyCulture User",
"template_title": "Test template"
}
]
}
| Key | Type | Description |
|---|---|---|
id | String | The ID of the inspection. |
created_at | Timestamp | The time that the inspection was created. |
status | String | The current status of the linked inspection. The values will be either INSPECTION_STATUS_IN_PROGRESS to indicate the inspection is in progress, INSPECTION_STATUS_COMPLETED to indicate that the inspection has been completed, or INSPECTION_STATUS_DELETED to indicate that the inspection has been deleted. |
title | String | The title of the inspection. |
template_title | String | The title of the template that this inspection was created from. |
Site
.site contains information about the site that the issue occurred at.
{
"site": {
"id": "704d6061-0383-4e2c-a8dc-a1804712677a",
"name": "Bilpin",
"region": "NSW",
"area": "Australia"
},
}
| Key | Type | Description |
|---|---|---|
id | String (UUID) | The ID of the site. |
name | String | The name of the site. |
region | String | The region of the site. |
area | String | The area of the site. |
Category
A category is used to classify an issue. For example, you can filter issues by category for analytics, or give users or groups access to issues from a category.
{
"category": {
"id": "01cc874c-a6c8-464b-ae75-ab8688f1113c",
"key": "Maintenance",
"label": "Maintenance",
"description": "",
"display_order": 0,
"is_visible": true,
"use_category_access_whitelist": false
}
}
| Key | Type | Label | Description |
|---|---|---|---|
id | String (UUID) | The UUID of a category. | |
key | String | The name of a category. This can be a default name or one that is customized in your organization. | |
label | String | The name of a category. This field's value is the same as the value for key. | |
description | String | The description of a category. This is unused, and is hardcoded to an empty string, ``. | |
display_order | int32 | The sorting order of a list of categories. This is unused, and is hardcoded as 0. | |
is_visible | Boolean | The indicator for whether a category is visible or not for an organization on the web app and the mobile app. | |
use_category_access_whitelist | Boolean | The indicator for whether a category's issues can be accessed by anyone in your organization or not. If this is false for a category, then that category's issues can only be accessed by creators and assignees. |
Media
The media attached to an issue. This can be either an image, PDF or a video.
{
"media": {
"id": "17fe46fd-93ef-49c9-8b90-a87f682a85d6",
"token": "2702fbfa8a6b8b1eba08c9481b137951cdc3be2acd4fffa4df76e9fbcbbd3dee",
"filename": "0e96f162-7ba3-4221-acd9-dc45ea33bf04.jpg",
"media_type": "MEDIA_TYPE_IMAGE"
},
}
| Key | Type | Description | |
|---|---|---|---|
id | String (UUID) | The ID of this media item. | |
token | String | A unique identifier for this media item. | |
filename | String | The filename for this media item. | |
media_type | String | The type of this media item. This will be MEDIA_TYPE_IMAGE for an image, MEDIA_TYPE_VIDEO for a video, or MEDIA_TYPE_PDF for a PDF. |
Issue location
The location of the issue.
{
"location": {
"name": "42 Wallaby Way, Sydney NSW 2037, Australia",
"thoroughfare": "Wallaby Way",
"sub_thoroughfare": "42",
"locality": "Sydney",
"sub_locality": "Sydney",
"administrative_area": "NSW",
"sub_administrative_area": "Sydney",
"postal_code": "2000",
"country": "Australia",
"iso_country_code": "AU",
"geo_position": {
"longitude": 151.2107,
"latitude": -33.8521,
"accuracy": 0
}
}
}
| Key | Type | Description |
|---|---|---|
| name | String | The name of the issue's location. |
| thoroughfare | String | The thoroughfare of the location. |
| sub_thoroughfare | String | The sub-thoroughfare of the location. |
| locality | String | The locality of the location. |
| sub_locality | String | The sub_locality of the location. |
| administrative_area | String | The administrative area of the location. |
| sub_administrative_area | String | The sub-administrative area of the location. |
| postal_code | String | The postal_code of the location. |
| country | String | The country of the location. |
| iso_country_code | String | The ISO country code of the location. |
| geo_position | Object | The geoposition of the location. |
Geoposition
A geoposition is an object containing the latitude and longitude.
{
"geo_position": {
"latitude": -33.8521,
"longitude": 151.2107,
"accuracy": 10,
}
}
| Key | Type | Description | |
|---|---|---|---|
| longitude | double | The longitude of the location. | |
| latitude | double | The latitude of the location. | |
| accuracy | int32 | The accuracy of the location. |
Reference
.reference contains information about an entity that originated from an issue.
{
"reference": {
"type": "ACTION",
"id": "51d4482f-f78b-5a30-9618-2217025f55cc",
"action_context": {},
}
}