> 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-creation.md).

# Creating tasks

{% 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-creation.md).
{% endhint %}

People report a job by creating a **task**. In the apps they snap a photo or a video, pick one from the phone's gallery, draw a sketch, write a short text or record a voice note, mark up the photo and name it, and then choose the **group** the task belongs to. On the web the same choices sit in one dialog, "Add a Task". A group can require details before a task is saved, such as tags, an assignee, an asset, a **room** or an **area**, and **Snapfix AI** can suggest the name and the group from a photo. The new task starts red and opens straight away, so the reporter can follow it in its chat.

## Rules

### Where a task starts

* In the apps: "Snap" in the bottom bar, "Create a new task" or "Create a new Voice Task" in the "+" menu, and the camera or "+" inside a group, a room or an area ([Home](https://docs.snapfix.com/how-the-apps-work/screens/tasks/home.md#bottom-bar), [Camera](https://docs.snapfix.com/how-the-apps-work/screens/tasks/camera.md)). iOS also has the home-screen quick action "Create a Task", which skips the location and camera checks.
* "Snap" opens the camera for everyone, but the "+" menu offers task creation only to members of at least one task group of the site ([Home](https://docs.snapfix.com/how-the-apps-work/screens/tasks/home.md#the--menu)).
* On the web: "Create" on a group's task list, "+" on the feed and on a room's or an area's task list, "Create Task" on a photo or video in a task chat or a checklist, and "+" on an asset's task list. All of them open [Add a Task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/add-task.md), as does "Create a task" on a group chat message.
* On a room's or an area's list anyone can start a task, which then gets that room or area; on a multi-site, only site admins can ([Group tasks](https://docs.snapfix.com/how-the-apps-work/screens/tasks/group-tasks.md#rooms-and-areas)).
* Started inside a group, the task goes into that group. Started anywhere else, the group is chosen at the end ([Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md)).

### What a task starts from

* A new task takes one photo or one video, a sketch, a short text or a voice note. Picking several gallery items works only when adding media to an existing task ([Camera](https://docs.snapfix.com/how-the-apps-work/screens/tasks/camera.md#inputs)).
* Camera videos stop after 60 seconds, and gallery videos may be up to 40 MB ([Camera](https://docs.snapfix.com/how-the-apps-work/screens/tasks/camera.md#actions)).
* A group with "Block Photos from Gallery" (`fBlockGalleryPhoto`) doesn't let its members pick gallery photos or videos. When the group is chosen after the photo (from Home in the apps, from the feed on the web), the block isn't applied ([Camera](https://docs.snapfix.com/how-the-apps-work/screens/tasks/camera.md#actions), [Add a Task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/add-task.md#inputs)); otherwise the web greys out photo and video.
* In the apps, a photo can be marked up with a pen, circles, rectangles, arrows and four lines of text, and cropped to a square once ([Photo edit and name](https://docs.snapfix.com/how-the-apps-work/screens/tasks/photo-edit.md)). The web draws on the photo in the dialog.
* A text task takes four lines of up to 13 characters (11 on the last), 50 in all, and the web takes 50 characters. The text becomes the task's name and its large text, shown in place of a photo ([Text or sketch task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/text-task.md#inputs)). The web saves the name as the large text, so line breaks are lost and a longer name goes past 50.
* A voice task records up to 10 minutes in the apps; the web sets no limit. It is named after the time it was recorded, such as "Voice task : Nov 11 17:22" ("Voice Task : …" on the web). Snapfix AI for voice tasks is off, so the name stays \[[ASK-15](https://github.com/snapfix/docs/blob/main/ASK.md#ask-15-is-snapfix-ai-for-voice-tasks-switched-off-on-purpose)] ([Voice task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/voice-task.md)).

### Name

* In the apps the name is optional. Left empty, the task takes the text written on the photo, or else the title "Task name" ([Photo edit and name](https://docs.snapfix.com/how-the-apps-work/screens/tasks/photo-edit.md#inputs)).
* iOS stops names at 255 characters, the size of the database field; Android has no limit.
* On the web the name is required and limited to 255 characters, and a photo, video or sketch task also needs its file; until then "Save" and "Next" stay disabled.

### Group

* The list holds the current site's task groups where the user is a member. Being a site admin adds no groups, and multi-site users switch site first ([Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#who-can-add-a-task-to-which-group)).
* Creating needs the group admin role or "Create New Task" ([Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#actions)). Without it, the iOS full screen says "You don’t have the right permissions to create task in this group. Reach out to the group admin to review your permissions.", the other app screens "You don’t have the permission to create task in this group. Reach out to the group admin to review your permission.", and the web "You don't have the necessary permissions".
* Members whose status in the group is inactive are refused: "You are inactive in this group. Reach out to the group admin to review your status." Inactive groups are left out or shown dimmed, and can't be picked ([Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#who-can-add-a-task-to-which-group)).

### Required details

* A group can require tags from its mandatory tag folders, an assignee, an asset, a room, an area, or a room or an area. "Tag your task" asks for them before the task is saved; the web asks with one dialog per requirement ([Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#tag-your-task), [Add a Task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/add-task.md#required-details)). The web adds them in separate requests after the task exists, and the API doesn't check them, so a failed request leaves the task without them.
* Room and area requirements apply only when the site has rooms or areas, and a task started from a room or an area already has one. A mandatory tag folder without tags doesn't block ([Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#tag-your-task)).
* When the group requires an assignee, the creator also needs "Assign Users": "To create a task, you need to assign a user to it. However, you do not have permission to assign users. Please contact your administrator for assistance." ([Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#actions)).
* Tasks created from a planner skip these requirements: no check was found when a planner is saved or when the scheduler creates its tasks \[[ASK-59](https://github.com/snapfix/docs/blob/main/ASK.md#ask-59-should-a-groups-task-requirements-apply-to-planned-tasks)].
* On iOS, the group sheet for tasks from rooms and areas, and voice tasks recorded by holding the button in a group, ignore mandatory tag folders.
* A group can ask the apps to confirm the task's location, "Set the task location" ([Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#set-the-task-location)). The web sets no location.

### The plan's task limit

* When the site's plan has no new tasks left, the apps' full-screen group picker shows "No new tasks left in this account." with "Learn more", and Android shows the same banner when "+" is tapped inside a group ([Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#task-limit-banner), [Group tasks](https://docs.snapfix.com/how-the-apps-work/screens/tasks/group-tasks.md#actions)).
* The group sheets for voice tasks (Android) and for rooms and areas (iOS) skip the check. The web and the API never check it when a task is created \[[ASK-23](https://github.com/snapfix/docs/blob/main/ASK.md#ask-23-should-plan-limits-be-enforced-on-the-web-and-the-server)].

### Snapfix AI

* When the site has AI suggestions on, Snapfix AI suggests a name for a photo and the best groups for it. Suggested values carry an AI badge, "Snapfix Recommends" ("Snapflix Recommends" on iOS) ([Photo edit and name](https://docs.snapfix.com/how-the-apps-work/screens/tasks/photo-edit.md#ai-name-suggestion), [Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#ai-group-suggestion)).
* Suggestions are made for photos only, not for videos, sketches, texts or voice notes. In the apps a failure is silent; the web says "Snapfix couldn’t make a recommendation from this photo."
* The task records whether its name and group came from the AI (`title_aiSuggested`, `business_aiSuggested`), for AI reporting ([Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#what-the-app-stores)).
* On the web, the new task then asks Snapfix AI for assignees, rooms, areas and tags ([Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#users-tags-rooms-assets-and-compliance)). How suggestions work: [Snapfix Recommends](https://docs.snapfix.com/product/features/ai/snapfix-recommends.md).

### The new task

* A new task is red, with the sub-status "New", unlocked and without priority, and its creator follows it ([Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#what-the-app-stores), [`POST /v1/app/tasks`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasks)).
* It records how it started in `enum_JobType` (201 to 206 for photos, videos, sketches and text, 41 for voice) and the platform in `enum_Origin` ([`enum_JobType`](https://docs.snapfix.com/engineering-reference/db/tables/enum_jobtype.md)).
* The apps give it the phone's position as its location, or 0,0 when there is none ([Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#what-the-app-stores)).
* The apps save the task on the phone, open it, and upload it in the background; nothing waits for the network ([Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#saving-the-task)).
* The web creates the task through the API, then adds the video, tags, assets, assignees, room and area one by one, and opens the task ([`POST /v1/app/tasks`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasks)).
* Setup does not create a first task. Neither app shows the first-task step after a new site's setup ([First task group](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/first-task.md), [Site setup in the app](https://docs.snapfix.com/product/features/onboarding/site-setup.md#creating-the-site)) \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)].

## Flow

```mermaid
flowchart TD
  start["Snap, + or Create"] --> media{"Photo, video, sketch, text or voice"}
  media --> edit["Mark up and name"]
  edit --> known{"Group known?"}
  known -- "started in a group" --> allowed
  known -- "from Home, feed, room or area" --> pick["Add task to a group"]
  pick --> ai["AI suggests groups for photos"]
  ai --> limit{"Tasks left in the plan?"}
  limit -- "no (apps)" --> stop["No new tasks left in this account."]
  limit -- yes --> allowed{"May create here?"}
  allowed -- no --> refused["Permission or inactive message"]
  allowed -- yes --> required{"Group requires details?"}
  required -- yes --> tag["Tag your task"]
  required -- no --> save["Save the task"]
  tag --> save
  save --> open["The task opens"]
  save -. "apps" .-> sync["Uploads in the background"]
```

## Platforms

| Capability                 | Web                                                                                                                                       | iOS                                             | Android                                               |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------- |
| Photo, video, gallery item | yes                                                                                                                                       | yes                                             | yes; landscape gallery photos are cropped to a square |
| Sketch, text               | yes                                                                                                                                       | yes                                             | yes                                                   |
| Voice task                 | yes, no time limit                                                                                                                        | up to 10 minutes                                | up to 10 minutes                                      |
| Photo markup               | drawing in the dialog                                                                                                                     | pen, shapes, text, one crop                     | same as iOS                                           |
| Name required              | yes                                                                                                                                       | no                                              | no                                                    |
| Group chosen               | in the dialog, after "Next"                                                                                                               | after Send                                      | after Send                                            |
| Required details           | one dialog each                                                                                                                           | "Tag your task"                                 | "Tag your task"; the assignee rule is checked first   |
| Location                   | none                                                                                                                                      | phone position, optional confirmation           | same as iOS                                           |
| AI name and group          | yes                                                                                                                                       | yes                                             | yes                                                   |
| Plan's task limit          | not checked \[[ASK-23](https://github.com/snapfix/docs/blob/main/ASK.md#ask-23-should-plan-limits-be-enforced-on-the-web-and-the-server)] | full-screen picker                              | full-screen picker and "+" in a group                 |
| Works offline              | no                                                                                                                                        | yes; a voice task from Home loses its recording | yes                                                   |
| Home-screen quick action   | no                                                                                                                                        | yes                                             | no                                                    |

## Screens

* [Camera](https://docs.snapfix.com/how-the-apps-work/screens/tasks/camera.md)
* [Photo edit and name](https://docs.snapfix.com/how-the-apps-work/screens/tasks/photo-edit.md)
* [Text or sketch task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/text-task.md)
* [Voice task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/voice-task.md)
* [Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md)
* [Add a Task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/add-task.md) (web)
* [Home](https://docs.snapfix.com/how-the-apps-work/screens/tasks/home.md)
* [Group tasks](https://docs.snapfix.com/how-the-apps-work/screens/tasks/group-tasks.md)
* [Feed](https://docs.snapfix.com/how-the-apps-work/screens/tasks/feed.md)
* [First task group](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/first-task.md)

## API and data

* Web: [`POST /v1/app/tasks`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasks) creates the task; [`POST /v1/app/tasks/tag/multi`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptaskstagmulti), [`POST /v1/app/tasks/assign/multi`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksassignmulti), [`POST /v1/app/tasks/asset-link`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksasset-link), [`POST /v1/app/tasks/room-add`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksroom-add) and [`POST /v1/app/tasks/area-add`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksarea-add) add the required details. A voice recording goes first to `POST /v1/app/upload/voice` ([Files API](https://docs.snapfix.com/engineering-reference/api/files.md)); name and group suggestions use `POST /v1/app/tasks/suggestions/title` and `/group` ([AI API](https://docs.snapfix.com/engineering-reference/api/ai.md)).
* Apps: media go to `?action=save_image`, `?action=save_video` and `?action=save_document` ([Files API](https://docs.snapfix.com/engineering-reference/api/files.md)); then the sync sends [`?action=save_pri_job`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_job), [`?action=save_pri_job_user`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_job_user), `?action=save_pri_job_chat` ([Chat API](https://docs.snapfix.com/engineering-reference/api/chat.md)), [`?action=save_pri_job_userassigned`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_job_userassigned), [`?action=save_pri_jobjoblink`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_jobjoblink), [`?action=save_pri_job_room`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_job_room) and [`?action=save_pri_job_area`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionsave_pri_job_area). Voice recordings use `?action=upload_voice_task_file`, and AI choices are logged with `?action=save_ai_job_log` ([AI API](https://docs.snapfix.com/engineering-reference/api/ai.md)).
* Tables: [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md), [`tPri_JobUser`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuser.md), [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md), [`tPri_JobUserAssigned`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobuserassigned.md), [`tPri_JobTag`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobtag.md), [`tPri_JobRoom`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobroom.md), [`tPri_JobArea`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobarea.md), [`tPri_JobJobLink`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobjoblink.md), [`enum_JobType`](https://docs.snapfix.com/engineering-reference/db/tables/enum_jobtype.md); group requirements in [`tPri_SettingsBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsbusiness.md) and [`tPri_BusinessTagHeaderRule`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_businesstagheaderrule.md); AI choices in [`log_ai_job`](https://docs.snapfix.com/engineering-reference/db/tables/log_ai_job.md).

## Depends on

* [Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md): everything that happens to the task after it opens.
* [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's requirements, its gallery block, and who may create tasks or assign users.
* [Rooms and areas](https://docs.snapfix.com/product/features/rooms/rooms-and-areas.md) and [Asset tasks](https://docs.snapfix.com/product/features/assets/asset-tasks.md): tasks started from a room, an area or an asset, and the requirements that ask for them.
* [Snapfix Recommends](https://docs.snapfix.com/product/features/ai/snapfix-recommends.md): AI names, groups, assignees, tags, rooms and areas, switched on per site ([Site details](https://docs.snapfix.com/product/features/console/site-details.md)).
* [Subscriptions](https://docs.snapfix.com/product/features/billing/subscriptions.md): the plan's task limit.
* [Task chat](https://docs.snapfix.com/product/features/chat/task-chat.md): the "created" line, and the video or voice message of a new task.
* [Push notifications](https://docs.snapfix.com/product/features/notifications/push-notifications.md): the group hears about the new task ([`POST /v1/app/tasks`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasks)).
* [Profile and settings](https://docs.snapfix.com/product/features/account/profile.md): the app setting that also saves new photos to the phone's gallery.
* Other ways tasks are created, each with its own rules: [QR forms](https://docs.snapfix.com/product/features/qr/qr-forms.md), [Planned tasks](https://docs.snapfix.com/product/features/planner/planned-tasks.md), [Cleaning tasks](https://docs.snapfix.com/product/features/housekeeping/cleaning-tasks.md), [Chat](https://docs.snapfix.com/product/features/chat/chat.md) messages, [Snapfix AI](https://docs.snapfix.com/product/features/ai/snapfix-ai.md), the [Open API](https://docs.snapfix.com/product/features/integrations/open-api.md) and the [Vendor API](https://docs.snapfix.com/product/features/integrations/vendor-api.md).

## Edge cases

* **Offline:** the apps create tasks without a connection and upload them later; AI suggestions are skipped ([Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#offline)). An iOS voice task started from Home loses its recording when it can't upload at once, or with an expired session. The web needs a connection.
* **Upload failures:** the apps retry in the background and never tell the user ([Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#on-failure)). When an iOS video upload fails, the video message loses its address, and a failed video or image step can leave the camera or edit screen stuck.
* **Backing out:** going back before the group is chosen drops the photo or recording, but iOS has already queued the "Created task" line, which is later uploaded for a task that doesn't exist.
* **Voice sheet on iOS:** tapping outside it closes the sheet while the recording goes on, and Send in the first second does nothing ([Voice task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/voice-task.md#actions)).
* **Missing phone permissions:** without location the task gets the last known position or 0,0. On iOS the first "Snap" after install stops at the location prompt; Android needs the microphone even for photos; iOS explains refused photo access with a message about saving photos ([Camera](https://docs.snapfix.com/how-the-apps-work/screens/tasks/camera.md#before-the-camera-opens)).
* **Limits reached:** the plan's task limit, the 40 MB video limit and the name limits are under [Rules](#rules).
* **Archived or inactive groups:** they can't be picked ([Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#who-can-add-a-task-to-which-group)).
* **Several sites:** only the current site's groups are offered; to add a task elsewhere, switch site first ([Switching sites](https://docs.snapfix.com/product/features/groups/site-switching.md)).
* **Time zones:** the apps take the creation time, and the time in a voice task's name, from the phone's clock, so a wrong clock gives wrong dates.


---

# 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-creation.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.
