HomeGuidesSamplesAPI
API

Start and pre-fill inspections

Automatically start inspections with pre-filled answered questions

Being able to start and share inspections automatically makes it easier for developers to build custom solutions that:

  • schedule inspections to be created at particular times,
  • pre-fill inspection information from external data sources or from previously completed inspections,
  • trigger custom actions like reminders or other notifications from third-party providers to be executed before and/or after inspections get created

and more.

With automation services (like Zapier, IFTTT, MS Flow etc.) work flows similar to the above can be achieved without any development effort.

One common use case example is where a supervisor wants an inspection to start automatically and be assigned to a team member to conduct at a particular time or on a recurring schedule. To save time, reduce human error and increase consistency, any responses that are known at the time the inspection is started should be automatically pre-filled. Such responses could include an equipment serial number, the full name of the person intended to complete the inspection, the inspection site or anything else relevant to the task at hand.

The API can be used to achieve such a scenario in 3 steps:

  1. Start an inspection to create an inspection against a specified template
  2. List group or organization users (or List groups) to discover the IDs of the users (or groups) to share the inspection with in order to conduct it
  3. Share an inspection with the IDs from the previous step

If the user/group IDs to share the inspection with are already known, the second step is not needed and the process can be simplified to two steps:

  1. Start an inspection to create an inspection against a specified template
  2. Share an inspection with the users or groups you want to conduct it.

Depending on the access you assign at the time of sharing, you may restrict some users' access to view only, edit to allow users to conduct the inspection, or delete to also permit users to delete the shared inspection. The person conducting the inspection doesn't need access to the template which also avoids the possibility of inspections getting started (e.g. using the SafetyCulture mobile app) outside the control of the supervisor.

In our example use case above, the supervisor creating the inspection will always be the owner of the created inspection but may not always be the author as well. The author of the created inspection is the last user who made any change to the inspection.

Any "auto-sharing" properties configured in the template that was used to start the inspection are inherited at inspection creation time so the inspection is automatically shared with the users and groups configured within the template. For instance, in our use case above, the supervisor creating the inspection may have configured the template so that inspections created from it are automatically shared with the management group.

Now that an inspection can be started and shared automatically, the supervisor may decide they want an inspection to start at pre-configured regular (or irregular) times e.g. a weekly inspection from the "Weekly Checklist" template every Monday at 11am etc. This can be achieved very easily by setting up a scheduled job (using any third party scheduler software like cron, Windows Scheduled Tasks, Zapier etc.) that triggers calls to the Start an inspection and Share an inspection API endpoints as shown above.

Especially in the case of repeatedly conducted inspections, it can be a tedious task to copy information from other systems or from previous inspection responses to pre-fill certain items of the newly created inspection. Pre-filling such information using the API makes this problem go away for many types of inspection responses. In our example use case above, the supervisor could maintain a database of equipment that needs to be inspected when a work order is generated by a field worker against a particular part or equipment. An inspection gets automatically created as a result and shared with the user to conduct the inspection. The inspection title, equipment location, serial number and description of the work order are pre-filled into the inspection so the inspector does not have to find and fill in that information manually, thus saving time and avoiding typing and consistency mistakes.

Step by step implementation

Let's assume the supervisor of our use case above want to schedule an inspection for equipment with serial number "SC-8799229947729942245".

The supervisor's SafetyCulture account is used to obtain an API access token used to perform all API interaction below.

A particular template is to be used for inspecting that sort of equipment, so the supervisor uses the Search modified templates API call to find the ID of the template to use.

Searching for the template ID to use

curl "https://api.safetyculture.io/templates/search?field=template_id&field=name" \
  -H "Authorization: Bearer {api_token}"

The above command returns the template ID corresponding to the template name for each template on the supervisor's account

{
  "count": 1,
  "total": 1,
  "templates": [
    {
      "template_id": "template_BB29F82814B64F559A33BF7CAA519787",
      "name": "Equipment Inspection Template"
    }
  ]
}

With the template ID and Start an inspection API capability, the supervisor requests from the API to start an inspection and pre-fill the inspection title response with

  • the equipment serial number
  • the name of the person to conduct the inspection (note: not shared with them yet, will do in the next step)

Create a new inspection from template_BB29F82814B64F559A33BF7CAA519787 with pre-filled information

curl -X POST "https://api.safetyculture.io/audits" \
-d '{
       "template_id": "template_BB29F82814B64F559A33BF7CAA519787",
       "header_items": [
         {
           "item_id": "f3245d40-ea77-11e1-aff1-0800200c9a66",
           "label": "Inspection Title",
           "type": "textsingle",
           "responses": {
             "text": "Equipment Inspection S/N SC-8799229947729942245"
           }
         },
         {
           "item_id": "f3245d43-ea77-11e1-aff1-0800200c9a66",
           "label": "Conducted By",
           "type": "textsingle",
           "responses": {
             "text": "John Citizen"
           }
         }
       ]
     }' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {api_token}"

The above command returns the JSON content of the created inspection (some fields omitted for brevity)

{
  "template_id": "template_BB29F82814B64F559A33BF7CAA519787",
  "audit_id": "audit_01ca38a821504cda885736cccbb9ba40",
  "created_at": "2017-01-25T01:13:20.584Z",
  "modified_at": "2017-01-25T01:13:20.584Z",
  "audit_data": {...},
  "template_data": {...},
  "header_items": [...],
  "items": [...]
}

The supervisor records the audit_id from the API response to use in a later step.

The owner and author of the created inspection are both the supervisor at this stage. The new inspection is immediately accessible (e.g. in SafetyCulture or via Search modified inspections) to any users configured to have access to it via the template's "auto-sharing" properties, if any were set.

Now the supervisor wants to "assign" the inspection to team member named John Citizen with email address "[email protected]" who do not have access to "Equipment Inspection Template" at all. To share the inspection with John Citizen the supervisor looks up their user ID using the List group or organization users API capability.

Lookup the user ID of the person to conduct the inspection

curl -X POST "https://api.safetyculture.io/users/search" \
-d "{"email": ["[email protected]"]}}" \
-H "Authorization: Bearer {api_token}"

The above command returns the user ID of John Citizen:

{
  "users": [
    {
      "id": "user_c4e2421223b5497186bb8ea4e4159fcc",
      "email": "[email protected]",
      "firstname": "John",
      "lastname": "Citizen"
    }
  ]
}

With the audit_id and user_id from the previous steps the supervisor can now share the newly created inspection with John Citizen using the Share an inspection API capability. Sharing with edit access allows John Citizen to complete the inspection but not delete it for increased security.

Share the created inspection with John Citizen (user_c4e2421223b5497186bb8ea4e4159fcc) with edit access level.

curl -X POST "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/share" \
-d '{"shares": [{"id":"user_c4e2421223b5497186bb8ea4e4159fcc", "permission":"edit"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {api_token}"

John Citizen can now see and conduct the inspection using SafetyCulture which makes him the author of the inspection. The supervisor remains the owner and maintains access to the inspection at all times.