API

Inspections

This API provides a number of interfaces to interact with your inspection data.

It is recommended you have the View all data permission if you want a read-only view of your data, or the Manage all data permission if you want to update data. Without these permissions you may not have access to all of the data that belongs to your organization.

Learn more about permissions in SafetyCulture.

Inspection format (legacy)

Top level

{
  "audit_id": "audit_50ba581235704a368d025056a583aa8b",
  "template_id": "template_4183bcc822f146d3be542118d3f15971",
  "archived": false,

  "created_at": "2015-06-04T02:34:25.000Z",
  "modified_at": "2015-06-04T02:39:21.000Z",

  "audit_data": {},
  "template_data": {},

  "header_items": [{}],
  "items": [{}]
}
KeyTypeDescription
audit_idStringThe inspection's ID
template_idStringID of the parent template
archivedBooleanIs the inspection archived or not
created_atStringISO date and time when the inspection was first synced to the cloud or created on SafetyCulture
modified_atStringISO date and time when the inspection was last synced to the cloud or modified on SafetyCulture
audit_dataObjectGeneral information about the inspection (dates, author, scores, GPS location, etc.)
template_dataObjectSome information on the template (predefined response sets, author, images, etc.)
header_itemsArrayInspection header items (first page, optional)
itemsArrayItems in all sections after the header (basically the answers to the questions and other line items)

Inspection data

.audit_data

Inspection data root

{
  "name": "title",
  "score": 10,
  "total_score": 21,
  "score_percentage": 25,
  "date_completed": "2015-06-04T02:38:02.000Z",
  "date_modified": "2015-06-04T02:38:11.000Z",
  "duration": 224,
  "authorship": {},
  "date_started": "2015-06-04T02:34:25.000Z",
  "location": {},
  "site": {}
}
KeyTypeDescription
nameStringName of the inspection
scoreDoubleScore of the inspection
total_scoreDoubleThe maximum possible score
score_percentageDoubleA value 0 to 100 calculated as score/total_score
durationDoubleTime taken to complete the inspection (on a device or on SafetyCulture) in seconds
date_startedStringA time and date when the inspection was started (on a device or on SafetyCulture)
date_modifiedStringA time and date when the inspection was last modified (on a device or on SafetyCulture)
date_completedStringA time and date when the inspection was completed (on a device or on SafetyCulture)
authorshipObjectInformation on the authorship of the inspection
locationObjectThe device (GPS) location of where the inspection was started and completed (if GPS was enabled on the device)
siteObjectThe site that was selected for the inspection by the user (if one was selected)

GPS location

.audit_data.location

{
  "location": {
    "started": {
      "accuracy": 21,
      "geometry": {
        "type": "Point",
        "coordinates": [151.2103808, -33.8846905]
      }
    },
    "completed": {
      "accuracy": 21.189,
      "geometry": {
        "type": "Point",
        "coordinates": [151.2103808, -33.8846905]
      }
    }
  }
}

Authorship

.audit_data.authorship

{
  "authorship": {
    "owner": "Edward Stark",
    "owner_id": "user_82465b736bb94071a9a47998cf5d7777",
    "device_id": "81A34706-7417-4D6F-8C61-50AC2C814755",
    "author": "Jon Snow",
    "author_id": "user_82465b736bb94071a9a47998cf5d7777"
  }
}
KeyTypeDescription
authorStringThe person who last made changes to the inspection. Initially it's the same as the owner.
author_idStringThe ID of the inspection author.
ownerStringThe person who created the inspection is the original owner of the inspection. The owner can transfer ownership to any other person in the organization via the web app.
owner_idStringThe ID of the inspection owner.
device_idStringThe ID of the device which was used to create the inspection. Generated when the app is installed

Site

.audit_data.site contains information about the site that was selected when starting or editing an inspection. Sites belong to an area, which in turn belongs to a region.

{
  "site": {
    "name": "Sydney",
    "area": {
      "name": "NSW"
    },
    "region": {
      "name": "AU"
    }
  }
}
KeyTypeDescription
nameStringName of the site.
areaObjectThe area that the site belongs to, which in turn belongs to the region.
regionObjectThe region that the site and area belong to.

.audit_data.site.area

KeyTypeDescription
nameStringName of the area.

.audit_data.site.region

KeyTypeDescription
nameStringName of the region.

Template data

.template_data

Template data root

{
  "metadata": {},
  "authorship": {},
  "response_sets": {}
}
KeyTypeDescription
metadataObjectSome metadata about the template (name, description, image, etc.)
response_setsObjectThe question responses attached to the template. (Yes/No/NA, Safe/At Risk/NA, etc.)
authorshipObjectInformation on the authorship of the template. Same as inspection authorship.

Template metadata

.template_data.metadata

