---
title: "Create a task"
method: POST
path: "/v1/org/{orgId}/task"
tags: ["task"]
---

# Create a task

`POST /v1/org/{orgId}/task`

## Path parameters

- `orgId` string, required

## Request body

- CreateTask
  - `orgId` string, required — parent organization id
  - `userId` string, required — user who is responsible for the task
  - `assessmentId` string — parent assessment id that this task belongs to
  - `parentEntityId` string — parent entity id that this task belongs to, should be used with entityId
  - `type` 'FORM_SUBMIT' | 'FORM_RESPONSE_APPROVE' | 'FORM_RESPONSE_RESUBMIT' | 'CHANGE_APPROVE' | 'TIMEOFF_APPROVE' | 'SCENARIO_CHANGES_APPROVE' | 'SCENARIO_CHANGES_CREATE' | 'ORG_IMPORT' | 'COMP_REVIEW_APPROVAL_SUBMIT' | 'SCENARIO_APPROVAL_SUBMIT' | 'APPROVAL_CHAIN_UPDATE_FALLBACK_APPROVER' | 'ACTION' | 'SIGNATURE' | 'GOAL_PROGRESS' | 'TODO', required — type of task
  - `entityId` string, required — the primary entity being referenced by the task - for example for a FORM_SUBMIT, this will be the form
  - `targetId` string — the optional target entity being referenced by the task - for example for a FORM_SUBMIT, this will be the person
  - `categoryId` string — the data category that the task belongs to
  - `status` 'PENDING' | 'DONE' | 'EXPIRED' | 'SKIPPED', required — status of this task
  - `label` string — The user-visible label for the task; if not set, will automatically default based on the task type
  - `message` string — The message attached to this task
  - `shareAccess` ShareAccess[] — users who are specifically granted permission to view or edit this task
    - `access` 'NONE' | 'LIMITED_READ' | 'LIMITED_WRITE' | 'STANDARD_READ' | 'STANDARD_WRITE' | 'COMPENSATION_READ' | 'FULL_READ' | 'COMP_PLANNING_PARTICIPANT' | 'COMPENSATION_WRITE' | 'WRITE' | 'COMPENSATION_OWNER' | 'OWNER', required — access permission level
    - `userId` string — user id
    - `groupId` string — group id
    - `fields` string — fields
  - `path` string — the optional path of this task (only applies to Type == ORG_IMPORT)
  - `taskConfigId` string — id of the TaskConfig
  - `slug` string — slug used to reference tasks in events
  - `dueAt` string — due date for the task
  - `pastDueAction` 'NONE' | 'SET_EXPIRED' — what action to take when the task is past its due date
  - `isSkippable` boolean — check for if the task can be skipped

## Response `201`

task created

- Task
  - `id` string, required — globally unique id
  - `orgId` string, required — parent organization id
  - `userId` string, required — user who is responsible for the task
  - `assessmentId` string — parent assessment id that this task belongs to
  - `parentEntityId` string — parent entity id that this task belongs to, should be used with entityId
  - `type` 'FORM_SUBMIT' | 'FORM_RESPONSE_APPROVE' | 'FORM_RESPONSE_RESUBMIT' | 'CHANGE_APPROVE' | 'TIMEOFF_APPROVE' | 'SCENARIO_CHANGES_APPROVE' | 'SCENARIO_CHANGES_CREATE' | 'ORG_IMPORT' | 'COMP_REVIEW_APPROVAL_SUBMIT' | 'SCENARIO_APPROVAL_SUBMIT' | 'APPROVAL_CHAIN_UPDATE_FALLBACK_APPROVER' | 'ACTION' | 'SIGNATURE' | 'GOAL_PROGRESS' | 'TODO', required — type of task
  - `entityId` string, required — the primary entity being referenced by the task - for example for a FORM_SUBMIT, this will be the form
  - `targetId` string — the optional target entity being referenced by the task - for example for a FORM_SUBMIT, this will be the person
  - `categoryId` string — the data category that the task belongs to
  - `actionId` string — the action that created the task, if the task was generated from an action
  - `status` 'PENDING' | 'DONE' | 'EXPIRED' | 'SKIPPED', required — status of this task
  - `doneAt` string — timestamp that the task was done, if it was done
  - `createId` string — created by user id
  - `createBehalfId` string — created on behalf of user id
  - `createAttribution` Attribution
    - `principalUserId` string
    - `agentUserIds` string[]
    - `eventId` string
    - `aiChatId` string
    - `aiToolUseId` string
    - `channel` 'WEB' | 'MOBILE' | 'SLACK' | 'TEAMS' | 'MCP'
  - `createAt` string — created timestamp
  - `label` string — The user-visible label for the task; if not set, will automatically default based on the task type
  - `message` string — The message attached to this task
  - `shareAccess` ShareAccess[] — users who are specifically granted permission to view or edit this task
    - `access` 'NONE' | 'LIMITED_READ' | 'LIMITED_WRITE' | 'STANDARD_READ' | 'STANDARD_WRITE' | 'COMPENSATION_READ' | 'FULL_READ' | 'COMP_PLANNING_PARTICIPANT' | 'COMPENSATION_WRITE' | 'WRITE' | 'COMPENSATION_OWNER' | 'OWNER', required — access permission level
    - `userId` string — user id
    - `groupId` string — group id
    - `fields` string — fields
  - `path` string — the optional path of this task (only applies to Type == ORG_IMPORT)
  - `updateId` string — last updated by user id
  - `updateBehalfId` string — last updated on behalf of user id
  - `updateAttribution` Attribution
    - `principalUserId` string
    - `agentUserIds` string[]
    - `eventId` string
    - `aiChatId` string
    - `aiToolUseId` string
    - `channel` 'WEB' | 'MOBILE' | 'SLACK' | 'TEAMS' | 'MCP'
  - `updateAt` string — last updated timestamp
  - `deleteId` string — deleted by user id
  - `deleteBehalfId` string — deleted on behalf of user id
  - `deleteAttribution` Attribution
    - `principalUserId` string
    - `agentUserIds` string[]
    - `eventId` string
    - `aiChatId` string
    - `aiToolUseId` string
    - `channel` 'WEB' | 'MOBILE' | 'SLACK' | 'TEAMS' | 'MCP'
  - `deleteAt` string — deleted timestamp
  - `taskConfigId` string — id of the TaskConfig
  - `slug` string — slug used to reference tasks in events
  - `dueAt` string — due date for the task
  - `pastDueAction` 'NONE' | 'SET_EXPIRED' — what action to take when the task is past its due date
  - `isSkippable` boolean — check for if the task can be skipped

## Other responses

- `400` — invalid data
- `401` — not authorized
- `403` — permission denied
- `404` — org not found

---

[API](https://skmtc.net/charthop/apis/charthop-api.md) · [All operations](https://skmtc.net/charthop/apis/charthop-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/charthop/charthop-api/revisions/2de21f45f447/schema)