Programming Guide to the Hours of Service Platform

Work Orders

Work Orders are tasks assigned to Drivers and is paired with an existing Job Site. Work Orders contain information regarding the status of the task, the time spent for the it and Media files and comments associated with it.

Fields

Tag Data Type Required Description
accountId Long No The id of the Account that owns this record.
actualStartTime Text No Date and time stamp indicating when work began.
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
actualStopTime Text No Date and time stamp indicating when work was completed.
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
comment Text (unlimited) No Additional notes about the work to be performed
completedTime Text No Target completion time for work order 
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
deletedAt Text No Timestamp of when the work order was soft deleted. This is not returned for records that have not been deleted.
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
description Text (unlimited) No Text overview of Work Order  
fields Object No Collection of default and custom field values in the record. 
id Auto-incremented Long Auto Unique identifier 
jobSiteId Long Yes ID of the Job Site where this Work Order is to be performed.
lastChangedDate Text Auto Auto-generated timestamp of the last change made to this record
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
media Array  No Collection of Media files attached to the Work Order Report
requestedStartTime Text No Target start time for work order 
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
signature Text (unlimited) No BLOB of the User’s signature 
totalTimeWorked Text No Total time spent by user on Work Order
Note: Must be in seconds Duration format (PT##S). Where ## is the number of seconds (see examples)
userId Long No Id of the User assigned to perform this Work Order.
viewTimestamp Text No Date and time stamp indicating when work was viewed by user.
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)

Read

