Bulk Initiations

This guide covers how to initiate bulk requests for tasks, task groups, and workflows. Bulk creation fans out a single request to multiple target users by replacing the singular target_user_id parameter with a plural target_user_ids

Rules

• Provide target_user_ids as an array of user IDs and omit target_user_id entirely

  (The two parameters are mutually exclusive and cannot appear in the same payload)

• A separate initiation is created per target user for the chosen resource type (task, task groups, or workflow)

• Tasks can auto-assign themselves with assigned_user_role by choosing current_user, target_user, or supervisor_user (supervisor of target user)

• If no role is provided, the assigned user is determined with an explicit assigned_user_id

Bulk Task

Endpoint: POST /api/v1/companies/{company_id}/tasks

The following payload creates 2 document delivery tasks and assigns each target user as the assignee.

{
  "target_user_ids": ["1", "2"],
  "task_type": "document_delivery",
  "name": "Collect signed handbook",
  "description": "Send and track acknowledgements",
  "document_id": "1",
  "due_at": "2024-10-01T17:00:00Z",
  "assigned_user_role": "target_user"
}

Bulk Task Group

Endpoint: POST /api/v1/companies/{company_id}/steps

This example produces 2 task groups and 2 corresponding document upload tasks, which are assigned to the target users

{
  "target_user_ids": ["1", "2"],
  "name": "Pre-start checklist",
  "ordered": true,
  "tasks": [
    {
      "task_type": "document_upload",
      "name": "Upload ID",
      "description": "Government-issued ID front and back",
      "assigned_user_role": "target_user"
    }
  ]
}

Bulk Workflow

Endpoint: POST /api/v1/companies/{company_id}/workflows

This payload creates 2 workflows, 2 task groups, and 4 tasks. The first task is auto-assigned to the supervisor of each target user and the second is assigned to the target user.

{
  "target_user_ids": ["1", "2"],
  "name": "Onboarding workflow",
  "description": "30-day onboarding plan",
  "ordered": true,
  "children": [
    {
      "name": "Day 1",
      "ordered": true,
      "tasks": [
        {
          "task_type": "to_do",
          "name": "Set up workspace",
          "assigned_user_role": "supervisor_user"
        },
        {
          "task_type": "document_delivery",
          "name": "Sign NDA",
          "document_id": "1",
          "assigned_user_role": "target_user"
        }
      ]
    }
  ]
}