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

# Update a job

`PATCH /v1/jobs/{jobId}`

## Request

- Base URL: `https://api.bigchange.com`
- URL: `https://api.bigchange.com/v1/jobs/{jobId}`
- Auth: HTTP bearer

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
  - `assistants` JobAssistantModel[]: Assistants associated with the job.<br/><br/>Optional: Omit to retain current value
    - `resourceId` integer: A unique identifier representing resource
  - `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

## Changes

- **2026-09-30** `45b05fe73cc9`: 1 info
  - added the new optional request property `assistants`

[Operation history](https://skmtc.dev/bigchange/apis/bigchange-dx/changes/v1/jobs/:jobId/patch.md)

---

[API](https://skmtc.dev/bigchange/apis/bigchange-dx.md) - [All operations](https://skmtc.dev/bigchange/apis/bigchange-dx/llms.txt) - [OpenAPI document](https://skmtc.dev/bigchange/apis/bigchange-dx/revisions/b262bfdb1dd0?raw)