List or Search for Jobs

Request

Shows all Jobs in vWork. Please ensure you read the tech note on paging of results.

Returns all jobs that match the provided search argument. If there is a large number of jobs then the results are divided across separate pages. You can specify the page you want by using the page argument. The available search filters are listed below. Each filter may only be used once per call.

Name	Type	Description
status	String	Returns jobs with this status. Possible values are: unassigned, unpublished, draft, pending, declined, assigned, postponed, started, paused, canceled, completed.
group_ids	Integer	This filter will only return jobs in the specified group.
start_at	DateTime	You can use the parameters (DateTime) start_at and (DateTime) end_at to define a time range to filter jobs. This filter will only return jobs that are allocated or assigned. For un-started jobs, the date range filter applies to the planned_start_at of the job. For started or completed jobs, the date range applies to the completed_at of the last completed step. This filter must be used in conjunction with the end_at filter. The format of the date/time must be iso8601.
end_at	DateTime	You can use the parameters (DateTime) start_at and (DateTime) end_at to define a time range to filter jobs. This filter will only return jobs that are allocated or assigned. For un-started jobs, the date range filter applies to the planned_start_at of the job. For started or completed jobs, the date range applies to the completed_at of the last completed step. This filter must be used in conjunction with the start_at filter. The format of the date/time must be iso8601.
completed_at	DateTime	Filters jobs by completed_at. This filter will only return jobs that have a completed_at between 00:00:00 and 23:59:59 on the specified date. The format of the date/time must be iso8601.
updated_at	DateTime	Filters jobs by updated_at. This filter will return jobs that have updated after the specified date and time. The format of the date/time must be iso8601.
customer_name	String	Returns jobs where the customer has this name (case sensitive).
customer_id	integer	Returns jobs where the customer has this ID.
worker_name	String	Returns jobs where the worker has this name (case sensitive).
worker_id	Integer	Returns jobs with this assigned worker (using the worker's ID).
worker_third_party_id	Integer	Returns jobs with this assigned worker (using the worker's third_party_id).
asset_name	String	Returns jobs where the job includes an asset with this name.
asset_id	Integer	Returns jobs where the job includes an asset with this ID.
template_name	String	Returns jobs where the template has this name.
template_id	Integer	Returns jobs where the template has this ID.
custom_field_value	String	Returns jobs where a custom field includes this value. This will includes partial matches, so searching for 1234, will return a job that has a custom field value of ABC12345. This only searches free text custom fields and pick list custom fields.
with_deleted	Boolean	When set to true the response will also include jobs that have been deleted.

It also possible to change the sort order of the results of your query. By default, jobs will be returned sorted by the created_at timestamp in descending order. However, you can sort by any of our base fields, in either ascending or descending order. Here are just some examples:

https://go.vworkapp.com/api/v5/jobs.xml?api_key={{apikey}}&sort_by=created_at&sort_dir=desc

https://go.vworkapp.com/api/v5/jobs.xml?api_key={{apikey}}&sort_by=updated_at&sort_dir=asc

https://go.vworkapp.com/api/v5/jobs.xml?api_key={{apikey}}&sort_by=status&sort_dir=desc

https://go.vworkapp.com/api/v5/jobs.xml?api_key={{apikey}}&sort_by=third_party_id&sort_dir=asc

https://go.vworkapp.com/api/v5/jobs.xml?api_key={{apikey}}&sort_by=actual_duration&sort_dir=desc

Security

apiKey

Query

api_keystringrequired

statusstring

Matches jobs with this state. Possible values are:

unassigned
unpublished
draft
pending
declined
assigned
postponed
started
paused
canceled
completed

Enum:"unassigned""unpublished""draft""pending""declined""assigned""postponed""started""paused""canceled"

group_idsinteger

This filter will only return jobs in the specified group.

Example:group_ids=1

start_atstring, (date-time)

You can use the parameters start at and end at to define a time range to filter jobs. This filter will only return jobs that are allocated or assigned. For un-started jobs, the date range filter applies to the planned start at of the job. For started or completed jobs, the date range applies to the completed at of the last completed step. This filter strong must be used in conjunction with the end at filter. The format of the date/time must be iso8601.

Example:start_at=2011-12-25T22%3A32%3A07%2B10

end_atstring, (date-time)

You can use the parameters start at and end at to define a time range to filter jobs. This filter will only return jobs that are allocated or assigned. For un-started jobs, the date range filter applies to the planned start at of the job. For started or completed jobs, the date range applies to the completed at of the last completed step. This filter must be used in conjunction with the start at filter. The format of the date/time must be iso8601.

Example:end_at=2011-12-25T22%3A32%3A07%2B10

completed_atstring, (date-time)

Filters jobs by completed at. This filter will only return jobs that have a completed at between 00:00:00 and 23:59:59 on the specified date. The format of the date/time must be iso8601.

Example:completed_at=2011-12-25T22%3A32%3A07%2B10

updated_atstring, (date-time)

Filters jobs by updated at. This filter will return jobs that have updated after the specified date and time. The format of the date/time must be iso8601.

Example:updated_at=2011-12-25T22%3A32%3A07%2B10

customer_namestring

Matches jobs where the customer has this name (case sensitive).

Example:customer_name=John%20Smith

customer_idinteger

Matches jobs where the customer has this id.

Example:customer_id=12345

worker_namestring

Matches jobs where the worker has this name (case sensitive).

Example:worker_name=Bob%20Jones

worker_idinteger

Matches jobs with this assigned worker (using the worker's id).

Example:worker_id=1

worker_third_party_idinteger

Matches jobs with this assigned worker (using the worker's third party id).

Example:worker_third_party_id=1

asset_namestring

This filter will only return jobs that include this asset.

Example:asset_name=Van12

asset_idinteger

This filter will only return jobs that include this asset.

Example:asset_id=1

template_namestring

This filter will only return jobs that use this template.

Example:template_name=Delivery

template_idinteger

This filter will only return jobs that use this template.

Example:template_id=1

custom_field_valuestring

This filter will return all jobs that have a custom field value that includes this string. (Including partial matches)

Example:custom_field_value=1

with_deletedboolean

When set to true the response will also include jobs that have been deleted.

Example:with_deleted=1

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

GET

/v5/jobs.xml

curl -i -X GET \
  'https://api.vworkapp.com/api/v5/jobs.xml?api_key=string&status=unassigned&group_ids=1&start_at=2011-12-25T22%253A32%253A07%252B10&end_at=2011-12-25T22%253A32%253A07%252B10&completed_at=2011-12-25T22%253A32%253A07%252B10&updated_at=2011-12-25T22%253A32%253A07%252B10&customer_name=John%2520Smith&customer_id=12345&worker_name=Bob%2520Jones&worker_id=1&worker_third_party_id=1&asset_name=Van12&asset_id=1&template_name=Delivery&template_id=1&custom_field_value=1&with_deleted=1&api_key=YOUR_API_KEY_HERE' \
  -H 'Accept-Encoding: gzip'

Responses

Headers

Transfer-Encodingstring

Example:"Chunked"

Statusstring

Example:"200 OK"

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"?>
<jobs type="array" current_page="1" per_page="1" total_pages="1" total_entries="1">
    <job>
        <id readonly="readonly">7996018</id>
        <job_type readonly="readonly">job</job_type>
        <group_ids/>
        <status>unassigned</status>
        <third_party_id>ABC123</third_party_id>
        <customer_name>JoeSmith</customer_name>
        <template_name>Template</template_name>
        <customer_id>822326</customer_id>
        <worker_id/>
        <worker_third_party_id/>
        <worker_name/>
        <worker_duration>0</worker_duration>
        <published_at type="datetime"/>
        <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="r…