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

[
  {
    "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

{
  "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

[
  {
    "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

[
  {
    "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

[
  {
    "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