Skip to content

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…