> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/product/features/tasks/task-approval.md).

# Task approval

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/task-approval.md).
{% endhint %}

**Task approval** makes a **group admin** check work before it counts as done. When a **group**, or a single **task**, requires approval, a member who turns the task green sends it for approval instead of completing it. The task stays green with "Pending Approval" until a group admin approves it, or rejects it with a note, which sends it back to red. Admins find the waiting tasks with the "Approval tasks only" **SnapFilter**, and every request and decision is kept in the approval activity.

## Rules

### When approval applies

* A group switches approval on with "Task approval required" in its settings ("Require Task Approval": "When enabled, all tasks for this group must be approved by a Group Admin when changed to Green by a user.") ([Group settings](https://docs.snapfix.com/how-the-apps-work/screens/groups/group-settings.md), `fTaskApprovalRequired` in [`tPri_SettingsBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsbusiness.md)).
* A task follows its group until a group admin turns "Require Task Approval" on or off for that task ([Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#task-menu), `approvalRequired` in the [task object](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-object)).
* Approval is about green only: red and amber changes never wait ([`PUT /v1/app/tasks/{uuid}`](https://docs.snapfix.com/engineering-reference/api/tasks.md#put-v1apptasksuuid)).
* On the web and iOS, cleaning and inspection tasks never wait when they turn green; an inspection approves or rejects its cleaning task instead ([Inspections](https://docs.snapfix.com/product/features/housekeeping/inspections.md), [Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#approval-and-housekeeping)).

### Sending for approval

* When a member who isn't a group admin turns a task that needs approval green, the task turns green, its chat gets "Sent for Approval", and lists show "Pending Approval" in place of the last update time ([Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#header-and-status), [Feed](https://docs.snapfix.com/how-the-apps-work/screens/tasks/feed.md#layout)).
* A group admin's green approves the task at once ([Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#header-and-status)).
* A request made on the web pushes a notification to the group's admins ([`PUT /v1/app/tasks/{uuid}`](https://docs.snapfix.com/engineering-reference/api/tasks.md#put-v1apptasksuuid)); Android sends its own push for requests made in the app.
* Changing many tasks to green at once follows the same rule, but sends the group's admins no request push ([`POST /v1/app/tasks/multi/status`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksmultistatus), [Multi-select](https://docs.snapfix.com/product/features/tasks/multi-select.md)).

### Reviewing

* Group admins review requests, and so do the users assigned to an inspection task ([Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#who-can-do-what)). They see the "Approval Request" card on the task with who asked and when.
* The API also takes a decision, or switches approval off, from anyone assigned to the task ([`PUT /v1/app/tasks/{uuid}`](https://docs.snapfix.com/engineering-reference/api/tasks.md#put-v1apptasksuuid)).
* "Approve" keeps the task green and marks it approved: "Task approved successfully." Approving an inspection task also turns it green and approves its cleaning task ([Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#approval-and-housekeeping)).
* "Reject" sends the task back to red, with "Task Rejected" and the reviewer's note in its chat: "Task rejected." ([Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#approval-and-housekeeping)).
* The web requires a rejection note ("Reject Task" stays disabled without one); the apps require it only for inspection tasks ([Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#approval-request-reject)).
* Rejecting an inspection task rejects its cleaning task and keeps the inspection green; the web also creates the follow-up housekeeping tasks ([Inspections](https://docs.snapfix.com/product/features/housekeeping/inspections.md)).
* Switching "Require Task Approval" off on a task that waits approves it ([`PUT /v1/app/tasks/{uuid}`](https://docs.snapfix.com/engineering-reference/api/tasks.md#put-v1apptasksuuid)).
* The API refuses a decision on a task that doesn't need approval: "Approve is not required" ([`PUT /v1/app/tasks/{uuid}`](https://docs.snapfix.com/engineering-reference/api/tasks.md#put-v1apptasksuuid)).

### Finding requests

* "Approval tasks only" shows completed tasks that wait for approval, on the feed and in a group's list ([Feed](https://docs.snapfix.com/how-the-apps-work/screens/tasks/feed.md#filters)).
* Turning it on clears the other filters except "Active tasks" or "Archived tasks" (the web also keeps the status), and on the web's group list switches to green; choosing any other filter, or a new sort on the web, turns it off ([Feed](https://docs.snapfix.com/how-the-apps-work/screens/tasks/feed.md#filters), [Group tasks](https://docs.snapfix.com/how-the-apps-work/screens/tasks/group-tasks.md#inputs)).
* While it's on, "Audit Trail" (web) or the approval activity button (apps) opens [Approval tasks activity](https://docs.snapfix.com/how-the-apps-work/screens/tasks/approval-activity.md): who requested, approved or rejected which task, and when, oldest first.
* The activity is read-only, and each platform lists different events: the web asks the server with the list's filters, iOS reads every task of the group on the phone, deleted ones included, and Android only the tasks the user can see ([Approval tasks activity](https://docs.snapfix.com/how-the-apps-work/screens/tasks/approval-activity.md#platform-differences)).
* The web builds each event's name as HTML.

### What is stored

* The task keeps its approval state: none (-1), rejected (0), approved (1) or pending (2), with when it was approved ([task object](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-object), [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) `fApprovalStatus`).
* Each request and decision adds a row to the status log and a line to the chat: "Sent for Approval", "Task Approved", "Task Rejected", and the rejection note ([`tPri_Job_StatusLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_statuslog.md), [Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#task-chat)).

## Flow

```mermaid
flowchart TD
  green["Member turns a task green"] --> needs{"Approval required?"}
  needs -- no --> done["Complete"]
  needs -- yes --> admin{"Group admin?"}
  admin -- yes --> approved["Approved"]
  admin -- no --> pending["Pending Approval"]
  pending --> notify["Admins notified"]
  notify --> review{"Review"}
  review -- Approve --> approved
  review -- "Reject with a note" --> red["Back to red"]
  red --> again["Work continues"] --> green
  pending -. "approval switched off" .-> approved
```

## Platforms

| Capability                             | Web                                                                     | iOS                         | Android                                                    |
| -------------------------------------- | ----------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------- |
| Group setting "Task approval required" | yes                                                                     | yes                         | yes                                                        |
| "Require Task Approval" on a task      | "Actions" menu                                                          | "+" menu                    | "+" menu; shows the group's setting when the task has none |
| Send for approval by turning green     | yes                                                                     | yes                         | yes                                                        |
| Approve, reject                        | "Approval Request" card                                                 | approval card               | approval card                                              |
| Rejection note required                | always                                                                  | inspection tasks only       | inspection tasks only                                      |
| "Approval tasks only" SnapFilter       | yes                                                                     | yes                         | yes                                                        |
| Approval activity                      | "Audit Trail", 20 at a time from the server; fails on a multi-site feed | from the phone, all at once | from the phone, 20 at a time                               |
| Works offline                          | no                                                                      | yes, synced later           | yes, synced later                                          |

## Screens

* [Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md)
* [Approval tasks activity](https://docs.snapfix.com/how-the-apps-work/screens/tasks/approval-activity.md)
* [Feed](https://docs.snapfix.com/how-the-apps-work/screens/tasks/feed.md)
* [Group tasks](https://docs.snapfix.com/how-the-apps-work/screens/tasks/group-tasks.md)
* [Group settings](https://docs.snapfix.com/how-the-apps-work/screens/groups/group-settings.md)

## API and data

* [`PUT /v1/app/tasks/{uuid}`](https://docs.snapfix.com/engineering-reference/api/tasks.md#put-v1apptasksuuid) with `color`, `approvalRequired` or `approvalStatus` (web); the apps save the same fields through [`?action=save_pri_job`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_job) and [`?action=save_job_status_log`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_job_status_log).
* Bulk green: [`POST /v1/app/tasks/multi/status`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksmultistatus) and [`POST /v1/app/tasks/all/status`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksallstatus).
* Approval activity: [`POST /v1/app/tasks/statuses`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksstatuses) (group) and [`POST /v1/app/tasks/statuses-by-parent`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksstatuses-by-parent) (feed); the filter is `approvalTasks` in [task list filters](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-list-filters).
* Housekeeping rejections: `POST /v1/app/housekeeping/reject-tasks` ([Housekeeping API](https://docs.snapfix.com/engineering-reference/api/housekeeping.md)).
* Tables: [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) (`fApprovalRequired`, `fApprovalStatus`, `fApprovedTs`), [`tPri_Job_StatusLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job_statuslog.md), [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md) (types 86 to 89), [`tPri_SettingsBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsbusiness.md) (`fTaskApprovalRequired`).

## Depends on

* [Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md): status changes and their permissions.
* [Groups](https://docs.snapfix.com/product/features/groups/groups.md) and [Group members](https://docs.snapfix.com/product/features/groups/group-members.md): the group setting, and who is a group admin.
* [Task lists](https://docs.snapfix.com/product/features/tasks/task-lists.md): the "Approval tasks only" SnapFilter and "Pending Approval" on rows.
* [Push notifications](https://docs.snapfix.com/product/features/notifications/push-notifications.md): request pushes to the group's admins.
* [Inspections](https://docs.snapfix.com/product/features/housekeeping/inspections.md) and [Cleaning tasks](https://docs.snapfix.com/product/features/housekeeping/cleaning-tasks.md): housekeeping approval.
* [Multi-select](https://docs.snapfix.com/product/features/tasks/multi-select.md): bulk status changes to green.

## Edge cases

* **Offline (apps):** sending for approval, approving and rejecting are saved on the phone and synced later, through actions that check nothing.
* **Missing permission:** a member without "Change task to green" can't send a task for approval at all ([Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md#status-and-priority)).
* **Copies:** when the apps copy a task from a group that requires approval to one that doesn't, the copy requires approval ([`?action=copy_job_v2`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actioncopy_job_v2)).
* **Archived or deleted tasks:** an archived task that waits shows only with "Archived tasks". Deleted tasks drop out of the lists, but iOS still lists them in the group's approval activity.
* **Several sites:** on a web multi-site, "Audit Trail" on the feed fails.
* **Time zones:** the server keeps event times in UTC, and each platform shows them in the device's time ([`POST /v1/app/tasks/statuses`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksstatuses)).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/product/features/tasks/task-approval.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
