---
title: "Update a job"
method: PATCH
path: "/v1/jobs/{jobId}"
tags: ["Jobs"]
---

# Update a job

`PATCH /v1/jobs/{jobId}`

Updates the details of a specific job. To set the JobGroupId, any existing JobGroupId must have been removed by setting it to null in a previous update. A job can be added to any job group, except a job group marked Financially Complete (required scope jobs:write)

## Path parameters

- `jobId` integer, required

## Headers

- `Customer-Id` integer, required

## Request body

- UpdateJobModel — Update job model.<br/>At least one optional value must be provided.<br/> <br/>Validation:<br/>- The request body must contain at least one provided value
  - `plannedDuration` integer — The planned duration for the job, indicated in minutes.<br/> <br/>Validation:<br/>- Must be greater than 0.<br/>- Must be less than or equal to 1440.<br/><br/>Optional: Omit to retain current value
  - `description` string — The textual details about the job.<br/>Cannot be updated if the job has been started or completed.<br/> <br/>Validation:<br/>- Only allowed when job status is New, Sent, Accepted, Refused, or Scheduled.<br/>- Cannot be null when provided.<br/>- Maximum length is 1000 characters.<br/><br/>Optional: Omit to retain current value
  - `reference` string, nullable — The internal reference of the job.<br/>Should usually be unique.<br/> <br/>Validation:<br/>- Maximum length is 40 characters.<br/><br/>Optional: Omit to retain current value or provide null to unset
  - `personId` string, uuid, nullable — The unique UUID identifier of the person who will serve as primary point of contact for the job.<br/>If set to null, the primary person for the contact will be set instead.<br/>Cannot be updated if the job has been started or completed.<br/> <br/>Validation:<br/>- Only allowed when job status is New, Sent, Accepted, Refused, or Scheduled.<br/>- If provided and not null, the person must exist and belong to the job’s contact.<br/><br/>Optional: Omit to retain current value or provide null to unset
  - `orderNumber` string, nullable — The order number associated with the job.<br/>May be required, dependent upon job type.<br/> <br/>Validation:<br/>- Required if the job type mandates an order number.<br/>- Maximum length is 40 characters.<br/>- Cannot be empty when required.<br/><br/>Optional: Omit to retain current value or provide null to unset
  - `jobGroupId` integer, nullable — The unique identifier of the job group to which this job belongs.<br/> <br/>Validation:<br/>- If provided, job must not already belong to another group.<br/>- The job group must exist.<br/>- The job group must not be financially completed.<br/><br/>Optional: Omit to retain current value or provide null to unset
  - `categoryId` integer, nullable — The unique identifier of the category that the job is assigned to.<br/><br/>Validation:<br/>- If provided and not null, the category must exist and be visible for Jobs (JobCategoryVisibility 0 or 2).<br/><br/>Optional: Omit to retain current value or provide null to unset
  - `isFinanciallyComplete` boolean — Indicates whether the job is financially complete.<br/> <br/>Validation:<br/>- Can only be set to true when job status is CompletedOk or CompletedWithIssues.<br/><br/>Optional: Omit to retain current value
  - `isActioned` boolean — A flag indicating whether all actions concerned with the job have been completed.<br/> <br/>Validation:<br/>- Can only be set to true when job status is CompletedOk or CompletedWithIssues.<br/><br/>Optional: Omit to retain current value
  - `officeNotes` string, nullable — Notes for the office team regarding the job.<br/> <br/>Validation:<br/>- Maximum length is 500 characters.<br/>- Only allowed when job status is CompletedOk or CompletedWithIssues if non-empty.<br/><br/>Optional: Omit to retain current value or provide null to unset
  - `customFields` CustomFieldWriteModel[] — Custom fields associated with the job.<br/>Omit or use an empty list to retain current values.<br/> <br/>Validation:<br/>- Cannot be null when provided.<br/>- Each custom field must satisfy its definition rules for the job type.<br/><br/>Optional: Omit to retain current value
    - `definitionId` integer, required — The unique identifier of the associated custom field definition
    - `value` string, nullable — The value of this custom field. If set to null, any existing value will be unset
  - `siteContactId` integer, nullable — The unique identifier of the site contact for this job.<br/>If provided, the contact must exist within the customer's account.<br/>Cannot be null when provided.<br/><br/>Optional: Omit to retain current value or provide null to unset

## Response `204`

No Content

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `404` — Not Found
- `422` — Unprocessable Content
- `500` — Internal Server Error

---

[API](https://skmtc.net/bigchange/apis/bigchange-dx.md) · [All operations](https://skmtc.net/bigchange/apis/bigchange-dx/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bigchange/bigchange-dx/revisions/916e669fc527/schema)