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": [{}]
}

Key	Type	Description
`audit_id`	String	The inspection's ID
`template_id`	String	ID of the parent template
`archived`	Boolean	Is the inspection archived or not
`created_at`	String	ISO date and time when the inspection was first synced to the cloud or created on SafetyCulture
`modified_at`	String	ISO date and time when the inspection was last synced to the cloud or modified on SafetyCulture
`audit_data`	Object	General information about the inspection (dates, author, scores, GPS location, etc.)
`template_data`	Object	Some information on the template (predefined response sets, author, images, etc.)
`header_items`	Array	Inspection header items (first page, optional)
`items`	Array	Items 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": {}
}

Key	Type	Description
`name`	String	Name of the inspection
`score`	Double	Score of the inspection
`total_score`	Double	The maximum possible score
`score_percentage`	Double	A value 0 to 100 calculated as `score/total_score`
`duration`	Double	Time taken to complete the inspection (on a device or on SafetyCulture) in seconds
`date_started`	String	A time and date when the inspection was started (on a device or on SafetyCulture)
`date_modified`	String	A time and date when the inspection was last modified (on a device or on SafetyCulture)
`date_completed`	String	A time and date when the inspection was completed (on a device or on SafetyCulture)
`authorship`	Object	Information on the authorship of the inspection
`location`	Object	The device (GPS) location of where the inspection was started and completed (if GPS was enabled on the device)
`site`	Object	The 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"
  }
}

Key	Type	Description
`author`	String	The person who last made changes to the inspection. Initially it's the same as the owner.
`author_id`	String	The ID of the inspection author.
`owner`	String	The 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_id`	String	The ID of the inspection owner.
`device_id`	String	The 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"
    }
  }
}

Key	Type	Description
`name`	String	Name of the site.
`area`	Object	The area that the site belongs to, which in turn belongs to the region.
`region`	Object	The region that the site and area belong to.

.audit_data.site.area

Key	Type	Description
`name`	String	Name of the area.

.audit_data.site.region

Key	Type	Description
`name`	String	Name of the region.

Template data

.template_data

Template data root

{
  "metadata": {},
  "authorship": {},
  "response_sets": {}
}

Key	Type	Description
`metadata`	Object	Some metadata about the template (name, description, image, etc.)
`response_sets`	Object	The question responses attached to the template. (Yes/No/NA, Safe/At Risk/NA, etc.)
`authorship`	Object	Information 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"
}

Key	Type	Description
`name`	String	The template name
`description`	String	The template description
`image`	Object	The 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": [{}]
}

Key	Type	Description
`id`	Object	ID of the response set
`responses`	Array	Array 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"
}

Key	Type	Description
`id`	String	ID of the response
`colour`	String	RGB colour of the response button when selected. I.e. "0,0,0" is black, "255,255,255" is white.
`enable_score`	Boolean	If Score checkbox is checked. Can be attached to any response type
`label`	String	Label of the response (e.g. 'Yes')
`score`	Number	Score of the response
`short_label`	String	Short label of the response (e.g. 'Y')
`type`	String	The 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": {}
}

Key	Type	Description
`item_id`	String	The UUID of the item
`parent_id`	String	Parent item ID. Can be null
`label`	String	The text label of the item
`type`	String	One the the following: `information`, `smartfield`, `checkbox`, `media`, `textsingle`, `element`, `primeelement`, `dynamicfield`, `category`, `section`, `text`, `signature`, `switch`, `slider`, `drawing`, `address`, `list`, `question`, `datetime`, `weather`, `scanner`
`options`	Object	A set of different options available to that type. Like: min/max values, condition, signature, media, various flags, etc.
`responses`	Object	Represents user selections. Like value, or list item, or photo, location, date-time, etc.
`media`	Array	Information about one or more image or photo files
`children`	Array	The list of child item IDs
`scoring`	Object	An 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
}

Key	Type	Description
`condition`	String	The smart field condition. UUID of a response set
`drawing_base_image`	Object	The base image (media) for annotation item
`element`	String	The title of each element of a dynamic field.
`enable_date`	Boolean	Toggles the date portion of an item containing a date-time
`enable_signature_timestamp`	Boolean	Toggles the timestamp set when filling in a signature field
`enable_time`	Boolean	Toggles the time portion of an item containing a date-time
`hide_barcode`	Boolean	Means that you can only scan barcode. Not editable.
`increment`	String	Controls the increment jumps in slider items
`is_mandatory`	Boolean	Toggles whether the item has to have a response before the inspection can be completed
`label`	String	The main visual text of an item
`link`	String	URL field in information items
`max`	String	Maximum value for a slider item
`media`	Object	A media attached to the item
`min`	String	Minimum value for a slider item
`multiple_selection`	Boolean	True if this field allows multiple selection
`response_set`	String	A UUID of the response set this item relates to
`failed_responses`	Array	Array 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”
`secure`	Boolean	"Barcode Scanner" - "Visible in Inspection" switch value
`type`	String	The type of an information field. Currently `text`, `media` or `link`
`values`	Array	The item's smart field response(s) as an array of strings. They are used to evaluate the smart field condition
`visible_in_audit`	Boolean	Represents checkbox telling if an information item should be seen by a person conducting the inspection
`visible_in_report`	Boolean	Represents checkbox telling if an information item should appear in reports
`weighting`	String	The weight used for generating inspection scores
`require_note`	Boolean	Only available in smart field items. Represents if a note needs to be provided as part of mandatory evidence for a response
`require_media`	Boolean	Only available in smart field items. Represents if media needs to be uploaded as part of mandatory evidence for a response
`require_action`	Boolean	Only 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

Key	Type	Description
`assets`	Array	Details about entities (e.g. equipment) to inspect
`locked`	Boolean	Toggles whether an asset item has been locked
`computed_field`	String	A older version of a smart field
`media_visible_in_report`	Boolean	Toggles whether a media item is included in a report
`url`	String	Use 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": {}
}

Key	Type	Description
`text`	String	A simple text the person conducting the inspection types into a text box
`value`	String	The selected value. Used for sliders, checkboxes and on-off switch
`name`	String	Someone's name. Used with signature, location and weather items
`timestamp`	String	Time of an action. Used only with barcode and signature fields
`datetime`	String	Manually entered date and time. Also used with weather item
`location_text`	String	Location represented as text (address or coordinates)
`location`	Object	The location object
`selected`	Array	The selected responses in questions and multi choice items. Same as template response items
`failed`	Boolean	Indicates whether the item has failed
`weather`	Object	Inspection time weather
`media`	Array	An array of attached photos
`image`	Object	Signature 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
}

Key	Type	Description
`score`	Number	Score for the answer
`max_score`	Number	Maximum possible score for the answer
`score_percentage`	Number	The percentage value calculated as `score/max_score`
`combined_score`	Number	Combined score from all responses if there are multiple
`combined_max_score`	Number	Combined max score from all responses if there are multiple
`combined_score_percentage`	Number	The 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": ""
}

Key	Type	Description
`administrative_area`	String
`country`	String
`formatted_address`	Array	Address text, line separated
`geometry`	Object	The geometry object from GeoJSON specification
`iso_country_code`	String
`locality`	String
`name`	String
`postal_code`	String
`sub_administrative_area`	String
`sub_locality`	String
`sub_thoroughfare`	String
`thoroughfare`	String

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"
}

Key	Type	Description
`date_created`	String	A timestamp of the image or photo
`file_ext`	String	A file extension representing image type (like png or jpeg)
`media_id`	String	A unique id of this media file
`label`	String	A label of the image or photo
`href`	String	A ready-to-go direct URI to retrieve the file from