Manage inspection access

📘️
The endpoints described in this guide are currently in Beta and may be subject to changes without notice.

Managing inspection access allows organizations to control who can view, edit, and delete specific inspections. Here are some examples:

• Change inspection ownership to appropriate team members.
• Grant site-based access so site managers can oversee inspections at their locations.
• Share inspections with entire groups rather than individual users.

The API provides two endpoints for managing inspection access: GetInspectionAccess to retrieve the current access configuration, and SetInspectionAccess to modify it. These endpoints offer bulk configuration management, allowing you to view and update the complete access configuration in a single operation, as opposed to endpoints like ShareInspection and RemoveInspectionUserAccess, which modify access incrementally.

Access levels and actors

Before managing inspection access, it's helpful to understand the available access levels and actor types:

Access levels:

• View: Users can view the inspection but cannot make changes.
• Edit: Users can view and edit the inspection (conduct the inspection, add responses).
• Delete: Users have full access, including view, edit, and the ability to delete the inspection.

Actor types:

• User: Grant access to a specific individual user by user ID.
• Group: Grant access to all members of a group/role by group ID.
• Everyone: Grant access to all users in the inspection's organization.
• Organisation: Grant access to all users in a specific organization.
• SelectedSite: Grant access to users who are members of the site selected in the inspection (dynamic).
• SiteIntersection: Grant access to users who are members of a specific group, as well as the site selected in the inspection (dynamic).

📘

Some actor types (User, Group, Organisation) support cross-organization access through cross_org and organisation_id fields. See the Cross-organization access section for details and limitations.

Retrieve current inspection access

Before modifying inspection access, you should first retrieve the current configuration to understand who already has access. This is particularly important because SetInspectionAccess replaces the entire access configuration.

Retrieve the current access configuration for an inspection

curl "https://api.safetyculture.io/inspections/integration/v1/inspections/audit_abc123/access" \
  -H "Authorization: Bearer {api_token}"

The above command returns the current owner and permissions

{
  "inspection_identity": {
    "inspection_id": "audit_abc123",
    "organisation_id": "role_456"
  },
  "owner_id": "user_original_owner",
  "permissions": [...]
}

The response shows the inspection owner (who always has full access) and all permission rules defining who else can access the inspection and at what level.

Set inspection access

🚧

Critical: SetInspectionAccess completely replaces the access configuration with the permissions list you provide in the request. This is NOT a patch operation. Any permissions not included in your request will be removed. Be sure to always call GetInspectionAccess first to retrieve the current access configuration if you need to preserve certain permissions.

🚧

Critical: If the access rules for the template are updated and then retroactively applied to all inspections, access rules previously modified by SetInspectionAccess will be updated to follow the defined template access rules.

Example: Grant access to users and groups

A common scenario is sharing an inspection with specific team members and groups. You can grant different access levels to different users based on their role in the inspection process, and use groups for easier management.

Let's say you want to configure an inspection with:

• View access for a supervisor.
• Edit access for an inspector.
• View access for everyone in the Quality Assurance team.

Grant access to specific users and a group

curl -X PUT "https://api.safetyculture.io/inspections/integration/v1/inspections/audit_abc123/access" \
  -H "Authorization: Bearer {api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "owner_id" : "user_original_owner",
    "permissions": [
      {
        "actor": {
          "user": {
            "user_id": "user_supervisor"
          }
        },
        "access_level": "ACCESS_LEVEL_VIEW"
      },
      {
        "actor": {
          "user": {
            "user_id": "user_inspector"
          }
        },
        "access_level": "ACCESS_LEVEL_VIEW_EDIT"
      },
      {
        "actor": {
          "group": {
            "group_id": "group_qa_team"
          }
        },
        "access_level": "ACCESS_LEVEL_VIEW"
      }
    ]
  }'

The above command returns the updated access configuration

{
  "inspection_identity": {
    "inspection_id": "audit_abc123",
    "organisation_id": "org_456"
  },
  "owner_id": "user_original_owner",
  "permissions": [
    {
      "actor": {
        "user": {
          "user_id": "user_original_owner"
        }
      },
      "access_level": "ACCESS_LEVEL_VIEW_EDIT_DELETE"
    },
    {
      "actor": {
        "user": {
          "user_id": "user_inspector"
        }
      },
      "access_level": "ACCESS_LEVEL_VIEW_EDIT"
    },
    {
      "actor": {
        "user": {
          "user_id": "user_supervisor"
        }
      },
      "access_level": "ACCESS_LEVEL_VIEW"
    },
    {
      "actor": {
        "group": {
          "group_id": "group_qa_team"
        }
      },
      "access_level": "ACCESS_LEVEL_VIEW"
    }
  ]
}

🚧

Remember: This request completely replaced all previous permissions. If the inspection had other users or groups with access before, they no longer have access unless they were included in the permissions list above.

Example: Organization-wide and site-based access

For more advanced scenarios, you can use actor types that dynamically grant access based on organizational structure, sites, or combinations of sites and groups.

Let's configure an inspection with:

• Organization-wide view access (everyone can see it).
• Edit access for users associated with the site selected during the inspection.
• Delete access for users in the "Site Managers" group at a specific site.

Grant access using organization-wide, selected site, and site intersection actors

curl -X PUT "https://api.safetyculture.io/inspections/integration/v1/inspections/audit_abc123/access" \
  -H "Authorization: Bearer {api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "owner_id": "user_original_owner",
    "permissions": [
      {
        "actor": {
          "everyone": {}
        },
        "access_level": "ACCESS_LEVEL_VIEW"
      },
      {
        "actor": {
          "selected_site": {}
        },
        "access_level": "ACCESS_LEVEL_VIEW_EDIT"
      },
      {
        "actor": {
          "site_intersection": {
            "group_id": "group_site_managers"
          }
        },
        "access_level": "ACCESS_LEVEL_VIEW_EDIT_DELETE"
      }
    ]
  }'

