Create and install apps in SafetyCulture

You can embed a private app or marketplace app in your SafetyCulture organization in three steps:

Please note that apps are only available to organizations on the Enterprise Plan and to SafetyCulture Partners and can only be managed by users with the "Platform management: Organization" permission.

1. Create an app

Start by creating an app you want to embed in the SafetyCulture platform. Specify the domain(s) where the app is hosted. Apps can only be embedded in domains specified in the allowlist.

Use the Register application API.

Register an app request

The following example shows how to register a third-party app that has a scope to display an embedded iframe. The iframe's host must match the one in the allowlist_hosts.

curl --request POST \
     --url https://api.safetyculture.io/integrations/v1beta/apps \
     --header 'accept: application/json' \
     --header 'authorization: Bearer YOUR_API_TOKEN_GOES_HERE' \
     --header 'content-type: application/json' \
     --header 'sc-integration-id: sc-readme' \
     --data '
{
  "external_web_experience": {
    "allowlist_hosts": [
      "my-company.com"
    ]
  },
  "app_name": "My Dashboard"
}
'

Register an app response

Upon a successful request, you will receive a unique app ID.

{
  "app_id": "YOUR_APP_UNIQUE_ID"
}

2. Install an app

A private app or marketplace app can be installed via the API. Each app can only be installed or uninstalled once, and multiple installations are not allowed.

Use the Install an application API.

Install an app request

To use the newly created app, you need to install it. In the path parameter, include the unique app_id you received when you registered the app.

curl --request POST \
     --url https://api.safetyculture.io/integrations/v1beta/apps/YOUR_APP_UNIQUE_ID/installations \
     --header 'accept: application/json' \
     --header 'authorization: Bearer YOUR_API_TOKEN_GOES_HERE' \
     --header 'content-type: application/json' \
     --header 'sc-integration-id: sc-readme'

Install an app response

Upon a successful request, you will receive a unique app installation ID.

{
  "installation_id": "YOUR_INSTALLATION_UNIQUE_ID"
}

3. Embed an app

You can use app configurations to embed an installed app in an iframe within the SafetyCulture platform. To add an app configuration, the app must be installed and the embedding URL must match the app domain allowlist.

Multiple configurations can be added for an app to load different pages in separate iframes, such as two configurations for two different spreadsheets from Google Sheets.

Use the Create an application installation configuration API.

Create an application configuration request

Include the app_id and installation_id from the previous steps in the path parameters. The body of the request should contain the URL of the iframe, the label for the button on the web interface, and the destination. Currently, the only value for the destination is APPLICATION_IFRAME_DESTINATION_STANDALONE, with other options reserved for future extensions.

curl --request POST \
     --url https://api.safetyculture.io/integrations/v1beta/apps/YOUR_APP_UNIQUE_ID/installations/YOUR_INSTALLATION_UNIQUE_ID/configurations \
     --header 'accept: application/json' \
     --header 'authorization: Bearer YOUR_API_TOKEN_GOES_HERE' \
     --header 'content-type: application/json' \
     --header 'sc-integration-id: sc-readme' \
     --data '
{
  "external_web_experience": {
    "url": "https://my-company.com/iframe.html",
    "label": "My Dashboard",
    "destination": "APPLICATION_IFRAME_DESTINATION_STANDALONE"
  }
}
'