Sign in
Jobs

Get a job

Retrieve the details of a single job (required scope jobs:read)

get/v1/jobs/{jobId}

Path parameters

jobIdinteger required

The unique identifier of the job

Headers

Customer-Idinteger required

The customer identifier

Response

OK

idinteger

The unique identifier of the job

uidstring uuid nullable

The unique uid of the job

typeIdinteger

The unique identifier of the type assigned to this job

typeNamestring

The name of the type assigned to this job

contactIdinteger

The unique identifier of the contact (customer) for whom this job is to be performed

contactNamestring

The name of the customer (business or individual) for whom this job is to be performed

contactAddressstring

The complete address of the contact (customer) for whom this job is to be performed

status'new' | 'scheduled' | 'unscheduled' | 'sent' | 'read' | 'accepted' | 'refused' | 'onTheWay' | 'started' | 'suspended' | 'completedOk' | 'completedWithIssues' | 'cancelled' | 'lateStart' | 'lateFinish' | 'rescheduled'

Describes each possible status of a Job<p>Possible values:</p><ul><li><b>new</b>: A job that is newly created in BigChange All Jobs start with a New status, regardless of schedule detail</li><li><b>scheduled</b>: Job has been scheduled. Scheduled status is when the Vehicle, Driver, and Planned Date Time are all allocated</li><li><b>unscheduled</b>: Job has been unscheduled. Unscheduled status happens when any combination of the Vehicle, Driver, and Planned Date Time are all removed from a Scheduled job</li><li><b>sent</b>: The scheduled job has been delivered to the driver's mobile device (tablet/phone). The driver must be logged into BigChange for jobs to be sent</li><li><b>read</b>: Job Detail has been read by the Driver on their mobile terminal</li><li><b>accepted</b>: Driver accepted the job</li><li><b>refused</b>: Driver refused the job</li><li><b>onTheWay</b>: Driver indicated they are on route to the Job Address</li><li><b>started</b>: Driver has indicated they have started the work detailed in the Job</li><li><b>suspended</b>: Driver paused work – ie taking a break</li><li><b>completedOk</b>: Job Completed with no issues</li><li><b>completedWithIssues</b>: Job Completed with issues</li><li><b>cancelled</b>: Job was Cancelled</li><li><b>lateStart</b>: Internal Status used by BigChange Alert Management - should not be visible from the the API</li><li><b>lateFinish</b>: Internal Status used by BigChange Alert Management - should not be visible from the the API</li><li><b>rescheduled</b>: Internal Status used by BigChange Alert Management - should not be visible from the the API</li></ul>

statusModifiedAtstring date-time nullable

The UTC timestamp for when the job status was last updated

plannedDurationinteger

The planned duration of the job, specified in minutes

dueAtstring date-time nullable

The UTC date and time the job is required to be completed by

referencestring

The internal reference of the job - should usually be unique

descriptionstring

The textual details about the job

createdAtstring date-time

The UTC timestamp of when this job was created

orderNumberstring nullable

The order number associated to the job

personIdstring uuid nullable

The unique uuid identifier of the person who will serve as primary point of contact for the job

personNamestring nullable

The full name of the person who will serve as primary point of contact for the job

isConfirmedboolean

A flag indicating whether the job has been confirmed by the contact

categoryIdinteger nullable

The unique identifier of the category that the job is assigned to

categoryNamestring nullable

The name of the category that the job is assigned

resourceIdinteger nullable

The unique identifier of the resource assigned to this job

resourceNamestring nullable

The full name of the resource assigned to this job

vehicleIdinteger nullable

The unique identifier of the vehicle assigned to this job

vehicleRegistrationstring nullable

The registration number of the vehicle assigned to this job

plannedStartAtstring date-time nullable

The UTC timestamp for when the job is planned to begin

plannedEndAtstring date-time nullable

The UTC timestamp for when the job is planned to finish

actualStartAtstring date-time nullable

The UTC timestamp for when the job actually started (as indicated by resource's device)

actualEndAtstring date-time nullable

The UTC timestamp for when the job actually finished (as indicated by resource's device)

actualDurationinteger nullable

The actual duration of the job, specified in seconds (as indicated by resource's device)

internalCommentstring

Notes about the job outcome, added by the back office

resourcesCommentstring

Notes about the job outcome, added by the resource

contactCommentstring

Notes about the job outcome, added by the customer

resultstring nullable

The result of a job that has been completed or completed with issues. This will be null if the job has any other status

jobGroupIdinteger nullable

The unique identifier of the job group

isFinanciallyCompleteboolean

A flag indicating whether the job is financially complete

isActionedboolean

A flag indicating whether all actions concerned with the job have been completed

officeNotesstring

Notes for the office team regarding the job

contractIdinteger nullable

The unique identifier of the contract that the job is associated with

recurrenceIdinteger nullable

The unique identifier of the recurrence series this job belongs to, or null if the job is not part of a recurring series

siteContactIdsinteger[]

The unique identifiers of the site contacts associated with this job

Example response

{
  "id": 5514123,
  "uid": "3729C414-ED21-4849-816F-25D332265DC8",
  "typeId": 5514123,
  "typeName": "Boiler Service",
  "contactId": 5514123,
  "contactName": "Global Solutions Ltd",
  "contactAddress": "15 High Street, Lichfield, Staffordshire, WS15 3TT",
  "contactLocation": {
    "latitude": 51.31349,
    "longitude": -0.7464233
  },
  "status": "new",
  "statusModifiedAt": "2022-11-29T13:39:00.0000000+00:00",
  "plannedDuration": 90,
  "dueAt": "2022-11-29T06:00:00.0000000+00:00",
  "reference": "ABC/5514123",
  "description": "New boiler install - please remove and retain the old boiler",
  "createdAt": "2022-11-29T16:50:16.0000000+00:00",
  "orderNumber": "PAO/1312KU",
  "personId": "3729c414-ed21-4849-816f-25d332265dc8",
  "personName": "Peter Brown",
  "isConfirmed": true,
  "categoryId": 5514123,
  "categoryName": "Global Solutions Ltd",
  "resourceId": 243556,
  "resourceName": "John Smith",
  "vehicleId": 665433,
  "vehicleRegistration": "BC21 BCL",
  "plannedStartAt": "2022-11-29T12:00:00.0000000+00:00",
  "plannedEndAt": "2022-11-29T13:30:00.0000000+00:00",
  "actualStartAt": "2022-11-29T12:03:00.0000000+00:00",
  "actualEndAt": "2022-11-29T13:39:00.0000000+00:00",
  "actualDuration": 6000,
  "internalComment": "Old boiler has been moved to storage",
  "resourcesComment": "Boiler removed and stored in van",
  "contactComment": "No issues with new boiler",
  "result": "Ok",
  "jobGroupId": 123456789,
  "officeNotes": "Customer has requested a follow-up call",
  "contractId": 123456,
  "recurrenceId": 789012,
  "customFields": [
    {
      "definitionId": 5514123,
      "value": "Purple",
      "definition": {
        "caption": "Favourite colour",
        "type": "boolean",
        "listOptions": [
          "Red",
          "Blue",
          "Green",
          "Purple"
        ],
        "isRequired": true,
        "isEditable": true,
        "default": "10"
      },
      "systemListValueMetadata": {
        "label": "John Doe",
        "entityType": "resource"
      }
    }
  ],
  "siteContactIds": [
    15548440,
    9425766
  ]
}