Working With Issues From Forms

Monitor and retrieve issues submitted via Samsara forms to enable real-time workflows and proactive resolution.

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.

curl 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 alongside the field. Each field inside 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 'https://api.samsara.com/form-submissions?ids=f38a7a5b-4b3f-4e32-a5da-f0eab27ce318' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer YOUR_API_TOKEN'

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 IssueCreated Event Schema for more details.