Introduction

This portal provides resources to learn and get started with the SafetyCulture (formerly iAuditor) API.

Access to the API requires a Premium or Enterprise Plan. You can sign up and upgrade to trial our Premium Plan for 30 days, or contact us to find out more about our Enterprise Plan.

Generate an authorization token (API token)

The API requires an authorization token (API token) for each request. A token can be generated from your SafetyCulture account.

🚧

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.

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 SafetyCulture 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 SafetyCulture account. A pre-registered client ID and secret are not required to create an authorization token.

Authorize a request

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

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 {api_token}. If you're using sample requests to try the API, remember to replace {your access token} with your access token.

Search for inspections

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

{
  "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 modified inspections section for more information on search parameters.

📘

You must pass at least the audit_id field to a search inspections request, otherwise the API would return a 400 HTTP error code to indicate a bad 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 {api_token}"

Search inspections conducted from a specific template

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

📘

All date/time values in requests and responses are in Coordinated Universal Time (UTC), following the ISO 8601 date and time format.

Retrieve an inspection

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

{
  "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 via the web app.

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

curl "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/media/9E3BD015-6275-4668-BAF1-296B2F38444C" \
  -o 9E3BD015-6275-4668-BAF1-296B2F38444C.jpg \
  -H "Authorization: Bearer {api_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 SafetyCulture 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.

👍

Please contact our customer support team if you have any questions.