vWork API V5 (Stable Release)
We have broken our API documentation into three parts. The following documentation is for creating and managing everything except jobs.
If you want to easily create jobs from your existing templates, then you should use our Templated Jobs API documentation. Please note: this is the recommended way of creating new jobs.
If you need to search for, download, or update your jobs, then you should use our Jobs API documentation.
Welcome to vWork’s API! Our API gives you a chance to add vWork’s dispatching functionality to other platforms. Dig into our API to integrate vWork with your existing workflow, or combine vWork with third party tools to make something new.
The base URL for our API is: https://api.vworkapp.com/
You need to have a vWork account with the API enabled to obtain an API key.
If you already have an API enabled vWork account, you can create your own API Key here on the integrations page.
If you do not yet have a vWork account, please get in touch with us.
There is a list of frequently asked questions on our helpdesk page as well as a brief intro to the vWork API. If you get stuck, please don't hesitate to send us an email at: support@vworkapp.com
Do you want to be emailed when we make a change to the API? You can signup for notifications about the vWork API here. We don't email very often, but we will notify you about any changes, as well as notifications about both planned and unplanned outages.
By default, the vWork API requires users to support gzip HTTP response compression on all requests. This is enabled by setting a 'Accept-Encoding: gzip' header on requests, and properly handling the 'Content-Encoding' header on responses. For more information please see http://en.wikipedia.org/wiki/HTTP_compression.
Failure to specify HTTP compression may result in requests being rejected with a HTTP response of type 406/Not Acceptable.
When providing dates you must supply them in the following ISO8601 format: YYYY-MM-DDTHH:MM:SS.
The API uses GMT by default. In order for you to receive localized results you must also supply a timezone on your ISO8601 date (e.g. 2011-12-25T22:32:07+10).
Finally, you may need to url encode the date string depending on your environment (e.g. 2011-12-25T22%3A32%3A07%2B10)
Here is an explanation of some of the error codes you may see when developing your integration.
HTTP 401 (Authorization Required) is returned if you don’t have permission to call this service. Check that your api_key is correct.
HTTP 404 (Not Found) is returned if the resource requested was not found.
HTTP 406 (Not Acceptable) is returned if the request did not include headers for http compression.
HTTP 422 (Unprocessable Entity) is returned if vWork wasn’t able to process the request body, for example when the XML is incorrectly formatted.
HTTP 429 (Too Many Requests) is returned if vWork is unable to process the number of requests you have sent, please throttle your queries and try again in a minute or two.
HTTP 500 (Server Error) is returned if a logic error was found, such as a required field is missing.
Please note, that quite often the reason for a 422 error is included in the body of the XML that is returned to you. This is often an excellent source of debugging information, here is a sample that says a date time custom field value was not a valid date and time.
<?xml version='1.0' encoding='utf-8' ?>
<errors>
<error>
<attribute>custom_fields.custom_field</attribute>
<message>'tomorrow night' must be a valid ISO8601 value.</message>
</error>
</errors>By default, the API will return only the first 50 results for any query. The rest of the results are available but are on separate pages. The number of results and number of pages available are included in the header row.
For example, the request: https://api.vworkapp.com/v4/jobs.xml?api_key=[API_KEY] might show the following header: <jobs type="array" current_page="1" per_page="50" total_pages="3" total_entries="112"> This indicates there were 112 results spread over three pages with a maximum of 50 entries per page, and that you are currently viewing page 1 of 3.
You are able to request more records per page using the per_page switch as per the following example: https://api.vworkapp.com/v4/jobs.xml?api_key=[API_KEY]&per_page=200 or, request different pages like this: https://api.vworkapp.com/v4/jobs.xml?api_key=[API_KEY]&page=2
Please note, that when making multiple requests to view a dataset, it is possible for the underlying data to change in the intervening timeframe. (For example if a job was deleted between viewing page 1 and page 2, the number of total results would be different when viewing the second page.)
The vWork website promotes the use of templates for web users to create and manage their jobs. This makes it easy for web users to create the same job type over and over again.
The use of templates is not supported via our standard API. You define what a job looks like when you send the job XML to the API.
However, there is a field in the API called "template_name", you can use this as a free text field to describe the job, it will be prominently displayed on both the website and the mobile app.
If you enter a template name that exists on the website, we will attempt to include this job in any alerts or reports that are run for that template.
This may or may not be possible, for example if a user has setup an alert for a step or custom field that exists in the web template but not in your API created job.
We also have an alternate API that can be used for creating jobs from templates. The documentation for this API can be found here: /v5-templated-jobs.json
It is possible to set a password for a user via the API. Many integrators want to know what the minimum requirements are for the password, or if they can re-use another password from an existing system.
vWork does not have a prescribed password policy, instead we measure the password entropy and only allow passwords that would require over 10^8 guesses. We also disallow a list of 93,000 commonly used passwords.
The best way around this is to use a passphrase instead of a password, something like: “battery horse staple”. Easy to remember, Easy to type and highly secure.
For general information about Webhooks, see http://en.wikipedia.org/wiki/Webhook
To minimise the requirement for a vWork API consumer to frequently poll the API for updates, vWork can send webhook callbacks to a predetermined endpoint URL when a change is made.
Depending on the information contained in the webhook, the consumer may then choose to perform a GET on that specific resource to retrieve the updated resource.
You can select to recieve a webhook when any of the following actions occur: Job Created, Job Assigned, Job Unassigned, Job Reassigned, Job Declined, Job Accepted, Job Rescheduled, Job Started, Job Completed, Job Deleted, Job Paused, Job Unpaused, Step Completed, Step Uncompleted, Custom Field Updated, Invoice Updated, User Created, User Updated, User Deleted, Proof of Delivery (POD) Created, and Proof of Delivery Deleted.
Note that if a single action triggers multiple events (for example, creating an assigned job will trigger both a Job Created and a Job Assigned webhook), the order of these events is not guaranteed. But if multiple separate changes happen, those events will be sent in order.
Please also note, that the Job Reassigned webhook only triggers if the job is reassigned from the jobs tab or the mobile app. If a job is reassigned by dragging it to a new worker on the schedule, this will result in two webhooks, a Job Unassigned followed by a Job Assigned.
You can configure your webhook endpoint, select the format you prefer (JSON or XML), as well as select what actions should trigger a webhook to be sent, from the admin section of the vWork website: https://go.vworkapp.com/html_client/admin/webhooks
The callback endpoint will be provided and maintained by the API consumer, and should support SSL/TLS encryption.
Given the potential for a relatively high volume of callbacks, it is strongly advised that the consumer employ asynchronous background task execution and/or a message queueing pattern for handling incoming Webhook callback events. Platforms such as Delayed Job, Resque and RabbitMQ are some well-known examples of asynchronous processing platforms.
(If you are using our legacy webhooks, turning on the new webhooks will not turn off the old ones. Please email support@vworkapp.com when you are ready for us to turn off the old webhooks. NB: If you update your webhook endpoint on the website, this will update the endpoint for both new and old webhooks.)
An example of a Job Created XML webhook is below:
<?xml version="1.0"?>
<event>
<transaction_id>617d4a74-7a19-11e6-bf7a-55542dc9080d</transaction_id>
<event_type>job_created</event_type>
<event_time>2016-09-14T01:20:10Z</event_time>
<resource>Job</resource>
<resource_id>9876234</resource_id>
<account_id>7829</account_id>
<request_user_type>User</request_user_type>
<request_user_id>123</request_user_id>
</event>An example of a Job Created JSON webhook is below:
{
"transaction_id": "617d4a74-7a19-11e6-bf7a-55542dc9080d",
"event_type": "job_created",
"event_time": "2016-09-14T01:20:10Z",
"resource": "Job",
"resource_id": 9876234,
"account_id": 7829,
"request_user_type": "User",
"request_user_id": 123
}An example of a Step Completed XML webhook is below:
<?xml version="1.0"?>
<event>
<transaction_id>63d75660-7a1a-11e6-8d5a-474090628a07</transaction_id>
<event_type>step_completed</event_type>
<event_time>2016-09-14T01:27:24Z</event_time>
<resource>Step</resource>
<resource_id>25062292</resource_id>
<account_id>8723</account_id>
<request_user_type>User</request_user_type>
<request_user_id>123</request_user_id>
<event_location>
<lat>-36.86524165519692</lat>
<lng>174.7806050757642</lng>
</event_location>
<data>
<step_name>Start Job</step_name>
<completed_at>2016-09-15T02:00:12Z</completed_at>
<job_id>8626773</job_id>
</data>
</event>An example of a Step Completed JSON webhook is below:
{
"transaction_id": "63d75660-7a1a-11e6-8d5a-474090628a07",
"event_type": "step_completed",
"event_time": "2016-09-14T01:27:24Z",
"resource": "Step",
"resource_id": 25062292,
"account_id": 8723,
"request_user_type": "User",
"request_user_id": 123,
"event_location": {
"lat": -36.86525719794106,
"lng": 174.780580958473
},
"data": {
"step_name": "Start Job",
"completed_at": "2016-09-15T02:58:31Z",
"job_id": 8621412
}
}Webhooks will always contain the following fields:
transaction_id - an internal vwork audit ID, can be ignored
event_type - the action that triggered the webhook
event_time - the time the server recieved the event, this may not be the time of the event (in UTC)
resource - the resource that was updated: job, custom field, proof of delivery, step or user.
resource_id - the vWork ID for the resource that was updated.
account_id - the ID of your vWork account (can be useful if you are recieving webhooks for multiple accounts.)
In addition, some webhooks may contain these extra fields:
request_user_type - Who triggered the action: a user, or a customer portal user. Will not be present for API events or automatic events (like an auto decline event).
request_user_id - The ID of the user who triggered the action. Will not be present for API events or automatic events (like an auto decline event).
resource_third_party_id - The 3rd Party ID for the resource that was updated. Only present when a 3rd Party ID exists.
data_worker_id - The ID of the worker the job is assigned to. Present on Job Accepted, Job Assigned and Job Reassigned Webhooks.
data_worker_name - The name of the worker the job is assigned to. Present on Job Accepted, Job Assigned and Job Reassigned Webhooks.
data_field_label - The label of the custom field that was updated. Only present on Custom Field Updated webhooks.
data_field_value - The new value of the custom field that was updated. Only present on Custom Field Updated webhooks.
data_field_type - The type of the custom field that was updated. Only present on Custom Field Updated webhooks.
event_location_lat - the lattitude of the worker's location when they completed the action. Only present on Step Completed, Step Uncompleted, Job Start and Job Complete when a location is available.
event_location_long - the longitude of the worker's location when they completed the action. Only present on Step Completed, Step Uncompleted, Job Start and Job Complete when a location is available.
data_step_name - The name of the step that was updated. Only present on Step Completed and Step Uncompleted webhooks.
data_completed_at - The time when the step was completed (in UTC). Only present on Step Completed webhook.
data_job_id - The job that the POD, step, or custom field is for. Only present on POD Created, POD Deleted, Custom Field Updated, Step Completed, and Step Uncompleted webhooks.
data_paused_at - The time when the job was paused (in UTC). Only present on Job Paused webhooks.
data_unpaused_at - The time when the job was unpaused (in UTC). Only present on Job Unpaused webhooks.
data_signed_at - When the POD was signed. Only present on POD Created and Deleted webhooks.
data_signed_by - Who Signed the POD. Only present on POD Created and Deleted webhooks.
data_name - The name of the user. Only present on User Created and User Updated webhooks.
data_email - The email address of the user. Only present on User Created and User Updated webhooks.
data_phone - The phone number of the user. Only present on User Created and User Updated webhooks.
data_notes - Any notes saved against the user. Only present on User Created and User Updated webhooks.
The vWork Webhook notifier will expect a HTTP/200 status code in the HTTP response from the callback endpoint provided by the API consumer. If a non-200 response is received, or the endpoint cannot be reached, vWork will discard the callback event.
Callbacks will always be sent in the order they were created; in the event of a single callback failure as described above, the failing callback will be discarded, but the Webhook notifier will attempt to send all subsequent callbacks in the normal manner.
Various factors could cause a callback to be discarded, such as an internet connection dropout or a momentary server problem. vWork recommends that the API consumer implement a low-frequency polling mechanism (e.g. hourly or daily) to “fill in” any data which may have been missed as a result of a discarded callback.
We implement a layer of security which is simple to consume. Using your api key and a "signature" that is calculated and sent with the Webhook, you can verify the contents of a Webhook as being authentic and un-tampered.
Webhooks are signed with a signature generated by taking an HMAC-SHA-256 hex digest of the raw HTTP Body of the Webhook post, using your api key as the secret.
This signature will be sent with the Webhook post in the header X-Vwork-Webhook-Signature-Hmac-Sha-256. If you chose not to implement this measure, you can just ignore the header.
As an example, the HMAC signature is generated in Ruby with this code:
OpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new('sha256'), api_key, webhook.body)If your api key is 123 and the Webhook request body contents are:
<job><name>test</name></job>using code like this:
OpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new('sha256'), '123', '<job><name>test</name></job>')the signature for this Webhook would be:
7643b9dbcab60ae6ae32e5683e1fae1db105bd31f1f0b5d51e5b773235359ff0Please note, that when calculating the HMAC SHA we strip out all line breaks and whitespace from the body of the webhook, in order for you to get the same result, you will need to do the same.
Postman is an API development and testing tool. We encourage our customers to use Postman as a way of quickly learning the capabilities of the vWork API. vWork support staff can often provide sample Postman collections or Postman friendly XML samples to assist you.
You can download a copy from here: https://www.getpostman.com/