Guides
SUPPORTFEEDBACK

Form statuses

Track progress and categorize next steps for form submissions

Suggest Edits

👍

Beta

Form API endpoints are in beta. Please reach out to your account team to enable them for your organization.

Form statuses allow you to track progress and categorize next steps for each form submission. For example, an admin might need visibility into which forms are awaiting driver input (notStarted or inProgress) versus which forms require approval.

StatusDescription & Typical Next StepsNon-Approval Form Status FlowApproval Form Status Flow
notStartedIndicates the form submission has been created or assigned but not yet touched by the assignee. Typically used to initiate a brand-new form for the first worker or correct an incorrect form assignment.- Set initially when you create/assign a form. - The driver/assignee sees the form in the Driver App. - Once the assignee begins work, the status transitions to inProgress or directly to completed if fully filled out in one go.- Same as non-approval flow. - If the assignee completes and submits, it transitions to needsReview if it’s an approval-required form.
inProgressA partially completed form, awaiting more work or a next action. For example, passing a form to a second worker for more data or edits.- The driver/assignee can submit at any time. - Upon submission, the status changes to completed for non-approvals.- For approval forms, once submitted from inProgress, status changes to needsReview.
completedAll required information has been filled out, and no further action is needed for non-approval forms.- Final status for non-approval forms. - The assignee sees no further prompts in the Driver App.- Not used for approval-required forms. Those flow through needsReview → (optionally) changesRequested or approved.
needsReviewOnly applies to approval flows. The form is complete from the assignee’s perspective, but it requires someone else’s review or approval.- Not applicable for non-approval forms.- An approval or reviewer is notified to review. - The reviewer can transition the form to approved or changesRequested.
changesRequestedOnly applies to approval flows. The reviewer has requested revisions. The submission is sent back to the assignee for adjustments.- Not applicable for non-approval forms.- The assignee is notified of the request. - The form reappears in the assignee’s Driver App inbox as changesRequested.
approvedOnly applies to approval flows. The form has been fully reviewed and approved; no further action is required.- Not applicable for non-approval forms.- Final status for an approval-required form. - The assignee sees no further prompts in the Driver App.
archivedMarks a form submission as no longer active or needed. Archived forms cannot be assigned or edited.- If the form was inProgress, it may only transition to completed, not directly archived.- Similarly, once a form is archived, it cannot transition to other statuses or be reassigned.

Changing Statuses

  • Automatic Transitions:
    • For non-approval forms:
      • If a form is notStarted or inProgress, once the assignee fully completes and submits it, the status automatically becomes completed.
    • For approval-required forms:
      • If a form is notStarted or inProgress, once the assignee submits it, it becomes needsReview.
      • From needsReview, an approver can either approve it (transition to approved) or request changes (transition to changesRequested). If changesRequested, when the assignee makes updates and resubmits, it typically goes back to needsReview again.
  • Manual Changes: An admin can manually update the status via the submission detail page if they have the appropriate permissions. Common manual updates include moving a form from inProgress to Archived (if no longer needed) or from needsReview to inProgress (if a second pass is needed before an official changesRequested is triggered).

Reassigning Forms with Status Considerations

You can reassign forms by editing the assignee of a form submission. When reassigning:

  • notStarted: Ideal if you want the new assignee to begin from scratch. The driver or worker will see it in their Samsara Driver App and can start filling it out.
  • inProgress: Useful for passing on a partially completed form to the next person. They will see the form in their inbox, continue filling in details, and eventually submit.
  • changesRequested (approval flows only): Specifically communicates to a new assignee (or the same one) that they must address requested changes.
  • completed, needsReview, or approved: These statuses typically do not prompt the newly assigned user to take action. If you want them to actively fill or change information, use notStarted, inProgress, or changesRequested.
  • archived: Once archived, a form cannot be reassigned or edited.

Updated 12 days ago