Sign in
Jobs

Update a job

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)

patch/v1/jobs/{jobId}

Path parameters

jobIdinteger required

Headers

Customer-Idinteger required

The customer identifier

Request body

plannedDurationinteger

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

descriptionstring

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

referencestring 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

personIdstring 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

orderNumberstring 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

jobGroupIdinteger 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

categoryIdinteger 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

isFinanciallyCompleteboolean

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

isActionedboolean

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

officeNotesstring 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

siteContactIdinteger 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

Example request

{
  "plannedDuration": 90,
  "description": "New boiler install - please remove and retain the old boiler",
  "reference": "ABC/5514123",
  "personId": "3729c414-ed21-4849-816f-25d332265dc8",
  "orderNumber": "PAO/1312KU",
  "jobGroupId": 42,
  "categoryId": 5514123,
  "officeNotes": "Customer has requested a follow-up call",
  "customFields": [
    {
      "definitionId": 5514123,
      "value": "High net worth"
    }
  ],
  "siteContactId": 15548440
}

Response

No Content