---
updatedAt: 2026-01-28T09:44:33.000Z
---

Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further.

# Create jobs

Create one or multiple jobs in a single request. Jobs can be standalone or include nested sub-jobs.

`POST /jobs/v1/jobs`

## Limits

* **Maximum 500 jobs** per request
* **Title maximum 128 characters**

## Request Body

The request accepts an array of job objects. Each job can be either a parent job or a sub-job.

### Parent Job Fields

| Field        | Type   | Required | Description                                     |
| :----------- | :----- | :------- | :---------------------------------------------- |
| instanceIds  | array  | Yes      | List of scheduler or time clock IDs             |
| title        | string | Yes      | Job title (max 128 characters)                  |
| code         | string | No       | Job code identifier                             |
| description  | string | No       | Job description                                 |
| color        | string | No       | Hex color code (default: #4B7AC5)               |
| gps          | object | No       | Location data with address, longitude, latitude |
| assign       | object | Yes      | Assignment settings (see below)                 |
| subJobs      | array  | No       | Nested sub-jobs to create with the parent       |
| customFields | array  | No       | Custom field values                             |

### Assign Object

| Field    | Type   | Required | Description                              |
| :------- | :----- | :------- | :--------------------------------------- |
| type     | string | Yes      | Must be `both`                           |
| userIds  | array  | Yes      | User IDs to assign (can be empty)        |
| groupIds | array  | Yes      | Smart group IDs to assign (can be empty) |

### Valid Colors

```
#4B7AC5 (default), #801A1A, #AE2121, #DC7A7A, #B0712E, #D4985A, #E4B37F,
#AE8E2D, #CBA73A, #D9B443, #487037, #6F9B5C, #91B282, #365C64, #5687B3,
#7C9BA2, #3968BB, #85A6DA, #225A8C, #548CBE, #81A8CC, #4E3F75, #604E8E,
#8679AA, #983D73, #A43778, #D178AD, #6B2E4C, #925071, #B57D9A, #3a3a3a,
#616161, #969696
```

***

## Example: Create a Simple Job

### Request

```json
[
  {
    "instanceIds": [6833518],
    "title": "Delivery Driver",
    "code": "DD-001",
    "description": "Delivery operations role",
    "color": "#3968BB",
    "gps": {
      "address": "123 Main St, New York",
      "longitude": -73.93,
      "latitude": 40.71
    },
    "assign": {
      "type": "both",
      "userIds": [7031021],
      "groupIds": []
    }
  }
]
```

### Response

```json
{
  "requestId": "6c5f7f64-df27-4430-b41e-fe0f86ec20dd",
  "data": {
    "jobs": [
      {
        "jobId": "9fdebf1f-0c69-4914-89d2-8f86c3e5f47d",
        "title": "Delivery Driver",
        "code": "DD-001",
        "color": "#3968BB",
        "description": "Delivery operations role",
        "gps": {
          "address": "123 Main St, New York",
          "longitude": -73.93,
          "latitude": 40.71
        },
        "isDeleted": false,
        "assign": {
          "type": "both",
          "userIds": [7031021],
          "groupIds": []
        },
        "useParentData": false,
        "parentId": null,
        "subJobs": [],
        "instanceIds": [6833518],
        "customFields": []
      }
    ]
  }
}
```

***

## Example: Create Job with Sub-Jobs

Create a parent job with nested sub-jobs in a single request. Sub-jobs inherit `assign`, `gps`, and `description` from the parent by default.

### Request

```json
[
  {
    "instanceIds": [6833518],
    "title": "Warehouse Operations",
    "code": "WH-001",
    "color": "#225A8C",
    "assign": {
      "type": "both",
      "userIds": [],
      "groupIds": [5321397]
    },
    "subJobs": [
      {
        "title": "Receiving"
      },
      {
        "title": "Picking"
      },
      {
        "title": "Shipping"
      }
    ]
  }
]
```

***

## Example: Sub-Job with Custom Settings

To give a sub-job its own settings, set `useParentData: false` and provide the `assign` field.

> 🚧 Important
>
> When `useParentData` is `false`, you **must** provide the `assign` field. When `useParentData` is `true` (default), you **cannot** set `assign`, `gps`, or `description`.

### Request

```json
[
  {
    "instanceIds": [6833518],
    "title": "Warehouse Operations",
    "code": "WH-001",
    "assign": {
      "type": "both",
      "userIds": [],
      "groupIds": [5321397]
    },
    "subJobs": [
      {
        "title": "Night Shift Receiving",
        "useParentData": false,
        "description": "Overnight receiving duties",
        "assign": {
          "type": "both",
          "userIds": [7031021],
          "groupIds": []
        }
      },
      {
        "title": "Picking"
      }
    ]
  }
]
```

***

## Example: Add Sub-Job to Existing Parent

To add a sub-job to an existing parent job, use `parentId` instead of `instanceIds`.

> ⚠️ Warning
>
> You **cannot** add sub-jobs to a job that was created without any. This is permanent.

### Request

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

***

## Error Responses

| Status | Error                      | Description                                 |
| :----- | :------------------------- | :------------------------------------------ |
| 400    | Invalid instance ids       | One or more instanceIds don't exist         |
| 400    | Parent name already exists | A job with this title already exists        |
| 400    | Duplicate sub job name     | Sub-job titles must be unique within parent |
| 400    | Parent job not found       | parentId doesn't exist                      |
| 400    | Invalid color              | Color not in allowed list                   |

[Create Jobs API reference](https://developer.connecteam.com/reference/create_jobs_jobs_v1_jobs_post)