Sub-jobs

Sub-jobs are nested job entities that belong to a parent job. They allow you to break down complex jobs into smaller, manageable tasks while optionally inheriting settings from their parent.

Key Concepts

useParentData

The useParentData field controls whether a sub-job inherits settings from its parent:

🚧

Important

Sub-jobs can only be added to a parent job that was created with at least one sub-job. You cannot add sub-jobs to a standalone job after creation.

Create Sub-Jobs

Option 1: Create with Parent Job

Include sub-jobs in the subJobs array when creating the parent:

[
  {
    "instanceIds": [6833518],
    "title": "Parent Job",
    "assign": {
      "type": "both",
      "userIds": [],
      "groupIds": [5321397]
    },
    "subJobs": [
      {
        "title": "Sub-Job 1"
      },
      {
        "title": "Sub-Job 2"
      }
    ]
  }
]

Option 2: Add to Existing Parent

Add a sub-job to an existing parent job using parentId:

[
  {
    "parentId": "19cc77e2-0aab-4578-a79c-0d8160671a34",
    "title": "New Sub-Job",
    "code": "SUB-003"
  }
]

Sub-Job with Custom Settings

To give a sub-job its own assignment settings:

[
  {
    "parentId": "19cc77e2-0aab-4578-a79c-0d8160671a34",
    "title": "Custom Sub-Job",
    "useParentData": false,
    "description": "Custom description",
    "assign": {
      "type": "both",
      "userIds": [7031021],
      "groupIds": []
    },
    "gps": {
      "address": "Different location"
    }
  }
]

Update Sub-Jobs

Use the Update Job endpoint with the sub-job ID:

PUT /jobs/v1/jobs/{subJobId}

You cannot change a sub-job's parent. The parentId in the request must match the current parent.

Request (inheriting from parent)

{
  "parentId": "19cc77e2-0aab-4578-a79c-0d8160671a34",
  "title": "Updated Sub-Job Title",
  "useParentData": true
}

Request (custom settings)

{
  "parentId": "19cc77e2-0aab-4578-a79c-0d8160671a34",
  "title": "Updated Sub-Job Title",
  "useParentData": false,
  "assign": {
    "type": "both",
    "userIds": [7031021],
    "groupIds": []
  }
}

Delete Sub-Jobs

Use the Delete Job endpoint with the sub-job ID:

DELETE /jobs/v1/jobs/{subJobId}

curl -X DELETE \
  'https://api.connecteam.com/jobs/v1/jobs/7c86a7c2-6736-4c91-aeec-b1beb64fb7b5' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Note: You cannot delete the last remaining sub-job. A parent must always have at least one sub-job.

Error Responses

Jobs API reference