Introduction
As you scroll through the page, you can follow these code snippets 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 audits, sharing them and retrieving audit data and attached media. Audits can be retrieved individually, or can be searched by a set of parameters. The search parameters include the last modification date of an audit, allowing you to use the API for tasks such as extracting all audits from the system, and retrieving new and updated audits periodically.
Access to the iAuditor API requires a Premium plan. You can sign up for a free 30-day trial of the plan from the SafetyCulture website. If you need to trial the plan for longer than that, contact us.
Getting Started
In this section, we will provide a quick guide to getting started with the iAuditor API. We will walk through the process of obtaining an authorisation token, using it to authorise a request, and searching available audits.
The examples use the curl application to allow them to be run from the command-line wherever curl is installed.
For more information on the structure of each request, see to the reference sections in the navigation.
Generating an Authorisation Token
curl \
-X POST \
-d username=example@safetyculture.io \
-d password=secret \
-d grant_type=password \
"https://api.safetyculture.io/auth"
To get started with the API, you will need to generate an authorisation token. This token is used to authorise all requests you make so that you will not need to use or store your username and password in your own scripts or applications.
Following the example, you will POST the username and password fields along with the field grant_type with a value
of password to the https://api.safetyculture.io/auth endpoint.
{
"access_token": "b7f8f791920c1618ace0e24b4d52ce260473dad870e7bd56b869f8d2f26e554d",
"token_type": "Bearer"
}
The access_token is your secret token for authorising all requests to the API, and has access to all the same audits
as the username normally does.
Authorising a Request
curl "https://api.safetyculture.io/audits/search?field=audit_id" \
-H "Authorization: Bearer b7f8f791920c1618ace0e24b4d52ce260473dad870e7bd56b869f8d2f26e554d"
You can use the authorisation token to make requests to the API by passing it in the Authorization HTTP header using
the format Authorization: Bearer b7f8f791920c1618ace0e24b4d52ce260473dad870e7bd56b869f8d2f26e554d. This header needs
to be passed on every request.
If the header is forgotten, then the API will respond with a 401 HTTP error code, indicating the user is not authorised.
Searching for available audits
curl "https://api.safetyculture.io/audits/search?field=audit_id&field=modified_at" \
-H "Authorization: Bearer ..."
The response will look like the following:
{
"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 audits using the API, make a GET request to the https://api.safetyculture.io/audits/search endpoint.
By default the audits will be returned in ascending order from the earliest to latest, limited to the first 1000 audits.
You can pass the list of fields that you want included, as well as a number of other parameters to narrow the request. For more information on the available search options, see the Search Audits reference.
Search available audits in a given period of time:
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 ..."
Or search audits based on a particular template:
curl "https://api.safetyculture.io/audits/search?field=audit_id"\
"&template=template_37afc5890aa94e778bbcde4fc4cbe480" \
-H "Authorization: Bearer ..."
Retrieving an audit
curl "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40" \
-H "Authorization: Bearer ..."
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": {
}
}
Once you have found the list of audits that you’d like to retrieve, you can fetch them individually using the
https://api.safetyculture.io/audits/<audit_id> endpoint. You can use the audit ID retrieved from a previous search, or
by opening it in the iAuditor website to edit and looking at the URL, e.g.:
https://app.safetyculture.io/#/iauditor/audits/<audit_id>
The JSON returned from this endpoint is a complete representation of the audit data, including the template that it was based from. A description of the audit JSON format can be found in the Audit Format reference.
The audit will also contain media attached to particular items:
{
"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"
}
]
}
A particular section of interest is the media section as you can see in the snippet. These references can be used to determine how to retrieve the media from the API.
Retrieving media from an audit
curl "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/media/9E3BD015-6275-4668-BAF1-296B2F38444C" \
-o 9E3BD015-6275-4668-BAF1-296B2F38444C.jpg \
-H "Authorization: Bearer ..."
In this case, the response will not be JSON, but the actual media file with an appropriate
Content-Typeheader.
After retrieving the audits that you would like to use, you may want to retrieve their associated media (including photos, images, drawings and signatures). To fetch a piece of media, you will need the audit ID, and the media ID within the audit which can be retrieved from the audit JSON as described above.
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 audit JSON to construct the filename <media_id>.<file_ext>.
Repeat the request for as many of the media items in the audit that you need.
Next steps
This concludes a basic walkthrough of the audit retrieval methods of the iAuditor API. Read on to the following sections to learn about all of the available requests and parameters, or take a look at the Use Cases for examples of API tasks that you might like to try.
Making Requests
curl "https://api.safetyculture.io/" \
-H "User-Agent: MyIAuditorClient/1.0"
If you are writing your own client or sending requests via the command line, you should always ensure that an
appropriate User-Agent header is sent. For example, for a client called MyIAuditorClient version 1.0, you
might use a user agent of MyIAuditorClient/1.0 as in the example snippet. In your code, we recommend you replace MyIAuditorClient with some text unique to your organisation or use case like SalesforceIntegration/1.0
curl "https://api.safetyculture.io/" \
-H "Accept: application/json"
You must also send the Accept header to indicate what content type is desired. This should be application/json or
a wildcard such as */*.
Authentication
The API requires an authorisation token for each request. This token is initially generated by making a request to the
https://api.safetyculture.io/auth endpoint with your username and password. After this initial request, you will use
the authorisation token, and will not need to use your own username and password.
Once you have obtained a token, it is passed in the Authorization header on ach request to the API, for example:
Authorization: Bearer b7f8f791920c1618ace0e24b4d52ce260473dad870e7bd56b869f8d2f26e554d.
The iAuditor API uses OAuth 2.0 as the means of authorisation for individual requests. The initial authorisation uses the Resource Owner Password Credentials Grant method and does not currently 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 account. A pre-registered client ID and secret are not required to create an authorisation token at this time.
The token expires after 1 month of inactivity. After that point you will need to create a new token. If the token makes any API requests within that period then it will not expire until it is revoked by the owner. (A token revoking API endpoint will be available in the future)
Request Authorisation Token
curl \
-X POST \
-d username=example@safetyculture.io \
-d password=secret \
-d grant_type=password \
"https://api.safetyculture.io/auth"
The response will look like the following:
{
"access_token": "b7f8f791920c1618ace0e24b4d52ce260473dad870e7bd56b869f8d2f26e554d",
"token_type": "Bearer"
}
To generate an authorisation token, you must make a request to the https://api.safetyculture.io/auth endpoint with a
valid username and password that has access to the iAuditor API. 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 username requesting an authorisation token |
password |
The password of the iAuditor user |
grant_type |
Only password is supported as a value |
You do not supply a client ID and client secret at present.
Response
The response will have the content type application/json and include the following parameters:
| Parameter | Description |
|---|---|
access_token |
The token that can be used in the authorisation header for future requests |
token_type |
The type of access token returned. Will always be Bearer |
Errors
The errors for this method follow the OAuth specification. If an OAuth error occurs, the status code will be
400 Bad Request and the format of the body will differ 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, you may receive a 403 Forbidden if the user in question doesn’t have
access to the iAuditor API.
Users and Groups
Add User
The Add User endpoint allows an administrator (user with Admin permission) to add a user to their organisation.
This is a synchronous call which 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 user added will receive an email notifying them they have been added to the organisation.
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:
- If a password was submitted for that user in the
Add Userrequest, 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. - If no password was submitted for that user in the the
Add Userrequest and thereset_password_requiredflag was set totruefor that user in the request, then that user receives an email notifying them they have been added to the organisation 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. - If no password was submitted for that user in the the
Add Userand thereset_password_requiredflag was set tofalsefor that user in the request (the default behaviour), then that user receives an email notifying them they have been added to the organisation 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 organisation 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 organisation 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. The ability to reset a user’s password will be implemented in future.
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 organisation |
| 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 User
The Update User endpoint allows administrators (users with the Admin permission) to update any of the following user properties:
- username (email address)
- first name
- last name
- status (
activeorinactive)
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 organisation 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 User
Allows administrators (users with the Admin permission) to remove a user from a specified group or from their organisation.
To remove a user from a user group, the following conditions must be satisfied:
- The requesting user cannot remove themselves
- Only users with the
Adminpermission can remove other users - Administrators (users with
Adminpermission) can remove other administrator users from any group in the organisation - If the user to be removed belongs to a group with
Adminpermission they inherit theAdminpermission. In that case the user can only be removed from the group if they are not the only administrator in the organisation. After removal from the group the user loses the previously inheritedAdminpermission. - The last remaining user with
Adminpermission in the organisation cannot be removed
Remove a user with user ID
To lookup the user ID required by the remove user endpoint use the Search Users endpoint.
curl \
-X DELETE “https://api.safetyculture.io/groups/role_01ca38a821504cda885736cccbb9ba40/users/user_22ca38a821504cda885736cccbb9ba40" \
-H “Authorization: Bearer …”
The above command returns a JSON object structured like this
{"ok": true}
HTTP Request
DELETE https://api.safetyculture.io/groups/<group_id>/users/<user_id>
URL Parameters
| Parameter | Description |
|---|---|
group_id |
The ID of the organisation or a group within the organisation to remove the user from |
user_id |
The ID of the user to remove |
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 ID/ organisation ID or the user ID specified was not found |
See the Errors section for more details.
Add User to Group
The Add User to Group endpoint allows any user with Group Management permissions to add a user to a group within their organisation.
A user can only be added to a group within the requesting user’s organisation and only users within the requesting user’s organisation 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 organisation of the requesting user or the group does not belong to the organisation of the requesting user |
See the Errors section for more details.
List Users in Group
The List Users in Group endpoint allows administrators (users with the Admin permission) to list users in their organisation or a group within their organisation.
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 organisation. 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 organisation |
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 ..."
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 organisation 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 ..."
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 organisation 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.
Get Organisation Groups
The Get Organisation Groups endpoint allows administrators (users with the Admin permission) to list all the groups in their organisation.
This endpoint lists all groups in the organisation 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 organisation |
See the Errors section for more details.
Get Groups
curl "https://api.safetyculture.io/share/connections" \
-H "Authorization: Bearer ..."
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.
Audits
The iAuditor API contains a read-only interface to your audit data. There are methods to retrieve audits, their media, and to search for particular audits.
Search Audits
curl "https://api.safetyculture.io/audits/search?field=audit_id&field=modified_at" \
-H "Authorization: Bearer ..."
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 audit search endpoint allows you to retrieve the audit ID, modification date, and template ID of audits that meet a certain criteria. It is possible to request audits between given dates, based on a particular template, and whether or not to include archived audits.
This allows you to find particular audits, to gradually retrieve the audit IDs of every audit that you have access to, or to retrieve audits 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 audit ID will be always included in every audit result returned in the response.
To include other audit 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 ..."
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 ..."
To modify the order in which audits are returned, an optional param order can be given. order defaults to asc
meaning audits 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 audits 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 audit was modified. This will ensure that you may consistently find all of the audits 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 ..."
curl "https://api.safetyculture.io/audits/search?field=audit_id"\
"&template=template_37afc5890aa94e778bbcde4fc4cbe480"\
"&template=template_FCB63052F0D445AEB52F25DE6BEB8D40" \
-H "Authorization: Bearer ..."
Searching by template allows you to find all of the audits created from a certain template. You may specify one or more
template parameters to search for. The template ID can be obtained from an audit, 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 ..."
curl "https://api.safetyculture.io/audits/search?field=audit_id&owner=other" \
-H "Authorization: Bearer ..."
Including archived audits:
curl "https://api.safetyculture.io/audits/search?field=audit_id&archived=both" \
-H "Authorization: Bearer ..."
By default, archived audits are not included in the search. The archived parameter allows you to decide whether to
search only archived audits (true), not search archived audits (false), or search all audits including those
archived (both).
Including only completed audits:
curl "https://api.safetyculture.io/audits/search?field=audit_id&completed=true" \
-H "Authorization: Bearer ..."
Complete and incomplete audits 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 audits, false to search only
incomplete audits, or both to search all audits.
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 audits in each request. The limit is a maximum, and fewer audits may be returned
than the limit, even if there are more available within the search parameters. This can occur if two or more audits
have the same modified_at across the limit boundary, in which case no audits with that timestamp are returned,
allowing you to correctly retrieve the next “page” using the modified_after parameter.
The audits are returned in ascending order from the earliest first, up to the limit specified. More audits can be
retrieved by repeating the search, using the modified_at of the last audit 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 audit to retrieve. Valid values are audit_id, template_id and modified_at. Multiple field parameters may be specified. |
modified_before |
Only search for audits 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 audits 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 audits 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 audits with the given ownership. Valid values are me (audits owned by the current user), other (audits 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 audits. Valid values are true (search only archived audits), false (do not search archived audits) or both (search all audits including those archived). The default is false. |
completed |
Whether to search completed audits. Valid values are true (search only completed audits), false (do not search completed audits) or both (search all audits including those completed). The default is both. |
limit |
The maximum number of audits to retrieve. The maximum value is 1000. The default is also 1000. |
order |
The order in which audits 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 audits matching the search results. Each audit is an object containing the fields specified in the request. |
count |
The number of audits returned by this request. |
total |
The total number of audits that could have been returned by this search if it were unlimited. |
Get Audit
curl "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40" \
-H "Authorization: Bearer ..."
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 audit with the supplied audit ID. The audit response contains the information recorded in the audit, as well as relevant parts of the original template at the time the audit 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 audit to retrieve |
Response
A description of the audit format can be found in the Audit Format section.
Modify Audit
The endpoint allows you to modify certain properties of an existing audit. Specifically the following can be updated:
a) The archived property to archive or un-archive the audit
b) The responses of certain items in the header_items and items portion of the audit
The supported items whose response can be updated with this endpoint are the same as those for pre-filling when the audit 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 audit responses will set the author of this audit to the user account connected to the API and making the change. If the update is only to archive or un-archive the audit the author of the audit will not be changed.
Removing permissions from an audit is on our roadmap.
Caveats:
- Simultaneous updates to the same audit may result in concurrency errors. Prefer sequential updates to avoid these.
- 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 audit item to appear as having no response selected in the audit.
| Parameter | Description |
|---|---|
| archived | Boolean indicating if you want to archive or un-archive the audit |
| header_items | Array of any audit header items with updated responses |
| items | Array of any audit items with updated responses |
curl -X PUT "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40" \
-d '{
"archived": true,
"header_items": [
{
"item_id": "f3245d40-ea77-11e1-aff1-0800200c9a66",
"type": "textsingle",
"responses": {
"text": "Updated audit title"
}
}
]
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ..."
The above command will modify the audit and reply 200 OK. The response will contain the full audit.
{
"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": "f3245d40-ea77-11e1-aff1-0800200c9a66",
"type": "textsingle",
"responses": {
"text": "Updated audit title here"
}
},
[...]
]
}
Response
The successful response contains the updated audit. See the Get Audit endpoint.
| Status code | Description |
|---|---|
| 200 OK | Change successful |
| 400 Bad Request | Invalid request e.g. malformed audit ID or request payload |
| 403 Forbidden | The user does not have permission to view or to edit the audit with the given audit ID |
| 404 Not Found | The audit ID specified was not found |
See the Errors section for more details.
Get Audit Link
curl -X POST "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/deep_link" \
-H "Authorization: Bearer ..."
The above command returns JSON structured like this:
{
"url": "http://sfty.io/q1Af/PBByr3nTVA"
}
This endpoint generates a URL to the audit with the supplied audit 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 audit 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 audit to generate a link for |
Response
The generated URL is returned.
Get Audit Web Report Link
curl -X GET "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/web_report_link" \
-H "Authorization: Bearer ..."
The above command returns JSON structured like this:
{
"url": "https://reports.safetyculture.io/audit/b205b3422db0a7b97ec3120a9f4a97ba6fd1baa50534bb5710d24e43a94beea0/"
}
This endpoint returns the URL to the web report of the audit with the supplied audit 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 audit 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 audit ID |
| 403 Forbidden | The user does not have permission to access the audit with audit ID |
| 404 Not Found | The audit ID specified was not found |
See the Errors section for more details.
Delete Audit Web Report Link
curl -X DELETE "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/web_report_link" \
-H "Authorization: Bearer ..."
The above command returns a response with no content on successful completion.
This endpoint de-activates the URL to the web report of the audit with the supplied audit 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 audit 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 audit ID |
| 403 Forbidden | The user does not have permission to access the audit with audit ID |
| 404 Not Found | The audit ID specified was not found |
| 410 Gone | Link has been already de-activated |
See the Errors section for more details.
Start Audit
curl -X POST "https://api.safetyculture.io/audits" \
-d '{"template_id": "template_BB29F82814B64F559A33BF7CAA519787"}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ..."
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 audit with a pre-filled
Conducted onheader 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 ..."
Example request to start an audit with a pre-filled
Audit Titleheader item
curl -X POST "https://api.safetyculture.io/audits" \
-d '{
"template_id": "template_BB29F82814B64F559A33BF7CAA519787",
"header_items": [
{
"item_id": "f3245d40-ea77-11e1-aff1-0800200c9a66",
"label": "Audit Title",
"type": "textsingle",
"responses": {
"text": "<Enter custom audit title here>"
}
}
]
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ..."
Example request to start an audit with a
questionitem 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 ..."
This endpoint creates a new audit from a template specified by a template ID. The response contains the information of the newly created audit.
HTTP Request
POST https://api.safetyculture.io/audits
Starting an empty audit from template
To simply create an audit without pre-filling any responses send only the template_id in the request body as shown in the examples of this section.
Starting an audit with pre-filled responses
The type of audit items that can be pre-filled at audit creation time at present are: text, textsingle, address, datetime, question, list, checkbox, slider and switch.
Pre-fill responses by copying an existing audit
The easiest way to construct pre-filled item responses is by retrieving the information of an existing audit 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 audit request. See Get Audit for how to retrieve audit information. Tip: It is often enough to copy the entire audit information returned this way into the start audit 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 audit 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 Audit 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 audit 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 audit 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
- The
item_idof standard header items are always the same across all templates.
Pre-fill multi-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 audit 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 audit that you know has the desired responses filled in as appropriate.
Notes on audit creation
The created_at, modified_at, audit_data.date_started and audit_data.date_modified properties of the new audit are set and managed by the iAuditor platform. The Conducted on header item can be pre-filled by providing a UTC ISO8601 timestamp for it in the start audit request body as shown in the examples of this section or changed later via editing the audit. NB: It is up to the caller of the API to convert timestamp responses to UTC before making the request.
The owner and author of the created audit will be the user who is making the API request. Note: the author will change automatically the next time the audit is edited and saved by another user.
Auto-sharing properties are not currently inherited from the template for audits created via the API. See Share audit for how to share created audits with other users or groups.
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 audit 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 audit or an error.
| Status code | Description |
|---|---|
| 201 Created | The information of the new audit (see the Audit 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 Audit
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 ..."
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 audit 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 ..."
This endpoint allows you to share an audit with one or more users and/or groups. To find the IDs of users and groups that the authenticated user can share audits with see Search Users and Get Groups.
You can only share audits for which you have edit or delete permission.
You can only share with users and groups that are:
- already registered with SafetyCulture (not external users)
- members of at least one of the groups you are a member of
If the audit 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 audit 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 audit 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 audit that was modified. The sharing details are not included for security reasons.
| Error | Description |
|---|---|
| 403 Forbidden | The audit is not accessible to the user or the user does not have “edit” or “delete” permission to share the specified audit or at least one of the user or group IDs the user is trying to share the audit 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 ..."
The media endpoint allows you retrieve the media items associated with a particular audit. These can be identified by
the href elements in the media items of the audit 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 audit 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 audit to retrieve |
| media ID | The ID of the media within the audit 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.
Initiate Audit Export
The export endpoints allow you to retrieve an audit 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 ..."
The above command returns JSON structured like this:
{
"id": "94a427d1-1bd1-4f76-b3a5-4c5de1c75a3f"
}
The audit 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 audit 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. |
Poll for Completion of Audit Export
curl "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/exports/94a427d1-1bd1-4f76-b3a5-4c5de1c75a3f" \
-H "Authorization: Bearer ..."
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 audit to retrieve |
| export ID | The ID of the audit 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” |
Get Audit 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 ..."
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 audit to retrieve |
| export ID | The ID of the audit export |
| filename | The name of the document generated by the export process |
Response
The body of the response is the document itself.
Export Profiles
Search Export Profiles
curl "https://api.safetyculture.io/export_profiles/search?template=template_3E631E46F466411B9C09AD804886A8B4" \
-H "Authorization: Bearer ..."
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 audit 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 |
Get Export Profile
curl "https://api.safetyculture.io/export_profiles/template_3E631E46F466411B9C09AD804886A8B4:E15A6525-EFA5-4835-92F0-D11CA9F364F3" \
-H "Authorization: Bearer ..."
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 ..."
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 ..."
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 ..."
To modify the order in which templates are returned, an optional param 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 ..."
curl "https://api.safetyculture.io/templates/search?field=template_id&owner=other" \
-H "Authorization: Bearer ..."
Including archived templates:
curl "https://api.safetyculture.io/templates/search?field=template_id&archived=both" \
-H "Authorization: Bearer ..."
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. |
Actions
Actions represent information iAuditor users have entered about corrective actions associated with particular audits.
Actions are associated with an audit and optionally with a particular audit item. An Action may be assigned to a single user from within the requesting user’s organisation or to an external user. In the case of external users, their email address is used instead of an iAuditor user ID. To lookup the iAuditor user ID of a user within your organisation by email in order to assign an Action to, see Search Users.
If the user is the creator or the assignee of an Action then they have permission to view and edit it. Additionally, if a user has permission to view an audit then they can also view and edit all Actions associated with that audit.
Action Format
Each Action contains the following properties
| Parameter | Description |
|---|---|
type |
This is always action for Actions |
action_id |
The system-generated ID of the Action |
description |
The text description of the Action (maximum 2000 characters) |
status |
The status code of the Action (see below) |
priority |
The priority code of the Action (see below) |
audit.audit_id |
The ID of the (single) audit associated with the Action |
audit.name |
The name of the audit associated with the Action |
item.item_id |
The ID of the (single) audit item associated with the Action |
item.label |
The label of the audit item associated with the Action |
created_by.user_id |
The ID of the user who created the audit |
created_by.name |
The name of the user who created the audit |
assignees |
An array of users this Action has been assigned to (Note: currently a single assignee is supported here) |
assignees[x].id |
The user ID of the assignee (or the email if not within the same organisation as the requesting user) |
assignees[x].name |
The name of the assignee |
assignees[x].type |
The type of the assignee (user if within the same organisation as the requesting user or email otherwise) |
due_at |
The date/time this Action is due |
created_at |
The date/time this Action was created |
modified_at |
The date/time this Action was last modified |
completed_at |
The date/time this Action was completed (with any of the completed status codes) |
Actions have the following status codes:
| Status code | Description |
|---|---|
| 0 | To Do |
| 10 | In Progress |
| 50 | Done |
| 60 | Cannot Do |
Actions have the following priority codes:
| Priority code | Description |
|---|---|
| 0 | None |
| 10 | Low |
| 20 | Medium |
| 30 | High |
Search Actions
curl -X POST "https://api.safetyculture.io/actions/search \
-d '{
"audit_id": ["audit_37afc5890aa94e778bbcde4fc4cbe480", "audit_47afc5890aa94e778bbcde4fc4cbe480"],
"assignees": [
{
"id": "user_37afc5890aa94e778bbcde4fc4cbe480",
"type": "user"
}
],
"created_at": {
"from": "2017-06-02T07:30:51.652Z",
"to": "2018-06-02T07:30:51.652Z"
}
}' \
-H "Authorization: Bearer ..." \
-H "Content-Type:application/json"
The above command returns JSON structured like this
{
"count": 1,
"total": 1,
"offset": 0,
"actions": [
{
"type": "action",
"action_id": "action_08620d17f16d4daf92757cac2a604279",
"audit": {
"audit_id": "audit_cbb2b3e419574c18b2cc46fb79ab9675",
"name": "Job Site Inspection"
},
"item": {
"item_id": "fd493841-f182-4afa-9200-45a069621ce5",
"label": "Is sidewalk clean?"
},
"description": "Sidewalk clean action",
"priority": 0,
"status": 0,
"assignees": [
{
"id": "user_37afc5890aa94e778bbcde4fc4cbe480",
"name": "John Cleaner",
"type": "user"
}
],
"created_by": {
"user_id": "user_80a0569c75c211e49ed3001b1118ce11",
"name": "Fred Inspector"
},
"created_at": "2017-06-02T07:30:51.652Z",
"modified_at": "2017-06-05T00:17:51.248Z",
"due_at": "2016-02-01T06:30:48.000Z",
"completed_at": null
}]
}
This endpoint allows you to retrieve information about Actions generated by iAuditor users.
HTTP Request
POST https://api.safetyculture.io/actions/search
The payload of the request may contain one or more search criteria from the ones below:
| Key | Type | Description |
|---|---|---|
audit_id |
Array of String | Show only Actions from these audit IDs |
item_id |
Array of String | Show only Actions from these item IDs |
status |
Array of Number | Show only Actions with these status codes |
priority |
Array of Number | Show only Actions with these priority codes |
created_at |
Object | Show only Actions within the given created date |
created_at.from |
DateTime | Show only Actions created after this date (optional) |
created_at.to |
DateTime | Show only Actions created before this date (optional) |
modified_at |
Object | Show only Actions within the given modified date |
modified_at.from |
DateTime | Show only Actions modified after this date (optional) |
modified_at.to |
DateTime | Show only Actions modified before this date (optional) |
due_at |
Object | Show only Actions within the given due date |
due_at.from |
DateTime | Show only Actions due after this date (optional) |
due_at.to |
DateTime | Show only Actions due before this date (optional) |
assignees |
Array | Show only Actions assigned to these users |
assignees[x].id |
String | The user ID of the assignee (or the email if not within the same organisation as the requesting user) |
assignees[x].type |
String | The type of the assignee (user if within the same organisation as the requesting user or email otherwise) |
match_text |
String | Show only Actions whose description matches this text |
offset |
Integer | Show search results from this index (offset) onwards |
limit |
Integer | Show this many results in the search at most |
If no search criteria are given, no filter will be applied and the first page of Action search results will be returned. The default page limit for search results is 100. That is also the maximum limit applicable.
To retrieve all search results, repeat the search adjusting the offset accordingly until all results have been returned.
The sort order of the returned actions is currently fixed to be by created_at date.
Response
The response will have the content type application/json and the response payload will include the following parameters:
| Parameter | Description |
|---|---|
count |
The number of Actions found |
total |
The total number of Actions that can be retrieved for this search |
offset |
The results returned start from this offset index onwards. The number of results shown is controlled by the limit property of the request payload. |
actions |
An array of Actions found |
Each Action in the actions array will have the mentioned Action Format.
| Status code | Description |
|---|---|
| 200 OK | Action search request was successful |
| 400 Bad Request | Invalid request |
See the Errors section for more details.
Get Action
The Get Action endpoint allows a user with the right permissions to retrieve the details of an individual Action given the ID of that Action.
curl “ https://api.safetyculture.io/actions/action_08620d17f16d4daf92757cac2a604279" \
-H “Authorization: Bearer …”
The above command returns JSON structured like this
{
"type": "action",
"action_id": "action_08620d17f16d4daf92757cac2a604279",
"audit": {
"audit_id": "audit_cbb2b3e419574c18b2cc46fb79ab9675",
"name": "Job Site Inspection"
},
"item": {
"item_id": "fd493841-f182-4afa-9200-45a069621ce5",
"label": "Is sidewalk clean?"
},
"description": "Remove safety hazard",
"priority": 30,
"status": 0,
"assignees": [
{
"id": "user_37afc5890aa94e778bbcde4fc4cbe480",
"name": "John Cleaner",
"type": "user"
}
],
"created_by": {
"user_id": "user_80a0569c75c211e49ed3001b1118ce11",
"name": "Fred Inspector"
},
"created_at": "2017-06-02T07:30:51.652Z",
"modified_at": "2017-06-05T00:17:51.248Z",
"due_at": "2018-07-21T00:00:00Z",
"completed_at": null
}
HTTP Request
GET https://api.safetyculture.io/actions/<action_id>
URL Parameters
| Parameter | Description |
|---|---|
| action_id | The ID of the Action to retrieve |
Response
The response will have the content type application/json and will have the Action Format.
| Status code | Description |
|---|---|
| 200 OK | Action details retrieved successfully |
| 400 Bad Request | Invalid request |
| 403 Forbidden | The user does not have permission to retrieve this Action |
See the Errors section for more details.
Create Action
curl \
-X POST “ https://api.safetyculture.io/actions "\
-H “Authorzation: Bearer …” \
-H “Content-Type:application/json” \
-d `{
"audit_id": "audit_cbb2b3e419574c18b2cc46fb79ab9675",
"item_id": "fd493841-f182-4afa-9200-45a069621ce5",
"description": "Remove safety hazard",
"priority": "30",
"status": "0",
"due_at": "2018-07-21T00:00:00Z",
"assignees": [
{
"type": “user",
"id": "user_37afc5890aa94e778bbcde4fc4cbe480"
}
]
}`
The above command returns JSON structured like this
{
"type": "action",
"action_id": "action_08620d17f16d4daf92757cac2a604279",
"audit": {
"audit_id": "audit_cbb2b3e419574c18b2cc46fb79ab9675",
"name": "Job Site Inspection"
},
"item": {
"item_id": "fd493841-f182-4afa-9200-45a069621ce5",
"label": "Is sidewalk clean?"
},
"description": "Remove safety hazard",
"priority": 30,
"status": 0,
"assignees": [
{
"id": "user_37afc5890aa94e778bbcde4fc4cbe480",
"name": "John Cleaner",
"type": "user"
}
],
"created_by": {
"user_id": "user_80a0569c75c211e49ed3001b1118ce11",
"name": "Fred Inspector"
},
"created_at": "2017-06-02T07:30:51.652Z",
"modified_at": "2017-06-05T00:17:51.248Z",
"due_at": "2018-07-21T00:00:00Z",
"completed_at": null
}
HTTP Request
POST https://api.safetyculture.io/actions
Request Body
The body should use the content type application/json. Any of the following Action properties can be provided in the body of the request:
| Parameter | Description |
|---|---|
description |
The text description of the Action |
status |
The status code of the Action |
priority |
The priority code of the Action |
assignees |
An array of users this Action has been assigned to |
assignees[x].id |
The user ID of the assignee (or the email if not within the same organisation as the requesting user) |
assignees[x].type |
The type of the assignee (user if within the same organisation as the requesting user or email otherwise) |
due_at |
The date/time this Action is due |
Response
The response will have the content type application/json and will have the Action Format.
| Status code | Description |
|---|---|
| 200 OK | Action created successfully |
| 400 Bad Request | Invalid request |
| 403 Forbidden | The user does not have permission to create the Action |
See the Errors section for more details.
Update Action
The Update Action endpoint allows a user to update certain properties of an existing Action. If the user is not the creator or the assignee of the Action they must have permission to edit the corresponding audit in order to be able to update the Action. Partial updates are supported. For example, if an Action property is not given in the update request body it will not be updated.
curl \
-X PUT “ https://api.safetyculture.io/actions/action_7db5002c72754d2a99ac1e4b82f088be "\
-H “Authorization: Bearer …” \
-H “Content-Type:application/json” \
-d `{
"description": "updated description",
"status": 50
}`
The above command returns JSON structured like this
{
"type": "action",
"action_id": "action_08620d17f16d4daf92757cac2a604279",
"audit": {
"audit_id": "audit_cbb2b3e419574c18b2cc46fb79ab9675",
"name": "Job Site Inspection"
},
"item": {
"item_id": "fd493841-f182-4afa-9200-45a069621ce5",
"label": "Is sidewalk clean?"
},
"description": "Updated description",
"priority": 0,
"status": 50,
"assignees": [
{
"id": "user_37afc5890aa94e778bbcde4fc4cbe480",
"name": "John Cleaner",
"type": "user"
}
],
"created_by": {
"user_id": "user_80a0569c75c211e49ed3001b1118ce11",
"name": "Fred Inspector"
},
"created_at": "2017-06-02T07:30:51.652Z",
"modified_at": "2017-06-05T00:17:51.248Z",
"due_at": "2016-02-01T06:30:48.000Z",
"completed_at": null
}
HTTP Request
PUT https://api.safetyculture.io/actions/<action_id>
URL Parameters
| Parameter | Description |
|---|---|
action_id |
The ID of the Action to update. |
Request Body
The body should use the content type application/json. The following Action properties can be updated:
| Parameter | Description |
|---|---|
description |
The text description of the Action |
status |
The status code of the Action |
priority |
The priority code of the Action |
assignees |
An array of users this Action has been assigned to |
assignees[x].id |
The user ID of the assignee (or the email if not within the same organisation as the requesting user) |
assignees[x].name |
The name of the assignee |
assignees[x].type |
The type of the assignee (user if within the same organisation as the requesting user or email otherwise) |
due_at |
The date/time this Action is due |
Response
The response will have the content type application/json and will have the Action Format.
| Status code | Description |
|---|---|
| 200 OK | The Action was successfully updated |
| 400 Bad Request | Invalid request or payload |
| 403 Forbidden | The user does not have permission to update the Action |
| 404 Not Found | The Action was not found |
See the Errors section for more details.
Delete Action
The Delete Action endpoint allows a user with the right permissions to delete an Action. More specifically, an Action can be deleted by the user who created it or by any user who has the permission to delete the corresponding audit.
curl \
-X DELETE “ https://api.safetyculture.io/response_sets/action_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/actions/<action_id>
URL Parameters
| Parameter | Description |
|---|---|
action_id |
The ID of the action to delete |
Response
The response for this request will be one of the following:
| Status code | Description |
|---|---|
| 204 No Content | Deletion successful |
| 400 Bad Request | Invalid request |
| 403 Forbidden | The user does not have permission to delete the action |
| 404 Not Found | The action ID specified was not found |
See the Errors section for more details.
Webhooks
Webhooks allow third-party services to receive near real-time audit event notifications from SafetyCulture.
Webhooks are seen as one type of workflow that can be setup to be executed automatically when particular audit events happen. Future workflows may include the ability to generate an audit report automatically, send an email/sms or combine multiple action steps each time an audit 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 audit event like audit_completed takes place.
Any audit 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 audit 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_startedevent
{
"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 Audits functionality can help client code verify which audits changed in a given date range and to compare with received wehbooks to ensure completeness.
When audits 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 audits are synced to the SafetyCulture backend.
In the following sections we describe how to perform CRUD operations on webhook workflows.
Register workflows
curl \
-H "Authorization: Bearer ..." \
-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 audit responses, the audit_updated event will be triggered when the audit is started or the audit’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 audit 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 audit 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.
Get workflow
curl "https://api.safetyculture.io/workflows/workflow_37afc5890aa94e778bbcde4fc4cbe480 \
-H "Authorization: Bearer ..." \
-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 audit 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.
Get workflows
curl "https://api.safetyculture.io/workflows?org_id=role_37afc5890aa94e778bbcde4fc4cbe480" \
-H "Authorization: Bearer ..." \
-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 audit 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.
Update workflows
curl \
-X PUT "https://api.safetyculture.io/workflows/<workflow_id>" \
-d '{"trigger_events":["audit_started"]} \
-H "Authorization: Bearer ..." \
-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 audit 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 audit 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.
Delete workflows
curl \
-X "DELETE" "https://api.safetyculture.io/workflows/<workflow_id>" \
-H "Authorization: Bearer ..." \
-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.
Response Sets
A response set is a collection of responses. Endpoints are provided to manipulate response sets as well as individual responses within them.
Create 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 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.
Get 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 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 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 "\
-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.
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 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.
Audit Format
This section describes the complete audit 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 audit’s ID |
template_id |
String | ID of the parent template |
archived |
Boolean | Is the audit archived or not |
created_at |
String | ISO date and time when the audit was first synced to the cloud or created on SafetyCulture |
modified_at |
String | ISO date and time when the audit was last synced to the cloud or modified on SafetyCulture |
audit_data |
Object | General information about the audit (dates, author, scores, GPS location, etc.) |
template_data |
Object | Some information on the template (predefined response sets, author, images, etc.) |
header_items |
Array | Audit header items (first page, optional) |
items |
Array | Items in all sections after the header (basically the answers to the questions and other line items) |
Audit Data
.audit_data
Audit 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": {}
}
| Key | Type | Description |
|---|---|---|
name |
String | Name of the audit |
score |
Double | Score of the audit |
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 audit (on a device or on SafetyCulture) in seconds |
date_started |
String | A time and date when the audit was started (on a device or on SafetyCulture) |
date_modified |
String | A time and date when the audit was last modified (on a device or on SafetyCulture) |
date_completed |
String | A time and date when the audit was completed (on a device or on SafetyCulture) |
authorship |
Object | Information on the authorship of the audit |
location |
Object | The device (GPS) location of where the audit was started and completed (if GPS was enabled on the device) |
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 audit. Initially it’s the same as the owner. |
author_id |
String | The ID of the audit author. |
owner |
String | The person who created the audit is the original owner of the audit. The owner can transfer ownership to any other person in the organisation using the iAuditor web application. |
owner_id |
String | The ID of the audit owner. |
device_id |
String | The ID of the device which was used to create the audit. Generated when the app is installed |
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 audit 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 audit |
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) |
Audit Header Items
.header_items
Same structure as Audit Items. See below.
Audit Items
.items are the responses or selections made by the auditor.
Item Root
{
"label": "Audit",
"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 audits 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",
"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
}
| Key | Type | Description |
|---|---|---|
condition |
String | The smart field condition. UUID of a response set |
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 audit 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 |
String | 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 Audit” 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 auditor |
visible_in_report |
Boolean | Represents checkbox telling if an information item should appear in reports |
weighting |
String | The weight used for generating audit scores |
Deprecated items that may appear in older audits 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 an auditor 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 | Audit 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 audit 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 |
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 |
Use Cases
The following sections describe some common use cases for the API and how to best achieve them.
Starting audits automatically with pre-filled information
Being able to start and share audits automatically makes it easier for developers to build custom solutions that:
- schedule audits to be created at particular times,
- pre-fill audit information from external data sources or from previously completed audits,
- trigger custom actions like reminders or other notifications from third-party providers to be executed before and/or after audits get created
and more.
With automation services (like Zapier, IFTTT, MS Flow etc.) work flows similar to the above can be achieved without any development effort.
One common use case example is where a supervisor wants an audit 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 audit 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 audit, 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:
- Start Audit to create an audit against a specified template
- Search users (or Search groups) to discover the IDs of the users (or groups) to share the audit with in order to conduct it
- Share audit with the IDs from the previous step
If the user/group IDs to share the audit with are already known, the second step is not needed and the process can be simplified to two steps:
- Start Audit to create an audit against a specified template
- Share audit 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 audit or delete to also permit users to delete the shared audit. The person conducting the audit does not need access to the template which also avoids the possibility of audits started (e.g. using the iAuditor application) outside the control of the supervisor.
In our example use case above, the supervisor creating the audit will always be the owner of the created audit but may not always be the author as well. The author of the created audit is the last user who made any change to the audit.
Any “auto-sharing” properties configured in the template that was used to start the audit are inherited at audit creation time so the audit is automatically shared with the users and groups configured within the template. For instance, in our use case above, the supervisor creating the audit may have configured the template so that audits created from it are automatically shared with the management group.
Now that an audit can be started and shared automatically, the supervisor may decide they want an audit to start at pre-configured regular (or irregular) times e.g. a weekly audit 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 Audit and Share audit API endpoints as shown above.
Especially in the case of repeatedly conducted audits, it can be a tedious task to copy information from other systems or from previous audit responses to pre-fill certain items of the newly created audit. Pre-filling such information using the API makes this problem go away for many types of audit 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 audit gets automatically created as a result and shared with the user to conduct the inspection. The audit title, equipment location, serial number and description of the work order are pre-filled into the audit 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 ..."
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 Audit API capability, the supervisor requests from the API to start an audit and pre-fill the audit title response with
- the equipment serial number
- the name of the person to conduct the audit (note: not shared with them yet, will do in the next step)
Create a new audit 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": "Audit 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 ..."
The above command returns the JSON content of the created audit (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 audit are both the supervisor at this stage. The new audit is immediately accessible (e.g. in iAuditor or via Search Audits) 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 audit 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 audit
curl -X POST "https://api.safetyculture.io/users/search" \
-d "{"email": ["john.citizen@safetyculture.io"]}}" \
-H "Authorization: Bearer ..."
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 audit with John Citizen using the Share Audit API capability. Sharing with edit permission allows John Citizen to complete the audit but not delete it for increased security.
Share the created audit with John Citizen (user_c4e2421223b5497186bb8ea4e4159fcc) with
editpermission
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 ..."
John Citizen can now see and conduct the audit using iAuditor which makes him the author of the audit. The supervisor remains the owner and maintains access to the audit at all times.
Extracting all historical audit 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 audit data:
- Retrieve all the available audit identifiers
- Retrieve the corresponding audit data for each identifier
- Retrieve the media associated with each audit
Retrieve all the available audit identifiers
curl "https://api.safetyculture.io/audits/search?field=audit_id&field=modified_at" \
-H "Authorization: Bearer ..."
{
"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 audit IDs, you will use the process as described in the Search Audits section of the documentation. You can then use the IDs from the audit_id field of each record in the audits 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 ..."
If you have more than 1000 audits, 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 audit. Repeat this process until all of the audits have been retrieved.
Retrieve the corresponding audit data for each identifier
curl "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40" \
-H "Authorization: Bearer ..."
Given the list of audits retrieved in the previous step, the audits may then be retrieved individually, as described in Get Audit.
The audit data can then be stored or processed as desired within your own systems, using the Audit Format as a guide to the data available.
Retrieve the media associated with each audit
Finally, you may decide that you need to retrieve the media for some or all of the audits. To do so, for each of the audits retrieved above, find all of the elements that contain media. This includes:
- All
header_itemswith amediaelement - All
itemswith amediaelement - All
optionswithin an item or header item that contain amediaelement - All
responseswithin an item or header item that contain amediaorimageelement
curl "https://api.safetyculture.io/audits/audit_01ca38a821504cda885736cccbb9ba40/media/9E3BD015-6275-4668-BAF1-296B2F38444C" \
-o 9E3BD015-6275-4668-BAF1-296B2F38444C.jpg \
-H "Authorization: Bearer ..."
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.
Getting modified audits
curl "https://api.safetyculture.io/audits/search?field=audit_id&field=modified_at&modified_after=2015-03-24T06:31:47.203Z" \
-H "Authorization: Bearer ..."
Once you have extracted all of the historical data, the next obvious step is to retrieve the modified audits so that you can continue populating your own systems with new audit data. This function is also useful for producing regular updates from your audit data, such as a live dashboard.
To do this, you will search for audits that are either after the last audit that you have, or the last time you attempted to retrieve new audits, 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 audits modified since you last retrieved data, and often may contain no audits 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 audit content and media.
Note that the audits retrieved in this request may return identifiers that you have previously retrieved if the audit it points to has been modified. You should ensure that this overwrites any audit data that exists in your own system rather than duplicating them.
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 audit data exporting tool.
Javascript SDK
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.
Changelog
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 audit.
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: Audit data now contains GPS location of audit started and completed points in the audit_data property of the audit
2017-04-06: Added ability to archive and un-archive audits (see Modify audit)
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.
API Reference
The API reference auto-generated from our Swagger spec can be found on this page where you can also make requests to the iAuditor API right from your browser. To make authenticated requests from that page you will need to use an API access token that you can generate on your account profile details page inside the SafetyCulture application.
Limits
Rate Limiting
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 |
|---|---|---|
| All | 1000 | 60 seconds |
A stricter policy (currently in review, not yet enabled) will be introduced in future as shown below.
| Endpoint | Rate | Interval |
|---|---|---|
| POST /auth | 5 | 60 seconds |
| POST /audits/ |
20 | 60 seconds |
| Other | 500 | 60 seconds |