Samsara Developer Portal

Integrate your data with the Samsara API, customize the Samsara experience, and join a community of developers building with Samsara.

Get Started

Capture Task Completion

What are we building?

This guide will describe how to capture route stop task completions by:

  1. Configuring a document submission webhook notification
  2. Retrieving the full document object using the Documents API

Configure a Document Submission Webhook Notification

See the Webhooks guide for details on how to create a webhook. Specifically, you'll want to configure a Document Submission alert to send to the webhook.

Once you've configured the webhook and the alert, you'll receive a JSON payload like the following whenever a document is submitted:

{
  "eventId": "73746344-4b76-4e2a-ba19-3fa04b2f7038",
  "eventMs": 1587567280773,
  "eventType": "Alert",
  "event": {
    "alertEventUrl": "https://cloud.samsara.com/o/53729/alerts/incidents/v2/159570/5/1654973/1587567275566",
    "alertConditionDescription": "Document Submission",
    "alertConditionId": "DriverDocumentSubmitted",
    "details": "A Stop Tasks document was submitted by Tyler Freckmann at Wed, 22 Apr 2020 7:54am PDT. Document: https://cloud.samsara.com/o/53729/groups/54868/fleet/reports/documents/1654973/1587567275566 (ID: 1654973_1587567275566)",
    "driver": {
      "id": 1654973,
      "name": "Tyler Freckmann"
    },
    "orgId": 53729,
    "resolved": false,
    "startMs": 1587567275566,
    "summary": "Stop Tasks Submitted"
  }
}

In order to retrieve details about the document, you'll need to extract the driver ID and document ID from the webhook payload.

The driver object in the webhook payload contains an id field, which is the driver ID you'll need to retrieve the full document object.

The document ID is located in the details field of the webhook payload, and always has the following structure:

A {documentTemplateName} document was submitted by {driverName} at {submissionTime}. Document: {documentUrl} (ID: {documentId})

You can use regex or other string operations to extract the document ID from this field.

Retrieve the Document

Once you've extracted the document ID from the webhook notification, you can use the Documents API to retrieve the full document object.

The GET /v1/fleet/drivers/{driver_id}/documents/{document_id} endpoint allows you to retrieve the document object using the driver ID and document ID collected from the webhook notification payload.

For example, using the payload above, you would perform the following GET request:

GET /v1/fleet/drivers/1654973/documents/1654973_1587567275566

and you would receive the following payload back:

{
  "driverDocument": {
    "orgId": 53729,
    "driverId": 1654973,
    "id": "1654973_1587567275566",
    "driverCreatedAtMs": 1587567275566,
    "serverCreatedAtMs": 1587567281000,
    "serverUpdatedAtMs": 1587567281000,
    "dispatchJobId": 4335797294,
    "notes": "Some notes",
    "state": "Submitted",
    "documentType": "Stop Tasks",
    "vehicleId": 212014918732717,
    "fields": [
      {
        "value": "1234",
        "stringValue": "1234",
        "label": "Load #",
        "valueType": "ValueType_String"
      },
      {
        "value": [
          {
            "value": "Yes",
            "selected": true
          },
          {
            "value": "No",
            "selected": false
          }
        ],
        "multipleChoiceValue": [
          {
            "value": "Yes",
            "selected": true
          },
          {
            "value": "No",
            "selected": false
          }
        ],
        "label": "Did you drop the trailer?",
        "valueType": "ValueType_MultipleChoice"
      },
      {
        "value": 1,
        "numberValue": 1,
        "label": "# of pieces",
        "valueType": "ValueType_Number"
      },
      {
        "value": {
          "dateTimeMs": 1587567264724
        },
        "dateTimeValue": {
          "dateTimeMs": 1587567264724
        },
        "label": "Time unloaded",
        "valueType": "ValueType_DateTime"
      }
    ]
  }
}

See the Documents API for full reference.

Associating a Document with a Stop

The dispatchJobId field of the document will tell you which route stop this document was submitted at.

Alternative Strategies

In addition to capturing stop task completion via webhook handling, you can poll the Documents API for all documents either created or updated during a certain time window.

See the Fetch All Documents API endpoint for details.

Updated 3 months ago


Capture Task Completion


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.