NAV Navbar
Iauditor logo
shell

Introduction

As you scroll through the page, you can use sample requests to try the API for yourself.

The iAuditor API gives you direct access to your data in the iAuditor platform.

The API supports creating new inspections, sharing them, as well as retrieving inspection data and any attached media. Inspections can be searched by a set of parameters or retrieved individually. The search parameters include the last modification date of an inspection, allowing you to use the API for tasks such as extracting all inspections from the system, as well as retrieving new and updated inspections periodically.

Access to the iAuditor API requires a Premium subscription. You can sign up for an iAuditor account and upgrade to Premium starting with a 30-day trial.

Getting Started

This section aims to get you started with the iAuditor API by showing you how to obtain an authorization token, use the token to authorize a request, and search for inspections.

The examples use the curl application, allowing them to be run as command lines, wherever curl is installed.

Generate an authorization token

Sample request:

curl \
  -X POST \
  --data-urlencode username=example@safetyculture.io \
  --data-urlencode password=your_password \
  -d grant_type=password \
  "https://api.safetyculture.io/auth"

Access to the iAuditor API requires an authorization token. This token can be used to authorize all requests you make so that you don’t need to store your iAuditor username and password in your scripts or applications.

Following the example, POST the username and password fields with your iAuditor email and password, along with the grant_type value of password, to the https://api.safetyculture.io/auth endpoint.

Sample response:

{
    "access_token": "b7f8f791920c1618ace0e24b4d52ce260473dad870e7bd56b869f8d2f26e554d",
    "token_type": "Bearer"
}

The access_token is your secret token for authorizing all requests to the API and has access to all the same data as the iAuditor account.

Authorize a request

Sample request:

curl "https://api.safetyculture.io/audits/search?field=audit_id" \
  -H "Authorization: Bearer b7f8f791920c1618ace0e24b4d52ce260473dad870e7bd56b869f8d2f26e554d"

You can make requests to the API by passing the authorization token in the Authorization HTTP header, following the format Authorization: Bearer b7f8f791...f26e554d. This header needs to be passed on every request.

If a request doesn’t have the Authorization header, the API would return a 401 HTTP error code to indicate an unauthorized request.

Sample requests in this guide present the Authorization header with Bearer {your access token}. If you’re using sample requests to try the API, remember to replace {your access token} with your access token.

Search for inspections

Sample request:

curl "https://api.safetyculture.io/audits/search?field=audit_id&field=modified_at" \
  -H "Authorization: Bearer {your access token}"

Sample response:

{
  "count": 2,
  "total": 2,
  "audits": [
    {
      "audit_id": "audit_01ca38a821504cda885736cccbb9ba40",
      "modified_at": "2015-03-17T03:16:31.072Z"
    },
    {
      "audit_id": "audit_853C17E6040B43DA1DFDDD8E6A4D6D3A",
      "modified_at": "2015-03-24T06:31:47.203Z"
    }
  ]
}

To search for inspections using the API, make a GET request to the https://api.safetyculture.io/audits/search endpoint. By default, the response lists inspections in ascending order, from the oldest to the most recently modified, limited to the first 1,000 inspections.

You can pass the fields you want to see in the response, as well as the parameters to apply and narrow the search. See the search inspections section for more information on search parameters.

Sample request: search inspections within a given period

curl "https://api.safetyculture.io/audits/search?field=audit_id&field=modified_at&modified_after=2015-01-01T00:00:00.000Z&modified_before=2015-04-01T00:00:00.000Z" \
  -H "Authorization: Bearer {your access token}"

Sample request: search inspections conducted from a specific template

curl "https://api.safetyculture.io/audits/search?field=audit_id&template=template_37afc5890aa94e778bbcde4fc4cbe480" \
  -H "Authorization: Bearer {your access token}"

Retrieve an inspection

Sample request:

curl "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40" \
  -H "Authorization: Bearer {your access token}"

Sample response:

{
  "template_id": "template_BB29F82814B64F559A33BF7CAA519787",
  "audit_id": "audit_01ca38a821504cda885736cccbb9ba40",
  "created_at": "2015-05-01T01:13:20.584Z",
  "modified_at": "2015-06-30T05:03:40.754Z",
  "audit_data": {
  }
}

Once you have the list of inspections, you can retrieve each inspection individually using the https://api.safetyculture.io/audits/<audit_id> endpoint. You can find an inspection’s audit_id either from a previous search or in the iAuditor web app report URL.

Each successful request’s JSON response for this endpoint is a complete representation of the inspection data, including the template that was used. See the inspection format section for more information.

Sample response: Any media attachments are also included

    {
      "media": [
        {
          "date_created": "2015-06-24T22:59:59.000Z",
          "file_ext": "jpg",
          "label": "no label",
          "media_id": "9E3BD015-6275-4668-BAF1-296B2F38444C",
          "href": "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/media/9E3BD015-6275-4668-BAF1-296B2F38444C"
        }
      ]
    }

As you can see in the media attachments sample response, the media references can be used if you want to retrieve the media using the API.

Retrieve a media item from an inspection

Sample request:

curl "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/media/9E3BD015-6275-4668-BAF1-296B2F38444C" \
  -o 9E3BD015-6275-4668-BAF1-296B2F38444C.jpg \
  -H "Authorization: Bearer {your access token}"

For this endpoint, the request returns the actual media file with the relevant Content-Type header instead of JSON.

Once you’ve retrieved an inspection, you may also want to retrieve any media item attached in the inspection, such as photos, annotations, and PDFs. You can retrieve a media item by passing the inspection’s audit_id and the media item’s media_id.

Each request downloads the media item directly, so make sure to save the output with an appropriate name and the correct file extension. You can use the values from the media item in the inspection JSON to construct the filename, such as <media_id>.<file_ext>.

Repeat this request for as many inspection media items as you require.

Next steps

By now, you should have a basic understanding of the inspection retrieval methods using the iAuditor API. You can continue to learn about all the available requests and parameters or take a look at some API use cases that you might like to try yourself.

Use Cases

The following sections describe some common use cases for the API and how to best achieve them.

Automatically start inspections with pre-filled information

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

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 Inspection to create an inspection against a specified template
  2. Search users (or Search groups) to discover the IDs of the users (or groups) to share the inspection with in order to conduct it
  3. Share 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 Inspection to create an inspection against a specified template
  2. Share inspection with the users or groups you want to conduct it.

