VOW Help Centre

Request API usage ​

warning

The following guide is intended for developers only. It uses technical language and assumes basic familiarity with HTML and HTTP concepts. If you are a normal user of VOW, you can safely skip this page.

This page provides a quick-start guide for integrating a new or existing form with VOW's request API. The page is broken up into a few main segments:

  • Captcha: Information about the captcha system we use and how you'll need to integrate it. If you already use a captcha system, this might even be as simple as changing one string.
  • JSON form: This section is all about sending your form data using JS in a JSON format. Most modern sites using a framework like Vue, Angular or React will need information from here.
  • Legacy HTML form: Some sites still make use of tried-and-true HTML forms. For those, this section outlines what name attributes you'll need to include on your form to make use of the request API.

The examples on this page only demonstrates how to adjust your website's code to directly talk to VOW. Backend server code can come in many different forms and languages, and is thus not covered here. If you want more details relevant to incorporation of the requests API with backend code, documentation for the API endpoints can be viewed here.

Captcha ​

VOW's request API requires the use of a Google reCAPTCHA in the form. Specifically, we make use of the reCAPTCHA v3. For more information, see Google's documentation.

Google's reCAPTCHA makes use of key pairs. A public 'site key' and a private key, which is held by VOW. For your site, you will need to have your captcha site key set to match VOW's. If you need the site key for use with your website, please contact us.

Where reCAPTCHA_site_key is written in the following snippets, it should be replaced by the site key. If you already use Google reCAPTCHA on your forms, you may only need to change your site key to ours to make your form compatible with VOW's API captcha requirements.

At its simplest, reCAPTCHA can be included in a page by following these steps:

  1. Add the Google reCAPTCHA JS script to the form's page.
html
<script src="https://www.google.com/recaptcha/api.js?render=reCAPTCHA_site_key"></script>
  1. Adjust your form and/or JS to include the recaptcha token with the request.

For JS-based websites

Add code to your form submission function to grab the token and submit the form.

js
// grecaptcha is a global provided by the script in step 1.
grecaptcha.ready(function() {
  grecaptcha.execute('reCAPTCHA_site_key', { action: 'submit' }).then(function(token) {
      // Add your logic to submit to your backend server here.
  });
});

with async/await with modern syntax:

js
// grecaptcha is a global provided by the script in step 1.
grecaptcha.ready(async () => {
  const token = await grecaptcha.execute('reCAPTCHA_site_key', { action: 'submit' })
  // Add your logic to submit to your backend server here.
  // ....
});

For HTML form-based websites

Adjust your form submission button to automatically add Google's captcha key to the form data.

html
<button class="g-recaptcha"
  data-sitekey="reCAPTCHA_site_key"
  data-callback='onSubmit'
  data-action='submit'>Submit</button>
html
<script>
  function onSubmit(token) {
    // your-form-id-here is the id of the <form> element which contains the captcha button above
    document.getElementById("your-form-id-here").submit();
  }
</script>

JSON form ​

There are many possible ways to capture data from a page and assemble it into the relevant JSON structure. For simplicity, we'll assume you already have some method of collating your user's inputs into a JS object, which we'll call jsonForm. Once you have this, you can easily send the data to VOW using either the browser's built-in Fetch API, or using common third-party libraries like Axios.

Fetch API (built-in):

js
// You'll get your json data as an object however best suits your specific page design
const jsonForm = {}

// This call posts data to the structured endpoint.
// If your JSON structure doesn't conform to the needed spec, you can
// alternatively use the unstructured endpoint:
// https://officeworkflow.com.au/api/work-request/unstructured
fetch('https://officeworkflow.com.au/api/work-request', {
  method: 'POST',
  body: JSON.stringify(jsonForm),
  headers: {
    // While you could put your key in plaintext here, it's better
    // to at least put it in a .env with a bundler.
    'Authorization': environment.APIKEY,
    'Content-Type': 'application/json'
  }
})

Axios:

js
// You'll get your json data as an object however best suits your specific page design
const jsonForm = {}

