{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-v5-templated-jobs.json","sidebar":"sidebar-sidebars.yaml"},"props":{"definitionId":"v5-templated-jobs.json","settings":{"baseUrlPath":"/v5-templated-jobs"},"disableAutoScroll":true,"seo":{"title":"vWork API v5 Templated Jobs - Creation Only (Stable Release)","llmstxt":{"hide":true}},"dynamicMarkdocComponents":[],"metadata":{"type":"openapi","title":"vWork API v5 Templated Jobs - Creation Only (Stable Release)","version":"","description":"# Getting Started\n\n***We have broken our API documentation into three parts. The following documentation is for creating jobs from existing vWork templates.***\n\n***If you need full control over your jobs and don't want to reference your templates, then you should use our job API documentation.***\n\n***If you need to access something other than jobs, then you should use our vWork API documentation***\n\n## The Use of Templates\n\nvWork software is centred on the use of templates to manage multiple job types. This makes it easy for website users to create the same job type over and over again.\n\nThe 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.\n\nHowever, the Templated Job API does use the templates saved in your vWork account. In essence, you supply us with the template name (or the template ID) that you wish to use when creating the job, we will then inherit everything we can from the template; Step names, Custom Field Logic, Custom Labels, Duration, Tags, Time Windows, etc.\n\nThe only other information you may need to supply are any values that you wanted to include on the job creation. This may include a customer ID, or a customer name, an address for the job, any custom field values you want to supply, or invoice line items that need to appear on the job.\n\nYou are welcome to use the Templated Job API for your initial job creation, and then our standard API for updating, cancelling, downloading or deleting jobs. Our standard API also includes many other non-job related functions such as managing hazards, groups, messages, assets, users, etc..\n\nThe base URL for our API is: https://api.vworkapp.com/\n\n## What does Stable mean?\n\nStable means that this version is final and is not going to change in the future, even if we add new features to the product.\n\n## What can you build?\n\nvWork’s API allows you to build our dispatching functionality into other software. For example, you can use our API so that our dispatch software works hand-in-hand with your CRM software.\n\nYou can also pull data from vWork’s API to produce a tailored management report.\n\n## Getting your API key\n\nYou need to have a vWork account with the API enabled to obtain an API key.\n\nIf you already have an API enabled vWork account, you can create your own API Key here on the integrations page.\n\nIf you do not yet have a vWork account, please get in touch with us.\n\n# Need More Help?\n\n## Where to get more help\n\nThere 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\n\n## Mailing List\n\nDo 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.\n\n# Tech Notes\n\n## HTTP Compression\n\nBy 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.\n\n_Failure to specify HTTP compression may result in requests being rejected with a HTTP response of type 406/Not Acceptable._\n\n## ISO8601 Date and Time Format\n\nWhen providing dates you must supply them in the following ISO8601 format: YYYY-MM-DDTHH:MM:SS.\n\nThe API uses GMT by default. In order for you to use your local time you must also supply a timezone on your ISO8601 date (e.g. 2011-12-25T22:32:07+10).\n\nFinally, you may need to url encode the date string depending on your environment (e.g. 2011-12-25T22%3A32%3A07%2B10)\n\n## Error Codes\n\nHere is an explanation of some of the error codes you may see when developing your integration.\n\n* HTTP 401 (Authorization Required) is returned if you don’t have permission to call this service. Check that your api_key is correct.\n\n* HTTP 404 (Not Found) is returned if the resource requested was not found.\n\n* HTTP 406 (Not Acceptable) is returned if the request did not include headers for http compression.\n\n* HTTP 422 (Unprocessable Entity) is returned if vWork wasn’t able to process the request body, for example when the XML is incorrectly formatted.\n\n* 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.\n\n* HTTP 500 (Server Error) is returned if a logic error was found, such as a required field is missing.\n\nPlease 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.\n\n```\n\n\n \n custom_fields.custom_field\n 'tomorrow night' must be a valid ISO8601 value.\n \n\n```\n\n# Webhooks\n\n## What are Webhooks?\n\nFor general information about Webhooks, see http://en.wikipedia.org/wiki/Webhook\n\nTo 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.\n\nDepending 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.\n\n## What Webhooks are Available?\n\nYou 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.\n\nNote 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.\n\nPlease 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.\n\n## Setting up Webhooks\n\nYou 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\n\nThe callback endpoint will be provided and maintained by the API consumer, and should support SSL/TLS encryption.\n\nGiven 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.\n\n(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.)\n\n## Sample Webhooks\n\nAn example of a Job Created XML webhook is below:\n\n```\n\n\n 617d4a74-7a19-11e6-bf7a-55542dc9080d\n job_created\n 2016-09-14T01:20:10Z\n Job\n 9876234\n 7829\n User\n 123\n\n```\n\nAn example of a Job Created JSON webhook is below:\n\n```\n{\n \"transaction_id\": \"617d4a74-7a19-11e6-bf7a-55542dc9080d\",\n \"event_type\": \"job_created\",\n \"event_time\": \"2016-09-14T01:20:10Z\",\n \"resource\": \"Job\",\n \"resource_id\": 9876234,\n \"account_id\": 7829,\n \"request_user_type\": \"User\",\n \"request_user_id\": 123\n}\n```\n\nAn example of a Step Completed XML webhook is below:\n\n```\n\n\n 63d75660-7a1a-11e6-8d5a-474090628a07\n step_completed\n 2016-09-14T01:27:24Z\n Step\n 25062292\n 8723\n User\n 123\n \n -36.86524165519692\n 174.7806050757642\n \n \n Start Job\n 2016-09-15T02:00:12Z\n 8626773\n \n\n```\n\nAn example of a Step Completed JSON webhook is below:\n\n```\n{\n \"transaction_id\": \"63d75660-7a1a-11e6-8d5a-474090628a07\",\n \"event_type\": \"step_completed\",\n \"event_time\": \"2016-09-14T01:27:24Z\",\n \"resource\": \"Step\",\n \"resource_id\": 25062292,\n \"account_id\": 8723,\n \"request_user_type\": \"User\",\n \"request_user_id\": 123,\n \"event_location\": {\n \"lat\": -36.86525719794106,\n \"lng\": 174.780580958473\n },\n \"data\": {\n \"step_name\": \"Start Job\",\n \"completed_at\": \"2016-09-15T02:58:31Z\",\n \"job_id\": 8621412\n }\n}\n```\n\n## Webhook Content\n\nWebhooks will always contain the following fields:\n\n* transaction_id - an internal vwork audit ID, can be ignored\n\n* event_type - the action that triggered the webhook\n\n* event_time - the time the server recieved the event, this may not be the time of the event (in UTC)\n\n* resource - the resource that was updated: job, custom field, proof of delivery, step or user.\n\n* resource_id - the vWork ID for the resource that was updated.\n\n* account_id - the ID of your vWork account (can be useful if you are recieving webhooks for multiple accounts.)\n\nIn addition, some webhooks may contain these extra fields:\n\n* 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).\n\n* 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).\n\n* resource_third_party_id - The 3rd Party ID for the resource that was updated. Only present when a 3rd Party ID exists.\n\n* data_worker_id - The ID of the worker the job is assigned to. Present on Job Accepted, Job Assigned and Job Reassigned Webhooks.\n\n* data_worker_name - The name of the worker the job is assigned to. Present on Job Accepted, Job Assigned and Job Reassigned Webhooks.\n\n* data_field_label - The label of the custom field that was updated. Only present on Custom Field Updated webhooks.\n\n* data_field_value - The new value of the custom field that was updated. Only present on Custom Field Updated webhooks.\n\n* data_field_type - The type of the custom field that was updated. Only present on Custom Field Updated webhooks.\n\n* 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.\n\n* 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.\n\n* data_step_name - The name of the step that was updated. Only present on Step Completed and Step Uncompleted webhooks.\n\n* data_completed_at - The time when the step was completed (in UTC). Only present on Step Completed webhook.\n\n* 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.\n\n* data_paused_at - The time when the job was paused (in UTC). Only present on Job Paused webhooks.\n\n* data_unpaused_at - The time when the job was unpaused (in UTC). Only present on Job Unpaused webhooks.\n\n* data_signed_at - When the POD was signed. Only present on POD Created and Deleted webhooks.\n\n* data_signed_by - Who Signed the POD. Only present on POD Created and Deleted webhooks.\n\n* data_name - The name of the user. Only present on User Created and User Updated webhooks.\n\n* data_email - The email address of the user. Only present on User Created and User Updated webhooks.\n\n* data_phone - The phone number of the user. Only present on User Created and User Updated webhooks.\n\n* data_notes - Any notes saved against the user. Only present on User Created and User Updated webhooks.\n\n## Webhook Reliability and Monitoring\n\nThe 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.\n\nCallbacks 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.\n\nVarious 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.\n\n## Security Layer - HMAC SHA\n\nWe 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.\n\nWebhooks 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.\n\nThis 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.\n\nAs an example, the HMAC signature is generated in Ruby with this code:\n\n```\nOpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new('sha256'), api_key, webhook.body)\n```\n\nIf your api key is 123 and the Webhook request body contents are:\n\n```\ntest\n```\n\nusing code like this:\n\n```\nOpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new('sha256'), '123', 'test')\n```\n\nthe signature for this Webhook would be:\n\n```\n7643b9dbcab60ae6ae32e5683e1fae1db105bd31f1f0b5d51e5b773235359ff0\n```\n\nPlease 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.\n\nAlso the webhook body should be ASCII encoded.\n\n# Postman\n\n## What is Postman?\n\nPostman 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.\n\nYou can download a copy from here: https://www.getpostman.com/"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"apidocs.vworkapp.com","port":4000,"ipAddress":"216.73.216.74"},"lang":"default_locale","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"main"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/v5-templated-jobs","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}