Update job

Update an existing job or sub-job by its unique ID.

PUT /jobs/v1/jobs/{jobId}

How an Update Works

🚧
Important Note
PUT replaces the job, so send the full job. Some fields you leave out are reset, not kept.

When you update a job that isn't a sub-job (a standalone job or a parent job):

Field left out	Result
color	Resets to the default color
code, description, gps, fenceSize	Cleared
assign	Kept
instanceIds	Kept. Send `[]` to unassign the job from every scheduler and time clock
customFields	Kept. Only the custom fields you send are updated

Updating a Parent Job with Sub-Jobs

You can update a parent job that has sub-jobs. Its sub-jobs are kept, and the parent's request never creates, changes, or deletes a sub-job. To change a sub-job, update it by its own ID (see Example: Update Sub-Job).

When the parent is updated:

Every sub-job takes the parent's color and instanceIds
Sub-jobs with useParentData: true also take the parent's assign, description, gps, fenceSize, and custom field values
Sub-jobs with useParentData: false keep their own settings, but lose any users or groups that the parent's assign no longer includes

Restrictions

Cannot change a sub-job's parent (parentId cannot be modified)
Title must be unique

Path Parameters

Parameter	Type	Required	Description
jobId	string	Yes	The unique identifier of the job or sub-job

Request Body (Parent Job)

Field	Type	Required	Description
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
gps	object	No	Location data
fenceSize	integer	No	Geofence size
assign	object	No	Assignment settings. Left out: the current assignment is kept
instanceIds	array	No	Assigned scheduler/time clock IDs. Left out: the current ones are kept
customFields	array	No	Custom field values. Only the fields you send are updated

Request Body (Sub-Job)

Field	Type	Required	Description
parentId	string	Yes	ID of the parent job (cannot be changed)
title	string	Yes	Sub-job title
code	string	No	Sub-job code
useParentData	boolean	Yes	Whether to inherit from parent
description	string	Conditional	Required if useParentData is false
gps	object	Conditional	Required if useParentData is false
assign	object	Conditional	Required if useParentData is false
customFields	array	No	Custom field values

Example: Update Parent Job

The same request works for a standalone job and for a parent job with sub-jobs.

Request

{
  "title": "Updated Job Title",
  "code": "UPD-001",
  "description": "Updated description",
  "color": "#3968BB",
  "gps": {
    "address": "456 New Address, City",
    "longitude": -77.12,
    "latitude": 38.98
  },
  "assign": {
    "type": "both",
    "userIds": [],
    "groupIds": [1123124, 1234456]
  }
}

Response

{
  "requestId": "abc123-def456",
  "data": {
    "job": {
      "jobId": "9fdebf1f-0c69-4914-89d2-8f86c3e5f47d",
      "title": "Updated Job Title",
      "code": "UPD-001",
      "color": "#3968BB",
      "description": "Updated description",
      "gps": {
        "address": "456 New Address, City",
        "longitude": -77.12,
        "latitude": 38.98
      },
      "isDeleted": false,
      "assign": {
        "type": "both",
        "userIds": [],
        "groupIds": ["1123124", "1234456"]
      },
      "useParentData": false,
      "parentId": null,
      "subJobs": [],
      "instanceIds": [6833518],
      "customFields": []
    }
  }
}

Example: Update a Parent Job's Custom Field and Instances

Set a custom field on a parent job and assign it to an additional time clock. Its sub-jobs follow the new instances, and sub-jobs with useParentData: true return the parent's custom field value.

{
  "title": "Riverside Tower",
  "code": "RT-100",
  "description": "Main building site",
  "color": "#3968BB",
  "assign": {
    "type": "both",
    "userIds": [],
    "groupIds": [1123124]
  },
  "instanceIds": [6833518, 6833601],
  "customFields": [
    {
      "customFieldId": 121,
      "value": "006Hs00001SFDC42"
    }
  ]
}

Example: Update Sub-Job

When updating a sub-job, you must include the parentId and useParentData fields.

Request (inheriting from parent)

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

Request (with custom settings)

{
  "parentId": "19cc77e2-0aab-4578-a79c-0d8160671a34",
  "title": "Updated Sub-Job Title",
  "code": "SUB-UPD",
  "useParentData": false,
  "description": "Custom description for sub-job",
  "assign": {
    "type": "both",
    "userIds": [7031021],
    "groupIds": []
  }
}

Error Responses

Status	Error	Description
400	Cannot update sub-job parent	parentId cannot be changed
400	Invalid instance ids	instanceIds don't exist
400	Job name already exists	Title must be unique
400	assign must be defined when use_parent_data is false	Missing required field
404	Job not found	jobId doesn't exist

Update Job API reference

How an Update Works

Important Note

Updating a Parent Job with Sub-Jobs

Restrictions

Path Parameters

Request Body (Parent Job)

Request Body (Sub-Job)

Example: Update Parent Job

Request

Response

Example: Update a Parent Job's Custom Field and Instances

Example: Update Sub-Job

Request (inheriting from parent)

Request (with custom settings)

Error Responses

What’s Next