API

Introduction

Use the SafetyCulture API to connect SafetyCulture with your systems, retrieve data, and automate workflows.

The SafetyCulture API allows you to build integrations that move data and trigger workflows between SafetyCulture and your systems. Use it to export inspection data for reporting, automate follow-up work, and keep downstream tools in sync with operational activity.

The API exposes SafetyCulture data and operations across key platform areas, including inspections, templates, actions, users, and more. Each area has its own endpoints in the API reference.

How the API works

Most integrations follow a simple pattern:

  1. Search to find records and IDs.
  2. Retrieve a specific record by ID to get full details.
  3. Download any related files (such as media) using file endpoints.

Sync methods

You can integrate with SafetyCulture using one of two models or combine them.

Scheduled sync

Use scheduled sync when you need reporting, backfills, or periodic exports. A typical approach is to filter by “modified since” so you only fetch what changed since your last run, then store the checkpoint for the next run.

Event-driven workflows with webhooks

Use webhooks when you want near real-time notifications for key events, such as an inspection being completed or an action being assigned. SafetyCulture sends webhook notifications as HTTP POST requests to a URL you specify.

Verify webhook requests and confirm the payload came from SafetyCulture before you process them.

Use cases and examples

Use cases show end-to-end workflows that combine multiple requests. Start with one of these examples:

Requirements

🪄

If you don't have an account or your organization is on the Free Plan, you can sign up and trial our Premium Plan for free. If you're interested in our Enterprise Plan, you can contact us to find out more.

Reliability and performance

Build integrations that stay fast, respect limits, and recover cleanly. Plan for change and volume from the start to ensure your integration continues to work as usage grows.

Use incremental sync where possible. Fetch only what has changed since your last run and store a checkpoint so that the next run continues from the correct place. Request only the fields you need to reduce payload size and avoid unnecessary requests.

When you use webhooks, treat them as a signal and keep a scheduled sync as a fallback for missed events or reprocessing.

Base URL

Send requests to https://api.safetyculture.io.

Authentication

Send your API token in the Authorization header for every request:

Authorization: Bearer {api_token}

Use a service user API token for shared or long-running integrations. Use a user API token for personal workflows tied to one user’s access. See Authentication for setup steps, expiry rules, and token management.

Permissions and access

API requests run as the token owner (a user or a service user). Permissions and access rules determine what the API can return or change.

The API checks:

  • the owner’s permissions
  • the owner’s access to items (sharing, groups, sites, and org rules)

If results look incomplete, check whether the token owner can access the same content in SafetyCulture.

IDs

Most endpoints require IDs. Get IDs from API responses and store them in your system.

Do not create IDs manually. Use search endpoints to find IDs, then retrieve full details with those IDs.

See IDs for where to find common identifiers.

Response format and timestamps

Most endpoints return JSON. Some endpoints return a file instead of JSON, such as media downloads. Handle these responses as binary content and use the Content-Type header to determine file type.

When you send or receive timestamps, use the Internet Date-Time format (RFC 3339 subset), including timezone information such as Z for UTC. See Date/Time format for details.

Rate limits

SafetyCulture throttles requests sent at a high rate. When you exceed a limit, the API returns 429 Too Many Requests and includes rate limit headers (x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset). Review Rate limits before you run production workloads.

Build your first integration

Retrieve inspections and media

This walkthrough shows how to confirm your API token, find inspection IDs, retrieve an inspection, and download attached media.

Before you begin

  • Create an API token.
  • Confirm the token owner has access to the inspections you want to retrieve. For Inspections API, we recommend you set up these permissions: “View all data” for read-only access and “Manage all data” for updates.

1. Send a test request

Search inspections and request two fields using the inspections search endpoint. Include audit_id in field or the API returns 400 Bad Request.

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

By default, results are sorted by modified_at from oldest to newest and return up to 1,000 inspections.

{
  "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"
    }
  ]
}

Use the audit_id values from the response in later steps.

Add field parameters to control which fields return, and use filters to narrow results. See Search modified inspections for supported query parameters.

2. Filter by time range (optional)

Use modified_after and modified_before to limit results by inspection modification time. Send timestamps in Internet Date-Time format (UTC).

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

Example values

  • {start_time}: 2015-01-01T00:00:00.000Z
  • {end_time}: 2015-04-01T00:00:00.000Z

3. Filter by template (optional)

Use template={template_id} to return inspections created from a specific template. To get unique identifiers of different entities in SafetyCulture, see Get entity IDs for integrations and deep links.

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

4. Get the inspection

Select an audit_id from the search response, then retrieve the inspection.

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

Example value

  • {audit_id}: audit_01ca38a821504cda885736cccbb9ba40

The response returns the full inspection payload. If the inspection includes attachments, the response can include a media list with media references.

{
  "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": { ... },
  "media": [
    {
      "media_id": "9E3BD015-6275-4668-BAF1-296B2F38444C",
      "file_ext": "jpg",
      "href": "https://api.safetyculture.io/audits/{audit_id}/media/9E3BD015-6275-4668-BAF1-296B2F38444C"
    }
  ]
}

Use the href or the {audit_id} and media_id values to download the file in the next step.

5. Find media references

After you retrieve an inspection, look for a media list in the response. Each media item can include:

  • media_id
  • file_ext
  • href

Use these values in the next step to download the file.

6. Download a media item

Use the href value from the inspection response, or build the URL using audit_id and media_id. This endpoint returns the file, not JSON.

Repeat for each media item you want to download.

📘

The response includes a Content-Type header that matches the file type.

Next steps

Read Authentication to choose a token type and send authenticated requests. Then, explore the APIs to find endpoints, parameters, and response fields. You can also try a use case to follow an end-to-end workflow.

Updated 6 months ago

Updated 6 months ago