Tasks

Tasks belong to process runs. You can read task details (including form field values) and update tasks to mark them complete, assign them, or fill in form fields.

Get a Task


GET /api/v1/process-runs/:runId/tasks/:taskId

Returns a single task from a process run, including all custom elements and their current values.

Example Request


curl -H "Authorization: Bearer nxs_live_your_key" \
  "https://getnextstep.io/api/v1/process-runs/CWpVWwuj7Jkvl3Smlyxb/tasks/POPXQSSPZnYNjUz7QBbn"

Example Response


{
  "data": {
    "id": "POPXQSSPZnYNjUz7QBbn",
    "instance_id": "CWpVWwuj7Jkvl3Smlyxb",
    "template_task_id": "Y9Rxzi3uDOvGAYojkHti",
    "title": "Review employee details",
    "completed": false,
    "completed_at": null,
    "completed_by": null,
    "order": 0,
    "section_id": "sec_abc",
    "assignee": "user123",
    "is_essential": false,
    "type": "task",
    "due_date": null,
    "webhook_enabled": false,
    "custom_elements": [
      {
        "id": "elem_001",
        "type": "shortText",
        "label": "Employee Name",
        "value": "Jane Smith",
        "required": true,
        "display_only": false
      }
    ],
    "created_at": "2026-03-27T02:08:05.224Z"
  }
}

Update a Task


PATCH /api/v1/process-runs/:runId/tasks/:taskId

Update a task’s completion status, assignee, or form field values. You can update multiple fields in a single request.

You cannot update tasks on a completed process run.

Request Body

All fields are optional. Include only what you want to change.

Field	Type	Description
`completed`	boolean	Mark the task as complete (`true`) or incomplete (`false`)
`assignee`	string	User ID or email to assign the task to
`actor_email`	string	Email recorded as the person who completed the task (defaults to `"api"`)
`custom_elements`	array	Form field values to update (see below)

Completing a Task


curl -X PATCH \
  -H "Authorization: Bearer nxs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"completed": true}' \
  "https://getnextstep.io/api/v1/process-runs/CWpVWwuj7Jkvl3Smlyxb/tasks/POPXQSSPZnYNjUz7QBbn"

When all tasks in a run are completed or skipped, the run automatically changes to completed status.

Updating Form Fields

Pass a custom_elements array with the element id and new value:


curl -X PATCH \
  -H "Authorization: Bearer nxs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_elements": [
      { "id": "elem_001", "value": "Jane Smith" },
      { "id": "elem_002", "value": "jane@company.com" }
    ]
  }' \
  "https://getnextstep.io/api/v1/process-runs/CWpVWwuj7Jkvl3Smlyxb/tasks/POPXQSSPZnYNjUz7QBbn"

Completing and Filling Fields Together

You can complete a task and set form values in the same request:


{
  "completed": true,
  "actor_email": "jane@company.com",
  "custom_elements": [
    { "id": "elem_001", "value": "Jane Smith" },
    { "id": "elem_002", "value": "jane@company.com" }
  ]
}

Writable Element Types

Only input-type elements can be updated via the API. Display-only elements (text, image, video, lineBreak) are read-only.

Type	Accepted Values
`shortText`	String
`longText`	String
`number`	Number
`email`	String (email address)
`website`	String (URL)
`date`	String (ISO 8601 date)
`checkbox`	Boolean (`true` / `false`)
`dropdown`	String (must be one of the element’s `options`)
`multichoice`	Array of strings (each must be in the element’s `options`)

Validation

The API validates values against the element type:

Dropdown: The value must be one of the defined options
Multichoice: Every value in the array must be in the defined options
Read-only elements: Attempting to update a display_only element returns a 400 error

Error Example


{
  "error": {
    "code": "validation_error",
    "message": "Invalid value for dropdown \"Department\". Must be one of: Engineering, Marketing, Sales"
  }
}

Response Fields

Field	Description
`id`	Instance task ID (unique to this run)
`instance_id`	The process run this task belongs to
`template_task_id`	The original template task ID
`title`	Task title
`completed`	Whether the task is complete
`completed_at`	ISO 8601 timestamp when completed
`completed_by`	User ID or `"api"` who completed it
`order`	Position in the task list (0-based)
`section_id`	Section this task belongs to (matches section IDs from the run)
`assignee`	User ID assigned to this task
`is_essential`	If `true`, the task cannot be skipped
`skipped`	Whether the task was skipped
`type`	`"task"` or `"approval"`
`due_date`	Due date configuration
`webhook_enabled`	Whether task completion triggers a webhook
`custom_elements`	Array of form fields with current values