{
  "name": "name",
  "description": "description",
  "image": "52ED0287-93F1-4F53-B2C2-29EA3A2423E7"
}
KeyTypeDescription
nameStringThe template name
descriptionStringThe template description
imageObjectThe logo (media) of the template used to create this inspection

Response sets

.template_data.response_sets - The keys used in the object are the IDs of the stored responses. The values of the object are the sets themselves.

{
  "8a0161b0-a97d-11e4-800b-8f525e51b36e": { "id": "8a0161b0-a97d-11e4-800b-8f525e51b36e", "responses": [] },
  "ec410dd0-a97d-11e4-800b-8f525e51b36e": { "id": "ec410dd0-a97d-11e4-800b-8f525e51b36e", "responses": [] }
}
Response set

.template_data.response_sets.*

{
  "id": "8a0161b0-a97d-11e4-800b-8f525e51b36e",
  "responses": [{}]
}
KeyTypeDescription
idObjectID of the response set
responsesArrayArray of response set items

####### Response sets response

.template_data.response_sets.*.responses most of the fields can be absent.

{
  "id": "22a409a8-c02a-44d5-8b61-e66b6996927e",
  "colour": "5,255,84",
  "enable_score": true,
  "label": "At risk",
  "score": 1,
  "short_label": "R",
  "type": "list"
}
KeyTypeDescription
idStringID of the response
colourStringRGB colour of the response button when selected. I.e. "0,0,0" is black, "255,255,255" is white.
enable_scoreBooleanIf Score checkbox is checked. Can be attached to any response type
labelStringLabel of the response (e.g. 'Yes')
scoreNumberScore of the response
short_labelStringShort label of the response (e.g. 'Y')
typeStringThe response type. Can only be "question" (single selection) or "list" (multi choice)

Inspection header items

.header_items

Same structure as Inspection Items. See below.

Inspection items

.items are the responses or selections made by the person conducting the inspection.

Item root

{
  "label": "Inspection",
  "item_id": "379d3910-d2e2-11e4-9038-695120da729f",
  "action_item_profile_id": [],
  "type": "checkbox",
  "parent_id": "a78337ce-2cf2-419b-85b5-c81cd2d68090",
  "options": {},
  "responses": {},
  "media": {},
  "children": ["C5404AC4-2844-4D5A-A02C-9921B9B384C6"],
  "scoring": {}
}
KeyTypeDescription
item_idStringThe UUID of the item
parent_idStringParent item ID. Can be null
labelStringThe text label of the item
typeStringOne the the following: information, smartfield, checkbox, media, textsingle, element, primeelement, dynamicfield, category, section, text, signature, switch, slider, drawing, address, list, question, datetime, weather, scanner
optionsObjectA set of different options available to that type. Like: min/max values, condition, signature, media, various flags, etc.
responsesObjectRepresents user selections. Like value, or list item, or photo, location, date-time, etc.
mediaArrayInformation about one or more image or photo files
childrenArrayThe list of child item IDs
scoringObjectAn object containing all the related scores of this item

Deprecated properties that may appear in older inspections but are no longer used

action_item_profile_id | Array | The IDs of any follow up tasks added to this item

Item options

.items[].options most of the fields are absent usually.

{
  "condition": "3d346f01-e501-11e1-aff1-0800200c9a66",
  "drawing_base_image": {},
  "element": "Truck 1",
  "enable_date": true,
  "enable_signature_timestamp": true,
  "enable_time": true,
  "increment": 1,
  "is_mandatory": false,
  "label": "",
  "link": "",
  "locked": true,
  "max": 4,
  "media": {},
  "min": 2,
  "multiple_selection": false,
  "required": true,
  "response_set": "7bb1cb10-7020-11e2-bcfd-0800200c9a66",
  "failed_responses": ["8bcfbf01-e11b-11e1-9b23-0800200c9a66"],
  "secure": "",
  "type": "media",
  "url": "",
  "values": ["6565F809-B2F9-40AF-909E-2D76BC7683FF"],
  "visible_in_audit": true,
  "visible_in_report": true,
  "weighting": 8,
  "require_note": true,
  "require_media": false,
  "require_action": false
}
KeyTypeDescription
conditionStringThe smart field condition. UUID of a response set
drawing_base_imageObjectThe base image (media) for annotation item
elementStringThe title of each element of a dynamic field.
enable_dateBooleanToggles the date portion of an item containing a date-time
enable_signature_timestampBooleanToggles the timestamp set when filling in a signature field
enable_timeBooleanToggles the time portion of an item containing a date-time
hide_barcodeBooleanMeans that you can only scan barcode. Not editable.
incrementStringControls the increment jumps in slider items
is_mandatoryBooleanToggles whether the item has to have a response before the inspection can be completed
labelStringThe main visual text of an item
linkStringURL field in information items
maxStringMaximum value for a slider item
mediaObjectA media attached to the item
minStringMinimum value for a slider item
multiple_selectionBooleanTrue if this field allows multiple selection
response_setStringA UUID of the response set this item relates to
failed_responsesArrayArray of response IDs that indicate if the item has failed. E.g., for one question the answers “No” and “N/A” should be considered “failed”, but for another question only the “No” is “failed”
secureBoolean"Barcode Scanner" - "Visible in Inspection" switch value
typeStringThe type of an information field. Currently text, media or link
valuesArrayThe item's smart field response(s) as an array of strings. They are used to evaluate the smart field condition
visible_in_auditBooleanRepresents checkbox telling if an information item should be seen by a person conducting the inspection
visible_in_reportBooleanRepresents checkbox telling if an information item should appear in reports
weightingStringThe weight used for generating inspection scores
require_noteBooleanOnly available in smart field items. Represents if a note needs to be provided as part of mandatory evidence for a response
require_mediaBooleanOnly available in smart field items. Represents if media needs to be uploaded as part of mandatory evidence for a response
require_actionBooleanOnly available in smart field items. Represents if an action needs to be created as part of the response