API PATH: /api/v2/workOrders
METHOD: GET
PARAMETERS: user-id – Retrieves matching records for a specific User (e.g. user-id=1253461, current User by default)
job-site-id – Retrieves matching records for a specific Job Site (e.g. job-site-id=37133, all Job Sites by default)
from-completed-date – Retrieves matching records completed on or after the specified date (e.g. from-completed-date=2018-06-11T12:00:00.000Z, all dates by default)
to-completed-date – Retrieves matching records completed on or before the specified date (e.g. to-completed-date=2018-06-11T12:00:00.000Z, all dates by default)
from-request-date – Retrieves matching records requested on or after the specified date (e.g. from-request-date=2018-06-11T12:00:00.000Z, all dates by default)
to-request-date – Retrieves matching records requested on or before the specified date (e.g. to-request-date=2018-06-11T12:00:00.000Z, all dates by default)
from-deleted-at – Retrieves matching records that were deleted after the specified timestamp. Setting to * will return all records. (e.g. from-deleted-at=2018-06-11T12:00:00.000Z, null by default – returns only non-deleted records)
from-change-timestamp – Retrieves matching records that were changed after the specified timestamp (e.g. from-change-timestamp=2018-06-11T12:00:00.000Z)
to-change-timestamp – Retrieves matching records that were changed before the specified timestamp (e.g. to-change-timestamp=2018-06-11T12:00:00.000Z, REQUIRES from-change-timestamp)
offset – Retrieves matching records after an offset value (e.g. offset=2, zero offset by default)
limit – Retrieves a number of records per page specified by the value (e.g. limit=10, all records by default)
SORTING: sort=id – Sort records by their id field in ascending order (DEFAULT)
sort=-id – Sort records by their id field in descending order
sort=user-id – Sort records by their userId field in ascending order
sort=-user-id – Sort records by their userId field in descending order
sort=job-site-id – Sort records by their jobSiteId field in ascending order
sort=-job-site-id – Sort records by their jobSiteId field in descending order
sort=actual-start-time – Sort records by their actualStartTime field in ascending order
sort=-actual-start-time – Sort records by their actualStartTime field in descending order
sort=actual-stop-time – Sort records by their actualStopTime field in ascending order
sort=-actual-stop-time – Sort records by their actualStopTime field in descending order
sort=completed-time – Sort records by their actualStopTime field in ascending order
sort=-completed-time – Sort records by their actualStopTime field in descending order
sort=requested-start-time – Sort records by their requestedStartTime field in ascending order
sort=-requested-start-time – Sort records by their requestedStartTime field in descending order
sort=view-timestamp – Sort records by their viewTimestamp field in ascending order
sort=-view-timestamp – Sort records by their viewTimestamp field in descending order
sort=total-time-worked – Sort records by their totalTimeWorked field in ascending order
sort=-total-time-worked – Sort records by their totalTimeWorked field in descending order
QUERY STRING EXAMPLES: Get the Work Order with the specified id: api/v2/workOrders/21299
Get all Work Orders set on Jobsite 37133: ?job-site-id=37133
Get two work orders for the authenticated user with an offset of 1 : ?user-id=1253461&offset=1&limit=2
Get all work orders of the current account sorted by description alphabetically: ?sort=description
EXAMPLE RESPONSE: 
[
  {
    "description": "Work Order 1",
    "userId": 1253461,
    "jobSiteId": 37133,
    "comment": "Work order report",
    "actualStartTime": "2018-06-11T12:00:00.000Z",
    "actualStopTime": "2018-06-11T12:10:00.000Z",
    "completedTime": "2018-06-11T12:10:00.000Z",
    "requestedStartTime": "2018-06-11T12:00:00.000Z",
    "viewTimestamp": "2018-06-11T12:00:00.000Z",
    "signature": "BLOB value of signature",
    "totalTimeWorked": "PT600.0S",
    "fields": {
      "__WORK_ORDER_ON_DEVICE": "true"
    },
    "media": [
      {
        "name": "IMG_2018-06-11-20.04.33.jpg",
        "filename": "IMG_2018-06-11-20.04.33.jpg",
        "accountId": 1248401,
        "id": 4657,
        "lastChangedDate": null
      }
    ],
    "accountId": 1248806,
    "id": 21299,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]  

Create

API PATH: /api/v2/workOrders
METHOD: POST
EXAMPLE REQUEST: 
[
  {
    "description": "Work Order 1",
    "userId": 1253461,
    "jobSiteId": 37133,
    "requestedStartTime": "2018-06-11T12:00:00.000Z"
  }
]  
EXAMPLE RESPONSE 
[
  {
    "description": "Work Order 1",
    "userId": 1253461,
    "jobSiteId": 37133,
    "requestedStartTime": "2018-06-11T12:00:00.000Z",
    "fields": {},
    "media": [],
    "accountId": 1248806,
    "id": 21299,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]

Update

API PATH: /api/v2/workOrders
METHOD: PUT
EXAMPLE REQUEST: 
[
  {
    "description": "Work Order 1",
    "userId": 1253461,
    "jobSiteId": 37133,
    "comment": "Work order report",
    "actualStartTime": "2018-06-11T12:00:00.000Z",
    "actualStopTime": "2018-06-11T12:10:00.000Z",
    "completedTime": "2018-06-11T12:10:00.000Z",
    "requestedStartTime": "2018-06-11T12:00:00.000Z",
    "viewTimestamp": "2018-06-11T12:00:00.000Z",
    "signature": "BLOB value of signature",
    "totalTimeWorked": "PT600.0S",
    "fields": {
      "__WORK_ORDER_ON_DEVICE": "true"
    },
    "media": [],
    "id": 16677
  }
]
EXAMPLE RESPONSE 
[
  {
    "description": "Work Order 1",
    "userId": 1253461,
    "jobSiteId": 37133,
    "comment": "Work order report",
    "actualStartTime": "2018-06-11T12:00:00.000Z",
    "actualStopTime": "2018-06-11T12:10:00.000Z",
    "completedTime": "2018-06-11T12:10:00.000Z",
    "requestedStartTime": "2018-06-11T12:00:00.000Z",
    "viewTimestamp": "2018-06-11T12:00:00.000Z",
    "signature": "BLOB value of signature",
    "totalTimeWorked": "PT600.0S",
    "fields": {
      "__WORK_ORDER_ON_DEVICE": "true"
    },
    "media": [],
    "accountId": 1248806,
    "id": 21299,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]  

Update with attachments

API PATH: /api/v2/workOrders?_method=PUT
METHOD: POST
EXAMPLE REQUEST:

To update and complete a work order with attachments and send an email notification, the request must be a multipart.

Header

Content-Type: multipart/form-data; boundary=-------------------------acebdf13572468
User-Agent: Fiddler
Authorization: Basic [base64_Credentials]
Host: eld.azuga.com

Body

-----------------------------acebdf13572468
Content-Disposition: form-data; name="json"

[
  {
    "description": "Work Order 1",
    "userId": 1253461,
    "jobSiteId": 37133,
    "comment": "Work order report",
    "actualStartTime": "2018-06-11T12:00:00.000Z",
    "actualStopTime": "2018-06-11T12:10:00.000Z",
    "completedTime": "2018-06-11T12:10:00.000Z",
    "requestedStartTime": "2018-06-11T12:00:00.000Z",
    "viewTimestamp": "2018-06-11T12:00:00.000Z",
    "signature": "BLOB value of signature",
    "totalTimeWorked": "PT600.0S",
    "fields": {
      "__WORK_ORDER_ON_DEVICE": "true"
    },
    "media": [],
    "id": 21299
  }
] 
---------------------------acebdf13572468
Content-Disposition: form-data; name="file"; filename="work_order.jpg"
Content-Type: image/jpeg

<@INCLUDE *C:\Users\User\Desktop\work_order.jpg*@>
---------------------------acebdf13572468--
EXAMPLE RESPONSE: 
[
  {
    "description": "Work Order 1",
    "userId": 1253461,
    "jobSiteId": 37133,
    "comment": "Work order report",
    "actualStartTime": "2018-06-11T12:00:00.000Z",
    "actualStopTime": "2018-06-11T12:10:00.000Z",
    "completedTime": "2018-06-11T12:10:00.000Z",
    "requestedStartTime": "2018-06-11T12:00:00.000Z",
    "viewTimestamp": "2018-06-11T12:00:00.000Z",
    "signature": "BLOB value of signature",
    "totalTimeWorked": "PT600.0S",
    "fields": {
      "__WORK_ORDER_ON_DEVICE": "true"
    },
    "media": [
      {
        "name": "file",
        "filename": "work_order.jpg",
        "id": 34324
      }
    ],
    "accountId": 1248806,
    "id": 21299,
    "lastChangedDate": "2018-06-11T12:10:00.000Z"
  }
]  

Delete

API PATH: /api/v2/workOrders/<id>
METHOD: DELETE

API error calls

ERROR MESSAGE POSSIBLE CAUSES
JSON read failed: <message> JSON error with the error message
Cannot find requested work order. (id = <id>) PUT error because Work Order id does not exist
The requested work order has been closed and cannot be changed. PUT error because editing a close Work Order is not allowed
Work Order is not assigned to current user anymore. PUT error because the request must contain the correct assigned User