Priava API – Quickstart Guide

This guide is intended for developers/web designers seeking to connect to Priava via the API and contains the following sections.

What is the API for?

Priava’s REST API has been developed following best practice guidelines to facilitate seamless integration between Priava and other applications including, but not limited to, web forms, accounting packages, inventory and marketing systems. The Priava API is the key to achieving ultimate efficiency, by ensuring a real-time sync of information and removing the need for duplicate data entry across multiple applications.

The API enables information captured on web forms to automatically feed into Priava. This means that on-line event and booking enquiries can be recorded as new opportunities, which significantly reduces administration time and removes the risk of error caused from duplicate data entry.

A basic web form template is included as part of the subscription to the Priava API, however, our developers are able to create customised templates to suit corporate branding guidelines, company websites and legal requirements when required (additional charges apply). Alternatively, clients can use their own developers and/or IT departments to create web form templates.

Priava Definitions

• Venue: A space or room available for hire/booking. This may be a whole venue or a single room depending how the users have configured their system. Normally it is a single bookable space.
• Event: A function/reservation/occurrence that has been booked within Priava. And event is made up of a start and end date and time, a primary contact, and basic event details such as event type, event source, and number of people (PAX). Venue bookings, Inventory, Catering, Packages, and Event Details can be added to events.
• Opportunity: Is an enquiry and is normally the stage before an event. It contains many of the same details as an event however it uses opportunity status instead of event statuses. Opportunities can have venues added to them, but cannot have Inventory, Catering, Packages, and Event Details added to them.
• Booking: Refers to a venue being added to an Event.
• Warning: When booking venues or resources a warning could be thrown to make the end user aware of a possible issue or raise particular awareness e.g. placing a tentative booking over another booking – perfectly fine to do, but making sure the end user is notified that only one booking will ever be able to go ahead.
• Conflict: When booking venues or resources a conflict is when there is a blocking issue found that cannot let the operation go ahead e.g. attempting to place a confirmed booking over another confirmed booking (effectively a double booking situation).

Overview of the standard booking process using opportunities and events

The typical booking process followed in Priava for taking an enquiry and creating an event booking is as follows;

• A Customer makes an enquiry
• The Priava user creates an Opportunity (Optionally they could go straight to an event if they wish)
• The Priava user adds Venue/s to the opportunity during creation if desired
• The opportunity is developed over time i.e. multiple quotes may be added as the Priava User and Customer discuss needs
• The Opportunity is ready to convert to an event (the exact trigger for this is dependent on internal processes)
• The Event is created (if opportunities are not required, this can be the starting point of the booking process)
• Venues and any catalogue items on the chosen quote of the opportunity are automatically added to the event
• If not using Opportunities, then the Priava user adds Venue/s to the Event during creation, along with any desired Inventory, Catering, Packages, Venue rates, Events details.

Security

Priava's API uses OAuth 2.0 which refreshes the API token every 6 hours.

When first configuring an API Token, the code is only valid for 10 minutes and must have been connected to in order to start the 6 hour cycle.

Creating an API Token

Only Priava Administrators can create a new API Token in your system. Full instructions can be found in the Priava Help Centre: Generate your OAuth 2.0 Tokens 

Once you have your Client ID, Client Secret and Code you will need to generate your Access and Refresh tokens so you can use the access token to authorise each API request and the refresh token to get a new access token when it expires.

Common use cases

Below you will find a walk-through of the common use cases for interacting with the API. Follow the step by step guide by with your own access tokens and data.

Creating an enquiry webform to submit an opportunity into Priava

• Decide on the information you want to capture on the form, making sure you consider that the following details are mandatory for an Opportunity in Priava;
  
  
  • Opportunity Name - Free Text
  • Identified By - Must be an active user (event coordinator) within Priava
  • Owner - Must be an active user (event coordinator) within Priava
  • Opportunity Status – The status of the enquiry which should be a hidden form field as it is specified by the Priava Administrator so that all new opportunities are created in the required status. We suggest the Priava Administrator creates a specific Opportunity status of ‘Web Enquiry’ for ease of identification in Priava.
  • Event Type - You can specify this from the active list in Priava or serve the full (or partial) list to the end-user for their selection
  • Source - You can specify this from the active list in Priava or serve the full (or partial) list to the end-user for their selection
  • Contact - Free Text used to
  • First Name – Free Text
  • Last Name – Free Text
  • Email Address – Valid email address
  • Contact Phone Number - Free Text, recommend international phone format e.g. +61 2 8383 4333 or +61 02 8383 4333
  • Contact Phone Type - You can specify this as either M or P for Mobile or Phone respectively
  • Address
    • Address Line 1 – Free Text
    • City – Free Text
    • State – Recommend to provide a drop down of valid states or counties relevant to the country selected.
    • Country – Recommend to provide a drop down of valid countries as per Priava.
• In addition to the mandatory fields, we recommend you capture some, if not all of the following:
  
  
  • Start Date - Any Future Date
  • Start Time - Any Time
  • End Date - Any Future Date greater than the start date
  • End Time - Any Time
  • Organisation - Free text that can be searched against existing organisations or used to create a new organisation (use contact number and email for organisation as these are mandatory)
  • Venue - You can specify the venue if your enquiry form is for a specific venue or serve the full (or partial) list of venues to the end-user for them to select – See Getting the list of venues and their IDs for more information.
  • Comment - You can define the comment type (known as a note type within the full Priava application). Priava can have multiple comment types, we suggest creating a comment type of “Web Comment” for this purpose. Any text added here will be added to the opportunity as a note with the defined comment type.
