Jobs¶

The Job API caters for creating, monitoring and deleting jobs. Jobs can also be updated through the API as long as they are not on a mobile device. The job API currently has the following restrictions:

No support for advanced job state management. Job state management can only happen on mobile devices or through the webapp.
No support for scheduling recurrent jobs.

List Jobs¶

GET /job/?start=<start date>&end=<end date>¶

Retrieve list of jobs in given time window. Deferred and recurrent jobs are also listed and are discriminated by the existence of the notificationDelta field. The list can be sorted on scheduled time, jobId or state. The list also supports some limited filtering. In particular, the list can be filtered on exact match on job lead (by uuid), location (by uuid) or state. “state” field is an array of length at least one. The first value corresponds to the state and the remainder, if any, to the substates.

The <start date> and <end date> parameters must be given in ISO 8601 format, and need to be URL-encoded where appropriate. For example, the datetime 2014-01-31 10:00:00, must appear in the URL as 2014-01-31+10%3A00%3A00. The space between the date and time components needs to be URL-encoded (as a ‘+’), and the colons (:) between the hours, minutes and seconds must be encoded as well (as %3A00).

The job list can be sorted on scheduledOn, jobId, and state. The job list can be filtered on jobLead, locaton, and state.

Sample Request:

GET https://api.fieldaware.net/job/?start=2012-09-19T16%3A00&end=2012-09-19T17%3A00&pageSize=3 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
Accept: application/json

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://api.fieldaware.net/job/?start=2012-09-19T16%3A00&end=2012-09-19T17%3A00&page=0&pageSize=3>; rel=first,<https://api.fieldaware.net/job/?start=2012-09-19T16%3A00&end=2012-09-19T17%3A00&page=3&pageSize=3>; rel=last,<https://api.fieldaware.net/job/?start=2012-09-19T16%3A00&end=2012-09-19T17%3A00&page=1&pageSize=3>; rel=next

  {
      "count": 9,
      "pageSize": 3,
      "items": [
          {
              "startedOn": "2012-09-19T16:57:00+00:00",
              "state": [
                  "completed"
              ],
              "uuid": "99c313e92fb446bea07faeca5d5d392d",
              "invoice": {
                  "uuid": "0021b917a7b444a697c751f361c22545"
              },
              "completedOn": "2012-09-19T17:00:00+00:00",
              "jobLead": {
                  "uuid": "35e6bfb499e04e0fa7b2f80519a573f9"
              },
              "scheduledOn": "2012-09-19T17:00:00+00:00",
              "createdOn": "2012-09-19T16:57:04+00:00",
              "location": {
                  "uuid": "f367809ccd224716ad97cd685aafe899"
              },
              "jobId": "J598",
              "link": {
                "rel": "detail",
                "url": "https://api.fieldaware.net/job/99c313e92fb446bea07faeca5d5d392d",
              }
          },
          {
              "startedOn": "2012-09-12T21:33:00+00:00",
              "state": [
                  "active"
              ],
              "uuid": "5ec7b82dfbbf40e49e01cd46145cf069",
              "invoice": null,
              "completedOn": null,
              "jobLead": {
                  "uuid": "d4d01046ce194da7a5d6fc3df749667d"
              },
              "scheduledOn": "2012-09-12T21:33:00+00:00",
              "createdOn": "2012-09-12T21:33:23+00:00",
              "location": {
                  "uuid": "2e557478fbc443c08fc4da7d77f4cb21"
              },
              "jobId": "J583",
              "link": {
                "rel": "detail",
                "url": "https://api.fieldaware.net/job/5ec7b82dfbbf40e49e01cd46145cf069",
              }
          },
          {
              "startedOn": "2012-09-05T15:45:00+00:00",
              "state": [
                  "active"
              ],
              "uuid": "6739f71557c24a5ab16dc8549584ff30",
              "invoice": null,
              "completedOn": null,
              "jobLead": {
                  "uuid": "d4d01046ce194da7a5d6fc3df749667d"
              },
              "scheduledOn": "2012-09-11T12:19:00+00:00",
              "createdOn": "2012-08-29T20:34:26+00:00",
              "location": {
                  "uuid": "25952d48ee5e486fac57d9c7999bd7db"
              },
              "jobId": "J551",
              "link": {
                "rel": "detail",
                "url": "https://api.fieldaware.net/job/6739f71557c24a5ab16dc8549584ff30",
              }
          }
      ],
      "sortedBy": [
          "-scheduledOn"
      ],
      "page": 0
  }

Query Parameters:

start – starting date (required)
end – end date (required)
sortedBy – Available sorting criteria: scheduledOn, jobLead , location and state
location – filtered by location
jobLead – filtered by jobLead
state – filtered by state

