Skip to content

Job Basics

A job represents a task that gets assigned to (and completed by) a mobile worker. As well as the job’s basic details (when, where, and who for) you can also specify the job’s workflow (i.e. steps) and additional information (custom fields) for the job.

This section is only intended to cover the basics of job workflow; creating, editing and deleting jobs, as well as some of the more common job components. You will find more detail on some of the optional components in the following sections.

Here are the fields you can use when making a job request:

NameTypeDescription
group_idsStringComma-separated list of ids of groups this job shall show up in.
statusStringStatus refers to the state of the job: unassigned, unpublished, draft, pending, declined, assigned, postponed, started, paused, canceled, completed
third_party_idStringA user defined ID for this job. Field is optional, but if specified must have a unique value of 256 characters or less.
template_nameStringA short free text field you can use to describe the job. This is displayed instead of the template name within vWork. (Please see the Tech Note about templates and the API.)
customer_nameStringSpecifies which customer that the job is for. If a customer with this name doesn't exist then a new customer is created. (Please note, that use of this field should be avoided as this is not guaranteed to be a unique value.)
customer_idIntegerAn alternative to customer_name. Specifies the ID of the customer that the job is for. If you supply a valid customer ID then customer_name will be ignored.
customer_third_party_idStringAn alternative to customer_name and customer_id. Specifies the Third Party ID of the customer that the job is for.
worker_idIntegerAssigns the job to a worker. You must also supply a planned_start_at time if assigning a job directly to a worker. (You can assign multiple workers to a job but only if Accept/Decline has been enabled in the account settings.)
worker_third_party_idStringAssigns the job to a worker. You must also supply a planned_start_at time if assigning a job directly to a worker. (You can assign multiple workers to a job but only if Accept/Decline has been enabled in the account settings.)
planned_start_atDateTimeThe date and time that the job is scheduled to start. The format of the date/time must be iso8601.
planned_durationIntegerThe length of time in seconds that the job is planned to run for. Adding this to the planned_start_time gives when the job is planned to finish.
stepsArrayAn array of the job's steps. Each step specifies a sub-task that must be completed. Steps optionally contain a location as well. A job must contain at least one step.
step.nameStringA short description of the step (e.g. Start, Check Wiring, etc).
location.formatted_addressStringThe address that the step is to be performed at.
location.latDecimalThe latitude of the location that the step is to be performed at. This must be included if you wish the job's location to be displayed on the map.
location.lngDecimalThe longitude of the location that the step is to be performed at. This must be included if you wish the job's location to be displayed on the map.
step.completed_atDateTimeThe date and time that the step was completed on. If the step doesn't have a completed_at value then the step hasn't been completed. The format of the date/time is iso8601 at UTC (e.g. 2011-12-25T22:32:07+00)
custom_fieldsArrayAn array of the job's custom fields. This can be omitted if the job doesn't require these.
custom_field.nameStringThe name of the custom field. This is used to label the custom field.
custom_field.valueStringThe value of the custom field. Omit this field if you don't wish to have a preset value.
custom_field.typeStringPlease see 'Custom fields types' below.
custom_field.permissionStringPlease see 'Permissions' below.
custom_field.pick_list_idIntegerThe unique id of a Pick List to show as the value options for this field. Omit this element if you don't want to use a pick list.
invoice.numberStringThe invoice number.
invoice.descriptionStringDetails about this invoice.
invoice.tax_rateStringApplied tax rate for the invoice.
invoice.line_itemsArrayAn array of the invoice line items.
invoice.line_items.codeStringLine item code, each item must have a code or description or both.
invoice.line_items.descriptionStringLine item description, each item must have a code or description or both.
invoice.line_items.unit_costDecimalCost per unit of line item
invoice.line_items.requested_quantityDecimalThe quantity that was requested by the customer, used to calculate quote totals.
invoice.line_items.actual_quantityDecimalThe actual quantity that was delivered, used to calculate invoice totals. Note, this field will be empty when the job is a quote.
invoice.line_items.notesStringNotes for the line item.

When retrieving a job from vWork, you may also see these additional fields in the response:

NameTypeDescription
job_typeStringEither 'job' or 'quote'. Denotes the type of job. It is not currently possible to create quotes via the API.
idIntegerThe unique ID of the job.
worker_nameStringThe name of the worker the job has been assigned to.
has_podBooleanIndicates if a Proof of Delivery Signature or Photo has been collected.
planned_end_atDateTimeThe planned start at plus the planned duration.
actual_start_atDateTimeThe date and time that the job was actually started. This field is only present if the job actually has started. The format of the date/time is iso8601 at UTC (e.g. 2011-12-25T22:32:07+00)
actual_durationIntegerThe length of time in seconds that the job actually ran for. Adding this to the actual_start_at gives when the job was actually finished.
paused_atDateTimeIf the job has a status of paused, this field will say when the job was paused, otherwise this field will be blank.
worker_durationDecimalThe actual duration minus any paused events, ie: the amount of time the worker spent on the job. Expressed in decimal, ie: 1.25 hours.
jobsArrayAn array of the jobs that matched the given search criteria. The current page being returned, the amount of jobs returned per page, the total number of pages, and the grand total of jobs matched are also provided.
custom_field.attachment_idStringA unique ID for any attached file. This field is only visible if there is an attachment present. You can use this ID to retrieve the file directly. Please see Attachments for more information.
signed_atDateTimeThe date/time that the job was signed for on the workers device. The format of the date/time is iso8601 at UTC (e.g. 2011-12-25T22:32:07+00).
signed_byStringThe supplied name of the person who signed the proof of delivery on the workers device.
enable_hazardsBooleanIndicates whether or not a user can add hazards to this job. (Only visible if the vWork Health and Safety module is enabled.)
is_incidentBooleanIndicates if a job has been created as a result of an accident or incident. (Only visible if the vWork Health and Safety module is enabled.)
hazardsArrayAn array of hazards that have been added to a job. (Only visible if the vWork Health and Safety module is enabled.)
hazards_confirmationBooleanIndicates the job step that will trigger a hazard review. (Only visible if the vWork Health and Safety module is enabled.)
Operations