Depending on the permissions you assign at the time of sharing you may restrict some users’ access to view only, edit allowing users to conduct the inspection or delete to also permit users to delete the shared inspection. The person conducting the inspection does not need access to the template which also avoids the possibility of inspections started (e.g. using the iAuditor application) 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 Inspection and Share 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 iAuditor 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 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 {your access 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 Inspection API capability, the supervisor requests from the API to start an inspection and pre-fill the inspection title response with

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 {your access 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 iAuditor or via Search 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 “john.citizen@safetyculture.io” 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 Search 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": ["john.citizen@safetyculture.io"]}}" \
-H "Authorization: Bearer {your access token}"

The above command returns the user ID of John Citizen:

{
  "users": [
    {
      "id": "user_c4e2421223b5497186bb8ea4e4159fcc",
      "email": "john.citizen@safetyculture.io",
      "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 Inspection API capability. Sharing with edit permission 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 permission

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 {your access token}"

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

Extract all historical inspection data

The API can be used to extract all historical data that your account has access to.

The steps described below can be seen in action in our open source audit data exporting tool.

There are several steps to extracting this inspection data:

  1. Retrieve all the available inspection identifiers
  2. Retrieve the corresponding inspection data for each identifier
  3. Retrieve the media associated with each inspection

Retrieve all available inspection identifiers

curl "https://api.safetyculture.io/audits/search?field=audit_id&field=modified_at" \
  -H "Authorization: Bearer {your access token}"
{
  "count": 1000,
  "total": 2023,
  "audits": [
    {
      "audit_id": "audit_01ca38a821504cda885736cccbb9ba40",
      "modified_at": "2015-03-17T03:16:31.072Z"
    },
    {
      "audit_id": "audit_853C17E6040B43DA1DFDDD8E6A4D6D3A",
      "modified_at": "2015-03-24T06:31:47.203Z"
    }
  ]
}

To retrieve all of the available inspection IDs, you will use the process as described in the Search Inspections section of the documentation. You can then use the IDs from the audit_id field of each record in the inspections array.

curl "https://api.safetyculture.io/audits/search?field=audit_id&field=modified_at&modified_after=2015-03-24T06:31:47.203Z" \
  -H "Authorization: Bearer {your access token}"

If you have more than 1000 inspections, then you’ll see that the amount is limited and the total will be greater than the count retrieved. In this case, you should make another request, setting the modified_after parameter to the date of the last retrieved inspection. Repeat this process until all of the inspections have been retrieved.

Retrieve the corresponding inspection data for each identifier

curl "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40" \
  -H "Authorization: Bearer {your access token}"

Given the list of inspections retrieved in the previous step, the inspections may then be retrieved individually, as described in Get Inspection.

The inspection data can then be stored or processed as desired within your own systems, using the Inspection Format as a guide to the data available.

Retrieve the media associated with each inspection

Finally, you may decide that you need to retrieve the media for some or all of the inspections. To do so, for each of the inspections retrieved above, find all of the elements that contain media. This includes:

curl "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/media/9E3BD015-6275-4668-BAF1-296B2F38444C" \
  -o 9E3BD015-6275-4668-BAF1-296B2F38444C.jpg \
  -H "Authorization: Bearer {your access token}"

The media element is described in the media reference. It contains an href element, that allows you to directly request the required media, if you have not retrieved it already. You can then retrieve it as described in Get Media.

Get modified inspections

curl "https://api.safetyculture.io/audits/search?field=audit_id&field=modified_at&modified_after=2015-03-24T06:31:47.203Z" \
  -H "Authorization: Bearer {your access token}"

Once you have extracted all of the historical data, the next obvious step is to retrieve the modified inspections so that you can continue populating your own systems with new inspection data. This function is also useful for producing regular updates from your inspection data, such as a live dashboard.

To do this, you will search for inspections that are either after the last inspection that you have, or the last time you attempted to retrieve new inspections, using the modified_after parameter.

{
  "count": 1,
  "total": 1,
  "audits": [
    {
      "audit_id": "audit_853C17E6040B43DA1DFDDD8E6A4D6D3A",
      "modified_at": "2015-03-24T06:31:47.203Z"
    }
  ]
}

This will retrieve only the inspections modified since you last retrieved data, and often may contain no inspections at all depending on the frequency of updates and the frequency data is retrieved. With this information, you may then follow the steps from the previous use case to retrieve the inspection content and media.

Note that the inspections retrieved in this request may return identifiers that you have previously retrieved if the inspection it points to has been modified. You should ensure that this overwrites any inspection data that exists in your own system rather than duplicating them.

Making Requests

curl "https://api.safetyculture.io/" \
  -H "User-Agent: MyIAuditorClient/1.0"

If you write your own client or send requests via command lines, you should always ensure that an appropriate User-Agent header is sent. For example, a client called MyIAuditorClient version 1.0 might require a user agent of MyIAuditorClient/1.0 in the header. In your code, we that recommend you replace MyIAuditorClient with some text unique to your organization or use a case like SalesforceIntegration/1.0.

curl "https://api.safetyculture.io/" \
  -H "Accept: application/json"

You must also send the Accept header to indicate the desired content type. This should be application/json or a wildcard such as */*.

Batch Requests

This endpoint can be used to send multiple API requests in a single call to the API e.g. to save round-trip network time. Up to 15 requests can be combined in a batch.

To make a batch request, you need to construct a JSON array of API requests and POST it to the /batch endpoint. Each request in the array contains a method, a path and an optional JSON payload. Each request in the batch uses the same Authorization, Content-Type and Accept headers as the batch request itself.

Requests in the batch are executed sequentially in the order they are specified in the array of the payload of the batch request.

The result of one request can be used in the immediately following request to create a request pipeline. The syntax used to create such pipelines is that of hoek.reach. The code examples section contains an example request to retrieve an array of iAuditor group data. Each array entry contains the name and ID of all groups the authenticated user is a member of. The ID of the first group in the array is then passed onto the next request, which retrieves all the users in that group. A properly constructed batch request returns a single response containing an array of the JSON responses of all requests is returned in the same order as the original request.

If an error occurs as a result of one the requests to an endpoint it will be included in the response in the same location in the array as the request causing the issue. The error object will include an error property that you can interrogate. The response status code of a properly constructed batch request will be 200 even when a request in the batch returns a different status code.

Be aware of rate limits when using the batch request endpoint.

curl \
-X POST “ https://api.safetyculture.io/batch "\
-H “Authorization: Bearer …” \
-H “Content-Type:application/json” \
-d `{
      "requests":[
       {"method": "get", "path": "/share/connections" },
       {"method": "get", "path": "/groups/role_00061a39d9104e809752f5e08c9677a6/users" },
       {"method": "post", "path": "/users/search", "payload": {"email": ["jsmith@safetyculture.io"]} }
       ]
    }`

The above command returns an array of JSON objects structured like this

[
    {
        "groups": [
            {
                "id": "role_00061a39d9104e809752f5e08c9677a6",
                "name": "SafetyCulture"
            }
        ]
    },
    {
        "total": 2,
        "offset": 0,
        "limit": 2000,
        "users": [
            {
                "email": "jsmith@safetyculture.io",
                "firstname": "John",
                "lastname": "Smith",
                "user_id": "user_000fdeb0738e4d1f8289bd56f999ff5e",
                "status": "active"
            },
            {
                "email": "john.citizen@safetyculture.io",
                "firstname": "John",
                "lastname": "Citizen",
                "user_id": "user_000ad1ca3faf439d9415c98ecf166d67",
                "status": "active"
            }
        ]
    },
    {
        "users": [
            {
                "id": "user_000fdeb0738e4d1f8289bd56f999ff5e",
                "email": "jsmith@safetyculture.io",
                "firstname": "John",
                "lastname": "Smith"
            }
        ]
    }
]

If one or more of the requests had failed with an error, it will be included in the response as shown below:

[
    {
        "groups": [
            {
                "id": "role_00061a39d9104e809752f5e08c9677a6",
                "name": "SafetyCulture"
            }
        ]
    },
    {
        "statusCode": 404,
        "error": "Not Found",
        "message": "Could not list users for: role_28161a39d9104e809752f5e08c9677a6"
    },
    {
        "statusCode": 400,
        "error": "Bad Request",
        "message": "child \"email\" fails because [\"email\" at position 0 fails because [\"0\" must be a string]]",
        "validation": {
            "source": "payload",
            "keys": [
                "email.0"
            ]
        }
    }
]

Example of a batch request pipeline

{
"requests":[
 {"method": "get", "path": "/share/connections" },
 {"method": "get", "path": "/groups/$0.groups.0.id/users" }
 ]
}

HTTP request

POST https://api.safetyculture.io/batch

Request body

The body should use the content type application/json with the following parameters:

Parameter Description
requests An array of (maximum 15) requests. See table below of how each request within the batch is structured:
Request body Description
method The HTTP Method used by the request (valid values are get, post, put, delete)
path The route of the individual request
payload The body of the individual request (optional)
query The query parameter can be assigned as a third property rather than placing it directly into the path. The query property accepts a JSON object that will be formatted into a query string (optional)

Response

Status code Description
200 OK Batch request was processed
400 Bad Request Invalid (e.g. malformed) request
404 Not Found The route specified was not found

Note: In request pipelines using the hoek.reach syntax, if the path on any individual request is malformed a 500 Internal Server Error may be returned. This is a known limitation of the current implementation.

See the Errors section for more details.

Authentication

The API requires an authorization token for each request. A token can be generated by making a request to the https://api.safetyculture.io/auth endpoint with your iAuditor username and password.

Once you’ve obtained a token, it needs to be passed in the Authorization header on requests to the API. For example, Authorization: Bearer b7f8f791...f26e554d.

The iAuditor API uses OAuth 2.0 as the means of authorization for individual requests. The initial authorization uses the Resource Owner Password Credentials Grant method and currently doesn’t support any other flows.

The token used by the API is a Bearer token. It should be considered as a “personal access token” that you control yourself, for your own iAuditor account. A pre-registered client ID and secret are not required to create an authorization token.

Please note that API tokens expire after 30 days of inactivity, at which point you would need to generate a new token to use. If a token is used to make API requests within that period, then it would not expire unless it’s made invalid from new tokens.

Request an authorization token

Sample request:

curl \
  -X POST \
  --data-urlencode username=example@safetyculture.io \
  --data-urlencode password=secret \
  -d grant_type=password \
  "https://api.safetyculture.io/auth"

Sample response:

{
    "access_token": "b7f8f791920c1618ace0e24b4d52ce260473dad870e7bd56b869f8d2f26e554d",
    "token_type": "Bearer"
}

Following the example, POST the username and password fields with your iAuditor email and password, along with the grant_type value of password, to the https://api.safetyculture.io/auth endpoint. This request follows the Resource Owner Password Credentials Grant method of OAuth 2.0.

HTTP request

POST https://api.safetyculture.io/auth

Request body

The body should use the content type application/x-www-form-urlencoded with the following required parameters in the body.

Parameter Description
username The iAuditor account email.
password The iAuditor account password.
grant_type The value must be password.

Response

The response for this request has the content type application/json and include the following parameters.

Parameter Description
access_token The token that can be used in the Authorization header for all other requests.
token_type The type of access token returned, which is Bearer.

Errors

The errors for this method follow the OAuth specification. If an OAuth error occurs, the returns a 400 Bad Request error code, where the format of the body differs from other API errors.

Parameter Description
error The error code that occurred, such as invalid_grant.
error_description A human readable description of the error code.

Other standard errors may occur. For example: - 403 Forbidden if the iAuditor account doesn’t have access to the iAuditor API. - 429 Too Many Requests if you are making too many request to this endpoint.

Inspections

The iAuditor API contains a read-only interface to your inspection data. There are methods to retrieve inspections, their media, and to search for particular inspections.

Search inspections

curl "https://api.safetyculture.io/audits/search?field=audit_id&field=modified_at" \
-H "Authorization: Bearer {your access token}"

The above command returns JSON structured like this:

{
  "count": 2,
  "total": 2,
  "audits": [
    {
      "audit_id": "audit_01ca38a821504cda885736cccbb9ba40",
      "modified_at": "2015-03-17T03:16:31.072Z"
    },
    {
      "audit_id": "audit_853C17E6040B43DA1DFDDD8E6A4D6D3A",
      "modified_at": "2015-03-24T06:31:47.203Z"
    }
  ]
}

The inspection search endpoint allows you to retrieve the inspection ID, modification date, and template ID of inspections that meet a certain criteria. It is possible to request inspections between given dates, based on a particular template, and whether or not to include archived inspections.

This allows you to find particular inspections, to gradually retrieve the inspection IDs of every inspection that you have access to, or to retrieve inspections updated since your last search.

In the request, you must specify the fields that you want to return. The field audit_id is not required, the inspection ID will be always included in every inspection result returned in the response. To include other inspection properties in the response you can optionally add parameters modified_at and template_id. Multiple field elements can be provided.

Searching by modification date:

curl "https://api.safetyculture.io/audits/search"\
"?field=audit_id&field=modified_at"\
"&modified_after=2015-01-01T00:00:00.000Z" \
 -H "Authorization: Bearer {your access token}"

curl "https://api.safetyculture.io/audits/search"\
"?field=audit_id&field=modified_at"\
"&modified_after=2015-01-01T00:00:00.000Z"\
"&modified_before=2015-04-01T00:00:00.000Z" \
 -H "Authorization: Bearer {your access token}"

To modify the order in which inspections are returned, an optional param order can be given. order defaults to asc meaning inspections are given from earliest to latest, but can also be set to desc.

To search between dates, use the modified_before and modified_after parameters. This will find inspections between the dates given.

The dates should be formatted according to ISO 8601 and include the date, time and timezone. For example, 2015-04-01T00:00:00.000Z or 2015-04-01T00:00+1000.

The modification dates used for searching are related to SafetyCulture’s cloud storage and include latest sync times, modifications through the iAuditor website, and other system modifications. This means that the date may not match the last date that the inspection was modified. This will ensure that you may consistently find all of the inspections modified since your last search, even if they are synced some time after they are last changed.

Searching by template:

curl "https://api.safetyculture.io/audits/search?field=audit_id"\
"&template=template_37afc5890aa94e778bbcde4fc4cbe480" \
 -H "Authorization: Bearer {your access token}"

curl "https://api.safetyculture.io/audits/search?field=audit_id"\
"&template=template_37afc5890aa94e778bbcde4fc4cbe480"\
"&template=template_FCB63052F0D445AEB52F25DE6BEB8D40" \
 -H "Authorization: Bearer {your access token}"

Searching by template allows you to find all of the inspections created from a certain template. You may specify one or more template parameters to search for. The template ID can be obtained from an inspection, or by opening it for editing in SafetyCulture, e.g.: https://app.safetyculture.io/#/iauditor/templates/<template_id>

Searching by ownership:

curl "https://api.safetyculture.io/audits/search?field=audit_id&owner=me" \
-H "Authorization: Bearer {your access token}"

curl "https://api.safetyculture.io/audits/search?field=audit_id&owner=other" \
-H "Authorization: Bearer {your access token}"

Including archived inspections:

curl "https://api.safetyculture.io/audits/search?field=audit_id&archived=both" \
-H "Authorization: Bearer {your access token}"

By default, archived inspections are not included in the search. The archived parameter allows you to decide whether to search only archived inspections (true), not search archived inspections (false), or search all inspections including those archived (both).

Including only completed inspections:

curl "https://api.safetyculture.io/audits/search?field=audit_id&completed=true" \
 -H "Authorization: Bearer {your access token}"

Complete and incomplete inspections are included in the search. The completed parameter can be used to change this behaviour. Like the archived flag, you can set it to true to search only completed inspections, false to search only incomplete inspections, or both to search all inspections.

The number of results returned defaults to 1000 at a time, which is the maximum allowed. It is possible to customise the limit parameter to retrieve fewer inspections in each request. The limit is a maximum, and fewer inspections may be returned than the limit, even if there are more available within the search parameters. This can occur if two or more inspections have the same modified_at across the limit boundary, in which case no inspections with that timestamp are returned, allowing you to correctly retrieve the next “page” using the modified_after parameter.

The inspections are returned in ascending order from the earliest first, up to the limit specified. More inspections can be retrieved by repeating the search, using the modified_at of the last inspection as the modified_after parameter to the next request.

HTTP request

GET https://api.safetyculture.io/audits/search

Query parameters

Parameter Description
field Field(s) of the inspection to retrieve. Valid values are audit_id, template_id and modified_at. Multiple field parameters may be specified.
modified_before Only search for inspections where modified_at is before the given date. The date should be specified in full form ISO 8601 format, e.g. 2015-04-01T00:00:00.000Z
modified_after Only search for inspections where modified_at is after the given date. The date should be specified in full form ISO 8601 format, e.g. 2015-04-01T00:00:00.000Z
template Only search for inspections that were created from the given template(s). Multiple template parameters may be specified to search across multiple templates. e.g. template=template_37afc5890aa94e778bbcde4fc4cbe480
owner Only search for inspections with the given ownership. Valid values are me (inspections owned by the current user), other (inspections shared with the current user) or all (both owned by and shared with the current user). The default is all.
archived Whether to search archived inspections. Valid values are true (search only archived inspections), false (do not search archived inspections) or both (search all inspections including those archived). The default is false.
completed Whether to search completed inspections. Valid values are true (search only completed inspections), false (do not search completed inspections) or both (search all inspections including those completed). The default is both.
limit The maximum number of inspections to retrieve. The maximum value is 1000. The default is also 1000.
order The order in which inspections are returned. Valid values are asc (earliest to latest) or desc (latest to earliest). The default is asc.

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
audits An array of inspections matching the search results. Each inspection is an object containing the fields specified in the request.
count The number of inspections returned by this request.
total The total number of inspections that could have been returned by this search if it were unlimited.

Get inspection

curl "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40" \
  -H "Authorization: Bearer {your access token}"

The above command returns JSON structured like this:

{
  "template_id": "template_BB29F82814B64F559A33BF7CAA519787",
  "audit_id": "audit_01ca38a821504cda885736cccbb9ba40",
  "created_at": "2015-05-01T01:13:20.584Z",
  "modified_at": "2015-06-30T05:03:40.754Z",
  "audit_data": {
  }
}

This endpoint retrieves a specific inspection with the supplied inspection ID. The inspection response contains the information recorded in the inspection, as well as relevant parts of the original template at the time the inspection was created, and links to media.

The full JSON object is much larger than the example here, including information in the audit_data and other fields.

HTTP request

GET https://api.safetyculture.io/audits/<audit ID>

URL parameters

Parameter Description
audit ID The ID of the inspection to retrieve

response

A description of the inspection format can be found in the Inspection Format section.

Modify inspection

The endpoint allows you to modify certain properties of an existing inspection. Specifically the following can be updated:

a) The archived property to archive or un-archive the inspection b) The responses of certain items in the header_items and items portion of the inspection

The supported items whose response can be updated with this endpoint are the same as those for pre-filling when the inspection is started and the same limits apply regarding acceptable input values like the length of the text of a text response etc.

This endpoint supports partial updates. Any items not present in the request will not be changed.

Updating any inspection responses will set the author of this inspection to the user account connected to the API and making the change. If the update is only to archive or un-archive the inspection the author of the inspection will not be changed.

Removing permissions from an inspection is on our roadmap.

Caveats:

  1. Simultaneous updates to the same inspection may result in concurrency errors. Prefer sequential updates to avoid these.
  2. Setting the response to a multiple choice item to an invalid response ID (e.g. one that does not belong in the response set attached to that item on the template) may result in that inspection item to appear as having no response selected in the inspection.
Parameter Description
archived Boolean indicating if you want to archive or un-archive the inspection
header_items Array of any inspection header items with updated responses
items Array of any inspection items with updated responses
curl -X PUT "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40" \
  -d '{
         "archived": true,
         "header_items": [
           {
             "item_id": "f3245d41-ea77-11e1-aff1-0800200c9a66",
             "type": "textsingle",
             "responses": {
               "text": "Updated client site"
             }
           }
         ]
       }' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {your access token}"

The above command will modify the inspection and reply 200 OK. The response will contain the full inspection.

{
  "template_id": "template_BB29F82814B64F559A33BF7CAA519787",
  "audit_id": "audit_01ca38a821504cda885736cccbb9ba40",
  "created_at": "2017-05-01T11:23:19.345Z",
  "modified_at": "2017-06-30T35:39:51.398Z",
  "audit_data": {...},
  "archived": true,
  "items": [...],
  "header_items": [
     [...],
     {
       "item_id": "f3245d41-ea77-11e1-aff1-0800200c9a66",
       "type": "textsingle",
       "responses": {
         "text": "Updated client site"
       }
     },
     [...]
   ]
}

Response

The successful response contains the updated inspection. See the Get Inspection endpoint.

Status code Description
200 OK Change successful
400 Bad Request Invalid request e.g. malformed inspection ID or request payload
403 Forbidden The user does not have permission to view or to edit the inspection with the given inspection ID
404 Not Found The inspection ID specified was not found

See the Errors section for more details.

Clone inspection

curl -X POST "https://api.safetyculture.io/inspections/v1/inspection:CloneInspection" \
  -d '{
        "inspection_id": "f3245d41-ea77-11e1-aff1-0800200c9a66"
      }' \
  -H "Authorization: Bearer {your access token}"

The above command returns JSON structured like this:

{
  "inspection_id": "e31dc526-5304-46f8-985f-e08727f34e4f"
}

This endpoint allows you to clone or copy an inspection. When you clone an inspection, the new inspection’s ID will be returned in the response from the API. Please note that you must provide IDs in the new UUID format for this endpoint.

HTTP request

POST https://api.safetyculture.io/inspections/v1/inspection:CloneInspection

Request body

The body should use the content type application/json with the following required parameters:

Parameter Description
inspection_id The new UUID formatted ID for the inspection being cloned.

Response

The new ID for the inspection is returned.

{
  "inspection_id": "e31dc526-5304-46f8-985f-e08727f34e4f"
}
curl -X POST "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/deep_link" \
  -H "Authorization: Bearer {your access token}"

The above command returns JSON structured like this:

{
  "url": "http://sfty.io/q1Af/PBByr3nTVA"
}

This endpoint generates a URL to the inspection with the supplied inspection ID. The link will open in the iAuditor mobile application if clicked on a mobile device with the iAuditor app installed. Otherwise it will open the inspection in the iAuditor web application.

HTTP request

POST https://api.safetyculture.io/audits/<audit ID>/deep_link

URL parameters

Parameter Description
audit ID The ID of the inspection to generate a link for

Response

The generated URL is returned.

curl -X GET "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/web_report_link" \
  -H "Authorization: Bearer {your access token}"

The above command returns JSON structured like this:

{
  "url": "https://app.safetyculture.com/report/public/audit/9043d5178b80f392d4f968a971fa8ae0cd715aee7ec2a132d9684aab7c5de0df"
}

This endpoint returns the URL to the web report of the inspection with the supplied inspection ID. The link will be valid until explicitly de-activated.

HTTP request

GET https://api.safetyculture.io/audits/<audit ID>/web_report_link

URL parameters

Parameter Description
audit ID The ID of the inspection to return the web report link for

Response

The response will have the content type application/json with the web report URL or an error.

Status code Description
200 OK Link retrieval succeeded
400 Bad Request Invalid request e.g. malformed inspection ID
403 Forbidden The user does not have permission to access the inspection with inspection ID
404 Not Found The inspection ID specified was not found

See the Errors section for more details.

curl -X DELETE "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/web_report_link" \
  -H "Authorization: Bearer {your access token}"

The above command returns a response with no content on successful completion.

This endpoint de-activates the URL to the web report of the inspection with the supplied inspection ID. After de-activation, users will see a ‘Not Found’ error when visiting the link.

HTTP request

DELETE https://api.safetyculture.io/audits/<audit ID>/web_report_link

URL parameters

Parameter Description
audit ID The ID of the inspection to return the web report link for

Response

The response will have the content type application/json with an empty body on success, otherwise an error.

Status code Description
200 OK Link de-activation succeeded
400 Bad Request Invalid request e.g. malformed inspection ID
403 Forbidden The user does not have permission to access the inspection with inspection ID
404 Not Found The inspection ID specified was not found
410 Gone Link has been already de-activated

See the Errors section for more details.

Start inspection

curl -X POST "https://api.safetyculture.io/audits" \
  -d '{"template_id": "template_BB29F82814B64F559A33BF7CAA519787"}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {your access token}"

The above command returns JSON structured like this (some fields omitted for brevity)

{
  "template_id": "template_BB29F82814B64F559A33BF7CAA519787",
  "audit_id": "audit_01ca38a821504cda885736cccbb9ba40",
  "created_at": "2016-12-09T01:13:20.584Z",
  "modified_at": "2015-12-09T01:13:20.584Z",
  "audit_data": {...},
  "template_data": {...},
  "header_items": [...],
  "items": [...]
}

Example request to start an inspection with a pre-filled Conducted on header item

curl -X POST "https://api.safetyculture.io/audits" \
  -d '{
        "template_id": "template_b043f583f34642f4b446f46eeb5405dd",
        "header_items": [
          {
            "item_id": "f3245d42-ea77-11e1-aff1-0800200c9a66",
            "label": "Conducted on",
            "type": "datetime",
            "responses": {
              "datetime": "2016-12-10T09:08:55+00:00"
            }
          }
        ]
      }' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {your access token}"

Example request to start an inspection with a pre-filled Client Site header item

curl -X POST "https://api.safetyculture.io/audits" \
  -d '{
         "template_id": "template_BB29F82814B64F559A33BF7CAA519787",
         "header_items": [
           {
             "item_id": "f3245d41-ea77-11e1-aff1-0800200c9a66",
             "label": "Client Site",
             "type": "textsingle",
             "responses": {
               "text": "<Enter custom client site name here>"
             }
           }
         ]
       }' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {your access token}"

Example request to start an inspection with a question item with a pre-filled response-set response

 curl -X POST "https://api.safetyculture.io/audits" \
   -d '{
          "template_id": "template_BB29F82814B64F559A33BF7CAA519787",
          "items": [
            {
              "item_id": "bd6c6ffd-a45a-4d57-b3ba-c2cb8766269a",
              "label": "What was the device type?",
              "type": "question",
              "responses": {
                "selected": [
                  {
                    "id": "8bcfbf01-e11b-11e1-9b23-0800200c9a66"
                  }
                ]
              }
            }
          ]
        }' \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer {your access token}"

This endpoint creates a new inspection from a specified template ID. Each successful request returns the full inspection body.

HTTP request

POST https://api.safetyculture.io/audits

Start an inspection from template

To simply create an inspection without pre-filling any responses send only the template_id in the request body as shown in the examples of this section.

Start an inspection with pre-filled responses

The type of inspection items that can be pre-filled at inspection creation time at present are: text, textsingle, address, datetime, question, list, checkbox, slider and switch.

Pre-fill responses by copying an existing inspection

The easiest way to construct pre-filled item responses is by retrieving the information of an existing inspection which has populated responses for the items to be pre-filled, copying the item(s) of interest and modifying their responses as desired before executing the start inspection request. See Get Inspection for how to retrieve inspection information. Tip: It is often enough to copy the entire inspection information returned this way into the start inspection request body as any unsupported JSON properties will be ignored. In some cases, however, you may need to remove the responses property from datetime items where the responses.datetime property is null.

Pre-fill by adding item responses one by one

To pre-fill inspection responses one by one, add one or more items to the header_items and/or items array. The JSON content of the pre-filled items should be as described in Inspection Format but only the item_id, type, label and responses fields are required to be present for pre-fill to work. Any additional properties of the items present in the request will be ignored.

For example, to start an inspection with a pre-filled Conducted on header item only, add the item to the header_items array, set its responses property to the desired value (an ISO8601 timestamp) and ensure its item_id matches the corresponding item on the template. An example request body for this is included in the examples of this section.

More items can be added the same way to the header_items and/or items array property of the start inspection request.

The format of the pre-filled response of each item must be valid for the type of the particular item e.g. a single line of text should be provided for items of textsingle type (otherwise newlines will be converted to spaces), a valid ISO8601 timestamp should be given for items of datetime type etc.

Tips

Pre-fill multiple-choice item responses

Multi-choice (question or list) item responses can be of different types. Only text and response-set responses are supported at this stage. See Template Data for more on response-set responses.

To add a text-type response simply populate the responses.text property of the item with the desired response text.

To add one or more response-set responses you will need to provide the ID of each response-set response. An example of this is included in the request examples of this section. You can discover the ID of available responses-set responses by retrieving an existing inspection created against the same template and copying the id of the desired response-set response from the available response sets in the Template Data. The safest way to ensure the right response IDs are added to the request, prefer to pre-fill responses by copying an existing inspection that you know has the desired responses filled in as appropriate.

Notes on inspection creation

The created_at, modified_at, audit_data.date_started, and audit_data.date_modified properties of each new inspection are set and managed by SafetyCulture. The Conducted on header item can be pre-filled by providing a UTC ISO8601 timestamp for it in the start inspection request body as shown in the examples of this section or changed later via editing the inspection. Please note that it’s up to the caller of the API to convert timestamp responses to UTC before making the request.

The owner and author of the created inspection will be the user who is making the API request. Note: the author will change automatically the next time the inspection is edited and saved by another user.

Limits apply to the size of pre-fill responses provided with the request. For instance, text responses cannot be more than 3000 characters long.

Malformed responses will typically cause the request to fail with a relevant error message. In some cases, however, malformed responses such as when the type property of the item is missing from the request body may simply cause the pre-fill responses to be ignored. Check the information of the created inspection in the response to ensure all responses have been successfully pre-filled.

Response

The response will have the content type application/json and include the information of the newly created inspection or an error.

Status code Description
201 Created The information of the new inspection (see the Inspection Format section for details)
400 Bad Request Invalid request e.g. malformed pre-fill item responses
404 Not Found The template ID specified was not found

See the Errors section for more details.

Share inspection

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 {your access token}"

The above command returns JSON structured like this (some fields omitted for brevity)

{
  "template_id": "template_BB29F82814B64F559A33BF7CAA519787",
  "audit_id": "audit_01ca38a821504cda885736cccbb9ba40",
  "created_at": "2016-12-09T01:13:20.584Z",
  "modified_at": "2015-12-09T01:13:20.584Z",
  "audit_data": {...},
  "template_data": {...},
  "header_items": [...],
  "items": [...]
}

Example request to share an inspection with multiple users and groups

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

This endpoint allows you to share an inspection with one or more users and/or groups. To find the IDs of users and groups that the authenticated user can share inspections with see Search Users and Get Groups.

You can only share inspections for which you have edit or delete permission.

You can only share with users and groups that are:

If the inspection is already shared with a particular user or group ID no change to the permissions of that ID will be made using this endpoint. The same applies for the owner of the inspection i.e. they cannot modify their permissions using this endpoint.

The capability to modify or remove existing shares via the API is on our roadmap.

HTTP request

POST https://api.safetyculture.io/audits/<audit ID>/share

URL parameters

Parameter Description
audit ID The ID of the inspection to share

The maximum number of user and/or role IDs that can be provided with a single request to this endpoint is 100.

Response

The response contains the information of the inspection that was modified. The sharing details are not included for security reasons.

Error Description
403 Forbidden The inspection is not accessible to the user or the user does not have “edit” or “delete” permission to share the specified inspection or at least one of the user or group IDs the user is trying to share the inspection with does not belong to one of the groups of the user who is trying to share.

Other Errors may also be returned.

Get media

curl "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/media/9E3BD015-6275-4668-BAF1-296B2F38444C" \
  -o 9E3BD015-6275-4668-BAF1-296B2F38444C.jpg \
  -H "Authorization: Bearer {your access token}"

The media endpoint allows you retrieve the media items associated with a particular inspection. These can be identified by the href elements in the media items of the inspection data.

The media is downloaded directly, so you should save the output to a file with an appropriate name. For example, you can use the values from the media item in the inspection JSON to construct the filename <media_id>.<file_ext>.

HTTP request

GET https://api.safetyculture.io/audits/<audit ID>/media/<media ID>

URL parameters

Parameter Description
audit ID The ID of the inspection to retrieve
media ID The ID of the media within the inspection to retrieve

Response

The Content-Type will be the MIME type associated with the media, and the body of the response is the media itself.

(New) Initiate inspection report export

The report endpoints allow you to retrieve an inspection report formatted as a PDF or Word (docx) document. This is a multi-request process involving initiation, polling, and retrieving.

curl -X POST "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/report" \
  -d '{
        "format": "PDF",
        "preference_id": "f76030c4-4859-41e4-b7f6-a47b20c5dae3"
      }' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {your access token}"

The above command returns JSON structured like this:

{
  "messageId": "b70f5357-4ba7-45a6-a801-706a0f57f2af"
}

The inspection export endpoint begins the process of generating the requested document.

HTTP request

POST https://api.safetyculture.io/audits/<audit_ID>/report

URL parameters

Parameter Description
audit_ID The ID of the inspection to export

Request body

The body should use the content type application/json with the following parameters:

Parameter Description
format The format of the document to generate. Valid values are PDF, or WORD.
preference_id Optional: The report preference to apply to the document.

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
messageId The ID of this specific export task.

(New) Poll for completion of inspection report export

curl "https://api.safetyculture.io/audits/audit_afdbf0b725b64b71905345bbdc9bfd78/report/f1b9e1b0-8652-454a-96c7-a4c714f8e4f1" \
  -H "Authorization: Bearer {your access token}"

The above command returns JSON structured like this:

{
  "status": "IN_PROGRESS"
}
{
    "url": "https://app.safetyculture.io/report-exports/f1b9e1b0-8652-454a-96c7-a4c714f8e4f1/20-Oct-2019-Inspection-Example.pdf?Expires=1571616427&Signature=l8To7ELdDikbEnzYHFSL8WNgo--XpTb6rzgMD~goLe3573NqLDXQXlNF8fG5cR4~yEOtJm-X1OS6YBOgyuuMzATyWoDjyS9NKGpUJWNCRO7Hn8LJ5o-KoQeqrsS2cShv2FgPHrft0DfLTAqY7D9fvx5l8ECfqV5RwTpN~CLR8ztFtfu4kILx9e4XCfPtFIJXAZJ0tGPIQTwq8i1BhdZbW4OUrpv-K~5so~jBjl3dwpNr5h4D3xJvFUtTqtZ2K1-SLCEwwkzZYExosvRHTQ9XaBF0zjABUuY9u2QVVl3-Vr27u-z0zxGEugc~e76QaAbtgULNmGFakFi2y5UszTWyyA__&Key-Pair-Id=APKAJCCN5EO55J74U7PQ",
    "status": "SUCCESS"
}

Check the status of an report request.

HTTP request

GET https://api.safetyculture.io/audits/<audit_ID>/report/<export_ID>

URL parameters

Parameter Description
<audit_ID> The ID of the inspection to retrieve
<export_ID> The ID of the inspection export

Response

The response will have the content type application/json and include some/one of the following parameters:

Parameter Description
status The status of the export. One of IN_PROGRESS, SUCCESS, or FAILED
error If the export fails, this will be a message such as Execution did not complete, status was: FAILED
url The URL which can be used to retrieve the exported document (only present on success)

In the case of request failure due to incorrect parameters the response may contain the following parameters:

Parameter Description
statusCode 500
error “Internal Server Error”
message “An internal server error occurred”

(New) Get inspection export

curl "https://app.safetyculture.io/report-exports/f1b9e1b0-8652-454a-96c7-a4c714f8e4f1/20-Oct-2019-Inspection-Example.pdf?Expires=1571616427&Signature=l8To7ELdDikbEnzYHFSL8WNgo--XpTb6rzgMD~goLe3573NqLDXQXlNF8fG5cR4~yEOtJm-X1OS6YBOgyuuMzATyWoDjyS9NKGpUJWNCRO7Hn8LJ5o-KoQeqrsS2cShv2FgPHrft0DfLTAqY7D9fvx5l8ECfqV5RwTpN~CLR8ztFtfu4kILx9e4XCfPtFIJXAZJ0tGPIQTwq8i1BhdZbW4OUrpv-K~5so~jBjl3dwpNr5h4D3xJvFUtTqtZ2K1-SLCEwwkzZYExosvRHTQ9XaBF0zjABUuY9u2QVVl3-Vr27u-z0zxGEugc~e76QaAbtgULNmGFakFi2y5UszTWyyA__&Key-Pair-Id=APKAJCCN5EO55J74U7PQ" --output 0-Oct-2019-Inspection-Example.pdf

Once an export check returns a url parameter the completed document can be retrieved.

HTTP request

GET https://app.safetyculture.io/report-exports/<export_ID>/<filename>

URL parameters

Parameter Description
export_ID The ID of the inspection export
filename The name of the document generated by the export process
AUTH_PARAMETERS Paramaters to authorise request against report generation service

Response

The body of the response is the document itself.

(Deprecated) Initiate inspection export

The export endpoints allow you to retrieve an inspection formatted as a PDF or DocX document. This is a multi-request process involving initiation, polling, and retrieving.

curl -X POST "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/export?format=pdf&timezone=Australia/Brisbane" \
  -H "Authorization: Bearer {your access token}"

The above command returns JSON structured like this:

{
  "id": "94a427d1-1bd1-4f76-b3a5-4c5de1c75a3f"
}

The inspection export endpoint begins the process of generating the requested document.

HTTP request

POST https://api.safetyculture.io/audits/<audit ID>/export

URL parameters

Parameter Description
audit ID The ID of the inspection to export

Query parameters

Parameter Description
format The format of the document to generate. Valid values are pdf, or docx.
timezone The Olsen Timezone name of the timezone to localise dates and times to. eg Australia/Brisbane or America/New_York.
export_profile The export profile to apply to the document (currently only supported for PDF).

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
id The ID of this specific export task.

(Deprecated) Poll for completion of inspection export

curl "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/exports/94a427d1-1bd1-4f76-b3a5-4c5de1c75a3f" \
  -H "Authorization: Bearer {your access token}"

The above command returns JSON structured like this:

{
  "status": "IN PROGRESS"
}
{
  "status": "SUCCESS",
  "href": "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/exports/94a427d1-1bd1-4f76-b3a5-4c5de1c75a3f/Daily%20Inspection%20-%20000012%20-%202016.02.04-20.31.47%2B0000.pdf",
  "filename": "Daily Inspection - 000012 - 2016.02.04-20.31.47+0000.pdf"
}

Check the status of an export request.

HTTP request

GET https://api.safetyculture.io/audits/<audit ID>/exports/<export ID>

URL parameters

Parameter Description
audit ID The ID of the inspection to retrieve
export ID The ID of the inspection export

Response

The response will have the content type application/json and include some/one of the following parameters:

Parameter Description
status The status of the export. One of IN PROGRESS, SUCCESS, or FAILED
error If the export fails, this will be a message such as Execution did not complete, status was: FAILED
href The URL which can be used to retrieve the exported document (only present on success)
filename The filename of the exported document which is not URL encoded (only present on success)

In the case of request failure due to incorrect parameters the response may contain the following parameters:

Parameter Description
statusCode 404
error “Not Found”
message “Unable to find the export 1a11fe23-b955-4c66-966c-93d566ffe4b”

(Deprecated) Get inspection export

curl -O -J "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/exports/94a427d1-1bd1-4f76-b3a5-4c5de1c75a3f/Daily%20Inspection%20-%20000012%20-%202016.02.04-20.31.47%2B0000.pdf" \
  -H "Authorization: Bearer {your access token}"

Once an export check returns an href parameter the completed document can be retrieved.

HTTP request

GET https://api.safetyculture.io/audits/<audit ID>/exports/<export ID>/<filename>

URL parameters

Parameter Description
audit ID The ID of the inspection to retrieve
export ID The ID of the inspection export
filename The name of the document generated by the export process

Response

The body of the response is the document itself.

Inspection Format

This section describes the complete inspection response format.

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 organisation using the iAuditor web application.
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

Report Preferences

The iAuditor API provides access to your report preferences to allow identification of your preference IDs. You can search either for all global preferences or for all preferences associated with an individual template.

Search report preferences

curl "https://api.safetyculture.io/preferences/search" \
  -H "Authorization: Bearer {your access token}"

The above command returns JSON structured like this:

{
  "preferences": [
    {
      "id": "da5dceac-188a-4738-9550-a82b8801cef3",
      "label": "Example Preference 01",
      "is_global": true,
      "is_default": false
    },
    {
      "id": "93b6194c-c6b9-464b-a8dc-79fb6b48615c",
      "label": "Example Prefernce 02",
      "is_global": true,
      "is_default": false
    }
  ]
}

Searching for a specific templates preferences

curl "https://api.safetyculture.io/preferences/search?template_id=<template_id>" \
  -H "Authorization: Bearer {your access token}"

HTTP reqeust

GET https://api.safetyculture.io/preferences/search

GET https://api.safetyculture.io/preferences/search?template_id=<template_id>

Query parameters

Parameter Description
template_id ID of the template you want to retrieve preferences from.

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
id The ID GUID for the preference.
label The text label you have assigned the preference.
is_global Boolean. True if it is a global preference.
is_default Boolean. True if this is the default prefernece for the template.

(Deprecated) Export Profiles

(Deprecated) Search export profiles

curl "https://api.safetyculture.io/export_profiles/search?template=template_3E631E46F466411B9C09AD804886A8B4" \
  -H "Authorization: Bearer {your access token}"

The above command returns JSON structured like this:

{
  "export_profiles": [
    {
      "id": "template_3E631E46F466411B9C09AD804886A8B4:E15A6525-EFA5-4835-92F0-D11CA9F364F3",
      "name": "My Export Profile",
      "templates": [
        {
          "id": "template_3E631E46F466411B9C09AD804886A8B4",
          "name": "My Test Template"
        }
      ]
    },
    {
      "id": "template_3E631E46F466411B9C09AD804886A8B4:E50645A1-2851-4E92-B4EA-60C5CE7981BE",
      "name": "Your Export Profile",
      "templates": [
        {
          "id": "template_3E631E46F466411B9C09AD804886A8B4",
          "name": "My Test Template"
        }
      ]
    }
  ]
}

The export profiles search endpoint allows you to retrieve the ID, name, and associated templates of your export profiles. Currently only export profiles which have been added to templates are available. It is possible to filter the results to profiles associated with specific templates.

The ID returned in these results can be used to apply an export profile to PDF exports from the inspection export endpoint.

HTTP request

GET https://api.safetyculture.io/export_profiles/search

Query parameters

Parameter Description
template The template ID(s) to use to filter the export profiles results

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
export_profiles An array of export profile metadata objects

Each profile metadata object will include the following parameters:

Parameter Description
id A unique identifier for the export profile
name The name of the export profile
templates An array of metadata objects for the templates associated with the export profile

Each template metadata object will include the following parameters:

Parameter Description
id The template ID
name The template name

(Deprecated) Get an export profile

curl "https://api.safetyculture.io/export_profiles/template_3E631E46F466411B9C09AD804886A8B4:E15A6525-EFA5-4835-92F0-D11CA9F364F3" \
  -H "Authorization: Bearer {your access token}"

The above command returns JSON structured like this:

{
  "identifier": "F5F52D58-39D8-4F1A-B73E-56332716C366",
  "profile_name": "test",
  "revision_id": "82F5E0F8-7D1A-4027-81B5-BF8739259C9A",
  "timestamp": "2016-03-03T06:14:38.752Z",
...
  "appendix_text": "Appendix",
  "audit_page_address_show_coords": true,
  "audit_page_category_background_colour": "255.0,255.0,255.0",
  "audit_page_category_colour": "0.0,0.0,0.0"
}

Export profiles are currently managed and attached to templates using the iAuditor mobile app.

HTTP request

GET https://api.safetyculture.io/export_profiles/<profile ID>

URL parameters

Parameter Description
profile ID The id returned by the export profiles search endpoint

Response

The response will have the content type application/json and the body will be the JSON formatted export profile.

Templates

The iAuditor API contains a search interface to your template metadata.

Search templates

curl "https://api.safetyculture.io/templates/search?field=template_id&field=modified_at" \
  -H "Authorization: Bearer {your access token}"

The above command returns JSON structured like this:

{
  "count": 2,
  "total": 2,
  "templates": [
    {
      "template_id": "template_093AAED63D0A40CAA287CC9AE1F724B7",
      "modified_at": "2013-03-15T13:16:55.000Z"
    },
    {
      "template_id": "template_7fc988ab936911e29499db43a4fa41d1",
      "modified_at": "2013-03-22T10:57:36.000Z"
    },
  ]
}

The template search endpoint allows you to retrieve the template ID, name, modification date and creation date, of templates that meet a certain criteria. It is possible to request templates modified between given dates, and whether or not to include archived templates.

In the request, you must specify the fields that you want to return. The field template_id is not required, the template ID will be always included in every template result returned in the response. To include other template properties in the response you can optionally add parameters modified_at, created_at and name. Multiple field elements can be provided.

Searching by modification date:

curl "https://api.safetyculture.io/templates/search"\
"?field=template_id&field=modified_at"\
"&modified_after=2015-01-01T00:00:00.000Z" \
  -H "Authorization: Bearer {your access token}"

curl "https://api.safetyculture.io/templates/search"\
"?field=template_id&field=modified_at"\
"&modified_after=2015-01-01T00:00:00.000Z"\
"&modified_before=2015-04-01T00:00:00.000Z" \
  -H "Authorization: Bearer {your access token}"

To modify the order in which templates are returned, an optional parameter order can be given. order defaults to asc meaning templates are given from oldest to most recently modified, but can also be set to desc.

To search between dates, use the modified_before and modified_after parameters. This will find templates between the dates given.

The dates should be formatted according to ISO 8601 and include the date, time and timezone. For example, 2015-04-01T00:00:00.000Z or 2015-04-01T00:00+1000.

The modification dates used for searching are related to SafetyCulture’s cloud storage and include latest sync times, modifications through the iAuditor website, and other system modifications. This means that the date may not match the last date that the template was modified. This will ensure that you may consistently find all of the templates modified since your last search, even if they are synced some time after they are last changed.

Searching by ownership:

curl "https://api.safetyculture.io/templates/search?field=template_id&owner=me" \
  -H "Authorization: Bearer {your access token}"

curl "https://api.safetyculture.io/templates/search?field=template_id&owner=other" \
  -H "Authorization: Bearer {your access token}"

Including archived templates:

curl "https://api.safetyculture.io/templates/search?field=template_id&archived=both" \
  -H "Authorization: Bearer {your access token}"

By default, archived templates are not included in the search. The archived parameter allows you to decide whether to search only archived templates (true), not search archived templates (false), or search all templates including those archived (both).

The number of results returned defaults to 1000 at a time, which is the maximum allowed. It is possible to customise the limit parameter to retrieve fewer templates in each request. The limit is a maximum, and fewer templates may be returned than the limit, even if there are more available within the search parameters. This can occur if two or more templates have the same modified_at across the limit boundary, in which case no templates with that timestamp are returned, allowing you to correctly retrieve the next “page” using the modified_after parameter.

The templates are returned in ascending order from the earliest first, up to the limit specified. More templates can be retrieved by repeating the search, using the modified_at of the last template as the modified_after parameter to the next request.

HTTP request

GET https://api.safetyculture.io/templates/search

Query parameters

Parameter Description
field Field(s) of the template to retrieve. Valid values are template_id, name, modified_at, and created_at. Multiple field parameters may be specified.
modified_before Only search for templates where modified_at is before the given date. The date should be specified in full form ISO 8601 format, e.g. 2015-04-01T00:00:00.000Z
modified_after Only search for templates where modified_at is after the given date. The date should be specified in full form ISO 8601 format, e.g. 2015-04-01T00:00:00.000Z
owner Only search for templates with the given ownership. Valid values are me (templates owned by the current user), other (templates shared with the current user) or all (both owned by and shared with the current user). The default is all.
archived Whether to search archived templates. Valid values are true (search only archived templates), false (do not search archived templates) or both (search all templates including those archived). The default is false.
limit The maximum number of templates to retrieve. The maximum value is 1000. The default is also 1000.
order The order in which templates are returned. Valid values are asc (earliest to latest) or desc (latest to earliest). The default is asc.

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
templates An array of templates matching the search results. Each template is an object containing the fields specified in the request.
count The number of templates returned by this request.
total The total number of templates that could have been returned by this search if it were unlimited.

Response Sets

A Global Response Set is a collection of responses that’s available to be used in all templates in an organization. Endpoints are provided to manipulate response sets as well as individual responses within them.

Create a Global Response Set

The Create Response Set endpoint allows a user to create a new response set.

curl \
-X POST “ https://api.safetyculture.io/response_sets "\
-H “Authorization: Bearer …” \
-H “Content-Type:application/json” \
-d `{
      "name": "employee",
      "responses": [
        {
          "label": “John Smith",
          "short_label": "John"
        }
      ]
    }`

The above command returns JSON structured like this

{
   "name": "employee",
   "responseset_id": "responseset_7db5002c72754d2a99ac1e4b82f088be",
   "responses": [
     {
       "id": "64285441-782f-4891-b0f7-2beffbdd78bc",
       "label": "John Smith",
       "short_label": "John"
     }
   ],
   "created_at": "2017-07-21T03:35:26.323Z",
   "modified_at": "2017-07-21T03:35:26.323Z"
}

HTTP request

POST https://api.safetyculture.io/response_sets

Request body

The body should use the content type application/json with the following parameters:

Parameter Description
name The name of the response set (with maximum character limit of 1000)
responses The array of responses to initialise the response set with

The responses should have the following properties:

Responses Description
label The text of the response (with maximum character limit of 1000)
short_label Optional Parameter for specifying a short version of the response text (with maximum character limit of 20)

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
responseset_id The ID of the response set
responses Contains the response if passed
modified_at Last modified timestamp of this response set
created_at Creation timestamp of this response set
Status code Description
200 OK Creation successful
400 Bad Request Invalid request e.g. malformed response or the sent payload
403 Forbidden The user does not have permission to create a response set

See the Errors section for more details.

Get a Global Response Set

The Get Response Set endpoint allows a user to retrieve the response set with a particular response set ID.

curl “ https://api.safetyculture.io/response_sets/responseset_7db5002c72754d2a99ac1e4b82f088be" \
-H “Authorization: Bearer …”

The above command returns JSON structured like this

{
   "name": "employee",
   "responseset_id": "responseset_7db5002c72754d2a99ac1e4b82f088be",
   "responses": [
     {
       "id": "64285441-782f-4891-b0f7-2beffbdd78bc",
       "label": "John Smith",
       "short_label": "John"
     }
   ],
   "created_at": "2017-07-21T03:35:26.323Z",
   "modified_at": "2017-07-21T03:35:26.323Z"
}

HTTP request

GET https://api.safetyculture.io/response_sets/<responseset_id>

URL parameters

Parameter Description
responseSet ID The ID of the response set to return

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
responseset_id The ID of the response set
responses Contains array of responses within the response set
modified_at Last modified timestamp of this response set
created_at Creation timestamp of this response set
Status code Description
200 OK Creation successful
400 Bad Request Invalid request e.g. malformed responses or the sent payload
403 Forbidden The user does not have permission to retrieve a response set

See the Errors section for more details.

Search Global Response Sets

The Get Response Sets endpoint allows a user to retrieve all the available response sets for the user’s organisation.

curl “ https://api.safetyculture.io/response_sets " \
-H “Authorization: Bearer …” \
-H "Content-Type:application/json"

The above command returns an array of JSON objects structured like this

[
  {
    "name": "John Smith",
    "responseset_id": "responseset_89c6fcb53531400ba3ec164fac2cf8b2",
    "created_at": "2017-07-15T12:04:18.152Z"
  },
  {
    "name": "Joe Bloggs",
    "responseset_id": "responseset_a0c1548da7db47bcb254a2e7aeab6070",
    "created_at": "2017-07-14T06:54:42.354Z"
  }
]

HTTP request

GET https://api.safetyculture.io/response_sets

Query parameters

Parameter Description
limit Optional parameter for specifying the maximum number of response sets to retrieve. Default is 200 and maximum is 200.

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
name The name of the response set
responseset_id The ID of the response set
created_at Creation timestamp of this response set
Status code Description
200 OK Retrieve successful
400 Bad Request Invalid request
403 Forbidden The user does not have permission to retrieve the response sets
404 Not Found The org ID was not found

See the Errors section for more details.

Update a Global Response Set

The Update Response Set endpoint allows a user to update a response set. If responses are specified in the payload then all the responses will be overwritten by the ones provided.

curl \
-X PUT “ https://api.safetyculture.io/response_sets/responseset_7db5002c72754d2a99ac1e4b82f088be "\
-H “Authorization: Bearer …” \
-H “Content-Type:application/json” \
-d `{
      "name": "employee",
      "responses" : [
        {
          "label": "John Smith",
          "short_label": "John"
        }
      ]
    }`

The above command returns JSON structured like this

{
  "name": "employee",
  "responseset_id": "responseset_7db5002c72754d2a99ac1e4b82f088be",
  "responses": [
    {
      "id": "64285441-782f-4891-b0f7-2beffbdd78bc",
      "label": "John Smith",
      "short_label": "John"
    }
   ],
  "created_at": "2017-07-21T03:35:26.323Z",
  "modified_at": "2017-07-21T03:35:26.323Z"
}

HTTP request

PUT https://api.safetyculture.io/response_sets/<responseset_id>

URL parameters

Parameter Description
responseset_id The ID of the response set to update.

Request body

The body should use the content type application/json with the following parameters:

Parameter Description
name The name of the response set (with maximum character limit of 1000)

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
name The name of the response set
responseset_id The ID of the response set
responses Contains the response of the response set
modified_at Last modified timestamp of this response set
created_at Creation timestamp of this response set
Status code Description
200 OK Update successful
400 Bad Request Invalid request or payload
403 Forbidden The user does not have permission to update a response set
404 Not Found The resonseSet ID specified was not found

See the Errors section for more details.

Delete a Global Response Set

The Delete Response Set endpoint allows a user to delete a response set.

curl \
-X DELETE “ https://api.safetyculture.io/response_sets/responseset_7db5002c72754d2a99ac1e4b82f088be " \
-H “Authorization: Bearer …” \
-H “Content-Type:application/json”

The above command returns JSON structured like this

{
  "ok": true
}

HTTP request

DELETE https://api.safetyculture.io/response_sets/<responseset_id>

URL parameters

Parameter Description
responseset_id The ID of the response set to delete

Response

The successful response for this request will be {“ok”: true}

Status code Description
200 OK Deletion successful
400 Bad Request Invalid request
403 Forbidden The user does not have permission to delete the response set
404 Not Found The responseSet ID specified was not found

See the Errors section for more details.

Add a response

The Add Response endpoint allows a user to add a new response to the response set. When you add a response to a response set it gets added at the bottom of the existing responses.

curl \
-X POST “ https://api.safetyculture.io/response_sets/responseset_7db5002c72754d2a99ac1e4b82f088be/responses "\
-H “Authorization: Bearer …” \
-H “Content-Type:application/json” \
-d `{
      "label": “New label”,
      "short_label": "New"
    }`

The above command returns JSON structured like this

{
  "id": "64285441-782f-4891-b0f7-2beffbdd78bc",
  "label": "New label",
  "short_label": "New"
}

HTTP request

POST https://api.safetyculture.io/response_sets/<responseset_id>/responses

URL parameters

Parameter Description
responseset_id The ID of the response set to which the response will be added

Request body

The body should use the content type application/json with the following parameters:

Parameter Description
label The text of the response (with maximum character limit of 1000)
short_label Optional Parameter for specifying a short version of the response text (with maximum character limit of 20)

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
id The ID of the response
label The text of the response (with maximum character limit of 1000)
short_label Optional Parameter for specifying a short version of the response text (with maximum character limit of 20)
Status code Description
200 OK Creation successful
400 Bad Request Invalid request e.g. malformed response payload
403 Forbidden The user does not have permission to create a response

See the Errors section for more details.

Update a response

The Update Response endpoint allows a user to update a response within a response set.

curl \
-X PUT “ https://api.safetyculture.io/response_sets/responseset_7db5002c72754d2a99ac1e4b82f088be/responses/64285441-782f-4891-b0f7-2beffbdd78bc "\
-H “Authorization: Bearer …” \
-H “Content-Type:application/json” \
-d `{
      "label": “New label”,
      "short_label": "New"
    }`

The above command returns JSON structured like this

{
  "id": "64285441-782f-4891-b0f7-2beffbdd78bc",
  "label": "New label",
  "short_label": "New"
}

HTTP request

PUT https://api.safetyculture.io/response_sets/<responseset_id>/responses/<response_id>

URL parameters

Parameter Description
responseset_id The ID of the response set which contains the response to be updated
response_id The ID of the response to update

Request body

The body should use the content type application/json with the following parameters:

Parameter Description
label The text of the response (with maximum character limit of 1000)
short_label Optional Parameter for specifying a short version of the response text (with maximum character limit of 20)

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
id The ID of the response
label The text of the response (with maximum character limit of 1000)
short_label Optional Parameter for specifying a short version of the response text (with maximum character limit of 20)
Status code Description
200 OK Update successful
400 Bad Request Invalid request e.g. malformed response payload
403 Forbidden The user does not have permission to update a response

See the Errors section for more details.

Delete a response

The Delete Response endpoint allows a user to delete a response from a response set.

curl \
-X DELETE “ https://api.safetyculture.io/response_sets/responseset_7db5002c72754d2a99ac1e4b82f088be/responses/64285441-782f-4891-b0f7-2beffbdd78bc "\
-H “Authorization: Bearer …” \
-H “Content-Type:application/json”

The above command returns JSON structured like this

{
  "ok": true
}

HTTP request

DELETE https://api.safetyculture.io/response_sets/<responseset_id>/responses/<response_id>/

URL parameters

Parameter Description
responseset_id The ID of the response set which contains the response to be updated
response_id The ID of the response to update

Response

Status code Description
200 OK Deletion successful
400 Bad Request Invalid request
403 Forbidden The user does not have permission to delete the response
404 Not Found The responseSet ID or the response ID specified was not found

See the Errors section for more details.

Actions

The iAuditor API gives you direct access to your Actions data. There are methods to search and retrieve actions.

Listing actions

Listing actions

curl -X POST "https://api.safetyculture.io/tasks/v2/actions:GetActions" \
-H "Authorization: Bearer {api_token}"

The action list endpoint allow you to retrieve all the actions that meet a certain criteria. It is possible to filter actions based on the time of the last modification (modified_at). The presence of next_page_token indicates that there are more results for this search. It is possible to provide the number of actions that will be returned using the optional parameter page_size. It accepts non-negative numbers with a default and maximum value of 100.

To modify the order in which the actions are returned, an optional param sorting can be provided. sorting defaults to desc, meaning that actions are given from latest to earliest, but can also be set to desc.

Searching for the 10 first actions

curl -X POST "https://api.safetyculture.io/tasks/v2/actions:GetActions" \
-H "Authorization: Bearer {api_token}" \
-d '{
      "page_size": 10
    }'

Searching for the next 10 actions (from 11 to 20)

curl -X POST "https://api.safetyculture.io/tasks/v2/actions:GetActions" \
-H "Authorization: Bearer {api_token}" \
-d '{
      "page_size": 10,
      "page_token": "NmM5Yjg5YzEtMjkxMC00NDAwLTg2OWMtMjgyM2FlYmUxMjVm"
    }'

Searching by modification date:

curl -X POST "https://api.safetyculture.io/tasks/v2/actions:GetActions" \
-H "Authorization: Bearer {api_token}" \
-d '{
      "filters": [
          {
              "modified_at": {
                  "from": {
                      "value": "2021-08-11T07:00:25.464490Z"
                  },
                  "to": {
                      "value": "2021-08-11T07:34:23.828360Z"
                  }
              }
          }
      ] 
    }'

HTTP Request

POST https://api.safetyculture.io/tasks/v2/actions:GetActions

Query Parameters

Parameter Type Description
page_size Integer (Optional) The number of actions which will be returned by the API (default = 100, maximum = 100)
page_token String (Optional) If present, gets the next batch of results from the preceding call. This should be the next_page_token of the previous response
filters Array (Optional) List of filters for listing actions
sorting Object (Optional) The sorting options for listing actions. The default is modified_at desc

Response

Key Type Description
actions Array List of actions.
next_page_token String If contains value, it indicates that there are more results than listed. Should be used as page_token for additional results

List actions sorting

It is possible to configure the sorting parameter for the action listing. Currently, the API only accepts sorting by last modification date.

Parameter Type Description
field String Represents the field which the listing will be sorted
direction String Represents the direction which the listing will be sorted

List actions sorting fields

Value Description
FIELD_MODIFIED_AT Indicates that the actions list will be sorted by the modified_at field

List actions sorting direction

Value Description
DIRECTION_ASC Indicates that the actions list will be sorted ascending
DIRECTION_DESC Indicates that the actions list will be sorted descending

List actions filters

It is possible to configure filters for the action listing. Currently, the API only accepts filtering by last modification date.

Parameter Type Description
modified_at Object Object that represents the Modified at filter
modified_at.from.value String ISO date and time that represents the initial value of the filter
modified_at.to.value String ISO date and time that represents the final value of the filter

Get action

Retrieving an action

curl "https://api.safetyculture.io/tasks/v2/actions:GetAction?id={action id}" \
-H "Authorization: Bearer {api_token}"

The GetAction endpoint allows you to retrieve an action given the id. The response will be in the action format structure.

HTTP Request

GET https://api.safetyculture.io/tasks/v2/actions:GetAction

Url Parameters

Parameter Description
id The ID of the action to be retrieved

Action Format

This section describes the complete action response format.

Action top level

{
  "action": {
    "action_id": "74b9212b-b5c1-4b79-b1a4-470455e4eb46",
    "creator": {},
    "title": "Replace the Kettle",
    "description": "Broken kettle on 6th floor",
    "created_at": "2021-08-11T01:40:15Z",
    "modified_at": "2021-08-11T01:41:01.772627Z",
    "completed_at": null,
    "due_at": "2021-08-18T01:40:15Z",
    "priority_id": "16ba4717-adc9-4d48-bf7c-044cfe0d2727",
    "status_id": "20ce0cb1-387a-47d4-8c34-bc6fd3be0e27",
    "site": {},
    "collaborators": [],
    "reference": {}
  }
}
Key Type Description
action_id String The action ID
creator Object Information about the action creator
title String The title of the action
description String The description of the action
created_at String ISO date and time when the action was created
modified_at String ISO date and time when the action was last modified
completed_at String ISO date and time when the action was completed
due_at String ISO date and time when the action is due
priority_id String ID of the action priority
status_id String ID of the action status
site Object General information of the site where the action was created
collaborators Array List of Collaborators of the action
reference Object Information about where the action was created. Only available when the action was created from an Inspection or a Sensor Alert

Creator

.creator contains the information about the creator of the action.

{
  "creator": {
    "id": "31d302e2-6f49-435f-944e-be8276f284b6",
    "firstname": "SafetyCulture",
    "lastname": "User"
  }
}
Key Type Description
id String 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

Action site

.site contains the information about the site which the action belongs to.

{
  "site": {
    "id": "704d6061-0383-4e2c-a8dc-a1804712677a",
    "name": "Bilpin",
    "ascending_folders": [
      "NSW",
      "Australia"
    ]
  }
}
Key Type Description
id String ID of the site
name String Name of the site
ascending_folders Array(String) Hierarchy of the sites (Region and Area)

Priority

.priority_id contains the id of the priority of an action.

The current accepted priorities are:

ID Value
58941717-817f-4c7c-a6f6-5cd05e2bbfde None
16ba4717-adc9-4d48-bf7c-044cfe0d2727 Low
ce87c58a-eeb2-4fde-9dc4-c6e85f1f4055 Medium
02eb40c1-4f46-40c5-be16-d32941c96ec9 High

Status

.status_id contains the id of the status of an action.

The current accepted statuses are:

ID Value Action is completed?
17e793a1-26a3-4ecd-99ca-f38ecc6eaa2e To do No
20ce0cb1-387a-47d4-8c34-bc6fd3be0e27 In progress No
7223d809-553e-4714-a038-62dc98f3fbf3 Complete Yes
06308884-41c2-4ee0-9da7-5676647d3d75 Can’t do Yes

Collaborators

.collaborators contains the information about the collaborators of the action. It can contains multiple users, groups or external users.

{
    "collaborators": [
      {
        "assigned_role": "COLLABORATOR_ROLE_ASSIGNEE",
        "collaborator_type": "COLLABORATOR_TYPE_USER",
        "user": {}
      },
      {
        "assigned_role": "COLLABORATOR_ROLE_ASSIGNEE",
        "collaborator_type": "COLLABORATOR_TYPE_GROUP",
        "group": {}
      },
      {
        "assigned_role": "COLLABORATOR_ROLE_ASSIGNEE",
        "collaborator_type": "COLLABORATOR_TYPE_EXTERNAL_USER",
        "external_user": {}
      }
    ]
}

Colaborator data

Key Type Description
assigned_role String The role of collaborator of the action.
collaborator_type String The type of collaborator of the action.
user Object Information about the user. Only available when the collaborator_type is COLLABORATOR_TYPE_USER
group Object Information about the group. Only available when the collaborator_type is COLLABORATOR_TYPE_GROUP
external_user Object Information about the external user. Only available when the collaborator_type is COLLABORATOR_TYPE_EXTERNAL_USER

Collaborator Role

The current role of an action collaborator.

Key Description
COLLABORATOR_ROLE_ASSIGNEE The collaborator is an assignee of the action.
COLLABORATOR_ROLE_CREATOR The collaborator is the creator of the action.

Collaborator Type

The type of the collaborator.

Key Description
COLLABORATOR_TYPE_USER The collaborator is a specific user.
COLLABORATOR_TYPE_GROUP The collaborator is a group. This means that every user that belongs to that group is also a collaborator.
COLLABORATOR_TYPE_EXTERNAL_USER The collaborator is not an iAuditor user.

User

.collaborators[].user contains the information about a specific user.

{
  "user": {
    "id": "31d302e2-6f49-435f-944e-be8276f284b6",
    "firstname": "SafetyCulture",
    "lastname": "User"
  }
}
Key Type Description
id String ID of the user
firstname String First name of the user
lastname String Last name of the user

Group

.collaborators[].group contains the information about a group.

{
  "group": {
    "id": "aec129f7-e22c-43ab-90c1-8d0577d4135b",
    "name": "SafetyCulture Employees"
  }
}
Key Type Description
id String ID of the group
name String Name of the group

External User

.collaborators[].external_user contains the information about an external user (an user who do not belong to the organisation).

{
  "external_user": {
    "id": "6750f7c9-963b-46ba-842b-39d4f000b443",
    "email": "external_collaborator@safetyculture.io"
  }
}
Key Type Description
id String ID of the external user
email String Email of the external user

Reference

.reference contains information about the entity that originated the action. Not available for standalone actions.

"reference": {
  "type": "REFERENCE_TYPE_INSPECTION",
  "id": "51d4482f-f78b-5a30-9618-2217025f55cc",
  "inspection_context": {},
  "sensor_alert_context": {}
}
Key Type Description
type String Type of the reference.
id String ID of the referenced entity.
inspection_context Object Information about the Inspection that originated the action. Only available when the action was created from an Inspection.
sensor_alert_context Object Information about the Sensor Alert that originated the action. Only available when the action was created from a Sensor Alert.

Reference Type

.reference.type contains the type of the entity that originated the action.

Type Description
REFERENCE_TYPE_INSPECTION Indicates that the action was created from an inspection or inspection item. When the reference is from this type, the reference.id will be the ID of the Inspection
REFERENCE_TYPE_SENSOR_ALERT Indicates that the action was created from a sensor alert. When the reference is from this type, the reference.id will be the ID of the Sensor Alert

Inspection Context

.reference.inspection_context contains the information of the inspection and inspection item that originated the action.

{
  "inspection_context": {
    "template_id": "fd70316e-9ec8-495a-830f-2f63ae5a948b",
    "inspection_id": "effa93bb-8cfb-4783-af5d-c507340dc6e0",
    "inspection_name": "11 Aug 2021 / Checklist",
    "inspection_item_id": "67034555-c11e-4411-bf75-140866c555be",
    "inspection_item_name": "Question Name",
  }
}
Key Type Description
template_id String ID of the inspection template (UUID)
inspection_id String ID of the inspection (UUID)
inspection_name String Name of the inspection
inspection_item_id String ID of the inspection item (UUID)
inspection_item_name String Name of the inspection item

Sensor Alert Context

.reference.sensor_alert_context contains the information of the sensor alert that originated the action.

{
  "sensor_alert_context": {
    "sensor_alert_id": "51d4482f-f78b-5a30-9618-2217025f55cc",
    "level": "ALERT_EVENT_LEVEL_UNSPECIFIED",
    "created_at": "2021-08-11T01:40:15Z",
    "detected_at": "2021-08-11T01:40:15Z",
    "sensor_id": "37d697bf-e20c-43aa-a010-6f560aecc39c",
    "site_name": "",
    "metric_type": "METRIC_TYPE_UNSPECIFIED",
    "sensor_name": ""
  }
}
Key Type Description
sensor_alert_id String ID of the sensor alert
level String Level of importance of the sensor alert
created_at String ISO date and time when the alert was created
detected_at String ISO date and time when the alert was detected
sensor_id String ID of the sensor where the alert was created
site_name String Name of the site where the alert was created
metric_type String Type of the alert metric
sensor_name String Name of the sensor where the alert was created

Sensor Alert Event Level

.reference.sensor_alert_context.level represents the level of importance of the sensor alert

Level Description
ALERT_EVENT_LEVEL_OK Indicates that the device metric becomes healthy
ALERT_EVENT_LEVEL_INFO Indicates that the first alert was sent
ALERT_EVENT_LEVEL_WARN Indicates that the second alert was sent
ALERT_EVENT_LEVEL_CRITICAL Indicates that the third alert was sent

Sensor Alert Metric Type

.reference.sensor_alert_context.metric_type represents the type of received metric

Type Description
METRIC_TYPE_TEMPERATURE Temperature metric
METRIC_TYPE_HUMIDITY Humidity metric
METRIC_TYPE_BATTERY Battery level. Percentage based i.e. 0 - 100
METRIC_TYPE_SIGNAL Signal strenght metric.
METRIC_TYPE_AIR_QUALITY_PM25 Air quality for particulate matter less than 2.5 microns
METRIC_TYPE_AIR_QUALITY_PM10 Air quality for particulate matter less than 10 microns
METRIC_TYPE_TEMPERATURE_2 Alternative temperature for hardwares that sends 2 temperatures
METRIC_TYPE_DIFFERENTIAL_AIR_PRESSURE Differential air pressure
METRIC_TYPE_CO Carbon monoxyde
METRIC_TYPE_DOOR_OPEN_CLOSED Door open/closed (boolean metric)
METRIC_TYPE_BATTERY_VOLTAGE Battery voltage metric

Folders (Sites)

The iAuditor API gives you access to list, search, create, update, and delete folders.

All write paths require site management permissions.

Create folder

Create a folder

curl -X POST "https://api.safetyculture.io/directory/v1/folder" \
-H "Authorization: Bearer {api_token}" \
-d '{
    "name": "Sydney",
    "meta_label": "area"
}'

Example response

{
  "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2f",
  "name": "Sydney",
  "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
  "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
  "created_at": "2020-04-28T04:14:31:00Z",
  "modified_at": "2020-04-28T04:14:31:00Z",
  "meta_label": "area"
}

Create a folder with a parent

curl -X POST "https://api.safetyculture.io/directory/v1/folder" \
-H "Authorization: Bearer {api_token}" \
-d '{
    "name": "Lacey St",
    "parent_id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2d",
    "meta_label": "location"
}'

Example response

{
  "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2f",
  "name": "Lacey St",
  "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
  "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
  "created_at": "2020-04-28T04:14:31:00Z",
  "modified_at": "2020-04-28T04:14:31:00Z",
  "meta_label": "location"
}

Create a folder with a specified id

curl -X POST "https://api.safetyculture.io/directory/v1/folder" \
-H "Authorization: Bearer {api_token}" \
-d '{
    "id": "8fb56fa8-fa23-4ahg-907e-8367abc75adf",
    "name": "Australia",
    "meta_label": "region"
}'

Example response

{
  "id": "8fb56fa8-fa23-4ahg-907e-8367abc75adf",
  "name": "Australia",
  "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
  "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
  "created_at": "2020-04-28T04:14:31:00Z",
  "modified_at": "2020-04-28T04:14:31:00Z",
  "meta_label": "region"
}

The create folder endpoint allows you to create a folder.

HTTP Request

POST https://api.safetyculture.io/directory/v1/folder

Request body

The body should use the content type application/json.

Parameter Type Description
name String The name of the folder. Limited to maximum 250 characters.
parent_id String (Optional) Parent folder UUID. If unspecified, the folder will be created as a top level folder.
id String (Optional) Custom folder UUID. If unspecified, The ID will be generated.
meta_label String (Optional) The label of the folder (location, area, or region).

Response

Key Type Description
folder Object A folder object.

Get folder

Get folder

curl -X GET "https://api.safetyculture.io/directory/v1/folder/4fb56fa8-fa23-4a9c-907e-8367abc75a2f" \
-H "Authorization: Bearer {api_token}" \

Example response

{
  "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2f",
  "name": "221 Sturt St",
  "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
  "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
  "created_at": "2020-04-28T04:14:31:00Z",
  "modified_at": "2020-04-28T04:14:31:00Z",
  "meta_label": "region"
}

The get folder endpoint allows you to get a folder by ID.

HTTP Request

GET https://api.safetyculture.io/directory/v1/folder/{folder_id}

Request body

N/A

Response

Key Type Description
folder Object A folder object.

Update folder item

Update folder item

curl -X PATCH "https://api.safetyculture.io/directory/v1/folder/4fb56fa8-fa23-4a9c-907e-8367abc75a2f" \
-H "Authorization: Bearer {api_token}" \
-d '{
    "name": { "val": "Lacey St" },
}'

Example response

{
  "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2f",
  "name": "Lacey St",
  "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
  "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
  "created_at": "2020-04-28T04:14:31:00Z",
  "modified_at": "2020-04-28T04:14:31:00Z",
  "meta_label": "region"
}

The update folder endpoint allows you to update a folder. Presently, this only supports updating a folders name.

Requires site management permission.

HTTP Request

PATCH https://api.safetyculture.io/directory/v1/folder/{folder_id}

Request body

The body should use the content type application/json.

{
  "name": {
    "val": "new name"
  }
}

Response

Key Type Description
folder Object A folder object

List folder items

List folder items

curl -X GET "https://api.safetyculture.io/directory/v1/folders" \
-H "Authorization: Bearer {api_token}" \

Example response

{
  "folders": [
    {
      "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2f",
      "name": "221 Sturt St",
      "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
      "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
      "created_at": "2020-04-28T04:14:31:00Z",
      "modified_at": "2020-04-28T04:14:31:00Z",
      "meta_label": "location"
    },
    {
      "id": "hgb56fa8-fa23-4a9c-907e-8367abc75sdfg",
      "name": "Townsville",
      "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
      "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
      "created_at": "2020-04-28T04:14:31:00Z",
      "modified_at": "2020-04-28T04:14:31:00Z",
      "meta_label": "area"
    }
  ],
  "folders_with_ancestors": [],
  "next_page_token": "5DeyZ8eKAq"
}

List folder items with ancestors

curl -X GET "https://api.safetyculture.io/directory/v1/folders?with_ancestors=true" \
-H "Authorization: Bearer {api_token}" \

Example response

{
  "folders": [],
  "folders_with_ancestors": [
    {
      "folder": {
        "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2f",
        "name": "221 Sturt St",
        "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
        "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
        "created_at": "2020-04-28T04:14:31:00Z",
        "modified_at": "2020-04-28T04:14:31:00Z",
        "meta_label": "location"
      },
      "ancestors": [
        {
          "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2d",
          "name": "Townsville",
          "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
          "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
          "created_at": "2020-04-28T04:14:31:00Z",
          "modified_at": "2020-04-28T04:14:31:00Z",
          "meta_label": "area"
        },
        {
          "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2c",
          "name": "Queensland",
          "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
          "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
          "created_at": "2020-04-28T04:14:31:00Z",
          "modified_at": "2020-04-28T04:14:31:00Z",
          "meta_label": "region"
        }
      ],
      "members_count": 5
    }
  ],
  "next_page_token": "5DeyZ8eKAq"
}

List the first 100 folder items

curl -X GET "https://api.safetyculture.io/directory/v1/folders?page_size=100" \
-H "Authorization: Bearer {api_token}" \

List the next 100 folder items

curl -X GET "https://api.safetyculture.io/directory/v1/folders?page_size=100&page_token={previous_next_page_token}" \
-H "Authorization: Bearer {api_token}" \

List 100 folder items in descending order

curl -X GET "https://api.safetyculture.io/directory/v1/folders?order_by.sort_order=2" \
-H "Authorization: Bearer {api_token}" \

HTTP Request

GET https://api.safetyculture.io/directory/v1/folders

Query Parameters

Parameter Type Description
page_size Number (Optional) [Default: 500] The number of folders to return (maximum 500)
only_leaf_nodes Boolean (Optional) [Default: false] Whether or not to only return leaf nodes (bottom level folders with no children).
with_ancestors Boolean (Optional) [Default: false] Whether or not to return folders with an array of their parent and ancestor folders.
order_by Object (Optional) An order_by object.
page_token String (Optional) A pagination token to return a subsequent page of results.

Response

Key Type Description
folders Array An array of folder objects (when with_ancestors is false).
folders_with_ancestors Array An array of folder_with_ancestor objects (when with_ancestors is true).
next_page_token String Used as the page_token in the next request to return more results.

Search folder items

When searching folders you have the ability to search for all folders (region,area,location) or just leaf_nodes (locations).

Search folder items

curl -X POST "https://api.safetyculture.io/directory/v1/folders/search" \
-H "Authorization: Bearer {api_token}" \
-d '{
    "query": "221 Sturt St",
    "include_folders_count": true,
}'

Example response

{
  "folders": [
    {
      "folder": {
        "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2f",
        "name": "221 Sturt St",
        "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
        "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
        "created_at": "2020-04-28T04:14:31:00Z",
        "modified_at": "2020-04-28T04:14:31:00Z",
        "meta_label": "location"
      },
      "ancestors": [
        {
          "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2d",
          "name": "Townsville",
          "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
          "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
          "created_at": "2020-04-28T04:14:31:00Z",
          "modified_at": "2020-04-28T04:14:31:00Z",
          "meta_label": "area"
        },
        {
          "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2c",
          "name": "Queensland",
          "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
          "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
          "created_at": "2020-04-28T04:14:31:00Z",
          "modified_at": "2020-04-28T04:14:31:00Z",
          "meta_label": "region"
        }
      ],
      "members_count": 5
    }
  ],
  "folder_count": 1,
  "next_page_token": "5DeyZ8eKAq"
}

Search first 100 folder items

curl -X POST "https://api.safetyculture.io/directory/v1/folders/search" \
-H "Authorization: Bearer {api_token}" \
-d '{
    "query": "221 Sturt St",
    "limit": 100
}'

Search next 100 folder items

curl -X POST "https://api.safetyculture.io/directory/v1/folders/search" \
-H "Authorization: Bearer {api_token}" \
-d '{
    "query": "221 Sturt St",
    "limit": 100,
    "page_token": "57kljdlzvvvsdfgg"
}'

Search for only location folders

curl -X POST "https://api.safetyculture.io/directory/v1/folders/search" \
-H "Authorization: Bearer {api_token}" \
-d '{
    "query": "221 Sturt St",
    "only_leaf_nodes": true
}'

Search folders in desc order

curl -X POST "https://api.safetyculture.io/directory/v1/folders/search" \
-H "Authorization: Bearer {api_token}" \
-d '{
    "query": "221 Sturt St",
    "order_by": { sort_order: 2 }
}'

Search for specific folders

curl -X POST "https://api.safetyculture.io/directory/v1/folders/search" \
-H "Authorization: Bearer {api_token}" \
-d '{
    "query": "221 Sturt St",
    "filters": [
        { "not": false, "folder_id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2d" },
        { "not": false, "folder_id": "3fb56fa8-fa23-4a9c-907e-8367abc75a2f" },
        { "not": false, "folder_id": "2fb56fa8-fa23-4a9c-907e-8367abc75a2c" }]
}'

Search for specific meta_labels and folders

curl -X POST "https://api.safetyculture.io/directory/v1/folders/search" \
-H "Authorization: Bearer {api_token}" \
-d '{
    "query": "221 Sturt St",
    "filters": [
        { "not": false, "meta_label": "location" },
        { "not": false, "folder_id": "3fb56fa8-fa23-4a9c-907e-8367abc75a2f" },
        { "not": false, "folder_id": "2fb56fa8-fa23-4a9c-907e-8367abc75a2c" }]
}'

HTTP Request

POST https://api.safetyculture.io/directory/v1/folders/search

Request Body

The body should use the content type application/json.

Parameter Type Description
query String The search value to query the organisations folders with.
filters Array An array of filter objects.
only_leaf_nodes Boolean (Optional) [Default: false] Whether to search all folders or only locations.
include_members_count Boolean (Optional) [Default: false] Whether to include the count of users directly assigned to each folder.
include_folders_count Boolean (Optional) [Default: false] Whether to return the total count of folders discovered in the query.
limit Number (Optional) [Default: 500] The number of folders to return (maximum 500).
order_by Object (Optional) A order_by object
page_token String (Optional) A pagination token to return a subsequent page of results.

Response

Key Type Description
folders Array An array of folders with ancestor objects.
folder_count Number The total number of folders discovered.
next_page_token String Used as the page_token in the next request to return more results.

Move folder items

Move folders allows you to move an array of folders to another parent. Folder hierarchies have a maximum depth of 3. Attempting to create a hierarchy with a depth higher than 3 will not work. You also cannot create circular relationships (a child of a folder cannot be that folder’s parent).

Requires site management permission.

Move folder item

curl -X POST "https://api.safetyculture.io/directory/v1/folders/move" \
-H "Authorization: Bearer {api_token}" \
-d '{
    "ids": ["dfb56fa8-fa23-4a9c-907e-8367abc75a2g"],
    "parent_id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2d"
}'

Example response

{
  "new_parent_id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2d"
}

Move 10 folder items

curl -X POST "https://api.safetyculture.io/directory/v1/folders/move" \
-H "Authorization: Bearer {api_token}" \
-d '{
    "ids": [
        "dfb56fa8-fa23-4a9c-907e-8367abc75a2g",
        "qfb56fa8-fa23-4a9c-907e-8367abc75a2s",
        "wfb56fa8-fa23-4a9c-907e-8367abc75a2d",
        "rfb56fa8-fa23-4a9c-907e-8367abc75a2f",
        "ufb56fa8-fa23-4a9c-907e-8367abc75a2g",
        "mfb56fa8-fa23-4a9c-907e-8367abc75a2h",
        "nfb56fa8-fa23-4a9c-907e-8367abc75a2j",
        "bfb56fa8-fa23-4a9c-907e-8367abc75a2k",
        "gfb56fa8-fa23-4a9c-907e-8367abc75a2l",
        "ffb56fa8-fa23-4a9c-907e-8367abc75a2e"
    ],
    "parent_id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2d"
}'

Example response

{
  "new_parent_id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2d"
}

HTTP Request

POST https://api.safetyculture.io/directory/v1/folders/move

Request body

The body should use the content type application/json.

Parameter Type Description
parent_id String (Optional) The ID of the new parent. If not specified, folders will be moved into the top level.
ids Array An array of ID’s belonging to folders to move under the new parent_id.

Response

Key Type Description
new_parent_id String The ID of the new parent.

Delete folder items

When deleting folders that have children, those children will also be deleted. Deleting folders will always cascade down the tree and delete children folders. Every folder ID that is returned has been deleted. Deleting folders cannot be undone.

Requires site management permission.

Delete folder items

curl -X DELETE "https://api.safetyculture.io/directory/v1/folders?folder_ids={folder_id_1}" \
-H "Authorization: Bearer {api_token}" \
{
  "folder_ids": ["4fb56fa8-fa23-4a9c-907e-8367abc75a2d"]
}

Delete 2 folder items

curl -X DELETE "https://api.safetyculture.io/directory/v1/folders?folder_ids={folder_id_1}&folder_ids={folder_id_2}" \
-H "Authorization: Bearer {api_token}" \
{
  "folder_ids": [
    "4fb56fa8-fa23-4a9c-907e-8367abc75a2d",
    "2bb56fa8-fa23-4a9c-907e-8367abc75a2e"
  ]
}

HTTP Request

DELETE https://api.safetyculture.io/directory/v1/folders

Query Parameters

Parameter Type Description
folder_ids String Repeated. Each folder ID to be deleted.

Response

Key Type Description
folder_ids Array An array of folder ID’s that were deleted.

Get folder items by parent

Get folder items by parent

curl -X GET "https://api.safetyculture.io/directory/v1/parent/{parent_id}/folders" \
-H "Authorization: Bearer {api_token}" \

Example response

{
  "folders": [
    {
      "folder": {
        "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2f",
        "name": "221 Sturt St",
        "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
        "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
        "created_at": "2020-04-28T04:14:31:00Z",
        "modified_at": "2020-04-28T04:14:31:00Z",
        "meta_label": "location"
      },
      "members_count": 5,
      "has_children": false,
      "inherited_member_count": 10,
      "depth": 3,
      "children_count": 0
    },
    {
      "folder": {
        "id": "bfb56fa8-fa23-4a9c-907e-8367abc75a2c",
        "name": "Townsville",
        "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
        "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
        "created_at": "2020-04-28T04:14:31:00Z",
        "modified_at": "2020-04-28T04:14:31:00Z",
        "meta_label": "area"
      },
      "members_count": 0,
      "has_children": true,
      "inherited_member_count": 0,
      "depth": 2,
      "children_count": 0
    }
  ],
  "next_page_token": ""
}

Get first 10 folder items by parent

curl -X GET "https://api.safetyculture.io/directory/v1/parent/{parent_id}/folders?limit=10" \
-H "Authorization: Bearer {api_token}" \

Get next 10 folder items by parent

curl -X GET "https://api.safetyculture.io/directory/v1/parent/{parent_id}/folders?limit=10&page_token={next_page_token}" \
-H "Authorization: Bearer {api_token}" \

Get folder items by parent including member count

curl -X GET "https://api.safetyculture.io/directory/v1/parent/{parent_id}/folders?include_member_count=true" \
-H "Authorization: Bearer {api_token}" \

HTTP Request

GET https://api.safetyculture.io/directory/v1/parent/{parent_id}/folders

Request body

The body should use the content type application/json.

Parameter Type Description
include_member_count Boolean (Optional) [Default: false] Whether or not to include the number of users assigned to the folder.
limit Number (Optional) [Default: 500] The number of folders to return (maximum 500)
page_token String (Optional) A pagination token to return a subsequent page of results.

Response

Key Type Description
folders Array An array of folder_with_member_count objects.
next_page_token String Used as the page_token in the next request to return more results.

Folder (Sites) users

The iAuditor API provides access to get, create, and delete folder <> user associations.

All write paths require site management permissions.

Add users to folder

Assigns multiple users to a single folder.

Requires site management permission.

Add users to folder

curl -X POST "https://api.safetyculture.io/directory/v1/folder/{folder_id}/users" \
-H "Authorization: Bearer {api_token}" \
-d '{
    "user_ids": [
        "h4b56fa8-fa23-4ahg-907e-8367abc75adc",
        "7nb56fa8-fa23-4ahg-907e-8367abc75adv"]
}'

Example response

{
  "user_status": {
    "jhb56fa8-fa23-4ahg-907e-8367abc75a65": 1,
    "jgb56fa8-fa23-4ahg-907e-8367abc75axe": 1
  }
}

HTTP Request

POST https://api.safetyculture.io/directory/v1/folder/{folder_id}/users

Query Parameters

Parameter Type Description
folder_id String (Required) The UUID of the folder you are assigning users to.

Request Body

The body should use the content type application/json.

Parameter Type Description
user_ids Array (Required) An array of user UUIDs to be assigned to the folder

Response

Key Type Description
user_status Object A map ofuser_id to status. 1 = Added; 2 = Duplicate

Add user to folders

Assign a single user to multiple folders

Requires site management permission.

Add user to folders

curl -X POST "https://api.safetyculture.io/directory/v1/user/{user_id}/folders" \
-H "Authorization: Bearer {api_token}" \
-d '{
    "folder_ids": [
            "jhb56fa8-fa23-4ahg-907e-8367abc75a65",
            "jgb56fa8-fa23-4ahg-907e-8367abc75axe"]
}'

Example response

{
  "folder_status": {
    "jhb56fa8-fa23-4ahg-907e-8367abc75a65": 1,
    "jgb56fa8-fa23-4ahg-907e-8367abc75axe": 1
  }
}

HTTP Request

POST https://api.safetyculture.io/directory/v1/user/{user_id}/folders

Query Parameters

Parameter Type Description
user_id String (Required) The UUID of the user you are assigning folders to.

Request Body

The body should use the content type application/json.

Parameter Type Description
folder_ids Array (Required) An array of folder UUIDs to assign to the user

Response

Key Type Description
folder_status Object A map offolder_id to status. 1 = Added; 2 = Duplicate; 3 = Failed

Remove users from a folder

Remove multiple users from a single folder

Requires site management permission.

Remove a single user from a folder

curl -X DELETE "https://api.safetyculture.io/directory/v1/folder/{folder_id}/users?user_ids={user_id_1}" \
-H "Authorization: Bearer {api_token}" \

Example response

{
  "user_status": {
    "jhb56fa8-fa23-4ahg-907e-8367abc75a65": 1
  }
}

Remove 3 users from a folder

curl -X DELETE "https://api.safetyculture.io/directory/v1/folder/{folder_id}/users?user_ids={user_id_1}&user_ids={user_id_2}&user_ids={user_id_3}" \
-H "Authorization: Bearer {api_token}" \

Example response. One of the users was not assigned to the folder

{
  "user_status": {
    "jhb56fa8-fa23-4ahg-907e-8367abc75a65": 1,
    "jhb56fa8-fa23-4ahg-907e-8367abc75a64": 1,
    "jhb56fa8-fa23-4ahg-907e-8367abc75a63": 2
  }
}

HTTP Request

DELETE https://api.safetyculture.io/directory/v1/folder/{folder_id}/users?user_ids={user_id_1}

Query Parameters

Parameter Type Description
folder_id String (Required) The UUID of the folder you are removing users from
user_ids String (Required, Repeated) The UUID of the user you are removing from the folder

Response

Key Type Description
user_status Object A map ofuser_id to status. 1 = Removed; 2 = Not Found

Remove a user from folders

Removes a single user from multiple folders

Requires site management permission.

Remove a user from a single folder

curl -X DELETE "https://api.safetyculture.io/directory/v1/user/{user_id}/folders?folder_ids={folder_id_1}" \
-H "Authorization: Bearer {api_token}" \

Example response

{
  "folder_status": {
    "jhb56fa8-fa23-4ahg-907e-8367abc75a65": 1
  }
}

Remove a user from 3 folders

curl -X DELETE "https://api.safetyculture.io/directory/v1/user/{user_id}/folders?folder_ids={folder_id_1}&folder_ids={folder_id_2}&folder_ids={folder_id_3}" \
-H "Authorization: Bearer {api_token}" \

Example response (the user was not assigned to one of the folders)

{
  "user_status": {
    "jhb56fa8-fa23-4ahg-907e-8367abc75a65": 1,
    "jhb56fa8-fa23-4ahg-907e-8367abc75a64": 1,
    "jhb56fa8-fa23-4ahg-907e-8367abc75a63": 2
  }
}

HTTP Request

DELETE https://api.safetyculture.io/directory/v1/user/{user_id}/folders?folder_ids={folder_id_1}

Query Parameters

Parameter Type Description
user_id String (Required) The UUID of the user you are removing folders from
folder_ids String (Required, Repeated) The UUID of the folder you are removing the user from

Response

Key Type Description
folder_status Object A map offolder_id to status. 1 = Removed; 2 = Not Found

Get folder users

Get all of the users directly assigned to a folder

Get folder users

curl -X GET "https://api.safetyculture.io/directory/v1/folder/{id}/users/associated" \
-H "Authorization: Bearer {api_token}" \

Example response

{
  "user_ids": [
    "jhb56fa8-fa23-4ahg-907e-8367abc75a65",
    "jhb56fa8-fa23-4ahg-907e-8367abc75a64"
  ]
}

HTTP Request

GET https://api.safetyculture.io/directory/v1/folder/{id}/users/associated

Query Parameters

Parameter Type Description
id String (Required) The UUID of the folder to get assigned users for

Response

Key Type Description
user_ids Array An Array of user UUIDs that are assigned to the folder

Get folder inherited users

Get all of the users that have inherited membership to a folder. Users have inherited membership to a folder when they have direct membership to one of the folders ancestors.

Get folder inherited users

curl -X GET "https://api.safetyculture.io/directory/v1/folder/{id}/users/inherited" \
-H "Authorization: Bearer {api_token}" \

Example response

{
  "user_ids": [
    "jhb56fa8-fa23-4ahg-907e-8367abc75a65",
    "jhb56fa8-fa23-4ahg-907e-8367abc75a64"
  ]
}

HTTP Request

GET https://api.safetyculture.io/directory/v1/folder/{id}/users/inherited

Query Parameters

Parameter Type Description
id String (Required) The UUID of the folder to get inherited users for.

Response

Key Type Description
user_ids Array An Array of user UUIDs that have inherited membership.

Get all folder users. Associated and inherited

Get all of the users that have access to the folder. This includes directly associated members and inherited members. Users have inherited membership to a folder when they have direct membership to one of the folders ancestors.

Get all folder users. Associated and inherited

curl -X GET "https://api.safetyculture.io/directory/v1/folder/{id}/users" \
-H "Authorization: Bearer {api_token}" \

Example response

{
  "user_ids": [
    "jhb56fa8-fa23-4ahg-907e-8367abc75a65",
    "jhb56fa8-fa23-4ahg-907e-8367abc75a64"
  ]
}

HTTP Request

GET https://api.safetyculture.io/directory/v1/folder/{id}/users

Query Parameters

Parameter Type Description
id String (Required) The UUID of the folder to get all users for.

Response

Key Type Description
user_ids Array An Array of user UUIDs that have either direct or inherited membership.

Get users folders

Get user folders will get the folders for each user requested.

Get users folders

curl -X GET "https://api.safetyculture.io/directory/v1/users/folders" \
-H "Authorization: Bearer {api_token}" \

Example response

{
  "user_folders": {
    "jhb56fa8-fa23-4ahg-907e-8367abc75a65": [
      {
        "folder": {
          "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2f",
          "name": "221 Sturt St",
          "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
          "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
          "created_at": "2020-04-28T04:14:31:00Z",
          "modified_at": "2020-04-28T04:14:31:00Z",
          "meta_label": "location"
        },
        "members_count": 5,
        "has_children": false,
        "inherited_member_count": 10,
        "depth": 3,
        "children_count": 0
      },
      {
        "folder": {
          "id": "5fb56fa8-fa23-4a9c-907e-8367abc75a2f",
          "name": "Matt St.",
          "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
          "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
          "created_at": "2020-04-28T04:14:31:00Z",
          "modified_at": "2020-04-28T04:14:31:00Z",
          "meta_label": "location"
        },
        "members_count": 5,
        "has_children": false,
        "inherited_member_count": 10,
        "depth": 3,
        "children_count": 0
      }
    ],
    "jhb56fa8-fa23-4ahg-907e-8367abc75a64": [
      {
        "folder": {
          "id": "5fb56fa8-fa23-4a9c-907e-8367abc75a2f",
          "name": "Matt St.",
          "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
          "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
          "created_at": "2020-04-28T04:14:31:00Z",
          "modified_at": "2020-04-28T04:14:31:00Z",
          "meta_label": "location"
        },
        "members_count": 5,
        "has_children": false,
        "inherited_member_count": 10,
        "depth": 3,
        "children_count": 0
      }
    ]
  }
}

HTTP Request

GET https://api.safetyculture.io/directory/v1/users/folders

Parameters

Parameter Type Description
user_ids Array (Required) An array of user UUIDs.
include_members_count Boolean (Optional) [Default:false] Whether to include the count of users directly assigned to each folder.

Response

Key Type Description
user_folders Object A map object of user UUID, to array of folder objects the user is assigned to.

Folder (Sites) Format

This section describes the complete folder response format.

Folder

{
  "folder": {
    "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2f",
    "name": "221 Sturt st",
    "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
    "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
    "created_at": "2020-04-28T04:14:31:00Z",
    "modified_at": "2020-04-28T04:14:31:00Z",
    "meta_label": "location"
  }
}
Key Type Description
id String The folder ID
name String The name of the folder
org_id String The ID of the creator’s organisation
creator_id String The ID of the creator
created_at String ISO date and time when the folder was created
modified_at String ISO date and time when the folder was last modified
meta_label String The label of the folder

Folder with member count

{
  "folder_with_member_count": {
    "folder": {
      "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2f",
      "name": "221 Sturt st",
      "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
      "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
      "created_at": "2020-04-28T04:14:31:00Z",
      "modified_at": "2020-04-28T04:14:31:00Z",
      "meta_label": "location"
    },
    "members_count": 5,
    "has_children": false,
    "inherited_member_count": 10,
    "depth": 3,
    "children_count": 0
  }
}
Key Type Description
folder Object The folder object
member_count Number The number of users directly assigned to this folder
has_children Boolean Whether or not the folder has any children folders
inherited_member_count Number The number of inherited members (members assigned to parent folders)
depth Number The depth in the hierarchy starting from 1
children_count Number The count of children folders underneath this folder

Folder with ancestors

{
  "folder_with_ancestors": {
    "folder": {
      "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2f",
      "name": "221 Sturt st",
      "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
      "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
      "created_at": "2020-04-28T04:14:31:00Z",
      "modified_at": "2020-04-28T04:14:31:00Z",
      "meta_label": "location"
    },
    "ancestors": [
      {
        "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2d",
        "name": "Townsville",
        "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
        "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
        "created_at": "2020-04-28T04:14:31:00Z",
        "modified_at": "2020-04-28T04:14:31:00Z",
        "meta_label": "area"
      },
      {
        "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2c",
        "name": "Queensland",
        "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
        "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
        "created_at": "2020-04-28T04:14:31:00Z",
        "modified_at": "2020-04-28T04:14:31:00Z",
        "meta_label": "region"
      }
    ],
    "members_count": 5
  }
}
Key Type Description
folder Array The folder object
ancestors Array An array of parent folder objects (ordered from closest relation to furthest)
members_count Number The number of users directly assigned to this folder

Folder with parent

{
  "folder": {
    "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2f",
    "name": "221 Sturt st",
    "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
    "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
    "created_at": "2020-04-28T04:14:31:00Z",
    "modified_at": "2020-04-28T04:14:31:00Z",
    "meta_label": "location"
  },
  "parent_id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2d",
  "depth": 3,
  "member_count": 5
}
Key Type Description
folder Object The folder object
parent_id String The UUID of the parent folder; folders with no parent will use a Nil/Empty UUID
depth Number The depth in the hierarchy starting from 1
members_count Number The number of users directly assigned to this folder

Folder order by

{
  "sort_order": 1
}
Key Type Description
sort_order Number The sort order where 1 is ascending and 2 is decending

Folder filter

Folders can be filtered using an array of meta_label and folder_id filter objects.

Examples can be seen here.

meta_label filter object

{
  "not": false,
  "meta_label": "location"
}
Key Type Description
not Boolean (required) Whether to include or exclude the filter. {"not": false} would mean include.
meta_label String (required) A meta_label to include or exclude from the results; e.g. location

folder_id filter object

{
  "not": false,
  "folder_id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2d"
}
Key Type Description
not Boolean (required) Whether to include or exclude the filter. {"not": false} would mean include.
folder_id String (required) A meta_label to include or exclude from the results; e.g. 4fb56fa8-fa23-4a9c-907e-8367abc75a2d

Schedules

The iAuditor API gives you access to create, update and delete schedule items.

List schedule items

List schedule items

curl -X GET "https://api.safetyculture.io/schedules/v1/schedule_items" \
-H "Authorization: Bearer {api_token}"

The schedule items list endpoint allows you to retrieve all of the schedule items that meet a certain criteria. It is possible to filter schedule items based on their current status. The presence of next_page_token indicates that there are more results for this listing. It is possible to provide the number of schedule items that will be returned using the optional parameter page_size. It accepts non-negative numbers with a default and maximum value of 100.

Listing the first 10 schedule items

curl -X GET "https://api.safetyculture.io/schedules/v1/schedule_items?page_size=10" \
-H "Authorization: Bearer {api_token}"

Listing the next 10 schedule items (from 11 to 20)

curl -X GET "https://api.safetyculture.io/schedules/v1/schedule_items?page_size=10&page_token={previous_next_page_token}" \
-H "Authorization: Bearer {api_token}"

Filtering schedule items by status

curl -X GET "https://api.safetyculture.io/schedules/v1/schedule_items?statuses=ACTIVE&statuses=PAUSED" \
-H "Authorization: Bearer {api_token}"

HTTP Request

GET https://api.safetyculture.io/schedules/v1/schedule_items

Query Parameters

Parameter Type Description
page_size Integer (Optional) The number of schedule items which will be returned by the API (default = 20, maximum = 100)
page_token String (Optional) If present, gets the next batch of results from the preceding call. This should be the next_page_token of the previous response
statuses Array (Optional) List of statuses to filter schedule items by.

Response

Key Type Description
items Array List of schedule items.
next_page_token String If contains value, it indicates that there are more results than listed. Should be used as page_token for additional results

Create schedule item

Create schedule item

curl -X POST "https://api.safetyculture.io/schedules/v1/schedule_items" \
-H "Authorization: Bearer {api_token}" \
-d '{
    "description": "Workplace Reopening Checklist - Every day",
    "must_complete": "ONE",
    "can_late_submit": true,
    "recurrence": "INTERVAL=1;FREQ=DAILY;DTSTART=20210803T090000Z",
    "start_time": {
        "hour": 9,
        "minute": 0
    },
    "duration": "PT8H",
    "timezone": "Pacific/Auckland",
    "from_date": "2021-08-02T21:00:00Z",
    "to_date": null,
    "reminders": [
        {
            "event": "START",
            "duration": "P0D"
        }
    ],
    "assignees": [
        {
            "id": "87894eeb-ee76-4551-b3ab-0c60c675d820",
            "type": "ROLE"
        }
    ],
    "document": {
        "id": "87894eeb-ee76-4551-b3ab-0c60c675d820",
        "type": "TEMPLATE"
    },
    "location_id": null
}'

The create schedule item endpoint allows you to create schedule items.

HTTP Request

POST https://api.safetyculture.io/schedules/v1/schedule_items

Request body

The body should use the content type application/json with Update Schedule Item as the payload.

Response

Key Type Description
id String ID of the newly created schedule item

Update schedule item

Update schedule item

curl -X PUT "https://api.safetyculture.io/schedules/v1/schedule_items/3acf5470-6215-4714-abb2-9b4aa9f45b40" \
-H "Authorization: Bearer {api_token}" \
-d '{
    "description": "Workplace Reopening Checklist - Every day",
    "must_complete": "ONE",
    "can_late_submit": true,
    "recurrence": "INTERVAL=1;FREQ=DAILY;DTSTART=20210803T090000Z",
    "start_time": {
        "hour": 9,
        "minute": 0
    },
    "duration": "PT8H",
    "timezone": "Pacific/Auckland",
    "from_date": "2021-08-02T21:00:00Z",
    "to_date": null,
    "reminders": [
        {
            "event": "START",
            "duration": "P0D"
        }
    ],
    "assignees": [
        {
            "id": "87894eeb-ee76-4551-b3ab-0c60c675d820",
            "type": "ROLE"
        }
    ],
    "document": {
        "id": "87894eeb-ee76-4551-b3ab-0c60c675d820",
        "type": "TEMPLATE"
    },
    "location_id": null
}'

The update schedule item endpoint allows you to update schedule items.

HTTP Request

PUT https://api.safetyculture.io/schedules/v1/schedule_items/{scheduleitem_id}

Request body

The body should use the content type application/json with Update Schedule Item as the payload.

Response

Key Type Description
id String ID of the updated schedule item

Delete schedule item

Delete schedule item

curl -X DELETE "https://api.safetyculture.io/schedules/v1/schedule_items/3acf5470-6215-4714-abb2-9b4aa9f45b40" \
-H "Authorization: Bearer {api_token}"

The delete schedule item endpoint allows you to delete schedule items.

HTTP Request

DELETE https://api.safetyculture.io/schedules/v1/schedule_items/{scheduleitem_id}

Request body

N/A

Response

N/A

Schedule item format

List schedule item format

This section describes the complete schedule item response format.

{
    "id": "87894eeb-ee76-4551-b3ab-0c60c675d820",
    "description": "Workplace Reopening Checklist - Every day",
    "must_complete": "ONE",
    "can_late_submit": true,
    "recurrence": "INTERVAL=1;FREQ=DAILY;DTSTART=20210803T210000Z",
    "start_time": {
        "hour": 9,
        "minute": 0
    },
    "duration": "PT8H",
    "timezone": "Pacific/Auckland",
    "from_date": "2021-08-02T21:00:00Z",
    "to_date": null,
    "reminders": [
        {
            "event": "START",
            "duration": "P0D"
        }
    ],
    "modified_at": "2021-08-10T00:09:50.488Z",
    "created_at": "2021-08-10T00:09:50.488Z",
    "status": "ACTIVE",
    "assignees": [
        {
            "id": "87894eeb-ee76-4551-b3ab-0c60c675d820",
            "type": "ROLE",
            "name": "Joe's Team"
        }
    ],
    "creator": {
        "id": "83224e56-ad58-4e19-b633-fde5271ac8e4",
        "type": "USER",
        "name": "Joe Bloggs"
    },
    "document": {
        "id": "dfa57152-4164-4534-90b4-4992f65630a0",
        "type": "TEMPLATE",
        "name": "Workplace Reopening Checklist"
    },
    "location_id": null,
    "next_occurrence": {
        "start": "2021-08-09T21:00:00Z",
        "due": "2021-08-10T05:00:00Z"
    }
}
Key Type Description
id String The ID of the schedule item.
description String The description of the schedule item.
must_complete String Whom must complete a given schedule, either ONE assignee or ALL assignees.
can_late_submit Boolean Can the inspections be started after the due date.
recurrence String (RRule) RRule formatted recurrence string.
start_time Object The time the schedule item starts on each occurrence e.g. {"hour": 15, "minute": 15} for 3:15 PM.
duration String ISO8601 duration string, e.g. PT1H. How long inspection can be started after the start_date.
timezone String Timezone the schedule item will appear in.
from_date String (ISO8601) The starting datetime of the schedule item.
to_date String (ISO8601) The end datetime of the schedule item.
reminders []Object The reminders that will be sent to assignees.
modified_at String (ISO8601) The datetime when the schedule item was last modified.
created_at String (ISO8601) The datetime when the schedule item was created.
status String The current status of the schedule item.
assignees []Object The assignees of this schedule item.
creator Object The creator of this schedule item.
document Object The document/inspection assigned to this schedule item.
location_id String The location assigned to this schedule item.
next_occurrence Object When this schedule item will next occur.

Update Schedule Item Format

This section describes the complete create/update schedule item format

{
    "id": "87894eeb-ee76-4551-b3ab-0c60c675d820",
    "description": "Workplace Reopening Checklist - Every day",
    "must_complete": "ONE",
    "can_late_submit": true,
    "recurrence": "INTERVAL=1;FREQ=DAILY;DTSTART=20210803T210000Z",
    "start_time": {
        "hour": 9,
        "minute": 0
    },
    "duration": "PT8H",
    "timezone": "Pacific/Auckland",
    "from_date": "2021-08-02T21:00:00Z",
    "to_date": "2022-08-02T21:00:00Z",
    "reminders": [
        {
            "event": "START",
            "duration": "P0D"
        }
    ],
    "assignees": [
        {
            "id": "87894eeb-ee76-4551-b3ab-0c60c675d820",
            "type": "ROLE"
        }
    ],
    "document": {
        "id": "dfa57152-4164-4534-90b4-4992f65630a0",
        "type": "TEMPLATE"
    },
    "location_id": "dfa57152-4164-4534-90b4-4992f65630a0"
}
Key Type Description
description String The description of a schedule item.
must_complete String Whom must complete a given schedule, either ONE assignee or ALL assignees.
can_late_submit Boolean Can the inspections be started after the due date.
recurrence String (RRule) RRule formatted recurrence string.
start_time Object The time the schedule item starts on each occurrence e.g. {"hour": 15, "minute": 15} for 3:15 PM.
duration String (ISO8601) ISO8601 duration string, e.g. PT1H. How long inspection can be started after the start_date.
timezone String Timezone the schedule item will appear in.
from_date String (ISO8601) The starting datetime of the schedule item.
to_date String (ISO8601) The end datetime of the schedule item.
reminders []Object The reminders that will be sent to assignees.
assignees []Object The assignees of this schedule item.
document Object The document/inspection assigned to this schedule item.
location_id String The new UUID formatted ID of the location assigned to this schedule item.

Schedule Item Entity

Contains information that relates to a user, group or organization.

{
  "id": "31d302e2-6f49-435f-944e-be8276f284b6",
  "type": "USER",
  "name": "Joe Bloggs"
}
Key Type Description
id String The new UUID formatted ID of the entity.
type String Type of entity either USER or ROLE (group/organization).
name String Name of the entity.

Schedule Item Document

Contains information that relates to the document a schedule is assigned to.

{
  "id": "31d302e2-6f49-435f-944e-be8276f284b6",
  "type": "TEMPLATE",
  "name": "Joe's Daily Site walk through"
}
Key Type Description
id String The new UUID formatted ID of the document.
type String Type of document TEMPLATE is the only accepted option.
name String Name of the document.

Schedule Item Reminder

Contains information that relates to a schedule reminder.

{
  "event": "START",
  "duration": "P0D"
}
Key Type Description
event String The event that this reminder should be triggered on either START or DUE.
duration String ISO8601 duration string, e.g. PT1H. How long before the event to remind the assignees.

Schedule Item Statuses

The current status of a schedule item, the current values are:

Value Description
ACTIVE Default value - schedule item is still active.
PAUSED Schedule has been paused e.g. manually paused/org frozen.
NO_TEMPLATE The template used for this schedule item has been deleted/archived.
NO_ASSIGNEE No valid assignees exist for this schedule item anymore.
FINISHED The schedule item has hit its end date or count limit and is now complete.

Users and Groups

Add a user

This endpoint allows an administrator (user with the “Admin” permission) to add a user to their organization. This is a synchronous call that returns the user ID of the created user in the response.

A user can be added to iAuditor with or without a password. In both cases, the request would send the new user an email to notify that they’ve been added to the organization.

If no password is given when a user is added, the user calling the API can indicate in the request if they would like the added user to set a password the first time they access iAuditor or to not set a password at all (e.g. for user that are to access iAuditor only via Single-Sign-On).

Upon successful addition of a user:

  1. If a password was submitted for that user in the request, the user will receive an email with a link to the iAuditor login screen so that user can sign in with the provisioned password to access iAuditor.
  2. If no password was submitted for that user in the the Add User request and the reset_password_required flag was set to true for that user in the request, then that user receives an email notifying them they have been added to the organization and inviting them to access iAuditor in their default web browser. Clicking the link takes the user to a page asking them to set a password in order to continue.
  3. If no password was submitted for that user in the the Add User and the reset_password_required flag was set to false for that user in the request (the default behaviour), then that user receives an email notifying them they have been added to the organization and inviting them to access iAuditor in their default web browser. Clicking the link takes the user straight into a single-sign-on page to login with their company credentials in order to access iAuditor.

Special cases:

If the user was added to the organization earlier and was de-activated or removed, then adding the user via the API will cause an email to be sent to the user asking the user to re-activate their account.

If the user added to the organization already existed in iAuditor any password provided with the Add User request will be ignored. The user will still be able to login to iAuditor with their old password.

It may take a few seconds until a newly added user is visible by other endpoints like those used to search users.

curl \
-X POST "https://api.safetyculture.io/users" \
-H "Authorization: Bearer …" \
-H "Content-Type:application/json" \
-d `{
      "firstname": "Thomas",
      "lastname": "Hardy",
      "email": "thomashardy@safetyculture.io"
    }`

The above command returns JSON structured like this:

{
    "user": {
        "firstname": "Thomas",
        "lastname": "Hardy",
        "email": "thomashardy@safetyculture.io",
        "user_id": "user_eacb68331f5b4e1cbe42e37f55b3ce5b"
    }
}

HTTP request

POST https://api.safetyculture.io/users

Request body

The body should use the content type application/json with the following parameters:

Parameter Description
firstname The first name of the user (with maximum character limit of 150)
lastname The last name of the user (with maximum character limit of 150)
email Email Address of the user (with maximum character limit of 200)
password Password of the user (with maximum character limit of 200 and minimum character limit of 6) (optional)
reset_password_required Boolean, if set to true the user will receive an email to reset their password the first time they access iAuditor (optional, the default value is false)

Response

Status code Description
200 OK User was added successfully to the organization
400 Bad Request Invalid request/User already exists
403 Forbidden The user does not have permission to add other users

See the Errors section for more details.

Update a user

The Update User endpoint allows administrators (users with the “Admin” permission) to update any of the following user properties:

Patch semantics are supported, meaning only the fields that are sent in the request are updated.

To update a user, the user must belong to the same organization as the requesting administrator (user with the “Admin” permission). When updating the username (email address) of another user, that user gets an email address change confirmation email. Only once the user has confirmed the request the new username is reflected in their account.

When a user is de-activated i.e. their status changed from active to inactive, their access to inspection data they owned or was previously shared with them ceases.

curl \
-X PUT "https://api.safetyculture.io/users/user_3618cfc7ab274df6bf8a44f546b5e443" \
-H "Authorization: Bearer …" \
-H "Content-Type:application/json" \
-d `{
      "firstname": "Tom",
      "lastname": "Hugh",
      "new_email": "tomhugh2@safetyculture.io",
      "status": "inactive"
    }`

The above command will update the user’s details and reply 200 response

HTTP request

PUT https://api.safetyculture.io/users/<user_id>

Request body

The body should use the content type application/json with the following parameters:

Parameter Description
firstname The first name of the user to update (with maximum character limit of 150 (optional)
lastname The last name of the user (with maximum character limit of 150) (optional)
new_email The new email address of the user to update (with maximum character limit of 200) (optional)
status The status of the user to update, allowed values are active or inactive (optional)

Response

Status code Description
200 OK User was updated successfully
400 Bad Request Invalid request
404 Not Found The user ID specified was not found
403 Forbidden The requesting user does not have permission to update the specified user

Remove a user

Remove a user from a specified group or their organization.

You’ll need

Take note

curl \
-X DELETE "https://api.safetyculture.io/groups/role_01ca38a821504cda885736cccbb9ba40/users/user_22ca38a821504cda885736cccbb9ba40?replacement_user=user_3f777e51d2154f1da1c773af3ff50e09" \
-H "Authorization: Bearer <api_token>"

The above command returns a JSON object structured like this:

{
  "ok": true
}

HTTP request

DELETE https://api.safetyculture.io/groups/<role_id>/users/<user_id>?replacement_user=<user_id>

URL parameters

Parameter Description
role_id The ID of the group or your organization you want to remove the user from.
user_id The ID of the user you want to remove.
replacement_user (optional) The ID of the user you want to reassign documents to.

See the Search Users section to retrieve user IDs and the List organization groups section to retrieve group IDs.

Response

Status code Description
200 OK Deletion successful.
400 Bad Request Invalid request.
403 Forbidden No permission to delete the user.
404 Not Found The group/organization ID or the user ID specified could not found.

See the Errors section for more details.

Add a user to a group

The Add User to Group endpoint allows any user with Group Management permissions to add a user to a group within their organization. A user can only be added to a group within the requesting user’s organization and only users within the requesting user’s organization can be added to a group.

When a user is added to a group, the user inherits the permissions of the group they are added to. The endpoint returns a list of all users in the group after the add user operation is complete.

curl \
-X POST "https://api.safetyculture.io/groups/role_6c5f0ce82ab0410eb3f2cdf50a799e6b/users" \
-H "Authorization: Bearer …" \
-H "Content-Type:application/json" \
-d `{
      "user_id": "user_55e75057df064e929b1faec2e84cbe03"
    }`

The above command returns an array structured like this:

    "user_55e75057df064e929b1faec2e84cbe03",
    "user_45e75057df064e929b1faec2e84cbe03"
]

HTTP request

POST https://api.safetyculture.io/groups/<group_id>/users

Request body

The body should use the content type application/json with the following parameters:

Parameter Description
user_id The ID of the user to add to the group

Response

Status code Description
200 OK User was added successfully to the group
400 Bad Request Invalid request or group_id
403 Forbidden The user does not have the right permissions or the user does not belong to the organization of the requesting user or the group does not belong to the organization of the requesting user

See the Errors section for more details.

List the users in a group

The List Users in Group endpoint allows administrators (users with the “Admin” permission) to list users in their organization or a group within their organization. The response returned can be filtered based on the status of the user (active or inactive or both). Inactive users are those who have been de-activated but are still part of the organization. If no status query parameter is given, both active and inactive users are returned. The maximum number of users that can be returned by a single request is 2000. To list more users use the offset and limit query parameters as described below.

curl \
-X GET "https://api.safetyculture.io/groups/role_6c5f0ce82ab0410eb3f2cdf50a799e6b/users?limit=50&offset=25&status=active" \
-H "Authorization: Bearer …" \
-H "Content-Type:application/json"

The above command returns an array structured like this:

{
    "total": 27,
    "offset": 25,
    "limit": 50,
    "users": [
        {
            "email": "test25@gmail.com",
            "firstname": "test25",
            "lastname": "test25",
            "user_id": "user_4dbad1ca3faf439d9415c98ecf166d67",
            "status": "active"
        },
        {
            "email": "test26@gmail.com",
            "firstname": "test26",
            "lastname": "test26",
            "user_id": "user_aec23bf3609b4f6abd1ff2a15022bc0c",
            "status": "active"
        }
    ]
}

HTTP request

GET https://api.safetyculture.io/groups/<group_id>/users

URL parameters

Parameter Description
group ID The ID of the group or the organization

Query parameters

Parameter Description
limit Controls the maximum number of users that may be returned for a single request. This parameter can be thought of as the page size. If no limit is specified, the system defaults to a limit of 2000. The maximum valid limit value is 2000.
offset Controls the starting point within the user listing results. For example, if you have a result of 15 users to be retrieved and you specify limit=5, you can retrieve the entire set of results in 3 successive requests by varying the offset value: offset=0, offset=5, and offset=10. Note that the first item in the user list is retrieved by setting a zero offset.
status An array of user statuses. The following statuses are supported: active and inactive. If no status is specified, it defaults to ['active', 'inactive']

Response

Status code Description
200 OK Users were retrieved successfully
400 Bad Request Invalid request or group_id or limit or offset value
403 Forbidden The user does not have the right permissions to list user information in this group

See the Errors section for more details.

Search users

Search users by user ID

curl -X GET "https://api.safetyculture.io/users/user_22ca38a821504cda885736cccbb9ba40" \
-H "Authorization: Bearer {your access token}"

The above command returns JSON structured like this:

{
    "email": "jsmith@safetyculture.io",
    "firstname": "John",
    "lastname": "Smith",
    "user_id": "user_22ca38a821504cda885736cccbb9ba40",
    "status": "active"
}

Use this endpoint to lookup user’s details by their user ID. Only users belonging to the same group(s) as the authenticated user can be looked up in this manner and Admin users (users with “Admin” permission) can lookup both active and inactive users in their organization with this endpoint whereas users without “Admin” permissions can lookup only active users for consistency with other iAuditor applications.

HTTP request

GET https://api.safetyculture.io/users/<user_id>

Response

The response will have the content type application/json and include a JSON object with the following properties:

Parameter Description
email The email address corresponding to this user
firstname The first name of the found user
lastname The last name of the found user
status The status of the user (active or inactive)
user_id The id of the user
Status code Description
200 OK User retrieval succeeded
400 Bad Request Invalid request
403 Forbidden No permission to view this user
404 Not Found The user ID specified was not found

A number of different Errors may be returned.

Search users by email address

curl -X POST "https://api.safetyculture.io/users/search" \
-d "{"email": ["john.citizen@safetyculture.io"]}}" \
-H "Authorization: Bearer {your access token}"

The above command returns JSON structured like this:

{
  "users": [
    {
      "id": "user_c4e2421223b5497186bb8ea4e4159fcc",
      "email": "john.citizen@safetyculture.io",
      "firstname": "John",
      "lastname": "Citizen",
      "status": "active"
    }
  ]
}

Use this endpoint to lookup one or more user’s details by their email address. Only users belonging to the same group(s) as the authenticated user can be looked up in this manner. Admin users (users with “Admin” permission) can lookup both active and inactive users in their organization with this endpoint whereas users without “Admin” permissions can lookup only active users for consistency with other iAuditor applications..

The maximum number of email addresses that can be provided to a single request is 100.

Note: It takes some time (usually a few seconds) after a user is added to iAuditor for them to be able to be looked up by email using this endpoint.

HTTP request

POST https://api.safetyculture.io/users/search

Response

The response will have the content type application/json and include an array of JSON objects with the following properties:

Parameter Description
id The id of the user corresponding to an email address from the request body
email The email address corresponding to the this user (same as the one from the request body)
firstname The first name of the found user
lastname The last name of the found user
status The status of the user (active or inactive)

Any email addresses that did not result in a successful lookup will be omitted from the response.

A number of different Errors may be returned.

List organization groups

The Get Organization Groups endpoint allows administrators (users with the “Admin” permission) to list all the groups in their organization. This endpoint lists all groups in the organization of the requesting user, regardless if the requesting user is a member or not of these groups.

curl \
-X GET "https://api.safetyculture.io/groups" \
-H "Authorization: Bearer …" \
-H "Content-Type:application/json"

The above command returns an array structured like this:

{
  "groups": [
    {
      "name": "Group 1",
      "id":"role_7c5f0ce82ab0410eb3f2cdf50a799e6b"
    },
    {
      "name": "Group 2",
      "id":"role_92f8dff1a22748f1b56516cda7af7c8e"
    },
    {
      "name": "Group 3",
      "id":"role_8c5f0ce82ab0410eb3f2cdf50a799e6b"
    }
  ]
}

HTTP request

GET https://api.safetyculture.io/groups

Response

Status code Description
200 OK Groups were retrieved successfully
400 Bad Request Invalid request
403 Forbidden The user does not have the right permissions to list groups in this organization

See the Errors section for more details.

List groups

curl "https://api.safetyculture.io/share/connections" \
-H "Authorization: Bearer {your access token}"

The above command returns JSON structured like this:

{
  "groups":
  [
    {
      "id": "role_e0d6f18b80e24c739c7b1bf77246e8dd",
      "name": "Acme Pty Ltd"
    },
    {
      "id": "role_08a05982612547518f7f5e63712ae9dc",
      "name": "Accounting Department"
    }
  ]
}

Use this endpoint to retrieve the name and ID of all groups the authenticated user is a member of.

HTTP request

GET https://api.safetyculture.io/share/connections

Response

The response will have the content type application/json and include an array of JSON objects with the following properties:

Parameter Description
id The id of a group the user is a member of
name The name of the group

For users that are not members of any group an empty groups array will be returned. The maximum number of groups that will be returned with a single request is 1000. See Errors for possible errors that can be returned.

Add a group

The Add Group endpoint allows a user with Group Management permission to add a group to their organization. This is a synchronous call which returns the name and group ID of the created group in the response.

curl -X POST \
"https://api.safetyculture.io/groups" \
-H "Authorization: Bearer {your access token}" \
-d '{ "name": "Accounting Department" }'

The above command returns JSON structured like this:

{
  "id": "role_08a05982612547518f7f5e63712ae9dc",
  "name": "Accounting Department"
}

Use this endpoint to add a group to your iAuditor organization.

HTTP request

POST https://api.safetyculture.io/groups

Response

The response will have the content type application/json and include a JSON object with the following properties:

Parameter Description
id The id of the newly created group
name The name of the newly created group

Error Codes

The iAuditor API uses the following error codes:

Error Code Meaning Description
400 Bad Request The request is incorrect
401 Unauthorized The authorisation token is missing from the request or it is incorrect
403 Forbidden The request is not available to the user
404 Not Found The specific resource (audit or other) requested was not found
405 Method Not Allowed The HTTP method used is not valid for that URI
406 Not Acceptable You requested a format that isn’t json
409 Conflict Concurrent updates of the same iAuditor resource may return this error. Retry the operation spacing out the requests
429 Too Many Requests Reduce the rate of your requests to the iAuditor API
500 Internal Server Error A problem occurred in the iAuditor platform, please contact support if the problem persists
503 Service Unavailable May happen as a result of scheduled maintenance or networking error. Ensure your code has sufficient retry logic to compensate

Limits

Rate limits

To ensure the stability and security of our servers requests sent to the API by the same user simultaneously at a high rate will be throttled. In that case the API will return a 429 HTTP status code with an error message Too Many Requests.

Our rate limiting policy consists of a hard throttling limit

Endpoint Rate Interval
POST /auth 100 60 seconds
POST /users/search 200 60 seconds
GET /share/connections 200 60 seconds
GET /audits/search 200 60 seconds
GET /export_profiles/search 200 60 seconds
GET /templates/search 200 60 seconds
GET /response_sets 200 60 seconds
POST /audits/<audit ID>/export 20 60 seconds
GET /audits/<audit ID>/exports/<export ID> 100 60 seconds
GET /audits/<audit ID>/exports/<export ID>/<filename> 100 60 seconds
GET /preferences/search 200 60 seconds
POST /audits/{audit ID}/report 200 60 seconds
GET /audits/{audit ID}/report/{export ID} 200 60 seconds
Other 800 60 seconds

Rate limit response headers

All responses sent from the API will include headers which can be used to help manage the rate which requests are being sent to the API.

Header Description
x-rate-limit-limit The rate limit credit for that given endpoint
x-rate-limit-remaining The number of requests left for the window
x-rate-limit-reset The Unix timestamp the next request will be allowed (Only shown when credit has been used up)

IDs

New IDs (UUIDs)

For the new iAuditor APIs, IDs must be provided in the format of a UUID f3245d39-ea77-11e1-aff1-0800200c9a66, to convert an old ID to this format use this sample code and convert it to your programming language.

const id = 'audit_f3245d39ea7711e1aff10800200c9a66';

function toUUID(str) {
  const uuid = str.split('_')[1];

  return `${uuid.substr(0, 8)}-${uuid.substr(8, 4)}-${uuid.substr(12, 4)}-${uuid.substr(16, 4)}-${uuid.substr(20)}`
}

toUUID(id) // f3245d39-ea77-11e1-aff1-0800200c9a66

Old IDs (iAuditor IDs)

For our older iAuditor APIs, IDs must be provided in our prefixed ID format audit_f3245d39ea7711e1aff10800200c9a66, to convert a new UUID to this format use this sample code and convert it to your programming language.

const uuid = 'f3245d39-ea77-11e1-aff1-0800200c9a66';

function toiAuditorID(prefix, id) {
  return `${prefix}_${id.replace(/-/g, '')}`;
}

toiAuditorID('audit', uuid) // audit_f3245d39ea7711e1aff10800200c9a66

Webhooks

Webhooks allow third-party services to receive near real-time inspection event notifications from iAuditor.

Webhooks are seen as one type of workflow that can be setup to be executed automatically when particular inspection events happen. Future workflows may include the ability to generate an inspection report automatically, send an email/sms or combine multiple action steps each time an inspection event takes place.

Webhooks will be sent in the form of a POST HTTP request to the specified URL when an event like inspection starting, updating, completing, archiving, unarchiving takes place.

Any inspection event in the top-level organization of the user that registered the webhook will trigger the webhook. In other words, webhooks are set up per organization, not per user account.

To create a webhook, register the URL within your application that will receive the webhook payload sent when the event is triggered.

To keep the payload size manageable, the webhook payload only contains a subset of the inspection and template information. The format of a webhook payload (here for the TRIGGER_EVENT_INSPECTION_STARTED event) is included as example code.

Example webhook payload for an TRIGGER_EVENT_INSPECTION_STARTED event

{
  "version": "1.0.0",
  "workflow_id": "workflow_8abb7bff902a43a5b3bd498f4bebb42j",
  "event": {
    "date_triggered": "2017-06-29T05:15:19.136Z",
    "event_types": [
      "audit_started"
    ],
    "triggered_by": {
      "type": "user",
      "user": "user_bb5b6ba050bf43c1b447b6f299de4b67",
      "name": "John Smith"
    }
  },
  "data": {
    "audit": {
      "template_id": "template_ca59d625954f4d51baf394400d6e3z87",
      "audit_id": "audit_7e9ee886325a4fb096989c3e2896e876",
      "archived": false,
      "created_at": "2017-06-29T05:15:18.511Z",
      "modified_at": "2017-06-29T05:15:18.511Z",
      "audit_data": {
        "score": 0,
        "total_score": 0,
        "name": "",
        "duration": 0,
        "authorship": {
          "device_id": "user_bb5b6ba050bf43c1b447b6f299de4b67",
          "owner": "John Smith",
          "owner_id": "user_bb5b6ba050bf43c1b447b6f299de4b67",
          "author": "John Smith",
          "author_id": "user_bb5b6ba050bf43c1b447b6f299de4b67"
        },
        "date_completed": null,
        "date_modified": "2017-06-29T05:15:18.509Z",
        "date_started": "2017-06-29T05:15:18.509Z"
      },
      "template_data": {
        "authorship": {
          "device_id": "8a582619-95e9-43e8-b671-6h765745b200",
          "owner": "John Smith",
          "owner_id": "user_bb5b6ba050bf43c1b447b6f299de4b67",
          "author": "John Smith",
          "author_id": "user_bb5b6ba050bf43c1b447b6f299de4b67"
        },
        "metadata": {
          "description": "",
          "name": "test"
        }
      },
      "header_items": [
        {
          "item_id": "f3245d39-ea77-11e1-aff1-0800200c9a78",
          "label": "Title Page",
          "type": "section",
          "children": [
            "f3245d46-ea77-11e1-aff1-0800200c9a66",
            "f3245d40-ea77-11e1-aff1-0800200c9a66",
            "f3245d41-ea77-11e1-aff1-0800200c9a66",
            "f3245d42-ea77-11e1-aff1-0800200c9a66",
            "f3245d43-ea77-11e1-aff1-0800200c9a66",
            "f3245d44-ea77-11e1-aff1-0800200c9a66",
            "f3245d45-ea77-11e1-aff1-0800200c9a66"
          ]
        },
        {
          "parent_id": "f3245d39-ea77-11e1-aff1-0800200c9a66",
          "item_id": "f3245d46-ea77-11e1-aff1-0800200c9a66",
          "label": "Document No.",
          "type": "textsingle",
          "responses": {
            "text": "000027"
          }
        },
        {
          "parent_id": "f3245d39-ea77-11e1-aff1-0800200c9a66",
          "item_id": "f3245d45-ea77-11e1-aff1-0800200c9a66",
          "label": "Personnel",
          "type": "text"
        }
      ]
    },
    "template": {
      "template_id": "template_ca59d625954f4d51baf394400d6e3z87",
      "name": "test"
    }
  }
}

If the service receiving the webhook replies with an error, the webhook will be retried with an exponentially increasing delay. A total of 18 attempts are made over 3 days at the following time intervals (in seconds):

0.5 2 5.5 13 28.5 60 123.5 251 506.5 1018 2041.5 4089 8184.5 16376 32759.5 65527 131062.5

Webhook delivery is on a best effort basis, no guarantee is provided that a particular webhook will be delivered within a time frame or at all. The Search Inspections functionality can help client code verify which inspections changed in a given date range and to compare with received wehbooks to ensure completeness.

When inspections are processed on a mobile device (as opposed to the iAuditor web application or using the API directly), webhooks will only be triggered when these inspections are synced to the iAuditor backend.

In the following sections we describe how to perform CRUD operations on webhooks.

Register a webhook

curl \
  -H "Authorization: Bearer {your access token}" \
  -X POST "https://api.safetyculture.io/webhooks/v1/webhooks" \
  -d '{
         "trigger_events": ["TRIGGER_EVENT_INSPECTION_COMPLETED"],
         "url": "https://example.com"
      }'

The above command returns JSON structured like this

{
  "webhook":  {
    "webhook_id":  "de6790b9-f3b0-4701-8c73-c02267ada1b2",
    "trigger_events":  [
      "TRIGGER_EVENT_INSPECTION_COMPLETED"
    ],
    "url":  "https://example.com",
    "user_id":  "7db5002c-7275-4d2a-99ac-1e4b82f088be",
    "organisation_id":  "7db5002c-7275-4d2a-99ac-1e4b82f088be",
    "enabled":  true,
    "created_at":  "2021-08-24T10:32:14.767453Z",
    "updated_at":  "2021-08-24T10:32:14.767454Z"
  }
}

This endpoint allows you to register a webhook for a given event type. The following event types are supported so far: TRIGGER_EVENT_INSPECTION_STARTED, TRIGGER_EVENT_INSPECTION_UPDATED, TRIGGER_EVENT_INSPECTION_COMPLETED, TRIGGER_EVENT_INSPECTION_ARCHIVED, and TRIGGER_EVENT_INSPECTION_UNARCHIVED.

In addition to changes in inspection responses, the TRIGGER_EVENT_INSPECTION_UPDATED event will be triggered when the inspection is started or the inspection’s sharing permissions change.

HTTP request

POST https://api.safetyculture.io/webhooks/v1/webhooks

Request body

The body should use the content type application/json with the following required parameters:

Parameter Description
trigger_events The array of inspection events for which you would want to be notified. Valid values are TRIGGER_EVENT_INSPECTION_STARTED, TRIGGER_EVENT_INSPECTION_UPDATED, TRIGGER_EVENT_INSPECTION_COMPLETED, TRIGGER_EVENT_INSPECTION_ARCHIVED and TRIGGER_EVENT_INSPECTION_UNARCHIVED.
url The URL you want the payload sent to.

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
webhook_id The new UUID formatted ID of a webhook.
trigger_events The array of inspection events for which you would want to be notified. Valid values are TRIGGER_EVENT_INSPECTION_STARTED, TRIGGER_EVENT_INSPECTION_UPDATED, TRIGGER_EVENT_INSPECTION_COMPLETED, TRIGGER_EVENT_INSPECTION_ARCHIVED and TRIGGER_EVENT_INSPECTION_UNARCHIVED.
url Contains the webhook URL that is registered.
user_id The new UUID formatted ID of the user who registered the webhook.
organisation_id The new UUID formatted ID of the organization who the webhook is registered to.
enabled Flag to check if webhook is enabled. If false no events will be triggered from this webhook. Defaults to true.
updated_at Last modified timestamp of this webhook setting.
created_at Creation timestamp of this webhook setting.
Status code Description
200 OK Registration successful.
400 Bad Request Invalid request e.g. malformed trigger_events or the sent payload.
403 Forbidden The user does not have permission to register a webhook.

See the Errors section for more details.

Get a webhook

curl "https://api.safetyculture.io/webhooks/v1/webhooks/{your webhook_id}" \
  -H "Authorization: Bearer {your access token}" \
  -H "Content-Type:application/json"

The above command returns JSON structured like this

{
  "webhook":  {
    "webhook_id":  "de6790b9-f3b0-4701-8c73-c02267ada1b2",
    "trigger_events":  [
      "TRIGGER_EVENT_INSPECTION_COMPLETED"
    ],
    "url":  "https://example.com",
    "user_id":  "7db5002c-7275-4d2a-99ac-1e4b82f088be",
    "organisation_id":  "7db5002c-7275-4d2a-99ac-1e4b82f088be",
    "enabled":  true,
    "created_at":  "2021-08-24T10:32:14.767453Z",
    "updated_at":  "2021-08-24T10:32:14.767454Z"
  }
}

This endpoint allows you to retrieve a webhook with the given webhook ID.

HTTP request

GET https://api.safetyculture.io/webhooks/v1/webhooks/<webhook_id>

URL parameters

Parameter Description
webhook_id The new UUID formatted ID of the webhook to retrieve.

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
webhook_id The new UUID formatted ID of a webhook.
trigger_events The array of inspection events for which you would want to be notified. Valid values are TRIGGER_EVENT_INSPECTION_STARTED, TRIGGER_EVENT_INSPECTION_UPDATED, TRIGGER_EVENT_INSPECTION_COMPLETED, TRIGGER_EVENT_INSPECTION_ARCHIVED and TRIGGER_EVENT_INSPECTION_UNARCHIVED.
url Contains the webhook URL that is registered.
user_id The new UUID formatted ID of the user who registered the webhook.
organisation_id The new UUID formatted ID of the organization who the webhook is registered to.
enabled Flag to check if webhook is enabled. If false no events will be triggered from this webhook. Defaults to true.
updated_at Last modified timestamp of this webhook setting.
created_at Creation timestamp of this webhook setting.
Status code Description
200 OK Retrieve successful.
400 Bad Request Invalid request.
403 Forbidden The user does not have permission to retrieve a webhook.
404 Not Found The webhook ID specified was not found.

See the Errors section for more details.

List webhooks

curl "https://api.safetyculture.io/webhooks/v1/webhooks" \
 -H "Authorization: Bearer {your access token}" \
 -H "Content-Type:application/json"

The above command returns JSON structured like this

{
  "webhook":  [
    {
      "webhook_id":  "de6790b9-f3b0-4701-8c73-c02267ada1b2",
      "trigger_events":  [
        "TRIGGER_EVENT_INSPECTION_COMPLETED"
      ],
      "url":  "https://example.com",
      "user_id":  "7db5002c-7275-4d2a-99ac-1e4b82f088be",
      "organisation_id":  "7db5002c-7275-4d2a-99ac-1e4b82f088be",
      "enabled":  true,
      "created_at":  "2021-08-24T10:32:14.767453Z",
      "updated_at":  "2021-08-24T10:32:14.767454Z"
    },
    {
      "webhook_id":  "de6790b9-f3b0-4701-8c73-c02267ada1b2",
      "trigger_events":  [
        "TRIGGER_EVENT_INSPECTION_COMPLETED"
      ],
      "url":  "https://example.com",
      "user_id":  "7db5002c-7275-4d2a-99ac-1e4b82f088be",
      "organisation_id":  "7db5002c-7275-4d2a-99ac-1e4b82f088be",
      "enabled":  true,
      "created_at":  "2021-08-24T10:32:14.767453Z",
      "updated_at":  "2021-08-24T10:32:14.767454Z"
    }
  ]
}

This endpoint returns an array of webhook setting objects which are registered for the given organization.

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
webhook_id The new UUID formatted ID of a webhook.
trigger_events The array of inspection events for which you would want to be notified. Valid values are TRIGGER_EVENT_INSPECTION_STARTED, TRIGGER_EVENT_INSPECTION_UPDATED, TRIGGER_EVENT_INSPECTION_COMPLETED, TRIGGER_EVENT_INSPECTION_ARCHIVED and TRIGGER_EVENT_INSPECTION_UNARCHIVED.
url Contains the webhook URL that is registered.
user_id The new UUID formatted ID of the user who registered the webhook.
organisation_id The new UUID formatted ID of the organization who the webhook is registered to.
enabled Flag to check if webhook is enabled. If false no events will be triggered from this webhook. Defaults to true.
updated_at Last modified timestamp of this webhook setting.
created_at Creation timestamp of this webhook setting.
Status code Description
200 OK Retrieve successful.
400 Bad Request Invalid request.
403 Forbidden The user does not have permission to list webhooks.

See the Errors section for more details.

Update a webhook

curl \
  -H "Authorization: Bearer {your access token}" \
  -X PUT "https://api.safetyculture.io/webhooks/v1/webhooks/<your webhook_id>" \
  -d '{
         "trigger_events": ["TRIGGER_EVENT_INSPECTION_COMPLETED"],
         "url": "https://example.com",
         "enabled": false
      }'

The above command returns JSON structured like this

{
  "webhook":  {
    "webhook_id":  "de6790b9-f3b0-4701-8c73-c02267ada1b2",
    "trigger_events":  [
      "TRIGGER_EVENT_INSPECTION_COMPLETED"
    ],
    "url":  "https://example.com",
    "user_id":  "7db5002c-7275-4d2a-99ac-1e4b82f088be",
    "organisation_id":  "7db5002c-7275-4d2a-99ac-1e4b82f088be",
    "enabled":  true,
    "created_at":  "2021-08-24T10:32:14.767453Z",
    "updated_at":  "2021-08-24T10:32:14.767454Z"
  }
}

This endpoint allows you to update a webhook setting object.

HTTP request

PUT https://api.safetyculture.io/webhooks/v1/webhooks/<webhook_id>

Request body

The body should use the content type application/json with the following required parameters:

Parameter Description
trigger_events The array of inspection events for which you would want to be notified. Valid values are TRIGGER_EVENT_INSPECTION_STARTED, TRIGGER_EVENT_INSPECTION_UPDATED, TRIGGER_EVENT_INSPECTION_COMPLETED, TRIGGER_EVENT_INSPECTION_ARCHIVED and TRIGGER_EVENT_INSPECTION_UNARCHIVED.
url Contains the webhook URL that is registered.
enabled Flag to check if webhook is enabled. If false no events will be triggered from this webhook. Defaults to true.

Note: You can specify only the fields that needs to be updated, i.e. do a partial update

Response

The response will have the content type application/json and include the following parameters:

Parameter | Description webhook_id | The new UUID formatted ID of a webhook. trigger_events | The array of inspection events for which you would want to be notified. Valid values are TRIGGER_EVENT_INSPECTION_STARTED, TRIGGER_EVENT_INSPECTION_UPDATED, TRIGGER_EVENT_INSPECTION_COMPLETED, TRIGGER_EVENT_INSPECTION_ARCHIVED and TRIGGER_EVENT_INSPECTION_UNARCHIVED. url | Contains the webhook URL that is registered. user_id | The new UUID formatted ID of the user who registered the webhook. organisation_id | The new UUID formatted ID of the organization who the webhook is registered to. enabled | Flag to check if webhook is enabled. If false no events will be triggered from this webhook. Defaults to true. updated_at | Last modified timestamp of this webhook setting. created_at | Creation timestamp of this webhook setting.

Status code Description
200 OK Update successful.
400 Bad Request Invalid request or payload.
403 Forbidden The user does not have permission to update a webhook.
404 Not Found The webhook ID specified was not found.

See the Errors section for more details.

Delete a webhook

curl \
  -X "DELETE" "https://api.safetyculture.io/webhooks/v1/webhooks/<webhook_id>" \
  -H "Authorization: Bearer {your access token}" \
  -H "Content-Type:application/json"

The above command returns JSON structured like this

{}

This endpoint allows you to delete a webhook with the specified webhook ID.

HTTP request

DELETE https://api.safetyculture.io/webhooks/v1/webhooks/<webhook_id>

URL parameters

Parameter Description
webhook_id The new UUID formatted ID of the webhook to delete.

Response

The successful response for this request will be {“ok”: true}

Status code Description
200 OK Deletion successful.
400 Bad Request Invalid request.
403 Forbidden The user does not have permission to delete the webhook.
404 Not Found The webhook ID specified was not found.

See the Errors section for more details.

(Deprecated) Workflows

Webhooks allow third-party services to receive near real-time inspection event notifications from SafetyCulture.

Webhooks are seen as one type of workflow that can be setup to be executed automatically when particular inspection events happen. Future workflows may include the ability to generate an inspection report automatically, send an email/sms or combine multiple action steps each time an inspection event takes place.

At the moment, workflows consist of a single step only which is to send a webhook.

Webhook workflows will be sent in the form of a POST HTTP request to the specified URL when an inspection event like audit_completed takes place.

Any inspection event in the top-level organisation of the user that registered the workflow will trigger the workflow. In other words, workflows are set up per organisation, not per user account.

To create a webhook workflow, register the URL within your application that will receive the webhook payload sent when the event is triggered.

To keep the payload size manageable, the webhook payload only contains a subset of the inspection and template information. The format of a webhook payload (here for the audit_started event) is included as example code.

Example webhook payload for an audit_started event

{
  "version": "1.0.0",
  "workflow_id": "workflow_8abb7bff902a43a5b3bd498f4bebb42j",
  "event": {
    "date_triggered": "2017-06-29T05:15:19.136Z",
    "event_types": [
      "audit_started"
    ],
    "triggered_by": {
      "type": "user",
      "user": "user_bb5b6ba050bf43c1b447b6f299de4b67",
      "name": "John Smith"
    }
  },
  "data": {
    "audit": {
      "template_id": "template_ca59d625954f4d51baf394400d6e3z87",
      "audit_id": "audit_7e9ee886325a4fb096989c3e2896e876",
      "archived": false,
      "created_at": "2017-06-29T05:15:18.511Z",
      "modified_at": "2017-06-29T05:15:18.511Z",
      "audit_data": {
        "score": 0,
        "total_score": 0,
        "name": "",
        "duration": 0,
        "authorship": {
          "device_id": "user_bb5b6ba050bf43c1b447b6f299de4b67",
          "owner": "John Smith",
          "owner_id": "user_bb5b6ba050bf43c1b447b6f299de4b67",
          "author": "John Smith",
          "author_id": "user_bb5b6ba050bf43c1b447b6f299de4b67"
        },
        "date_completed": null,
        "date_modified": "2017-06-29T05:15:18.509Z",
        "date_started": "2017-06-29T05:15:18.509Z"
      },
      "template_data": {
        "authorship": {
          "device_id": "8a582619-95e9-43e8-b671-6h765745b200",
          "owner": "John Smith",
          "owner_id": "user_bb5b6ba050bf43c1b447b6f299de4b67",
          "author": "John Smith",
          "author_id": "user_bb5b6ba050bf43c1b447b6f299de4b67"
        },
        "metadata": {
          "description": "",
          "name": "test"
        }
      },
      "header_items": [
        {
          "item_id": "f3245d39-ea77-11e1-aff1-0800200c9a78",
          "label": "Title Page",
          "type": "section",
          "children": [
            "f3245d46-ea77-11e1-aff1-0800200c9a66",
            "f3245d40-ea77-11e1-aff1-0800200c9a66",
            "f3245d41-ea77-11e1-aff1-0800200c9a66",
            "f3245d42-ea77-11e1-aff1-0800200c9a66",
            "f3245d43-ea77-11e1-aff1-0800200c9a66",
            "f3245d44-ea77-11e1-aff1-0800200c9a66",
            "f3245d45-ea77-11e1-aff1-0800200c9a66"
          ]
        },
        {
          "parent_id": "f3245d39-ea77-11e1-aff1-0800200c9a66",
          "item_id": "f3245d46-ea77-11e1-aff1-0800200c9a66",
          "label": "Document No.",
          "type": "textsingle",
          "responses": {
            "text": "000027"
          }
        },
        {
          "parent_id": "f3245d39-ea77-11e1-aff1-0800200c9a66",
          "item_id": "f3245d45-ea77-11e1-aff1-0800200c9a66",
          "label": "Personnel",
          "type": "text"
        }
      ]
    },
    "template": {
      "template_id": "template_ca59d625954f4d51baf394400d6e3z87",
      "name": "test"
    }
  }
}

If the service receiving the webhook replies with an error, the webhook will be retried with an exponentially increasing delay. A total of 18 attempts are made over 3 days at the following time intervals (in seconds):

0.5 2 5.5 13 28.5 60 123.5 251 506.5 1018 2041.5 4089 8184.5 16376 32759.5 65527 131062.5

Webhook delivery is on a best effort basis, no guarantee is provided that a particular webhook will be delivered within a time frame or at all. The Search Inspections functionality can help client code verify which inspections changed in a given date range and to compare with received wehbooks to ensure completeness.

When inspections are processed on a mobile device (as opposed to the iAuditor web application or using the API directly), workflows will only be triggered when these inspections are synced to the SafetyCulture backend.

In the following sections we describe how to perform CRUD operations on webhook workflows.

(Deprecated) Register a workflow

curl \
  -H "Authorization: Bearer {your access token}" \
  -H "Content-Type:application/json" \
  -X POST "https://api.safetyculture.io/workflows" \
  -d '{
         "trigger_events": ["audit_completed", "audit_archived"],
         "steps": [
           {
             "url": "https://example.com",
             "type": "webhook"
           }
         ]
      }'

The above command returns JSON structured like this

{
  "workflow_id": "workflow_de6790b9f3b047018c73c02267ada1b2",
      "trigger_events": [
          "audit_completed", "audit_archived"
      ],
      "steps": [
          {
              "url": "https://example.com",
              "type": "webhook",
              "id": "workflowstep_63aa1e21816f4bf78e6d3a4f7cbfaef1"
          }
      ],
      "user_id": "user_7db5002c72754d2a99ac1e4b82f088be",
      "org_id": "role_7db5002c72754d2a99ac1e4b82f088be",
      "enabled": true,
      "updated_at": "2017-06-19T03:51:12.299Z",
      "created_at": "2017-06-19T03:51:12.299Z",
      "version": "1.0.0"
}

This endpoint allows you to register a workflow for a given event type. The following event types are supported so far: audit_completed, audit_archived, audit_started, audit_updated and audit_unarchived

In addition to changes in inspection responses, the audit_updated event will be triggered when the inspection is started or the inspection’s sharing permissions change.

HTTP request

POST https://api.safetyculture.io/workflows

Request body

The body should use the content type application/json with the following required parameters:

Parameter Description
trigger_events The array of inspection events for which you would want to be notified. Valid values are audit_completed, audit_archived, audit_started, audit_updated and audit_unarchived
steps Array of workflow steps. Currently we support only one step, the ability to add more than one step in the array will be considered in the future. See table below of available workflow step types.
Step Type Description
webhook Must contain properties "type": "webhook" and "url". Only the HTTPS URL schema is allowed.

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
workflow_id The ID of the workflow
trigger_events The array of inspection events for which you would want to be notified. Valid values are audit_completed, audit_archived, audit_started, audit_updated and audit_unarchived
steps Contains the workflow URL that is registered and the type of the workflow. As of now only the type webhook is supported. It also contains the id of the step
user_id User ID of the user who registered the workflow
org_id Organization ID of the user who registered the workflow
enabled Flag to check if workflow is enabled. If false no events will be triggered from this workflow. Defaults to true
updated_at Last modified timestamp of this workflow setting
created_at Creation timestamp of this workflow setting
version JSON schema version of the workflow
Status code Description
200 OK Registration successful
400 Bad Request Invalid request e.g. malformed trigger_events or the sent payload
403 Forbidden The user does not have permission to register a workflow

See the Errors section for more details.

(Deprecated) Get a workflow

curl "https://api.safetyculture.io/workflows/workflow_37afc5890aa94e778bbcde4fc4cbe480 \
  -H "Authorization: Bearer {your access token}" \
  -H "Content-Type:application/json"

The above command returns JSON structured like this

{
  "workflow_id": "workflow_37afc5890aa94e778bbcde4fc4cbe480",
      "trigger_events": [
          "audit_completed"
      ],
      "steps": [
          {
              "url": "https://example.com",
              "type": "webhook",
              "id": "workflowstep_37afc5890aa94e778bbcde4fc4cbe480"
          }
      ],
      "user_id": "user_37afc5890aa94e778bbcde4fc4cbe480",
      "org_id": "role_37afc5890aa94e778bbcde4fc4cbe480",
      "enabled": true,
      "updated_at": "2017-06-19T03:51:12.299Z",
      "created_at": "2017-06-19T03:51:12.299Z",
      "version": "1.0.0"
}

This endpoint allows you to retrieve the workflow with the given workflow ID.

HTTP request

GET https://api.safetyculture.io/workflows/<workflow_id>

URL parameters

Parameter Description
workflow ID The ID of the workflow to return

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
workflow_id The ID of the workflow
trigger_events The array of inspection events for which you would want to be notified. Valid values are audit_completed, audit_archived, audit_started, audit_updated and audit_unarchived
steps Contains the workflow URL that is registered and the type of the workflow. As of now only the type webhook is supported. It also contains the id of the step
user_id User ID of the user who registered the workflow
org_id Organization ID of the user who registered the workflow
enabled Flag to check if workflow is enabled. If false no events will be triggered from this workflow. Defaults to true
updated_at Last modified timestamp of this workflow
created_at Creation timestamp of this workflow
version JSON schema version of the workflow
Status code Description
200 OK Retrieve successful
400 Bad Request Invalid request
403 Forbidden The user does not have permission to retrieve a workflow
404 Not Found The workflow ID specified was not found

See the Errors section for more details.

(Deprecated) Get workflows

curl "https://api.safetyculture.io/workflows?org_id=role_37afc5890aa94e778bbcde4fc4cbe480" \
 -H "Authorization: Bearer {your access token}" \
 -H "Content-Type:application/json"

The above command returns JSON structured like this

[
 {
      "workflow_id": "workflow_37afc5890aa94e778bbcde4fc4cbe480",
      "trigger_events": [
          "audit_completed"
      ],
      "steps": [
          {
              "url": "https://example.com",
              "type": "webhook",
              "id": "workflowstep_37afc5890aa94e778bbcde4fc4cbe480"
          }
      ],
      "user_id": "user_37afc5890aa94e778bbcde4fc4cbe480",
      "org_id": "role_37afc5890aa94e778bbcde4fc4cbe480",
      "enabled": true,
      "updated_at": "2017-06-19T03:51:12.299Z",
      "created_at": "2017-06-19T03:51:12.299Z",
      "version": "1.0.0"
 },
 {
       "workflow_id": "workflow_45afc5890aa94e778bbcde4fc4cbe480",
       "trigger_events": [
           "audit_completed"
       ],
       "steps": [
           {
               "url": "https://example.com",
               "type": "webhook",
               "id": "workflowstep_45afc5890aa94e778bbcde4fc4cbe480"
           }
       ],
       "user_id": "user_45afc5890aa94e778bbcde4fc4cbe480",
       "org_id": "role_37afc5890aa94e778bbcde4fc4cbe480",
       "enabled": true,
       "updated_at": "2017-06-19T03:51:12.299Z",
       "created_at": "2017-06-19T03:51:12.299Z",
       "version": "1.0.0"
 }
]

This endpoint returns an array of workflow setting objects which are registered for the given organization.

Query parameters

Parameter Description
org_id Organization ID of the workflows to be returned

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
workflow_id The ID of the workflow
trigger_events The array of inspection events for which you would want to be notified. Valid values are audit_completed, audit_archived, audit_started, audit_updated and audit_unarchived
steps Contains the workflow URL that is registered and the type of the workflow. As of now only the type webhook is supported. It also contains the id of the step
user_id User ID of the user who registered the workflow
org_id Organization ID of the user who registered the workflow
enabled Flag to check if workflow is enabled. If false no events will be triggered from this workflow. Defaults to true
updated_at Last modified timestamp of this workflow
created_at Creation timestamp of this workflow
version JSON schema version of the workflow
Status code Description
200 OK Retrieve successful
400 Bad Request Invalid request
403 Forbidden The user does not have permission to retrieve a workflow
404 Not Found The org ID specified was not found

See the Errors section for more details.

(Deprecated) Update a workflow

curl \
  -X PUT "https://api.safetyculture.io/workflows/<workflow_id>" \
  -d '{"trigger_events":["audit_started"]} \
  -H "Authorization: Bearer {your access token}" \
  -H "Content-Type:application/json"

The above command returns JSON structured like this

{
  "workflow_id": "workflow_de6790b9f3b047018c73c02267ada1b2",
      "trigger_events": [
          "audit_started"
      ],
      "steps": [
          {
              "url": "https://example.com",
              "type": "webhook",
              "id": "workflowstep_63aa1e21816f4bf78e6d3a4f7cbfaef1"
          }
      ],
      "user_id": "user_7db5002c72754d2a99ac1e4b82f088be",
      "org_id": "role_7db5002c72754d2a99ac1e4b82f088be",
      "enabled": true,
      "updated_at": "2017-06-19T03:51:12.299Z",
      "created_at": "2017-06-19T03:51:12.299Z",
      "version": "1.0.0"
}

This endpoint allows you to update a workflow setting object.

HTTP request

PUT https://api.safetyculture.io/workflows/<workflow_id>

Request body

The body should use the content type application/json with the following required parameters:

Parameter Description
trigger_events The inspection events for which you would want to be notified. Valid values are audit_completed, audit_archived, audit_started, audit_updated and audit_unarchived
steps Array of workflow steps to be updated.Currently we support only one step, the ability to add more than one step in the array will be considered in the future. See table below of available workflow step types.
Step Type Description
webhook Must contain properties "type": "webhook" and "url". Only the HTTPS URL schema is allowed.

Note: You can specify only the fields that needs to be updated, i.e. do a partial update

Response

The response will have the content type application/json and include the following parameters:

Parameter Description
workflow_id The ID of the workflow
trigger_events The updated inspection events for which you would want to be notified. Valid values are audit_completed, audit_archived, audit_started, audit_updated and audit_unarchived
steps Contains the workflow URL that is registered and the type of the workflow. As of now only the type webhook is supported. It also contains the id of the step
user_id User ID of the user who registered the workflow
org_id Organization ID of the user who registered the workflow
enabled Flag to check if workflow is enabled. If false no events will be triggered from this workflow. Defaults to true
updated_at Last modified timestamp of this workflow
created_at Creation timestamp of this workflow
version JSON schema version of the workflow
Status code Description
200 OK Update successful
400 Bad Request Invalid request or payload
403 Forbidden The user does not have permission to update a workflow
404 Not Found The workflow ID specified was not found

See the Errors section for more details.

(Deprecated) Delete a workflow

curl \
  -X "DELETE" "https://api.safetyculture.io/workflows/<workflow_id>" \
  -H "Authorization: Bearer {your access token}" \
  -H "Content-Type:application/json"

The above command returns JSON structured like this

{
  "ok": true
}

This endpoint allows you to delete a workflow with the specified workflow ID.

HTTP request

DELETE https://api.safetyculture.io/workflows/<workflow_id>

URL parameters

Parameter Description
workflow ID The ID of the workflow setting to delete

Response

The successful response for this request will be {“ok”: true}

Status code Description
200 OK Deletion successful
400 Bad Request Invalid request
403 Forbidden The user does not have permission to delete the workflow
404 Not Found The workflow ID specified was not found

See the Errors section for more details.

SDKs

The following SDKs are available as open source on GitHub. They offer partial coverage of the capabilities of the iAuditor API. For full, up to date coverage you can generate an SDK automatically in a number of languages using our Swagger spec file and swagger-codegen

Python SDK

Also includes a handy data export tool.

GitHub repository

Javascript SDK

GitHub repository

Swagger spec

The up to date Swagger spec file of the iAuditor API is here.

JSON schemas

Schemas of iAuditor API data structures can be found here.

Versioning

There is only one version of the iAuditor API, we are adding changes in a backwards compatible manner. If in future we introduce breaking changes we will introduce new versions accordingly and announce here.

Changelog

2021-09-20: Added support for Folder users(Sites) endpoints.

2021-09-16: Added support for Folders (Sites) endpoints.

2021-09-03: Added new Clone Inspection endpoint.

2021-08-25: Added new endpoint documentation for the new webhooks. Marked old workflows endpoints as deprecated.

2020-10-28: Updated the order of sections in the developer guide.

2020-10-15: Added documentation for drawing_base_image property of item options (See Inspection Items).

2019-10-24: Added new endpoint documentation for the new reports and preferences. Marked old reporting and export profiles endpoints as deprecated.

2019-09-09: Actions endpoints documentation removed to avoid confusion until API support is available for the new Collaborative Actions feature

2019-09-06: The rate limit for the start export endpoint has been reduced from 100 requests per minute to 20 (see Rate Limiting)

2019-08-26: The rate limit for exporting endpoints has been reduced from 200 requests per minute to 100 (see Rate Limiting)

2018-08-29: The rate limiting mechanism has been updated with a new policy (see Rate Limiting)

2018-08-20: Added support for adding a single group. (see Add Group)

2018-08-20: Updated the audit_data property of the inspection to include information about sites.

2018-08-02: Example code snippets referencing the Inspection Title header field have been changed to no longer reference this field because the Inspection Title header field is no longer added to new templates by default.

2018-02-19: The order of actions returned by a search is now by date created than by due date to facilitate certain types of integrations

2018-02-01: Updated the user lookup by user ID and user lookup by email address to return both active and inactive user information only for Admin users, Non Admin users see only active user information (see Search Users)

2018-02-01: The response of user lookup by user ID now also includes inactive users and the status of the user for completeness (see Search Users)

2018-01-29: The response of user lookup by email address now also includes inactive users and the status of the user for completeness (see Search Users)

2017-11-28: Updated the permission model of Actions. The Action Management permission is now deprecated. Users can access any Action if they have access to the associated inspection.

2017-11-21: Updated the Beta endpoint for listing all the groups in the organisation (see Get Organisation Groups)

2017-11-17: Added Beta support for listing all the groups in the organisation (see Get Organisation Groups)

2017-11-10: Added Beta support for batch requests (see Batch Requests)

2017-11-03: Added Beta support for listing the users of the organisation or a group (see List Users in Group)

2017-11-03: The response of user lookup by user ID now also returns the user ID for completeness (see Search Users)

2017-10-27: Added Beta support for adding a user to a group (see Add User to Group)

2017-10-26: Added a rate limiting mechanism (transparent to users) to prevent denial of service scenarios

2017-10-25: Added support for searching a user with user ID (see Search Users)

2017-10-19: Added Beta support for updating users via user ID (see update user)

2017-10-19: Added Beta support for adding a single user (see add user)

2017-10-19: Removed Beta support for adding users in bulk

2017-10-09: Added Beta support for adding and removing users (see Users and Groups)

2017-09-25: Improved error handling for consistency and better error messages

2017-09-25: Added support for creating, retrieving, updating and deleting actions

2017-08-09: PUT request on response sets can now update all responses of a response sets at once

2017-08-08: Added support for exporting actions

2017-07-31: Added CRUD API for response sets

2017-07-07: Added support for outgoing webhooks

2017-07-07: Inspection data now contains GPS location of inspection started and completed points in the audit_data property of the inspection

2017-04-06: Added ability to archive and un-archive inspections (see Modify inspection)