Sample invocations

/job/?start=2014-01-23&end=2014-01-31&jobLead=9a4b0eb2100a41349a178463c1ea569f
/job/?start=2014-01-23&end=2014-01-31&state=Completed&sortedBy=-jobId
/job/?start=2014-01-23&end=2014-01-31&jobLead=9a4b0eb2100a41349a178463c1ea569f&location=b17e350cfd404b068e373ed7661e2b55
/job/?start=2014-01-23&end=2014-01-31&location=b17e350cfd404b068e373ed7661e2b55&pageSize=200&page=2

Status Codes:

200 OK – no error

Get Job¶

GET /job/(job_ref)¶

Retrieve all information on a particular job.

Sample request:

GET /job/99c313e92fb446bea07faeca5d5d392d HTTP/1.1
Host: api.fieldaware.net
Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
Accept: application/json

Sample response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "tasks": [
        {
            "note": "Test",
            "task": {
                "uuid": "61b8a942d4e2487290c1b49618252305",
                "name": "HEPA filter install",
                "description": "Install of HEPA filter"
            },
            "done": true,
            "uuid": "c66de447e19744409c07bf88f7fe4043",
            "asset": {
                "uuid": "a4d28061ee5311e49c3180e65008eae2"
            },
            "items": [
                {
                    "item": {
                        "uuid": "f81eab99da674809a2841251cd327fca",
                        "name": "Labor",
                        "description": "Labor description"
                    },
                    "unitCost": 10,
                    "unitPrice": 10,
                    "uuid": "222a8990c2954b64a5382818b59592eb",
                    "quantity": 8
                },
                {
                    "item": {
                        "uuid": "c550698e989447b6bef17f9121d95b39",
                        "name": "Air Conditioner",
                        "description": "Install & supply A/C unit"
                    },
                    "unitCost": 0,
                    "unitPrice": 5000,
                    "uuid": "80f80f2016374630bbf6b77e45a5b1fd",
                    "quantity": 1
                }
            ],
            "unitPrice": 0,
            "unitCost": 0,
            "customFields": {},
            "attachments": []
        }
    ],
    "revenue": 5080,
    "scheduledDuration": 120,
    "jobId": "J598",
    "invoice": {
        "link": {
            "url": "https://api.fieldaware.net/invoice/0021b917a7b444a697c751f361c22545",
            "rel": "detail"
        },
        "uuid": "0021b917a7b444a697c751f361c22545"
    },
    "jobLead": {
        "emailAddress": "jmartin@gmailus.com",
        "telno": "9725551212",
        "surname": "Martin",
        "uuid": "35e6bfb499e04e0fa7b2f80519a573f9",
        "name": "Jack"
    },
    "jobType": {
        "uuid": "46e6bfb487e04e0fa7b2f81617b573e4",
        "name": "Install"
    },
    "scheduledOn": "2012-09-19T17:00:00+00:00",
    "labor": [],
    "uuid": "99c313e92fb446bea07faeca5d5d392d",
    "crew": [
        {
            "workedHours": [
                {
                    "start": "2012-09-19T16:57:00+00:00",
                    "inTransit": false,
                    "end": "2012-09-19T16:59:14+00:00",
                    "startLocation": {
                          "lat": 41.40338,
                          "lng": 2.17403
                    },
                    "endLocation": {
                          "lat": 41.40338,
                          "lng": 2.17403
                    },
                    "pauseReason": "lunch"
                },
                {
                    "start": "2012-09-19T16:59:44+00:00",
                    "inTransit": false,
                    "end": "2012-09-19T17:00:00+00:00",
                    "startLocation": {
                          "lat": 41.40338,
                          "lng": 2.17403
                    },
                    "endLocation": {
                          "lat": 41.40338,
                          "lng": 2.17403
                    },
                    "pauseReason": "break"
                }
            ],
            "pauseReason": "break",
            "state": "completed",
            "uuid": "35e6bfb499e04e0fa7b2f80519a573f9"
        }
    ],
    "state": [
        "completed"
    ],
    "scheduledState": "dispatched",
    "location": {
        "uuid": "f367809ccd224716ad97cd685aafe899",
        "locality": "Plano",
        "country": null,
        "region": "TX",
        "postcode": "75098",
        "streetName": "665544 Preston Road",
        "name": null
    },
    "completedOn": "2012-09-19T17:00:00+00:00",
    "customFields": {},
    "asset": null,
    "startedOn": "2012-09-19T16:57:00+00:00",
    "description": "Install new service",
    "estDuration": 180,
    "pre_signature": {
        "url": "http://fieldaware.s3.amazonaws.com/db84ba3e8e4845ecad61bae0831b3e6e.png",
        "terms_accepted": false,
        "is_shown": false,
        "name": null
    },
    "customer": {
        "uuid": "88e1aeee54c4431e99d1a126b8ea300d",
        "name": "Jimmy Smith",
        "customerId": 34
    },
    "createdOn": "2012-09-19T16:57:04+00:00",
    "contact": null,
    "signature": {
        "url": "http://fieldaware.s3.amazonaws.com/84ed671888254fa3932c119a3eabed77.png",
        "terms_accepted": false,
        "is_shown": false,
        "name": null
    },
    "timeSlots": [
        {
            "duration": 20,
            "scheduledOn": "2018-12-06T13:53:00+00:00",
            "uuid": "6084b55362bc45c59c27464a3feea5e8",
            "crew": ["35e6bfb499e04e0fa7b2f80519a573f9",
                     "79yt890b7194412189c5019b85794444"]
        }
    ],
    "plannedEffort": 40
}