Create A New Job

Request

Creates a job in vWork. Mandatory fields are planned_duration and at least one step name. All other fields are optional.

Jobs will also accept a third_party_id. This is useful for passing through an external job ID. If you supply a third_party_id, it must be unique.

Along with the job's basic details you may want to specify the job's Steps and Custom Fields. Steps specify a job's workflow and what locations need to be visited, and custom fields are used to specify additional data fields for the job.

The sample in this section includes two steps (one with a geocoded address) and samples of some of the custom field types. More detailed information on steps and custom fields is available in the following sections.

Security
apiKey
Query
api_keystringrequired
Headers
Accept-Encodingstringrequired

Must be gzip. The vWork API requires HTTP compression on all requests; requests without it may be rejected with 406 Not Acceptable (see Tech Notes → HTTP Compression).

Value:"gzip"
Example:gzip
Bodyapplication/xml; charset=utf-8
string

Raw XML payload — see the example.

POST
/v5/jobs.xml
curl -i -X POST \
  'https://api.vworkapp.com/api/v5/jobs.xml?api_key=string&api_key=YOUR_API_KEY_HERE' \
  -H 'Accept-Encoding: gzip' \
  -H 'Content-Type: application/xml; charset=utf-8' \
  -d '<?xml version="1.0" encoding="utf-8"?>
  <job>
      <third_party_id>1234567</third_party_id>
      <customer_name>John Smith</customer_name>
      <template_name>A Sample Template</template_name>
      <planned_duration>7200</planned_duration>
    <steps type="array">
      <step>
        <name>Pick up goods</name>
        <location>
          <formatted_address>12 Heather Street, Auckland, NZ</formatted_address>
          <lat>-36.879621</lat>
          <lng>174.751282</lng>
        </location>
      </step>
      <step>
        <name>Return to base</name>
      </step>
    </steps>
  <custom_fields type="array">
      <custom_field>
          <name>A Free Text Field</name>
          <type>text</type>
          <value>Hello World</value>
          <permission>optional</permission>
      </custom_field>
      <custom_field>
          <name>An Image Field</name>
          <type>image</type>
          <value></value>
          <permission>optional</permission>
      </custom_field>
      <custom_field>
          <name>A Date Time Field</name>
          <type>datetime</type>
          <value>2011-12-25T22:32:07+12</value>
          <permission>optional</permission>
      </custom_field>
      <custom_field>
          <name>A Number Field</name>
          <type>number</type>
          <value>5</value>
          <permission>optional</permission>
      </custom_field>
      <custom_field>
          <name>A Link Field</name>
          <type>link</type>
          <value>https://www.example.com</value>
          <permission>read_only</permission>
      </custom_field>
      <custom_field>
          <name>A Checkbox Field</name>
          <type>checkbox</type>
          <value>T</value>
          <permission>optional</permission>
      </custom_field>
      <custom_field>
          <name>A Currency Field</name>
          <type>currency</type>
          <value>95.00</value>
          <permission>optional</permission>
      </custom_field>
      <custom_field>
          <name>A Signature Field</name>
          <type>signature</type>
          <value></value>
          <permission>required</permission>
      </custom_field>
      <custom_field>
          <name>A Picklist Field</name>
          <type>pick_list</type>
          <value>Monday</value>
          <pick_list_id>118558</pick_list_id>
          <permission>optional</permission>
      </custom_field>
      <custom_field>
          <name>A Multi Picklist Field</name>
          <type>multi_pick_list</type>
          <pick_list_id>118558</pick_list_id>
          <values type="array">
              <value>Monday</value>
              <value>Tuesday</value>
              <value>Wednesday</value>
          </values>
      </custom_field>
  </custom_fields>
  </job>'

Responses

Created

Headers
Transfer-Encodingstring
Example:"Chunked"
Statusstring
Example:"201 Created"
Cache-Controlstring
Example:"max-age=0, private, must-revalidate"
Content-Encodingstring
Example:"gzip"
Bodyapplication/xml; charset=utf-8
string

Raw XML payload — see the example.

Response
<?xml version="1.0" encoding="utf-8"?>
<job>
    <id readonly="readonly">20589575</id>
    <job_type readonly="readonly">job</job_type>
    <group_ids/>
    <status>unassigned</status>
    <third_party_id>1234567</third_party_id>
    <customer_name>John Smith</customer_name>
    <template_name>A Sample Template</template_name>
    <customer_id>2689012</customer_id>
    <customer_third_party_id>vwork15748017484566596</customer_third_party_id>
    <worker_id/>
    <worker_third_party_id/>
    <worker_name/>
    <worker_duration>0</worker_duration>
    <published_at type="datetime"/>
    <published_by readonly="readonly"/>
    <has_pod readonly="readonly">false</has_pod>
    <signed_at readonly="readonly"/>
    <signed_by readonly="readonly"/>
    <paused_at/>
    <planned_duration>7200</planned_duration>
    <planned_start_at type="datetime"/>
    <planned_end_at type="datetime" readonly="readonly"/>
    <actual_start_at type="datetime" readonly="readonly"/>
    <actual_duration readonly…