// This call posts data to the structured endpoint. It is async, so should be await'ed
// Or called with .then() to handle subsequent logic
axios.post('https://officeworkflow.com.au/api/work-request', jsonForm, {
  // While you could put your key in plaintext here, it's better
  // to at least put it in a .env with a bundler.
  headers: { 'Authorization': environment.APIKEY }
})

If you are using the unstructured endpoint and only have a single string of data, you can alternatively replace jsonForm with a JS object with the single field text. For example, using axios:

js
const formText = '' // Assuming formText holds the string input data.
axios.post('https://officeworkflow.com.au/api/work-request/unstructured', { text: formText }, {
  // While you could put your key in plaintext here, it's better
  // to at least put it in a .env with a bundler.
  headers: { 'Authorization': environment.APIKEY }
})

Legacy HTML form ​

Legacy forms in HTML pages can automate sending the request to the API, but require specific setup for each of the fields. Each input element must be tied to a specific field using the name attribute on the element. The possible list of valid name fields can be found in the full API documentation.

Any field aside from those listed in the body params will be ignored, unless the form is sent to the unstructured endpoint. If it is, an LLM will attempt to parse all provided fields into relevant data about the work request.

Example HTML form:

html
<form action="https://officeworkflow.com.au/api/work-request" method="post" enctype="multipart/form-data">
  <!-- Your form inputs should go here. -->
  <!-- The following is an unstyled, bare-bones example of how each of the fields could be included -->
  <h3>Address information</h3>

  <label for="unit_number">Unit number</label>
  <input type="text" id="unit_number" name="unit_number" value=""/>

  <label for="house_number">House number</label>
  <input type="text" id="house_number" name="house_number" value=""/>

  <label for="street_name">Street name</label>
  <input type="text" id="street_name" name="street_name" value=""/>

  <label for="suburb">Suburb</label>
  <input type="text" id="suburb" name="suburb" value=""/>

  <label for="postcode">Postcode</label>
  <input type="text" id="postcode" name="postcode" value=""/>

  <label for="state">State</label>
  <select name="state" id="state">
    <option value="nsw">New South Wales</option>
    <option value="qld">Queensland</option>
    <option value="vic">Victoria</option>
    <option value="sa">South Australia</option>
    <option value="nt">Northern Territory</option>
    <option value="wa">Western Australia</option>
    <option value="act">Australian Capital Territory</option>
  </select>

  <h3>Contact details</h3>

  <label for="first_name">First name</label>
  <input type="text" id="first_name" name="first_name" value=""/>

  <label for="last_name">Last name</label>
  <input type="text" id="last_name" name="last_name" value=""/>

  <label for="phone">Phone number</label>
  <input type="text" id="phone" name="phone" value=""/>

  <label for="email_address">Email address</label>
  <input type="text" id="email_address" name="email_address" value=""/>

  <h3>Invoice contact</h3>

  <label for="invoice_address">Invoice address</label>
  <input type="text" id="invoice_address" name="invoice_address" value=""/>

  <label for="invoice_name">Invoice to be addressed to:</label>
  <input type="text" id="invoice_name" name="invoice_name" value=""/>

  <label for="report_type">Report type:</label>
  <input type="text" id="report_type" name="report_type" value=""/>

  <label for="report_purpose">Purpose of valuation</label>
  <select name="report_purpose" id="report_purpose">
    <option value="stamp_duty">Stamp duty</option>
    <option value="other">Other</option>
  </select>

  <label for="referral">How did you hear about us?</label>
  <select name="referral" id="referral">
    <option value="word">Word-of-mouth</option>
    <option value="facebook">Facebook</option>
  </select>

  <label for="work_type">Are you requesting a valuation, or just a quote?</label>
  <select name="work_type" id="work_type">
    <option value="quote">Quote</option>
    <option value="valuation">Valuation</option>
  </select>

  <label for="instructions">Do you have any additional instructions for this request?</label>
  <textarea id="instructions" name="instructions"></textarea>

  <button class="g-recaptcha"
    data-sitekey="reCAPTCHA_site_key"
    data-callback='onSubmit'
    data-action='submit'>Submit</button>
</form>