Deprecated items that may appear in older inspections but are no longer used

KeyTypeDescription
assetsArrayDetails about entities (e.g. equipment) to inspect
lockedBooleanToggles whether an asset item has been locked
computed_fieldStringA older version of a smart field
media_visible_in_reportBooleanToggles whether a media item is included in a report
urlStringUse the link URL field in information items instead

Item responses

.items[].responses most of the fields will be absent usually.

{
  "text": "Flinders St",
  "value": "8",
  "name": "Jon Snow",
  "timestamp": "2015-06-24T02:20:22.000Z",
  "datetime": "2015-06-24T02:01:30.000Z",
  "location_text": "Alligator Creek QLD 4816\nAustralia\n(-19.405835, 146.899124)",
  "location": {},
  "selected": [{}],
  "failed": false,
  "weather": {},
  "media": [{}],
  "image": {}
}
KeyTypeDescription
textStringA simple text the person conducting the inspection types into a text box
valueStringThe selected value. Used for sliders, checkboxes and on-off switch
nameStringSomeone's name. Used with signature, location and weather items
timestampStringTime of an action. Used only with barcode and signature fields
datetimeStringManually entered date and time. Also used with weather item
location_textStringLocation represented as text (address or coordinates)
locationObjectThe location object
selectedArrayThe selected responses in questions and multi choice items. Same as template response items
failedBooleanIndicates whether the item has failed
weatherObjectInspection time weather
mediaArrayAn array of attached photos
imageObjectSignature or drawing. See media

Item scoring

.items[].scoring

{
  "score": 5,
  "max_score": 10,
  "score_percentage": 50,
  "combined_score": 3,
  "combined_max_score": 12,
  "combined_score_percentage": 25
}
KeyTypeDescription
scoreNumberScore for the answer
max_scoreNumberMaximum possible score for the answer
score_percentageNumberThe percentage value calculated as score/max_score
combined_scoreNumberCombined score from all responses if there are multiple
combined_max_scoreNumberCombined max score from all responses if there are multiple
combined_score_percentageNumberThe percentage value calculated as combined_score/combined_max_score

Location

{
  "administrative_area": "QLD",
  "country": "Australia",
  "formatted_address": [
    "Alligator Creek QLD 4816",
    "Australia"
  ],
  "geometry": {
    "coordinates": [
      146.8991244532996,
      -19.40583490239377
    ],
    "type": "Point"
  },
  "iso_country_code": "AU",
  "locality": "Alligator Creek",
  "name": "",
  "postal_code": "4816",
  "sub_administrative_area": "",
  "sub_locality": "Woodstock-Cleveland-Ross",
  "sub_thoroughfare": "",
  "thoroughfare": ""
}
KeyTypeDescription
administrative_areaString
countryString
formatted_addressArrayAddress text, line separated
geometryObjectThe geometry object from GeoJSON specification
iso_country_codeString
localityString
nameString
postal_codeString
sub_administrative_areaString
sub_localityString
sub_thoroughfareString
thoroughfareString

Media

This object is used across the entire inspection JSON.

{
  "date_created": "2015-03-23T23:57:52.000Z",
  "file_ext": "jpg",
  "media_id": "5f32d80c-3531-457f-b853-5f087927f5b1",
  "label": "can be a file name or any random text",
  "href": "https://api.safetyculture.io/audits/audit_50ba581235704a368d025056a583aa8b/media/5f32d80c-3531-457f-b853-5f087927f5b8"
}
KeyTypeDescription
date_createdStringA timestamp of the image or photo
file_extStringA file extension representing image type (like png or jpeg)
media_idStringA unique id of this media file
labelStringA label of the image or photo
hrefStringA ready-to-go direct URI to retrieve the file from