• Your end customer completes the required fields of the webform and submits the form
• If you are linking Contacts to Organisations, your application first creates/updates the Organisation using the Create or Update organisation endpoint.
• Next your application creates/updates the contact.
• You can now create the opportunity with the end user completed data and any pre-configured data

Getting the list of venues and their IDs

Often, you’d like to be able to present your users with a list of venues they can choose from. Alternatively, you may need to find the ID of a specific venue for subsequent transactions. This is exactly what the Get Venue List API is for. Importantly, it’s not just a flat list of venues, rather it provides you with their grouping and relationships so you can reconstruct the Priava Venue Tree / Venue Group Hierarchy if required.

Checking what venues are available

Priava provides the Get Venue API that allows you to search for venues that are available through the use of the OnlyAvailable property. For example, if you’re looking to check what venues are available between 9:00 AM and 11:00 AM on 24 November 2020, then you would call POST /v2/venue/get with the following parameters.

This would provide a JSON response listing the venues and their properties for you to display back to your user.

Checking if a particular venue is available

Pre-requisite: You must have the venue ID of the venue you are checking availability for. Refer to Getting the list of venues and their IDs earlier in this document

In order to check if a particular venue is available between a particular date and time, you would utilise the Search Venue Bookings API. For example, if you’re looking to check if the Moonlight Room is available between 9:00 AM and 11:00 AM on 24 November 2020, then you would call POST /v2/venue/get with the following parameters.

Creating an Enquiry Webform to Submit an Event in Priava

The basic flow for creating an event is to.

• Capture the event information
  
  
• If you want to book (a) venue(s) then create a venue booking block for the requested venue(s) at the requested date and time(s).
  
  
• Create the event and if you are booking venues pass the Booking Block ID.
  
  

Step 1 – Capture the event information:

• Decide on the event information you want to capture, making sure you consider that the following details are mandatory for an Event in Priava:
  
  
  • Event Name - Free Text
  • Event Start Date - Any Future Date
  • Event Start Time - Any Time
  • Event End Date – Any Future Date greater than the start date
  • Event End Time - Any Time
  • Event Coordinator - Must be an active user (event coordinator) within Priava
  • Event Status – The status of the event which should be a hidden form field as it is specified by the Priava Administrator. Rules around which status to use should be discussed and agreed with the Priava Administrator based on their current processes and needs.
  • Event Type - You can specify this from the active list in Priava or serve the full (or partial) list to the end-user for their selection
  • Source - You can specify this from the active list in Priava or serve the full (or partial) list to the end-user for their selection
  • Contact – Free text used to
    • First Name – Free Text
    • Last Name – Free Text
    • Email Address – Valid email address
    • Contact Phone Number – Free Text, recommend international phone format e.g. +61 2 8383 4333 or +61 02 8383 4333
    • Contact Phone Type - You can specify this as either M or P for Mobile or Phone respectively
    • Address
      • Address Line 1 – Free Text
      • City – Free Text
      • State – Recommend to provide a drop down of valid states or counties relevant to the country selected.
      • Country – Recommend to provide a drop down of valid countries as per Priava.
  • Event Contact Type - You can specify this from the active list in Priava or serve the full (or partial) list to the end-user for their selection
  • Any custom fields that are set to mandatory by the Priava Administrator. Please discuss these and submit as part of the create event API call.
• In addition to the mandatory fields, we recommend you capture some, if not all of the following.
  
  
  • Organisation – Free text that can be searched against existing organisations or used to create a new organisation (use contact number and email for organisation as these are mandatory)
  • Comment - You can define the comment type (known as a note type within the full Priava application). Priava can have multiple comment types, we suggest creating a comment type of “Web Comment” for this purpose. Any text added here will be added to the event as a note with the defined comment type.
  • Venue(s) – You need to pass the Block Venue ID to associate venue bookings to an event – Refer to Step 2 below.
• If you are linking Contacts to Organisations, your application first creates/updates the Organisation using the Create or Update organisation endpoint.
• Next your application creates/updates the contact.

Step 2 – (If Adding Venues to Event) block the venues

As part of the booking process, before you create your event and provide confirmation to your end used, you’d want to attempt to block the venue bookings. When blocking the venue bookings, any warnings (if the ignore Warning parameter is not passed) or conflicts will be returned. If none are present or warnings are ignored by your application or the end user than you can proceed to block those venues and ensure no other user or system can book that space either.

To do this, follow the instructions on the Block Venues API and be sure to keep the response as it’s to be used in the create event call.

Step 3 – Create the event

You can now create the event with the end user completed data and any pre-configured data. Note, this call will again carry out any conflict checks to ensure bookings and resources don’t have any issues, so be sure to handle any error cases or warnings as appropriate.

The event number will be returned, and that Event Number correlates the Event Number in the Priava Web Application – searchable via the Global Search or Find Events screen.