API

Issues

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": {},
      "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"
  },
}
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.

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"
      }
    }
  ]
}
KeyTypeDescription
assigned_roleStringThe role of the assignee of the issue. Will only be ASSIGNEE.
collaborator_typeStringThe type of assignee of the issue. Will only be USER.
userObjectInformation about the user.
KeyTypeDescription
user_idString (UUID)The ID of the user who is assigned to the issue.
firstnameStringThe first name of the user who is assigned to the issue.
lastnameStringThe 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"
    }
  ]
}
KeyTypeDescription
idStringThe ID of the inspection.
created_atTimestampThe time that the inspection was created.
statusStringThe 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.
titleStringThe title of the inspection.
template_titleStringThe 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"
  },
}
KeyTypeDescription
idString (UUID)The ID of the site.
nameStringThe name of the site.
regionStringThe region of the site.
areaStringThe 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
  }

}
KeyTypeLabelDescription
idString (UUID)The UUID of a category.
keyStringThe name of a category. This can be a default name or one that is customized in your organization.
labelStringThe name of a category. This field's value is the same as the value for key.
descriptionStringThe description of a category. This is unused, and is hardcoded to an empty string, ``.
display_orderint32The sorting order of a list of categories. This is unused, and is hardcoded as 0.
is_visibleBooleanThe indicator for whether a category is visible or not for an organization on the web app and the mobile app.
use_category_access_whitelistBooleanThe 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"
  },
}
KeyTypeDescription
idString (UUID)The ID of this media item.
tokenStringA unique identifier for this media item.
filenameStringThe filename for this media item.
media_typeStringThe 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
    }
  }
}
KeyTypeDescription
nameStringThe name of the issue's location.
thoroughfareStringThe thoroughfare of the location.
sub_thoroughfareStringThe sub-thoroughfare of the location.
localityStringThe locality of the location.
sub_localityStringThe sub_locality of the location.
administrative_areaStringThe administrative area of the location.
sub_administrative_areaStringThe sub-administrative area of the location.
postal_codeStringThe postal_code of the location.
countryStringThe country of the location.
iso_country_codeStringThe ISO country code of the location.
geo_positionObjectThe 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,
  }
}
KeyTypeDescription
longitudedoubleThe longitude of the location.
latitudedoubleThe latitude of the location.
accuracyint32The 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": {},
  }
}
KeyTypeDescription
typeStringThe type of a reference.
idString (UUID)The unique identifier of a referenced entity.
action_contextObjectThe information about an action that originated from an issue.