Skip to content

Templates

Templates define the job types used in your account: their steps, custom fields, sections, invoice, hazards, time windows and labels. Jobs can be created from them with our Templated Jobs API.

Templates take the same fields as a job, described in our job API documentation, sent inside a <template> element instead of <job>. Use template_name for the name of the template.

A few job fields cannot be set on a template, and sending them is rejected with a 422 error: status and planned_start_at.

These calls only work on templates: using them with the ID of a job is rejected with a 422 error, use the job API for jobs instead.

Template responses also include web_labels and mobile_labels (the custom labels shown for jobs created from the template) and enable_invoicing. With the Health and Safety module they also include enable_hazards, is_incident, taggings and hazards, and each step's hazards_confirmation; with route optimisation, time_windows, required_capacity and negative_time_windows.

Sub-records can be removed from a template with the DELETE calls below, which reference the ID of the record within the template (for example the ID of a tagging, not of the tag).

Create A New Template

Request

Creates a new template in vWork.

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/templates.xml
curl -i -X POST \
  'https://go.vworkapp.com/api/v5/templates.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"?>
  <template>
      <template_name>Lawn Mowing</template_name>
      <planned_duration>3600</planned_duration>
      <steps type="array">
          <step>
              <name>Start</name>
          </step>
          <step>
              <name>Finish</name>
          </step>
      </steps>
      <custom_fields type="array">
          <custom_field>
              <name>Notes</name>
              <type>text</type>
              <permission>optional</permission>
          </custom_field>
      </custom_fields>
  </template>
  '

Responses

Created

Headers
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"?>
<template>
    <id readonly="readonly">1</id>
    <template_name>Lawn Mowing</template_name>
    <job_type readonly="readonly">job</job_type>
    <group_ids/>
    <web_labels type="array">
        <label>Customer Name</label>
        <label>Template Name</label>
        <label>Job ID</label>
    </web_labels>
    <mobile_labels type="array">
        <label>Customer Name</label>
        <label>Template Name</label>
    </mobile_labels>
    <enable_invoicing>false</enable_invoicing>
    <customer_name/>
    <customer_id/>
    <customer_third_party_id/>
    <worker_id/>
    <worker_third_party_id/>
    <worker_name/>
    <planned_duration>3600</planned_duration>
    <notes type="array"/>
    <steps type="array">
        <step>
            <id readonly="readonly">1</id>
            <name>Start</name>
            <created_at type="datetime" readonly="readonly">2026-10-06T19:11:55+13:00</created_at>
            <updated_at type="datetime" readonly="read…