The iAuditor API gives you direct access to your data in the iAuditor platform. Using the API, you can interact with your organization’s actions data in a range of ways. Including the ability to search and retrieve, as well as create and update actions.

This article shows you how to interact with actions in your organization via the iAuditor API.

Before you begin

Keep in mind that you must be on our Premium subscription in order to generate an iAuditor API token and use the API.

Please note, as we improve iAuditor and introduce new features, there may be two versions or experiences of the same feature at the same time. Currently, there are two experiences of the Actions feature in iAuditor. Whilst most organizations are now on the new experience, referred to as “Collaborative Actions”, some are still on the old experience, referred to as “Legacy Actions”.

This article covers the API for the Collaborative Actions experience. You can find out which experience you are on via the steps below.

  1. Log in to the iAuditor web app.
  2. Select "Actions" from the menu on the left-hand side.
  3. If you see “+ Create action” on the upper-right corner of the page, this means that your organization is on the Collaborative Actions experience.

If you’re on the Legacy Actions experience, the API for Legacy Actions will remain available until we complete the work for the Collaborative Actions API.

Actions JSON

This section details the body format and codes you may come across when interacting with actions via the API.

Body format

ParameterDescription
typeThe body type. This field is always “actions” for actions.
action_idThe unique identifier of the action.
titleThe title of the action. Allows up to 255 characters.
siteThe site of the action.
descriptionThe description of the action. Allows up to 500 characters. 
statusThe status code of the action.
priorityThe priority code of the action.
audit.audit_idThe unique identifier of the inspection associated with the action.
audit.nameThe name of the inspection associated with the action.
item.item_idThe unique identifier of the inspection question associated with the action.
item.labelThe label of the inspection question associated with the action.
created_by.user_idThe unique identifier of the user who created the action.
created_by.nameThe name of the user who created the action.
assigneesThe array of users the action has been assigned to. Please note that each action can only have one assignee at this stage.
assignees[x].idThe unique identifier of the assignee. If the assignee is external, the assignee email would replace the unique identifier.
assignees[x].nameThe name of the assignee. If the assignee is external, the assignee email would replace the name.
assignees[x].typeThe type of assignee. Either “user” if the assignee is in the same organization or “email” if the assignee is external.
due_atThe timestamp of the due date and time in Coordinated Universal Time (UTC).
created_atThe timestamp of the creation date and time in Coordinated Universal Time (UTC).
modified_atThe timestamp of the last modified date and time in Coordinated Universal Time (UTC).

Status codes

CodeDescription
0To Do
10In Progress
50Done
60Can’t Do

Priority codes

CodeDescription
0None
10Low
20Medium
30High

Error codes

CodeDescription
200 OKThe request was successful.
400 Bad RequestThe request was invalid. See the relevant message for more details.

Search actions

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

This endpoint allows you to retrieve actions based on the filter or parameters you provide. You can download this sample code snippet to try the API for yourself.

The payload of the request may contain one or more of the following search parameters.

ParameterTypeDescription
audit_idStringReturn actions created from specific inspection(s).
item_idStringReturn actions created from specific inspection question(s).
statusStringReturn actions that are in specific status(es).
modified_at.fromDateTimeReturn actions modified after a specific date and time in Coordinated Universal Time (UTC).
modified_at.toDateTimeReturn actions modified before a specific date and time in Coordinated Universal Time (UTC).
created_at.fromDateTimeReturn actions created after a specific date and time in Coordinated Universal Time (UTC).
created_at.toDateTimeReturn actions created before a specific date and time in Coordinated Universal Time (UTC).
assigneesArrayThe array of users the action has been assigned to. Please note that each action can only have one assignee at this stage.
assignees[x].idStringThe unique identifier of the assignee. External assignees are currently not supported for the search actions endpoint.
assignees[x].typeStringThe type of assignee. As external assignees are currently not supported for the search actions endpoint, set the type to “user”.
offsetIntegerDisplay the returned search results from a specific index (offset).
limitIntegerReturn no more than a specific number of results. Each search can return a maximum of 100 results.

Please note that actions in the “Done” and “Can’t Do” statuses are not by default not included in search results unless specified in the payload. To retrieve all search results, you can repeat the search by increasing the “offset” in each repeat until all results have been returned. The results are sorted by the “modified_at” date and time.

The search actions endpoint returns the results in the “application/json” content type with the following parameters.

ParameterDescription
countThe number of actions returned.
totalThe total number of actions found in the search parameters.
offsetThe results returned start from this “offset” index onwards. The number of results shown is controlled by the “limit” parameter of the request payload.
actionsThe array of actions returned.

Get actions

GET: https://api.safetyculture.io/actions/<action_id>

This endpoint allows you to retrieve the details of an action given the unique identifier of that action. You can download this sample code snippet to try the API for yourself. Make sure to supply the unique identifier or “action_id” in the URL.

Create actions

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

This endpoint allows you to create an action, either standalone or associated with an inspection question. You can download this sample code snippet to try the API for yourself.

The payload of the request may contain one or more of the following parameters, depending on the type of action you wish to create. A standalone action, an action associated with an inspection, or an action associated with a specific question in an inspection.

ParameterDescription
audit_idThe unique identifier of the inspection associated with the action. This can be omitted for standalone actions.
item_idThe unique identifier of the inspection question associated with the action. This requires the “audit_id” parameter.
titleThe title of the action. Allows up to 255 characters.
descriptionThe description of the action. Allows up to 500 characters.
assigneesThe array of users the action has been assigned to. Please note that each action can only have one assignee at this stage.
assignees[x].idThe unique identifier of the assignee. If the assignee is external, input the email.
assignees[x].typeThe type of assignee. Either “user” if the assignee is in the same organization or “email” if the assignee is external.
statusThe status code of the action.
priorityThe priority code of the action.
due_atThe timestamp of the due date and time in Coordinated Universal Time (UTC).

Update actions

PUT: https://api.safetyculture.io/actions/<action_id>

This endpoint allows you to update the details of an existing action given the unique identifier of that action. You can download this sample code snippet to try the API for yourself. Make sure to supply the unique identifier or “action_id” in the URL.

The payload of the request must contain the following parameters. Fields that you don’t wish to update can be left unchanged with the existing action details. Please note that the “title” parameter is currently not supported for the update actions endpoint.

ParameterDescription
descriptionThe description of the action. Allows up to 500 characters.
assigneesThe array of users the action has been assigned to. Please note that each action can only have one assignee at this stage.
assignees[x].idThe unique identifier of the assignee. If the assignee is external, input the email.
assignees[x].typeThe type of assignee. Either “user” if the assignee is in the same organization or “email” if the assignee is external.
statusThe status code of the action.
priorityThe priority code of the action.
due_atThe timestamp of the due date and time in Coordinated Universal Time (UTC).
Was this article helpful?

We love your feedback. Please tell us what you think.


Yes No
Care to share a bit more so we can continue to make improvements for you? Care to share a bit more so we can make this article even better for you? Thanks for your feedback!