The above command returns the updated access configuration

{
  "inspection_identity": {
    "inspection_id": "audit_abc123",
    "organisation_id": "org_456"
  },
  "owner_id": "user_original_owner",
  "permissions": [
    {
      "actor": {
        "site_intersection": {
          "group_id": "group_site_managers"
        }
      },
      "access_level": "ACCESS_LEVEL_VIEW_EDIT_DELETE"
    },
    {
      "actor": {
        "user": {
          "user_id": "user_original_owner"
        }
      },
      "access_level": "ACCESS_LEVEL_VIEW_EDIT_DELETE"
    },
    {
      "actor": {
        "selected_site": {}
      },
      "access_level": "ACCESS_LEVEL_VIEW_EDIT"
    },
    {
      "actor": {
        "everyone": {}
      },
      "access_level": "ACCESS_LEVEL_VIEW"
    }
  ]
}

Cross-organization access

🚧

Important limitation: You cannot set up new cross-organization access using SetInspectionAccess. You can only modify the access level or remove existing cross-organization access. To set up new access, you can share inspections externally via the web app.

Inspections can be shared across organizations via the web app. The actor type includes two fields for this purpose:

• cross_org: A boolean flag indicating whether this permission grants access to an entity from a different organization.
• organisation_id: The ID of the organization that the actor belongs to.

Actor type support:

• Supported: User, Group, and Organisation actors support cross-organization access.
• Not supported: Everyone, SiteIntersection, and SelectedSite actors do not support cross-organization access. The cross_org and organisation_id fields are ignored for these actor types.

What you can and cannot do with SetInspectionAccess:

When calling SetInspectionAccess:

• Cannot add: New cross-organization access cannot be created.
• Can modify: Existing cross-organization permissions can have their access_level changed (e.g., from VIEW to VIEW_EDIT).
• Can remove: Existing cross-organization permissions can be removed by omitting them from the permissions list. Once removed, they can't be added again via SetInspectionAccess.
• Cannot change cross-org status: You cannot modify the cross_org flag or organisation_id of existing permissions for User, Group, and Organisation actors.

Example: Modifying existing cross-org access

If an inspection already has cross-organization access set up, granting view access to a user from another organization, you can change their access level while leaving all the other fields the same:

{
  "permissions": [
    {
      "actor": {
        "user": {
          "user_id": "user_external_auditor"
        },
        "cross_org": true,
        "organisation_id": "org_external_123"
      },
      "access_level": "ACCESS_LEVEL_VIEW_EDIT"
    }
  ]
}

In this example, we're modifying the access level of an existing cross-org user to VIEW_EDIT. If this user didn't already have cross-org access to the inspection, this request would fail.

To remove the cross-org permission entirely, simply omit it from the permissions list (remember that SetInspectionAccess replaces all permissions).

Change the inspection owner

You can transfer ownership of an inspection by specifying a different owner_id in your SetInspectionAccess request. The owner has implicit full access to the inspection.

🚧

Permission required: The user making the request must have the "Override permissions: Manage all data" permission to change the inspection owner.

When changing ownership:

• The new owner automatically receives full access (view, edit, delete) to the inspection.
• The previous owner loses their implicit full access. You must add them to the permissions list if they need to retain access.
• The new owner must be a valid user in the same organization as the inspection.

Example: Transfer ownership to a new user

Let's say you want to transfer an inspection from the original owner to a new team lead, while giving the original owner continued edit access:

Transfer ownership and grant previous owner edit access

curl -X PUT "https://api.safetyculture.io/inspections/integration/v1/inspections/audit_abc123/access" \
  -H "Authorization: Bearer {api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "owner_id": "user_new_team_lead",
    "permissions": [
      {
        "actor": {
          "user": {
            "user_id": "user_original_owner"
          }
        },
        "access_level": "ACCESS_LEVEL_VIEW_EDIT"
      }
    ]
  }'

The above command returns the updated access configuration with the new owner

{
  "inspection_identity": {
    "inspection_id": "audit_abc123",
    "organisation_id": "org_456"
  },
  "owner_id": "user_new_team_lead",
  "permissions": [
    {
      "actor": {
        "user": {
          "user_id": "user_new_team_lead"
        }
      },
      "access_level": "ACCESS_LEVEL_VIEW_EDIT_DELETE"
    },
    {
      "actor": {
        "user": {
          "user_id": "user_original_owner"
        }
      },
      "access_level": "ACCESS_LEVEL_VIEW_EDIT"
    }
  ]
}

Best practices and tips

Access management best practices:

• Always call GetInspectionAccess first to retrieve current permissions before modifying them, since SetInspectionAccess replaces all permissions.
• The inspection owner implicitly has full access and doesn't need to be included in the permissions list, but it will be in the response.
• You can configure up to 1,000 permissions per inspection.
• All users, groups, and sites must exist and belong to the same organization (except for existing cross-organization rules, which are preserved).
• It's best to set up group-based permissions over individual user permissions for easier long-term maintenance.
• When transferring ownership using the owner_id field, explicitly add the previous owner to the permissions list if they need to retain access.

Related endpoints:

• For incremental access changes (add/remove individual permissions without replacing all), use the legacy ShareInspection and RemoveInspectionUserAccess endpoints.
• See the Remove owner's access to a completed inspection use case for a practical workflow example.