Working with issues from forms

Key concepts

A form Issue is an issue reported while submitting a form, typically for inspections or field observations. Common examples include missing equipment, maintenance issues, or safety incidents. Drivers and other field personnel document the issue directly in the Samsara Driver App through forms. Issues are created when forms are submitted and issues are tracked in real time so that teams can quickly address and resolve them.

Receiving issue data

When new issues are created, receive notifications through two main methods:

Form submissions API and Issues API : REST APIs that return issue data.
IssueCreated webhooks : Real-time notifications sent whenever a new issue is submitted.

How to fetch issues with the APIs

Using the issues API

You can fetch all issues, including those reported via forms with the Issues API. Note the issueSource contains the ID of the FormSubmission related to the issue.

Example request

curl --request GET \
     --url https://api.samsara.com/issues/stream?startTime=2025-03-01T00:00:00Z \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <YOUR_API_TOKEN>'

Example response

{
  "data": [
    {
      "id": "0e7a6ec7-ca54-4258-bb7f-e25a905ad23c",
      "title": "This is a new issue",
      "description": "Rear right hubcap missing bolt",
      "status": "open",
      "createdAtTime": "2025-04-09T13:53:12Z",
      "submittedAtTime": "2025-04-09T13:53:12Z",
      "updatedAtTime": "2025-04-09T13:53:12Z",
      "submittedBy": {
        "id": "1130771",
        "type": "user"
      },
      "asset": {
        "id": "281474994182986",
        "entryType": "tracked"
      },
      "issueSource": {
        "id": "a93e2dc9-ad52-43ec-8fa7-a5e8212b040e",
        "type": "form"
      }
    }
  ],
  "pagination": {
    "endCursor": "a0270449-edb4-4f7a-aea5-d67e6bddca12",
    "hasNextPage": true
  }
}

Using the form submissions API

Issues created while submitting a form are also referenced in the form submission data. This is helpful if you need to know which specific form field an issue was related to, or to display a form submission with issue data along side the field. Each field inside of a form submission may have an issue object with an id.

Example request for a form submission with ID f38a7a5b-4b3f-4e32-a5da-f0eab27ce318

curl --request GET \
     --url 'https://api.samsara.com/form-submissions?ids=f38a7a5b-4b3f-4e32-a5da-f0eab27ce318' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $SAMSARA_KEY'

Example response with a field containing an issue

{
  "data": [
    {
      "id": "f38a7a5b-4b3f-4e32-a5da-f0eab27ce318",
      "formTemplate": {
        "id": "9e118726-41e2-5ba9-8c1a-eb78e8a391ac",
        "revisionId": "889fd3ae-b378-452a-b7b7-4b9a86cac4d9"
      },
      "createdAtTime": "2025-04-09T18:06:42Z",
      "submittedAtTime": "2025-04-09T18:06:42Z",
      "updatedAtTime": "2025-04-09T18:06:42Z",
      "submittedBy": {
        "id": "1130771",
        "type": "user"
      },
      "fields": [
        {
          "id": "30d55ab0-7bd2-4259-8c11-a4dbdc64111c",
          "type": "check_boxes",
          "issue": {
            "id": "43528820-00b5-40bd-8516-b458f0c14dd6"
          }
        }
      ],
      "status": "completed",
      "isRequired": false
    }
  ]
}

Listen for `IssueCreated` webhook notifications

As an alternative to polling the APIs, use IssueCreated (and optionally FormSubmitted) webhooks to receive immediate notifications when new issues or forms are submitted.

See the [Beta] IssueCreated Event Schema for more details.