If retrieving a deferred job that has already been dispatched, the service returns a HTTP 307 redirection status with the URL of the newly dispatched job in the response’s Location header. This value can then be used in a second request to obtain the desired information about the dispatched job. For example, if requesting a deferred job that has already been dispatched.

GET /job/86082ca89a444a3fb1aaf39049423815 HTTP/1.1
Host: api.fieldaware.net
Accept: application/json
Authorization: Token d943a51d68c44ca38cab9abda20a4d18

The response will have the Location header set and an empty body.

HTTP/1.1 307 TEMPORARY REDIRECT
Location: https://api.fieldaware.net/job/4ce32c5a0d03407a8a572d0300ac0d69

Status Codes:

200 OK – no error
307 Temporary Redirect – redirection due to dispatch
404 Not Found – resource not found

Note

timeSlots data is read-only via the API. Time slots can only be modified in the webapp. The duration of each timeSlots entry is expressed in minutes.

The value for plannedEffort is a calculated field based on the number of time slots, their duration, and the number of assignees per time slot. The units for planned effort are minutes. This field is read-only.

The value for scheduledDuration is a calculated field based on the time taken between the start of the first time slot and the end of the last time slot. The units for scheduled duration are minutes. This field is read-only.

pauseReason`, ``startLocation and endLocation for crew workedHours cannot be set via the API. This field is read-only. The pauseReason for workedHours is the last pauseReason of the crew array.

scheduledState can not be set directly via the API presently, only via Planning Mode in the web application. scheduledState on an unassigned job will be updated indirectly from tentative or confirmed to dispatched if a job lead is set via the API. A job created without a job lead will return with a scheduledState of tentative.

Create Job¶

All fields are optional unless stated otherwise.

POST /job/¶

Create a new job.

Sample minimal request

POST /job/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
Accept: application/json

{
  "scheduledOn": "2015-11-11T14:30:00",
  "location": {
    "uuid": "067e238dd9354ea09073babbcbefa053"
  }
}

HTTP/1.1 201 CREATED
Content-Type: application/json
Location: https://api.fieldaware.net/job/21cbeb8f0606469899cc22c96ddb778d


{
  "link": {
    "url": "https://api.fieldaware.net/job/21cbeb8f0606469899cc22c96ddb778d",
    "rel": "detail"
  },
  "tasks": [],
  "revenue": 0,
  "jobId": "J2225",
  "invoice": null,
  "jobLead": null,
  "scheduledOn": "2014-09-27T00:00:00+00:00",
  "labor": [],
  "uuid": "f4e4341f7dc7416cadf64e7e99bb207f",
  "crew": [],
  "state": [
      "scheduled"
  ],
  "scheduledState": "tentative",
  "location": {
        "uuid": "f367809ccd224716ad97cd685aafe899",
        "locality": "Plano",
        "country": null,
        "region": "TX",
        "postcode": "75098",
        "streetName": "665544 Preston Road",
        "name": null
  },
  "completedOn": null,
  "customFields": {},
  "asset": null,
  "startedOn": null,
  "description": "",
  "estDuration": null,
  "pre_signature": null,
  "customer": {
      "uuid": "7b4d6ecf8a094937a1afae4479485d49",
      "name": "ABC Company",
      "customerId": 30
  },
  "createdOn": "2014-09-28T16:31:49+00:00",
  "contact": null,
  "signature": null,
  "timeSlots": {
      "duration": 0,
      "scheduledOn": "2014-09-27T00:00:00+00:00",
      "uuid": "5ab2e3f511a142908dda8db647c86ab8",
      "crew": []
  },
  "plannedEffort": 0
}

Sample request:

POST /job/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
Accept: application/json

{
  "scheduledOn": "2014-12-11T09:00:00",
  "notificationDelta": 2,
  "description": "collecting items",
  "estDuration": 180,
  "location": {
    "uuid": "38be890b7194412189c5019b85790zzz"
  },
  "contact": {
    "uuid": "11as890b7194412189c5019b85790293"
  },
  "asset": {
    "uuid": "41xs890b7194412189c5019b85791113"
  },
  "jobType": {
    "uuid": "81ds910g8144337187d6023j88792229"
  },
  "jobLead": {
    "uuid": "96vb890b7194412189c5019b85790999"
  },
  "crew": [
    {
      "uuid": "79yt890b7194412189c5019b85794444"
    }
  ],
  "tasks": [
    {
      "task": {
        "uuid": "bg56890b7194412189c5019b85790293"
      },
      "asset": {
        "uuid": "511ffeefddf34d0190524e738fe12303"
      },
      "assignee": {
        "uuid": "79yt890b7194412189c5019b85794444",
        "emailAddress": "bthompson@gmailus.com"
      },
      "note": "note for this task",
      "unitCost": 10.23,
      "unitPrice": 10.23,
      "done": true,
      "customFields": {
        "f713aba8bd2b11e6b6b7f45c89b2e1d5": "my sample string task custom field value",
        "23daaec2bd2c11e6bdc3f45c89b2e1d5": false
      },
      "items": [
        {
          "item": {
            "uuid": "56uy890b7194412189c5019b85790293"
          },
          "quantity": 2.0,
          "unitCost": 23.30,
          "unitPrice": 34.12
        }
      ]
    }
  ],
  "customFields": {
    "67as890b7194412189c5019b85790293": true,
    "my_custom_reference_key": "my sample text"
  },
  "labor": [
    {
      "user": {
        "uuid": "98de890b7194412189c5019b85790293"
      },
      "quantity": 3,
      "rate": {
          "name": "Overtime",
          "rate": 200.00,
          "cost": 120.00,
          "taxable": true,
          "taxes": [
            {
              "name": "Standard",
              "group": "Taxes"
            }
          ],
          "glAccount": "GL-40130"
      }
    }
  ]
}

Request JSON Object:

scheduledOn (datetime) – When the job is scheduled (required).
notificationDelta (integer) – When present, a deferred job is created and will be dispatched at time (scheduledOn - notificationDelta)
description (string) – Textual description of the job.
estDuration (integer) – The estimated duration of the work in minutes.
location (obj) – JSON object representing the location for the job.
contact (obj) – JSON object representing the contact person for the job.
asset (obj) – JSON object representing what asset is needed, if any.
jobLead (obj) – Who is the lead member for this job.
crew (array) – A list of JSON objects representing crew members.
tasks (array) – A list of JSON objects representing tasks.
task (obj) – Each object in tasks array has this form
task.task (obj) – JSON object defining the uuid of a task
task.note (string) – A note
task.assignee (obj) – JSON object defining the uuid of the task assignee. Must be an existing crew member.
task.unitCost (number) – The unitary cost of the task
task.unitPrice (number) – The unitary price of the task
task.customFields (obj) – Mapping of declaration keys to values (see note below)
done (boolean) – The status of the task
items (array) – An array of item
item (object) – Each object in items array has this form
item.item (obj) – JSON object defining the uuid of an item
item.quantity (integer) – Quantity needed of a specific item
item.unitCost (number) – The unitary cost of the item
item.unitPrice (number) – The unitary price of the item
customFields (obj) – A JSON objects representing custom fields, see Custom Fields
labor (object) – A list of JSON labor objects
labor – Each object in labor array has this form
labor.user (obj) – JSON object representing a user
labor.quantity (integer) – How many minutes spent on the job.
labor.rate (object) – a rate object (Details below)
labor.rate.name (string) – A descriptive name for the rate, used for displaying (required)
labor.rate.rate (number) – Price per hour to be charged (required)
labor.rate.cost (number) – Internal cost associated with unit (defaults to 0)
labor.rate.taxable (number) – Whether tax is to be applied to this on invoice generation (defaults to False)
labor.rate.taxes (array) – an array of tax objects
glAccount (string) – General Ledger account identifier

Note

Job lead is automatically added to the crew.

Note

Task assignee field is only available to True-Crew enabled customers.

Note

Labor can be specified either by an existing rate from the: Company settings (that is applicable to the specified user), or, by an ad-hoc rate for this labor entity (as in the previous example). In the former case, the rate is specified by UUID, in the latter case, there is no UUID but a number of fields need to be provided. If those value fields are present, a UUID, even if provided, is ignored.

Alternative rate specification

POST /job/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
Accept: application/json

{
  "scheduledOn": "2014-12-11T09:00:00",
  "location": {
    "uuid": "38be890b7194412189c5019b85790zzz"
  },
  "labor": [
    {
      "user": {
        "uuid": "98de890b7194412189c5019b85790293"
      },
      "quantity": 3,
      "rate": {
          "uuid": "091a93d117b34958acd9ab3234016550"
      }
    }
  ]
}

<json string labor.rate.uuid:: UUID referring to a specific rate

Note

To map a Custom Field to a job task, the declaration must have an entityClass of Task and have availableOnJob set to true. Attempting to map a declaration not having these values will be silently ignored.

These mappings support typical CRUD operations: adding, retrieving, updating and removing. Passed custom field keys that do not correspond to any of existing Task custom field declaration are silently ignored. The update semantics of these mappings can be summarized as “last write overwrites previous mapping”. Thus, for example, sending an empty mapping ({}) will remove all custom fields values associated with a job task.

Update Job¶

POST /job/(job_ref)¶

Update a given job.

JSON request body: Same as Create Job, with all properties being optional.

Warning

It is not possible to add, delete or update individual tasks or items using this endpoint (see below how to manage an individual task). It is only possible to specify the whole list of tasks on an update. When UUIDs of existing tasks on the job are listed, they are re-used, if only the UUID of the task to be added to the job is listed, a new task is added, for which the attributes note, unitCost, unitPrice, and done can be specified. Passing an empty array effectively deletes all tasks (and associated items) from the job.

Note

The job crew can only be updated when the job is in the ‘Scheduled’ state. For jobs that are in any other state, such as ‘Active’ or ‘Completed’, attempts to update the crew will result in a Conflict Error. Also, attempt to remove the job lead from the crew will result in a Conflict Error.

Note

It is currently not possible to update the labor section of a job.

If updating a deferred job that has already been dispatched, the service returns a HTTP 307 redirection status with the URL of the newly dispatched job in the response’s Location header.

Status Codes:

204 No Content – job updated successfully
307 Temporary Redirect – redirection due to dispatch
404 Not Found – resource not found
409 Conflict – request could not be full filled because state of resource does not allow payload to be applied

Delete Job¶

DELETE /job/(job_ref)¶

Delete a given job.

If deleting a deferred job that has already been dispatched, the service returns a HTTP 307 redirection status with the URL of the newly dispatched job in the response’s Location header.

Sample request:

DELETE /job/3b6d8b52006c46abbde3275f10fe9108 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5

Sample response

HTTP/1.1 204 NO CONTENT

Status Codes:

204 No Content – job deleted successfully
307 Temporary Redirect – redirection due to dispatch
404 Not Found – resource not found

Dispatch a Deferred Job¶

POST /job/(job_ref)/dispatch¶

Dispatch a deferred job.

When dispatching a job, the service returns a HTTP 303 redirection status with the URL of the newly dispatched job in the response’s Location header.

Sample request:

POST /job/3b6d8b52006c46abbde3275f10fe9108/dispatch HTTP/1.1
Host: api.fieldaware.net
Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
Accept: application/json

Sample response

HTTP/1.1 303 SEE OTHER
Location: https://api.fieldaware.net/job/d43f849cf8b146babc740cb3e4ec705f

Status Codes:

303 See Other – dispatch successful, dispatched job uuid can be found in the response’s Location header
404 Not Found – resource not found
409 Conflict – cannot dispatch an already dispatched job

Managing a Job Task¶

POST /job/(job_ref)/task/¶

Create a new job Task by appending it to the end of tasks array. The payload is the same used for task in the Job payload

POST /job/f4e4341f7dc7416cadf64e7e99bb207f/task/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
Accept: application/json
  {
    "task": {
      "uuid": "bg56890b7194412189c5019b85790293"
    },
    "asset": {
      "uuid": "511ffeefddf34d0190524e738fe12303"
    },
    "assignee": {
      "uuid": "79yt890b7194412189c5019b85794444"
    },
    "note": "note for this task",
    "unitCost": 10.23,
    "unitPrice": 10.23,
    "done": true,
    "items": [
      {
        "item": {
          "uuid": "56uy890b7194412189c5019b85790293"
        },
        "quantity": 2.0,
        "unitCost": 23.30,
        "unitPrice": 34.12
      }
    ]
  }

HTTP/1.1 201 CREATED
Content-Type: application/json
Location: https://api.fieldaware.net/job/f4e4341f7dc7416cadf64e7e99bb207f/task/2189c5019b8579029356uy890b719441
    {
      "uuid: "2189c5019b8579029356uy890b719441",
      "task": {
        "uuid": "bg56890b7194412189c5019b85790293"
      },
      "asset": {
        "uuid": "511ffeefddf34d0190524e738fe12303"
      },
      "assignee": {
        "uuid": "79yt890b7194412189c5019b85794444"
      },
      "note": "note for this task",
      "unitCost": 10.23,
      "unitPrice": 10.23,
      "done": true,
      "items": [
        {
          "item": {
            "uuid": "56uy890b7194412189c5019b85790293"
          },
          "quantity": 2.0,
          "unitCost": 23.30,
          "unitPrice": 34.12
        }
      ]
    }

GET /job/(job_ref)/task/(task_ref)¶: Get a single Task

PUT /job/(job_ref)/task/(task_ref)¶: Update a Task. The payload is the same used for updating a task in the Job payload. There is no need to specify the “uuid” field though.

DELETE /job/(job_ref)/task/(task_ref)¶: Delete a Task.

Upload Attachment to Job Task¶

A detailed guide about attachments is here

POST /job/(job_ref)/task/(task_ref_or_index)/attachment/¶

Upload one or more files and attach them to a given job task.

The task can be specified either by its UUID (if it is unique for this job) or its index (0-based) in the “tasks” array, as returned by Get Job.

The file(s) to be uploaded must be encoded as a “multipart/form-data” content type.

If adding an attachment to a task belonging to a deferred job that has already been dispatched, the service returns a HTTP 307 redirection status with the URL of the newly dispatched job in the response’s Location header.

Sample response:

HTTP/1.1 201 CREATED
Content-Type: application/json

[
  {
    "mimetype": "text/plain",
    "name": "requirements.txt",
    "uuid": "36e4a048a9354e7d9dd7caee7563bb9e"
  },
  {
    "mimetype": "application/msword",
    "name": "Summary.doc",
    "uuid": "67e02c4a4a2d464bb3f1dcdd2e736372"
  }
]

Status Codes:

201 Created – successful upload
307 Temporary Redirect – redirection due to dispatch
400 Bad Request – attachment too large
404 Not Found – resource not found

List Attachments of Job Task¶

GET /job/(job_ref)/task/(task_ref_or_index)/attachment/¶

Sample request:

GET /job/3b6d8b52006c46abbde3275f10fe9108/task/61b8a942d4e2487290c1b49618252305/attachment/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
Accept: application/json

Sample response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "mimetype": "image/png",
    "createdDate": "2013-08-11T14:00:00+00:00",
    "uuid": "a3aa9575739c43989bfec0fca014d3d0",
    "caption": "file description",
    "name": "pict.png"
  },
  {
    "mimetype": "image/png",
    "createdDate": "2013-08-11T15:00:00+00:00",
    "uuid": "c0fca014d3d0a3aa9575739c43989bfe",
    "caption": "file description",
    "name": "picture.png"
  }
]

Download Attachment of Job Task¶

GET /job/(job_ref)/task/(task_ref_or_index)/attachment/(attachment_ref)¶

Download a given file attached to a given job task.

The task can be specified either by its UUID (if it is unique for this job) or its index (0-based) in the “tasks” array, as returned by Get Job. The attachment is specified by its UUID, as returned by Upload Attachment to Job Task.

If downloading an attachment from a job task belonging to a deferred job that has already been dispatched, the service returns a HTTP 307 redirection status with the URL of the newly dispatched job in the response’s Location header.

Status Codes:

307 Temporary Redirect – redirection due to dispatch
404 Not Found – resource not found

Update Attachment caption¶

PUT /job/(job_ref)/task/(task_ref_or_index)/attachment/(attachment_ref)¶

You can update the attachment caption

Sample request:

PUT /job/3b6d8b52006c46abbde3275f10fe9108/task/61b8a942d4e2487290c1b49618252305/attachment/c0fca014d3d0a3aa9575739c43989bfe HTTP/1.1
Host: api.fieldaware.net
Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
Accept: application/json

{
  "caption": "caption text"
}

Sample response:

HTTP/1.1 204 No Content

Delete Attachment from Job Task¶

DELETE /job/(job_ref)/task/(task_ref_or_index)/attachment/(attachment_ref)¶

Delete a given file attached to a given job task.

The task can be specified either by its UUID (if it is unique for this job) or its index (0-based) in the “tasks” array, as returned by Get Job. The attachment is specified by its UUID, as returned by Upload Attachment to Job Task.

If deleting an attachment belonging to a deferred job that has already been dispatched, the service returns a HTTP 307 redirection status with the URL of the newly dispatched job in the response’s Location header.

Sample request:

DELETE /job/3b6d8b52006c46abbde3275f10fe9108/task/61b8a942d4e2487290c1b49618252305/attachment/c0fca014d3d0a3aa9575739c43989bfe HTTP/1.1
Host: api.fieldaware.net
Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5

Sample response:

HTTP/1.1 204 NO CONTENT

Status Codes:

204 No Content – attachment deleted successfully
307 Temporary Redirect – redirection due to dispatch
404 Not Found – resource not found

Job dependencies¶

In order to define a explicit order for the execution of jobs, the API supports the definition of predecessor and successor jobs for a given one. These must be set under the dependencies attribute.

POST /job/¶

Sample minimal request

POST /job/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
Accept: application/json

{
    "scheduledOn": "2013-08-21T14:30:00",
    "location": {
        "uuid": "f367809ccd224716ad97cd685aafe899",
    },
    "dependencies": {
      "predecessor": {
          "uuid": "c1ae96d5cc8a4f03b7af6882697bd382"
      },
      "successor": {
          "uuid": "3b6d8b52006c46abbde3275f10fe9108"
      }
    }
}

HTTP/1.1 201 CREATED
Content-Type: application/json
Location: https://api.fieldaware.net/job/21cbeb8f0606469899cc22c96ddb778d


{
  "link": {
    "url": "https://api.fieldaware.net/job/21cbeb8f0606469899cc22c96ddb778d",
    "rel": "detail"
  },
  "tasks": [],
  "revenue": 0,
  "jobId": "J2225",
  "invoice": null,
  "jobLead": null,
  "scheduledOn": "2014-09-27T00:00:00+00:00",
  "labor": [],
  "uuid": "21cbeb8f0606469899cc22c96ddb778d",
  "crew": [],
  "state": [
      "scheduled"
  ],
  "location": {
        "uuid": "f367809ccd224716ad97cd685aafe899",
        "locality": "Plano",
        "country": null,
        "region": "TX",
        "postcode": "75098",
        "streetName": "665544 Preston Road",
        "name": null
  },
  "completedOn": null,
  "customFields": {},
  "asset": null,
  "startedOn": null,
  "description": "",
  "estDuration": null,
  "pre_signature": null,
  "customer": {
      "uuid": "7b4d6ecf8a094937a1afae4479485d49",
      "name": "ABC Company",
      "customerId": 30
  },
  "createdOn": "2014-09-28T16:31:49+00:00",
  "contact": null,
  "signature": null,
  "dependencies": {
      "predecessor": {
          "uuid": "c1ae96d5cc8a4f03b7af6882697bd382",
          "link": {
            "url": "https://api.fieldaware.net/job/c1ae96d5cc8a4f03b7af6882697bd382",
            "rel": "detail"
      },
      "successor": {
          "uuid": "3b6d8b52006c46abbde3275f10fe9108",
          "link": {
            "url": "https://api.fieldaware.net/job/3b6d8b52006c46abbde3275f10fe9108",
            "rel": "detail"
          }
      }
  }
}

Job time windows¶

It is possible to set a “time window” on a job. This will indicate the earliest time when work for that job should start, and a deadline for when that job should be finished by or before. The values for these times should be nested under the timeWindow attribute

POST /job/¶

Sample minimal request

POST /job/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
Accept: application/json

{
    "scheduledOn": "2013-08-21T14:30:00",
    "location": {
        "uuid": "f367809ccd224716ad97cd685aafe899",
    },
    "timeWindow": {
      "startAfter": "2014-12-01T00:00:00",
      "deadline": "2014-12-05T00:00:00"
    }
}

HTTP/1.1 201 CREATED
Content-Type: application/json
Location: https://api.fieldaware.net/job/21cbeb8f0606469899cc22c96ddb778d


{
  "link": {
    "url": "https://api.fieldaware.net/job/21cbeb8f0606469899cc22c96ddb778d",
    "rel": "detail"
  },
  "tasks": [],
  "revenue": 0,
  "jobId": "J2225",
  "invoice": null,
  "jobLead": null,
  "scheduledOn": "2014-09-27T00:00:00+00:00",
  "labor": [],
  "uuid": "21cbeb8f0606469899cc22c96ddb778d",
  "crew": [],
  "state": [
      "scheduled"
  ],
  "location": {
        "uuid": "f367809ccd224716ad97cd685aafe899",
        "locality": "Plano",
        "country": null,
        "region": "TX",
        "postcode": "75098",
        "streetName": "665544 Preston Road",
        "name": null
  },
  "completedOn": null,
  "customFields": {},
  "asset": null,
  "startedOn": null,
  "description": "",
  "estDuration": null,
  "pre_signature": null,
  "customer": {
      "uuid": "7b4d6ecf8a094937a1afae4479485d49",
      "name": "ABC Company",
      "customerId": 30
  },
  "createdOn": "2014-09-28T16:31:49+00:00",
  "contact": null,
  "signature": null,
  "timeWindow": {
      "startAfter": "2014-12-01T00:00:00",
      "deadline": "2014-12-05T00:00:00"
  }
}

Warning

Job time windows and job dependencies are not compatible at the moment. Setting up job dependencies to a job with a time window will result in the removal of the startAfter and deadline values. Trying to set up a job time window on a job already having dependencies set up will result in a conflict error (status code 409).

Enterprise Job Updates¶

Warning

The following changes are only visible if the organisation using the API is Enterprise-enabled.

An additional attribute group has been added to jobs when enterprise mode is enabled for a company using the API. This attribute specifies the group which is in charge of fulfilling the job.

GET /job/(job_ref)¶

Sample response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "tasks": [],
    "revenue": 5080,
    "jobId": "J598",
    "invoice": null,
    "jobLead": {
        "emailAddress": "jmartin@gmailus.com",
        "telno": "9725551212",
        "surname": "Martin",
        "uuid": "35e6bfb499e04e0fa7b2f80519a573f9",
        "name": "Jack"
    },
    "jobType": {
        "uuid": "46e6bfb487e04e0fa7b2f81617b573e4",
        "name": "Install"
    },
    "scheduledOn": "2012-09-19T17:00:00+00:00",
    "labor": [],
    "uuid": "99c313e92fb446bea07faeca5d5d392d",
    "crew": [],
    "state": [
        "completed"
    ],
    "location": {
        "uuid": "f367809ccd224716ad97cd685aafe899",
        "locality": "Plano",
        "country": null,
        "region": "TX",
        "postcode": "75098",
        "streetName": "665544 Preston Road",
        "name": null
    },
    "completedOn": "2012-09-19T17:00:00+00:00",
    "customFields": {},
    "asset": null,
    "startedOn": "2012-09-19T16:57:00+00:00",
    "description": "Install new service",
    "estDuration": 180,
    "pre_signature": null,
    "customer": {
        "uuid": "88e1aeee54c4431e99d1a126b8ea300d",
        "name": "Jimmy Smith",
        "customerId": 34
    },
    "createdOn": "2012-09-19T16:57:04+00:00",
    "contact": null,
    "signature": null,
    "group": {
        "uuid": "c1ae96d5cc8a4f03b7af6882697bd382",
        "name": "Plano Branch"
    }
}

Request JSON Object:

group (obj) – Indicates the uuid and name of the group or branch in charge of the job.

This group attribute is also required on the creating payload for new jobs when enterprise is enabled:

POST /job/¶

Sample minimal request

POST /job/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token ab9a4326a6d7403b9a6ece2519f848a5
Accept: application/json

{
    "scheduledOn": "2013-08-21T14:30:00",
    "location": {
        "uuid": "f367809ccd224716ad97cd685aafe899",
    },
    "group": {
        "uuid": "c1ae96d5cc8a4f03b7af6882697bd382"
    }
}

HTTP/1.1 201 CREATED
Content-Type: application/json
Location: https://api.fieldaware.net/job/21cbeb8f0606469899cc22c96ddb778d


{
  "link": {
    "url": "https://api.fieldaware.net/job/21cbeb8f0606469899cc22c96ddb778d",
    "rel": "detail"
  },
  "tasks": [],
  "revenue": 0,
  "jobId": "J2225",
  "invoice": null,
  "jobLead": null,
  "scheduledOn": "2014-09-27T00:00:00+00:00",
  "labor": [],
  "uuid": "21cbeb8f0606469899cc22c96ddb778d",
  "crew": [],
  "state": [
      "scheduled"
  ],
  "location": {
        "uuid": "f367809ccd224716ad97cd685aafe899",
        "locality": "Plano",
        "country": null,
        "region": "TX",
        "postcode": "75098",
        "streetName": "665544 Preston Road",
        "name": null
  },
  "completedOn": null,
  "customFields": {},
  "asset": null,
  "startedOn": null,
  "description": "",
  "estDuration": null,
  "pre_signature": null,
  "customer": {
      "uuid": "7b4d6ecf8a094937a1afae4479485d49",
      "name": "ABC Company",
      "customerId": 30
  },
  "createdOn": "2014-09-28T16:31:49+00:00",
  "contact": null,
  "signature": null,
  "group": {
      "uuid": "c1ae96d5cc8a4f03b7af6882697bd382",
      "name": "Plano Branch"
  }
}